docs: clarify rtk name collision and fix installation confusion

[FlorianBruniaux]

Problem

Users are accidentally installing the wrong "rtk" package due to a name collision:

• ✅ Rust Token Killer (rtk-ai/rtk) - LLM token optimizer for Claude Code
• ❌ Rust Type Kit (reachingforthejack/rtk) - Rust codebase query and type generation tool

This causes significant confusion when users run cargo install rtk and then find that rtk gain (the token savings analytics command) doesn't exist. Multiple users have reported this issue.

Solution

This PR adds clear warnings and verification steps throughout the documentation to prevent and diagnose this issue.

Documentation Updates

README.md

• Added prominent ⚠️ warning section at the top explaining the name collision
• Fixed installation instructions to require mandatory verification via rtk gain
• Added link to new TROUBLESHOOTING.md guide

CLAUDE.md

• Added name collision warning with verification steps
• Helps AI assistants understand the correct rtk package

INSTALL.md

• Enhanced pre-installation checks to detect wrong package
• Added uninstall/reinstall instructions for users with Type Kit
• Clarified warning about cargo install rtk ambiguity

New Files

docs/TROUBLESHOOTING.md
Comprehensive troubleshooting guide covering:

• Wrong rtk installed (Type Kit vs Token Killer detection)
• cargo install rtk pitfalls and solutions
• Missing commands (vitest, pnpm, next, etc.) - fork vs upstream
• PATH issues, compilation errors, and other common problems
• Links to both fork and upstream issue trackers

scripts/check-installation.sh
Automated diagnostic script that verifies:

• ✅ RTK installed and in PATH
• ✅ Correct version (Token Killer with working rtk gain command)
• ✅ Available features (core + optional fork features)
• ✅ Claude Code integration (CLAUDE.md files)
• ✅ Auto-rewrite hook configuration

Users can run bash scripts/check-installation.sh for instant diagnosis.

Testing

The diagnostic script has been tested with:

• ✅ Correct RTK installation (Token Killer)
• ✅ Wrong RTK installation (Type Kit) - properly detects and suggests fix
• ✅ Missing RTK - provides installation instructions
• ✅ Partial feature set detection (upstream vs fork)

Impact

This PR will:

• Reduce user confusion by making the name collision explicit upfront
• Speed up issue resolution with the automated diagnostic script
• Prevent wrong installations with mandatory rtk gain verification steps
• Improve onboarding for new users with clearer documentation

Files Changed

README.md                        +42 -17
CLAUDE.md                        +13 -3
INSTALL.md                       +28 -12
docs/TROUBLESHOOTING.md          +441 new
scripts/check-installation.sh    +109 new

Total: 5 files changed, 605 insertions(+), 31 deletions(-)

---

This addresses confusion reported by users who installed reachingforthejack/rtk thinking it was the token optimizer.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR addresses user confusion caused by a name collision between two different "rtk" packages on crates.io: the Rust Token Killer (this project) and Rust Type Kit (a different project). The PR adds comprehensive documentation and diagnostic tooling to help users identify and fix installation issues.

Changes:

• Added prominent warning sections across all documentation explaining the name collision
• Created comprehensive troubleshooting guide covering common installation and configuration issues
• Added automated diagnostic script to verify correct installation and detect common problems

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
scripts/check-installation.sh	New automated diagnostic script that verifies correct RTK installation, detects Type Kit vs Token Killer, checks available features, and validates Claude Code integration
docs/TROUBLESHOOTING.md	New comprehensive troubleshooting guide covering wrong package installation, missing commands, PATH issues, compilation errors, and Claude Code integration problems
README.md	Added name collision warning section at top, enhanced installation instructions with mandatory verification steps, added link to troubleshooting guide
INSTALL.md	Added name collision warning, enhanced pre-installation checks to detect wrong package, clarified cargo install rtk pitfalls, added uninstall/reinstall instructions
CLAUDE.md	Added name collision warning with verification steps to help AI assistants understand the correct rtk package

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.