feat(cli): CLI command-surface redesign — remove redundant/vestigial commands (#183)

[aroff]

Summary

Implements issue #183 — reduces the fastskill CLI surface by removing four redundant/vestigial commands, collapsing their capabilities into well-named selectors, and adding diagnostics + auto-reindex.

Command removals (hard, no aliases)

• resolve → search <q> --local --paths [--content full] --json
• show → read <id> --meta / read <id> --tree / list
• sync → removed (agents read the skills directory directly)
• disable → remove <id>

Additions / changes

• read gains --meta, --tree, --format, --json, --locked (metadata/tree modes, content port from show).
• search --local gains --paths and --content <none|preview|full> (reuses context_resolver), reaching parity with all resolve use cases; --paths forces JSON.
• reindex is now a no-op (exit 0 + informational message) when no embedding provider is configured.
• Auto-reindex after successful add/install/update/remove when a provider is configured, overridable via --reindex/--no-reindex and the new auto_reindex config flag.
• Graceful degradation: search --local warns and falls back to text search; analyze subcommands print an informational note and continue with structural-only analysis.
• New doctor command (--json supported) reporting environment readiness with [PASS]/[WARN]/[FAIL] and a non-zero exit on hard failures.
• fastskill <id> shorthand routes a bare positional to read.
• Downstream artifacts updated: help/spec (auto-derived), webdocs, CHANGELOG.

What this PR completed on top of the in-progress branch

The branch had crashed mid-implementation. The remaining gaps fixed here:

1. Wired the fastskill <id> shorthand in main.rs (was documented + tested but never implemented). The argv rewrite skips global flags, recognizes commands and groups, and excludes the four retired command names so they still error as "unrecognized subcommand".
2. --content value validation now runs eagerly (any invalid value errors, not just under --paths); fixed stale help text.
3. --reindex/--no-reindex mutual-exclusion added to install and update (was only on add/remove).
4. Added compiled regression tests for the new search validations and refreshed a stale read doc comment.

Testing

• cargo nextest run — 334 passed, 0 failed.
• cargo clippy --workspace --all-targets --all-features — no new warnings (2 pre-existing test-code lints in add/install.rs unrelated to this change).
• Manually verified acceptance criteria AC1–AC24 against the built binary (removed commands error; read --meta/--tree/--json; search --local --paths/--content; reindex/analyze/search degradation; doctor exit codes & JSON; bare-positional shorthand).

Notes

• The spec's required test files under the repo-root tests/cli/ are not compiled in this virtual workspace (pre-existing infra debt — only crate-level tests/ and inline unit tests run). Behaviors are covered by inline unit tests + manual binary verification; rewiring that harness is out of scope for CLI command-surface redesign: remove redundant/vestigial commands and put discovery on consistent axes #183.
• update --help panics in debug builds due to a pre-existing --version arg colliding with clap's propagated --version (present on main, debug-only assert). Release builds work; left untouched as out of scope.

🤖 Generated with Claude Code

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
fastskill	🟢 Ready	View Preview	Jun 8, 2026, 3:19 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.