scip-query 0.7.1 → 0.7.2

package/README.md

@@ -165,1027 +165,108 @@ All query results are filtered through your project's `.gitignore`. Build artifa
 
 ## Command Reference
 
-### Index Management
+<!-- BEGIN GENERATED COMMAND REFERENCE -->
 
-#### `reindex`
+This syntax summary is generated from the CLI command descriptors. Keep workflow guidance hand-authored, but keep command syntax, descriptions, and option flags descriptor-owned.
 
-Index (or re-index) the codebase. Auto-detects which languages are present, runs the appropriate SCIP indexer, and converts the output to SQLite.
+### Indexing
 
-```bash
-scip-query reindex
-scip-query reindex --language typescript
-scip-query reindex --pnpm-workspaces        # for pnpm monorepos
-```
-
-**Options:**
-- `-l, --language <lang>` — Index only this language (can repeat)
-- `--pnpm-workspaces` — Enable pnpm workspace support (TypeScript)
-
-**When to use:** After significant code changes, after pulling, or before running analysis commands for the first time.
-
----
-
-#### `watch`
-
-Watch the project for file changes and automatically reindex in the background. Uses a single-flight model: only one reindex runs at a time, changes during reindex set a dirty flag for one follow-up run.
-
-```bash
-scip-query watch
-scip-query watch --debounce 60000           # wait 60s after last change
-```
-
-**Options:**
-- `--debounce <ms>` — Milliseconds to wait after the last file change before reindexing (default: 30000)
-- `--cooldown <ms>` — Minimum milliseconds between reindex completions (default: 60000)
-
-**How it works:** Watches for file changes (respecting `.gitignore`), debounces, runs reindex in a child process writing to a temp file, then atomically swaps the database. Queries against the old index continue working during reindex — no downtime.
-
----
-
-#### `status`
-
-Show the current index status: where it's stored, how big it is, when it was built.
-
-```bash
-scip-query status
-```
-
----
-
-#### `stats`
-
-Show index statistics: document count, symbol count, definition count, reference count, database size.
-
-```bash
-scip-query stats
-# Documents:   42
-# Symbols:     1111
-# Definitions: 803
-# References:  2094
-# Index size:  660 KB
-# Last built:  2026-04-10 16:12:58
-```
-
-**Value:** Quick sanity check that your index is healthy and up to date.
-
----
-
-#### `init`
-
-Create a `.scipquery.json` config file in the project root with auto-detected languages and default settings.
+| Command | Description | Options |
+|---|---|---|
+| `reindex` | Index the codebase and convert to SQLite | `-l, --language <lang>`<br>`--pnpm-workspaces`<br>`--force`<br>`--allow-partial`<br>`--indexer-concurrency <n>` |
+| `augment-sources` | Add source files skipped by upstream SCIP indexers to the SQLite documents table | - |
+| `augment-vue` | Add compiler-resolved Vue SFC references to the SQLite index using Volar | `--project <tsconfig>` |
 
-```bash
-scip-query init
-```
+### Core
 
----
+| Command | Description | Options |
+|---|---|---|
+| `stats` | Show index statistics | - |
 
 ### Navigation
 
-These commands help you understand and navigate the codebase — find where things are defined, where they're used, and how files relate to each other.
-
-#### `files <pattern>`
-
-Find indexed files matching a path pattern.
-
-```bash
-scip-query files auth              # all files with "auth" in the path
-scip-query files .service.ts       # all service files
-```
-
-**Value:** Quick file discovery without leaving the terminal. Respects gitignore.
-
----
-
-#### `symbols <file>`
-
-List all symbols defined in a file with their line ranges and type signatures.
-
-```bash
-scip-query symbols auth.service.ts
-#   1-50   AuthService  — class AuthService
-#   5-20   AuthService:login()  — login(email: string): Promise<Token>
-#   22-35  AuthService:logout()  — logout(): void
-```
-
-**Value:** Instant overview of a file's API surface — like a table of contents with type information. Faster than reading the file.
-
----
-
-#### `methods <className>`
-
-List all methods of a class with their line ranges.
-
-```bash
-scip-query methods AuthService
-#   5-20   login
-#   22-35  logout
-```
-
-**Value:** Quick method inventory for a class. Useful when you need to know what a class can do without reading its full source.
-
----
-
-#### `refs <symbol>`
-
-Find every file that references a symbol, grouped by file with line numbers.
-
-```bash
-scip-query refs login
-# src/controllers/auth.controller.ts
-#   line 15
-# src/__tests__/auth.test.ts
-#   line 8
-```
-
-**Value:** "Who uses this?" — the most fundamental code intelligence question. Compiler-resolved, so no false positives from string matches.
-
----
-
-#### `trace <symbol>`
-
-Show a symbol's definition (with signature) and every file that references it. Like `refs` but also shows you where the symbol is defined.
-
-```bash
-scip-query trace parseSymbol
-# ═══ DEFINITION ═══
-#   src/symbols/symbol-parser.ts:35-99  — parseSymbol(raw: string): ScipSymbol | ScipLocalSymbol
-#
-# ═══ REFERENCED BY ═══
-#   src/index.ts
-#   src/symbols/symbol-parser.ts
-```
-
-**Value:** End-to-end symbol investigation. Answers "where is this defined, what's its signature, and who uses it?" in one command.
-
----
-
-#### `outline <file>`
-
-Tree-structured view of all symbols in a file, using parent-child nesting when the indexer provides `enclosing_symbol` data.
-
-```bash
-scip-query outline db.ts
-# 0-111  src:db
-# 19-110  src:db:ScipDatabase
-#   24-29  src:db:ScipDatabase:constructor()
-#   32-34  src:db:ScipDatabase:setPathFilter()
-```
-
-**Value:** Visual file structure at a glance — like an IDE's outline panel but in the terminal.
-
----
-
-#### `hierarchy <symbol>`
-
-Show a symbol's ancestry chain — from the symbol up through its enclosing scopes (method → class → module → file).
-
-```bash
-scip-query hierarchy login
-# src:auth:AuthService:login()
-#   src:auth:AuthService
-```
-
-**Value:** Understand where a symbol lives in the nesting hierarchy. Requires the indexer to populate `enclosing_symbol`.
-
----
-
-#### `members <symbol>`
-
-Find all direct children of a symbol (methods, fields, nested types) using the enclosing_symbol relationship.
-
-```bash
-scip-query members AuthService
-#   5-20   [method]  login
-#   22-35  [method]  logout
-#   37-37  [term]    tokenSecret
-```
-
-**Value:** Like `methods` but includes fields, nested types, and anything else directly inside a symbol. Requires `enclosing_symbol` support from the indexer.
-
----
-
-#### `call-graph <symbol>`
-
-Show what calls a symbol (incoming) and what the symbol calls (outgoing).
-
-```bash
-scip-query call-graph shortenSymbol
-# Symbol: src:symbol-parser:shortenSymbol()
-#
-# ═══ CALLERS (16) ═══
-#   src/queries/dead.ts        src:queries:dead
-#   src/queries/hotspots.ts    src:queries:hotspots
-#   ...
-#
-# ═══ CALLEES (0) ═══
-```
-
-**Value:** Understand a function's role in the call chain. High caller count = widely used, be careful changing it. Many callees = complex function, may need decomposition.
-
----
-
-### Dependency Analysis
-
-These commands map how files and modules depend on each other — forward deps, reverse deps, and full module maps.
-
-#### `deps <file>`
-
-List all internal files that this file depends on (forward dependencies).
-
-```bash
-scip-query deps cli.ts
-# src/runtime/config.ts
-# src/storage/db.ts
-# src/queries/index.ts
-# src/reindex/index.ts
-```
-
-**Value:** "What does this file need to work?" Useful before refactoring — tells you what you're coupled to.
-
----
-
-#### `rdeps <file>`
-
-List all files that depend on this file (reverse dependencies).
-
-```bash
-scip-query rdeps symbol-parser
-# src/index.ts
-# src/queries/dead.ts
-# src/queries/hotspots.ts
-# ...
-```
-
-**Value:** "Who breaks if I change this?" The blast radius of a modification. High rdeps count = be very careful with changes.
-
----
-
-#### `system <module>`
-
-Full module map: all files in the module, all exported symbols, all inbound and outbound dependencies.
-
-```bash
-scip-query system queries
-# ═══ FILES ═══
-# src/queries/dead.ts
-# src/queries/deps.ts
-# ...
-#
-# ═══ EXPORTED SYMBOLS ═══
-#   8-124  dead()
-#   4-23   deps()
-# ...
-#
-# ═══ DEPENDS ON (internal) ═══
-#   src/storage/db.ts
-#   src/symbols/symbol-parser.ts
-#
-# ═══ DEPENDED ON BY ═══
-#   src/runtime/cli.ts
-#   src/index.ts
-```
-
-**Value:** Complete module overview in one command. Shows the module's interface, its internal structure, and its position in the dependency graph.
-
----
-
-#### `surface <module>`
-
-What symbols do external consumers actually use from this module? The true public API — not what's exported, but what's actually imported and referenced by other modules.
-
-```bash
-scip-query surface storage/db.ts
-#   src/runtime/cli.ts → ScipDatabase
-#   src/runtime/cli.ts → ScipDatabase:close()
-#   src/queries/dead.ts → ScipDatabase:all()
-#   src/queries/dead.ts → ScipDatabase:isIgnored()
-```
-
-**Value:** Distinguish "exported" from "actually used." If you export 20 symbols but only 5 are referenced externally, the other 15 are candidates for removal or making private.
-
----
-
-#### `imports <file>`
-
-What symbols does this file import? Uses SCIP `role=2` (import) mentions.
-
-```bash
-scip-query imports auth.controller.ts
-#   AuthService:login()  ← src/services/auth.service.ts
-#   validateInput()      ← src/utils/validation.ts
-```
-
-**Value:** Quick import inventory. Note: depends on the indexer emitting `role=2` — not all do (e.g., `scip-typescript` currently doesn't).
-
----
-
-#### `imported-by <symbol>`
-
-Which files import this symbol?
-
-```bash
-scip-query imported-by AuthService
-#   src/controllers/auth.controller.ts
-#   src/__tests__/auth.test.ts
-```
-
----
-
-#### `unused-imports <file>`
-
-Find imports in a file that are never referenced in the same file — likely unused imports that should be cleaned up.
-
-```bash
-scip-query unused-imports auth.controller.ts
-#   formatDate  in src/controllers/auth.controller.ts
-# 1 unused import(s)
-```
-
-**Value:** Automated unused import detection. Note: same `role=2` limitation as `imports`.
-
----
-
-### Code Quality & Dead Code
-
-These commands find code that can be removed, consolidated, or cleaned up.
-
-#### `dead [scope]`
-
-Find dead exports: symbols defined locally with no cross-file references. Distinguishes between "dead code" (not referenced anywhere, even in the same file) and "dead exports" (used locally but never imported by other files).
-
-```bash
-scip-query dead --min-loc 10
-scip-query dead src/utils --skip-barrels --include-members
-```
-
-**Options:**
-- `--min-loc <n>` — Only show symbols >= N lines (default: 1)
-- `--include-tests` — Include test files in results (excluded by default)
-- `--skip-barrels` — Ignore references from inactive barrel re-export files
-- `--include-members` — Include class members (module-level only by default)
-- `--only-dead` — Show only `[dead code]` symbols (skip `[file-internal only]`)
-- `--only-internal` — Show only `[file-internal only]` symbols (skip `[dead code]`)
-
-**Value:** Find code you can delete. The `--skip-barrels` flag is key when a codebase has unused barrels, but it now keeps live entry-surface barrels counted so active exports do not look dead.
-
----
-
-#### `isolated`
-
-Find completely orphaned symbols: defined locally, not referenced by anything (not even in the same file), and not referencing anything external. These are truly disconnected from the codebase graph.
-
-```bash
-scip-query isolated --min-loc 5
-scip-query isolated --scope src/utils
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-loc <n>` — Minimum lines of code (default: 3)
-
-**Value:** Stricter than `dead` — these symbols serve no purpose at all. Safe deletion candidates.
-
----
-
-### Codebase Metrics
-
-These commands measure structural properties of the codebase — hotspots, coupling, bottlenecks, fan-in/out.
-
-#### `hotspots`
-
-Find the most-referenced symbols in the codebase. These are the choke points where changes have the widest blast radius.
-
-```bash
-scip-query hotspots -n 15
-#   refs  files  symbol
-#   ────  ─────  ──────
-#     39     39  src:types
-#     33     31  src:db:ScipDatabase
-#     27     27  src:db:ScipDatabase:all()
-```
-
-**Options:**
-- `-n, --limit <n>` — Number of results (default: 30)
-- `-s, --scope <path>` — Limit to files matching path
-
-**Value:** Identify the symbols where a bug or breaking change would affect the most consumers. Hotspots deserve the most careful review and the most stable interfaces.
-
----
-
-#### `fan-in [symbol]`
-
-How many distinct files reference a symbol. Without an argument, shows the top N symbols by fan-in across the codebase.
-
-```bash
-scip-query fan-in ScipDatabase
-#    19 files  ScipDatabase
-#    16 files  ScipDatabase:all()
-#    13 files  ScipDatabase:isIgnored()
-
-scip-query fan-in -n 10
-#   files  symbol
-#   ─────  ──────
-#      31  ScipDatabase
-#      27  ScipDatabase:all()
-```
-
-**Options:**
-- `-n, --limit <n>` — Number of results for top mode (default: 30)
-- `-s, --scope <path>` — Limit to files matching path
-
-**Value:** High fan-in = widely depended upon. Changes to high fan-in symbols have large blast radius. These symbols should have stable interfaces and careful review.
-
----
-
-#### `fan-out [file]`
-
-How many external symbols a file references. Without an argument, shows the top N files by fan-out. High fan-out files are fragile — they depend on many things, so upstream changes are more likely to break them.
-
-```bash
-scip-query fan-out runtime/cli.ts
-#    23 symbols  src/runtime/cli.ts
-
-scip-query fan-out -n 10
-#   symbols  file
-#   ───────  ────
-#       68  src/queries/index.ts
-#       23  src/runtime/cli.ts
-```
-
-**Options:**
-- `-n, --limit <n>` — Number of results for top mode (default: 30)
-- `-s, --scope <path>` — Limit to files matching path
-
-**Value:** Identify files that are tightly coupled to the rest of the codebase. High fan-out files are the first to break when dependencies change.
-
----
-
-#### `bottlenecks`
-
-Find coupling hubs: symbols with both high fan-in (many consumers) AND high fan-out (many dependencies). Score = fan-in × fan-out. These are the most dangerous symbols to change — they sit at the intersection of many dependency paths.
-
-```bash
-scip-query bottlenecks -n 10
-#   score  fan-in  fan-out  symbol
-#   ─────  ──────  ───────  ──────
-#     136       2       68  src:queries:index
-#     124      31        4  src:storage:db:ScipDatabase
-```
-
-**Options:**
-- `-n, --limit <n>` — Number of results (default: 20)
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-fan-in <n>` — Minimum fan-in (default: 2)
-- `--min-fan-out <n>` — Minimum fan-out (default: 2)
-
-**Value:** These are the architectural pressure points. A symbol with fan-in=20 and fan-out=5 is both heavily depended upon and heavily dependent — changes to it are risky in both directions.
-
----
-
-#### `coupling [file1] [file2]`
-
-Measure coupling between two specific files (how many symbols they share), or find the most coupled file pairs across the codebase.
-
-```bash
-scip-query coupling storage/db.ts runtime/cli.ts
-# storage/db.ts ↔ runtime/cli.ts: 4 shared symbols
-
-scip-query coupling -n 10
-#   shared  file1 → file2
-#   ──────  ─────────────
-#        5  src/storage/db.ts → src/queries/stats.ts
-```
-
-**Options:**
-- `-n, --limit <n>` — Number of results for top mode (default: 20)
-- `-s, --scope <path>` — Limit to files matching path
-
-**Value:** Quantify how tightly two files are linked. High coupling between files that shouldn't be related is a design smell. Useful for identifying candidates for interface extraction.
-
----
-
-#### `cycles`
-
-Detect circular dependency chains between files. A cycle exists when file A depends on B, B on C, and C on A.
-
-```bash
-scip-query cycles
-# No circular dependencies found.
-
-scip-query cycles --scope src/services
-# Cycle 1 (3 files):
-#   src/services/auth.ts →
-#   src/services/user.ts →
-#   src/services/auth.ts (cycle)
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--max-depth <n>` — Maximum cycle depth (default: 10)
-
-**Value:** Circular dependencies make code harder to test, harder to understand, and harder to refactor. This command finds them so you can break the cycles.
-
----
-
-#### `deep-chains`
-
-Find the longest transitive dependency chains in the codebase. A chain A → B → C → D means A depends on B, B on C, C on D.
-
-```bash
-scip-query deep-chains -n 5 --min-depth 4
-# Chain 1 (depth 5):
-#   → src/runtime/cli.ts
-#   → src/queries/index.ts
-#   → src/queries/surface.ts
-#   → src/storage/db.ts
-#   → src/domain/types.ts
-```
-
-**Options:**
-- `-n, --limit <n>` — Number of chains to show (default: 10)
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-depth <n>` — Minimum chain depth (default: 3)
-
-**Value:** Long dependency chains mean changes at the bottom ripple through many layers. If chains are excessively deep, it may indicate that the architecture needs flattening or that intermediate layers aren't adding value.
-
----
-
-#### `by-kind <kind>`
-
-Find symbols by their SCIP symbol kind (class, interface, enum, function, struct, method, etc.).
-
-```bash
-scip-query by-kind class
-scip-query by-kind interface --scope src/types
-scip-query by-kind 68                          # kind number for Struct
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `-n, --limit <n>` — Number of results (default: 100)
-
-**Value:** Structural inventory — "how many classes do we have?", "where are all the interfaces?", "list every enum." Requires the indexer to populate the `kind` field.
-
----
-
-#### `kind-counts`
-
-Show a histogram of symbol kinds in the codebase.
-
-```bash
-scip-query kind-counts
-#   count  kind
-#   ─────  ────
-#      45  Class (9)
-#      23  Interface (27)
-#      12  Enum (16)
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-
-**Value:** Architectural overview — what types of symbols make up the codebase? Useful for understanding whether a codebase is class-heavy, function-heavy, interface-driven, etc.
-
----
-
-### Similarity & Consolidation
-
-These commands find duplication, redundancy, and extraction opportunities — the tools for de-bloating a codebase.
-
-#### `similar [symbol]`
-
-Find functions with similar callee fingerprints using TF-IDF weighted cosine similarity. Each callee is weighted by how rare it is across the codebase — two functions sharing a niche helper (`sendWelcomeEmail()`) score much higher than two functions sharing infrastructure callees (`db.all()`, `shortenSymbol()`). The "shared" list shown for each pair is the high-IDF (significant) intersection, not every shared callee.
-
-Without a symbol argument, finds the top N most similar pairs across the codebase. With a symbol, finds what's most similar to that specific function.
-
-```bash
-scip-query similar --min-similarity 0.5
-# 80% similar:
-#   A: by-kind  (src/queries/by-kind.ts)
-#   B: call-graph  (src/queries/call-graph.ts)
-#   Shared: ScipDatabase, db.all(), db.get(), db.isIgnored(), shortenSymbol()
-
-scip-query similar dead --min-similarity 0.3
-# 64% similar:
-#   A: dead  (src/queries/dead.ts)
-#   B: bottlenecks  (src/queries/bottlenecks.ts)
-#   Shared callees: db, ScipDatabase, db.all(), db.isIgnored(), shortenSymbol()
-#   Only in A: DeadOptions, DeadSummary, DeadSymbolResult
-#   Only in B: BottleneckResult
-```
-
-**Options:**
-- `--min-similarity <n>` — Minimum cosine similarity 0-1 (default: 0.4)
-- `-n, --limit <n>` — Number of results (default: 20)
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-callees <n>` — Minimum callees to consider a symbol (default: 4)
-- `--cross-file-only` — Only show cross-file pairs (skip same-file matches)
-
-**Value:** Finds "these two functions do basically the same thing" at scale. The shared callee list shows exactly what's duplicated. The unique callees show where they diverge — that's the parameterization point for a consolidated version.
-
----
-
-#### `similar-files [file]`
-
-Find files with similar dependency profiles using Jaccard similarity on their dependency sets. Files that import the same modules are structurally doing similar work.
-
-```bash
-scip-query similar-files --min-similarity 0.7
-# 100% similar:
-#   src/queries/symbols.ts
-#   src/queries/system.ts
-#   Shared deps (4): db.ts, types.ts, symbol-parser.ts, clean-signature.ts
-
-scip-query similar-files auth.controller.ts
-```
-
-**Options:**
-- `--min-similarity <n>` — Minimum Jaccard similarity 0-1 (default: 0.5)
-- `-n, --limit <n>` — Number of results (default: 20)
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-deps <n>` — Minimum dependencies on the smaller side (auto-tunes by default; pass to override)
-
-**Value:** Finds copy-paste file variants and structurally redundant modules. When two files have 90%+ dependency overlap, they're likely doing similar jobs and should share code or be merged.
-
----
-
-#### `similar-chains`
-
-Find end-to-end dependency flows through the codebase that are structurally similar but diverge at a few points. Uses edit distance on the file-node sequences.
-
-```bash
-scip-query similar-chains --min-similarity 0.5
-# ── Chain pair 1 (67% similar, 1 divergence point) ──
-#   Chain A: auth.controller.ts → auth.service.ts → user.repo.ts
-#   Chain B: org.controller.ts  → org.service.ts  → user.repo.ts
-#   Common suffix: user.repo.ts
-#   Divergence points (consolidation targets):
-#     [0] auth.controller.ts  ↔  org.controller.ts
-#     [1] auth.service.ts     ↔  org.service.ts
-```
-
-**Options:**
-- `--min-similarity <n>` — Minimum chain similarity 0-1 (default: 0.5)
-- `-n, --limit <n>` — Number of results (default: 15)
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-length <n>` — Minimum chain length (default: 3)
-- `--max-length <n>` — Maximum chain length (default: 8)
-
-**Value:** This is the most powerful consolidation finder. It detects "you have two parallel end-to-end mechanisms doing the same thing through different code paths." The divergence points are exactly where to extract a shared abstraction. Unlike function-level similarity, this catches architectural-level duplication.
-
----
-
-#### `extract-candidates`
-
-Find large functions with natural extraction seams — isolated groups of callees that form distinct clusters within a single function. When a function calls symbols A, B, C together and separately calls D, E, F, that's two potential extracted functions.
-
-```bash
-scip-query extract-candidates --min-loc 20 --min-callees 6
-# src/services/auth.ts:10-85  processAuth  (75 LOC, 12 callees)
-#   Cluster 1 (92% isolated, 4 callees):
-#     validateToken, parseJwt, checkExpiry, refreshToken
-#   Cluster 2 (88% isolated, 3 callees):
-#     formatUser, enrichProfile, cacheResult
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-loc <n>` — Minimum function LOC (default: 10)
-- `--min-callees <n>` — Minimum callees to analyze (default: 6)
-- `-n, --limit <n>` — Number of results (default: 20)
-
-**Value:** Identifies concrete extraction opportunities within large functions. Each cluster is a group of callees that are used together but independently from the rest of the function — a natural candidate for "Extract Method" refactoring. The isolation score tells you how cleanly the extraction would separate.
-
----
-
-### Impact & Planning
-
-#### `affected <symbol>`
-
-Full transitive closure of symbols that could break if this symbol changes. BFS through the mention graph at configurable depth.
-
-```bash
-scip-query affected login --max-depth 3
-#   ── Depth 1 ──
-#   src/controllers/auth.controller.ts  handleLogin
-#   src/__tests__/auth.test.ts  authTests
-#
-#   ── Depth 2 ──
-#   src/routes/index.ts  routes
-```
-
-**Options:**
-- `--max-depth <n>` — Maximum traversal depth (default: 5)
-- `-s, --scope <path>` — Limit to files matching path
-
-**Value:** "If I change this, what's the full blast wave?" Goes beyond direct `rdeps` to show consumers-of-consumers.
-
----
-
-#### `change-surface <file>`
-
-Pre-change briefing for a file: every exported symbol, consumer count, and blast-radius risk.
-
-```bash
-scip-query change-surface auth.service.ts
-# File: src/services/auth.service.ts
-# External consumers: 45
-#
-#   1-50   AuthService  [12 consumers] *** HIGH RISK ***
-#   5-20   login()      [8 consumers]  * medium risk *
-#   22-35  logout()     [0 consumers]
-```
-
-**Value:** One command before modifying any file. Shows what's exported, who uses it, and which symbols carry the largest downstream blast radius.
-
----
-
-#### `diff-impact`
-
-Compute affected symbols from the current git diff.
-
-```bash
-scip-query diff-impact
-scip-query diff-impact --base main
-# Changed files: 3
-# Changed symbols: 12
-# Affected consumer files: 28
-```
-
-**Options:**
-- `--base <ref>` — Git ref to diff against (default: HEAD)
-
-**Value:** Run before committing. Shows everything your changes affect and which consumer files sit downstream of the changed symbols.
-
----
-
-### De-bloating
-
-#### `drift [module]`
-
-Detect unused imports, layer violations, and dependency-pattern deviations.
-
-```bash
-scip-query drift --min-deviation 6
-#
-# src/services/legacy-auth.ts
-#   [LAYER] Imports from infra/ (infra/raw-sql.ts) — may cross architectural boundary
-#          app/ should not depend on infra/
-```
-
-**Options:**
-- `--min-deviation <n>` — Minimum sibling files before reporting unique dependency deviations (default: 5)
-
-**Value:** Finds unused imports, layer-policy violations, and files that don't follow their neighbors' dependency conventions. The outliers are either legacy code needing migration or intentional exceptions needing documentation.
-
----
-
-#### `wrapper-candidates`
-
-Find symbols only called by one consumer — potential premature abstractions.
-
-```bash
-scip-query wrapper-candidates --max-loc 15
-#   src/utils/format.ts:10-18  formatCurrency  (8 LOC)
-#     Only called by: formatInvoice  (fan-in: 12)
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--max-loc <n>` — Maximum LOC (default: 15)
-- `-n, --limit <n>` — Number of results (default: 30)
-
-**Value:** If a function is only called by one other function, it might be inlineable. The smaller it is, the stronger the signal.
-
----
-
-#### `passthrough-candidates`
-
-Find functions that forward to exactly one callee — pure indirection.
-
-```bash
-scip-query passthrough-candidates
-#   src/services/user.ts:5-10  getUser  (5 LOC)
-#     Forwards to: userRepo.findById  (src/repos/user.repo.ts)
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--max-loc <n>` — Maximum LOC (default: 15)
-- `-n, --limit <n>` — Number of results (default: 30)
-
-**Value:** Functions that just call one other function without adding logic. Either inline them or verify they serve a purpose (testing boundary, dependency inversion).
-
----
-
-#### `stale-abstractions`
-
-Find types, interfaces, and classes with 0-1 cross-file consumers.
-
-```bash
-scip-query stale-abstractions --min-loc 5
-#   src/types/deprecated.ts:1-25  OldUserType  (25 LOC, unused)
-#   src/interfaces/single.ts:1-15  ISingleUse  (15 LOC, 1 consumer)
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-loc <n>` — Minimum LOC (default: 3)
-- `-n, --limit <n>` — Number of results (default: 30)
-- `--include-low-confidence` — Include 1-consumer classes (usually encapsulation, not stale)
-
-**Value:** An interface with one implementation isn't an abstraction — it's indirection. Finds over-engineering.
-
----
-
-#### `complexity-hotspots`
-
-Composite complexity score per symbol: LOC x fan-in x fan-out.
-
-```bash
-scip-query complexity-hotspots -n 10
-#   score   LOC  fan-in  fan-out  callees  symbol
-#   ─────  ────  ──────  ───────  ───────  ──────
-#   101.7   541      47        0       16  types
-#    31.3   279      28        5       33  symbol-parser
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-loc <n>` — Minimum LOC (default: 10)
-- `-n, --limit <n>` — Number of results (default: 20)
-
-**Value:** The symbols most likely to contain bugs and be hardest to modify. High score = high LOC + many consumers + many dependencies.
-
----
-
-### Composite Reports
-
-#### `health`
-
-Single command that runs all analyses and produces a prioritized action list with a health score.
-
-```bash
-scip-query health
-# Codebase Health Score: 72/100
-# 54 files | 1501 symbols | 900 KB
-#
-# Findings:
-#   Dead code:          12 symbols (340 LOC)
-#   Similar pairs:      8
-#   Stale abstractions: 5
-#
-# Prioritized Actions:
-#   1. [low effort / high impact] 12 symbols with zero references — safe to delete (~340 LOC)
-#   2. [low effort / medium impact] 5 types with 0-1 consumers — premature abstraction
-#   3. [medium effort / medium impact] 8 pairs with >60% callee overlap — consolidation candidates
-
-scip-query health --json    # JSON output for programmatic use
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--json` — Output as JSON
-
-**Value:** The one command to rule them all. Runs every cleanup analysis, scores the codebase, and tells you exactly what to fix and in what order.
-
----
-
-#### `convergence <symbol1> <symbol2>`
-
-Given two similar functions (from `similar`), show what a consolidated version would look like.
-
-```bash
-scip-query convergence bottlenecks hotspots
-# 82% callee overlap
-#
-#   A: bottlenecks  (src/queries/bottlenecks.ts, 68 LOC)
-#   B: hotspots     (src/queries/hotspots.ts, 54 LOC)
-#
-#   Shared callees (9): ScipDatabase, db.all(), db.isIgnored(), ...
-#   Unique to A (1): BottleneckResult
-#   Unique to B (1): HotspotResult
-#
-#   Strategy: Create a shared function with the 9 common callees.
-#   Pass the 2 divergent callees as parameters or strategy callbacks.
-```
-
-**Value:** Turns "these two functions are similar" into a concrete refactoring prescription.
-
----
-
-### Source & Analysis
-
-#### `code <symbol>`
-
-Read the source code for a symbol, bounded to its definition range.
-
-```bash
-scip-query code shortenSymbol
-scip-query code shortenSymbol -C 5    # 5 extra lines of context
-```
-
-**Options:**
-- `-C, --context <n>` — Extra lines above/below the definition (default: 0)
-
-**Value:** Read source without leaving the terminal. Language-agnostic — just reads the file at the line range from the index.
-
----
-
-#### `complexity <symbol>`
-
-Per-symbol complexity analysis: source-level branch counting + index-level metrics.
-
-```bash
-scip-query complexity login
-#   LOC:                  41
-#   Branches:             8
-#   Cyclomatic estimate:  9
-#   Callees:              5
-#   Fan-in:               12
-#   Fan-out:              3
-```
-
-**Value:** Combines source-level analysis (branch counting via language-aware regex) with graph-level metrics (fan-in, fan-out, callee count) for a complete complexity picture.
-
----
-
-#### `dataflow <symbol>`
-
-Reference-level dataflow: where data around a symbol comes from and where it goes.
-
-```bash
-scip-query dataflow login
-#   ═══ DEFINED AT ═══
-#     src/auth.service.ts:5
-#   ═══ USED AT ═══
-#     src/auth.controller.ts:15  in handleAuth
-#   ═══ PRODUCERS (feeds into this) ═══
-#     validateInput, formatName
-#   ═══ CONSUMERS (this feeds into) ═══
-#     sendEmail, logAudit
-```
-
-**Value:** Shows the data flow context: what other symbols are referenced alongside this one, what feeds in, what consumes it.
-
----
-
-#### `slice <symbol>`
-
-Reference-level program slicing: what affects a symbol (backward) or what it affects (forward).
-
-```bash
-scip-query slice login               # backward: what feeds in
-scip-query slice login --forward     # forward: what this feeds into
-```
-
-**Options:**
-- `--forward` — Forward slice instead of backward (default: backward)
-- `--depth <n>` — Max transitive depth for backward slice (default: 3)
-
-**Value:** Backward slice shows inputs/dependencies. Forward slice shows outputs/effects. Useful for tracing data flow through error handling and concurrency paths.
-
----
-
-### Additional Cleanup
-
-#### `redundant-reexports`
-
-Find barrel file re-exports that nobody imports through.
-
-```bash
-scip-query redundant-reexports
-# No redundant re-exports found.
-```
-
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `-n, --limit <n>` — Number of results (default: 30)
-
-**Value:** Finds dead entries in inactive barrel files. Live barrels are skipped so shared entry surfaces like package roots and CLI registries do not show up as false positives.
-
----
+| Command | Description | Options |
+|---|---|---|
+| `files <pattern>` | Find files matching a pattern | - |
+| `symbols <file>` | List symbols defined in a file (with line ranges + signatures) | - |
+| `methods <className>` | List methods of a class (with line ranges) | - |
+| `refs <symbol>` | Find all files referencing a symbol | `--full` |
+| `trace <symbol>` | Trace a symbol: definition + all references | `--full` |
+| `deps <file>` | Files this file depends on (internal) | - |
+| `rdeps <file>` | Files that depend on this file/module | - |
+| `system <module>` | Full module map: files, symbols, deps in/out | - |
+| `surface <module>` | What symbols consumers actually use from this module | - |
+| `imports <file>` | What symbols does this file import? | `--full` |
+| `imported-by <symbol>` | Which files import this symbol? | - |
+| `outline <file>` | Tree view of symbols in a file (using nesting hierarchy) | - |
+| `members <symbol>` | All children of a symbol (methods, fields, nested types) | - |
+| `by-kind <kind>` | Find symbols by SCIP kind (class, interface, enum, function, etc.) | `-s, --scope <path>`<br>`-n, --limit <n>` |
+| `kind-counts` | Histogram of symbol kinds in the codebase | `-s, --scope <path>` |
+| `hierarchy <symbol>` | Show a symbol's ancestry chain (method → class → module) | - |
+| `code <symbol>` | Read the source code for a symbol (bounded to its definition range) | `-C, --context <n>` |
+| `dataflow <symbol>` | Reference-level dataflow: definition sites, usage sites, producers, consumers | `--full` |
+| `slice <symbol>` | Reference-level program slice: what affects this (backward) or what this affects (forward) | `--forward`<br>`--depth <n>`<br>`--full` |
+
+### Cleanup
+
+| Command | Description | Options |
+|---|---|---|
+| `dead [scope]` | Find dead code and file-internal symbols (no cross-file consumers) | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full` |
+| `unused-imports <file>` | Find imports not referenced in the same file | `--full` |
+| `isolated` | Find completely orphaned symbols (no references at all) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full` |
+| `similar [symbol]` | Find heuristic function similarity candidates from callee fingerprints | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-callees <n>`<br>`--cross-file-only`<br>`--full` |
+| `similar-files [file]` | Find heuristic similar-file candidates from dependency profiles | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-deps <n>` |
+| `similar-chains` | Find heuristic similar-chain candidates from dependency flows | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-length <n>`<br>`--max-length <n>` |
+| `extract-candidates` | Find heuristic extraction candidates from isolated callee clusters | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-callees <n>`<br>`-n, --limit <n>`<br>`--full` |
+| `drift [module]` | Detect heuristic drift candidates: unused imports, layer violations, and pattern deviations | `--min-deviation <n>`<br>`--full` |
+| `wrapper-candidates` | Find heuristic wrapper candidates only called by one consumer | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full` |
+| `passthrough-candidates` | Find heuristic passthrough candidates that forward to one callee | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full` |
+| `stale-abstractions` | Find heuristic stale abstraction candidates with 0-1 consumers | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--include-low-confidence`<br>`--full` |
+| `complexity-hotspots` | Find heuristic complexity hotspot candidates from LOC x fan-in x fan-out | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full` |
+| `convergence <symbol1> <symbol2>` | Show what a consolidated version of two similar functions would look like | `--full` |
+| `redundant-reexports` | Find barrel re-exports that nobody imports through | `-s, --scope <path>`<br>`-n, --limit <n>` |
+| `similar-signatures` | Find functions with near-identical type signatures (same shape) | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full` |
+
+### Graph
+
+| Command | Description | Options |
+|---|---|---|
+| `hotspots` | Most-referenced symbols in the codebase (choke points) | `-n, --limit <n>`<br>`-s, --scope <path>` |
+| `fan-in [symbol]` | How many files reference a symbol (or top fan-in across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>` |
+| `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | `-n, --limit <n>`<br>`-s, --scope <path>` |
+| `coupling [file1] [file2]` | Coupling between two files, or top coupled pairs in codebase | `-n, --limit <n>`<br>`-s, --scope <path>` |
+| `cycles` | Detect circular dependency chains between files | `-s, --scope <path>`<br>`--max-depth <n>` |
+| `bottlenecks` | Find coupling hubs: high fan-in AND high fan-out | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-fan-in <n>`<br>`--min-fan-out <n>`<br>`--full` |
+| `deep-chains` | Find the longest transitive dependency chains | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>` |
+| `call-graph <symbol>` | Show incoming callers and outgoing callees for a symbol | `--full` |
+
+### Impact
+
+| Command | Description | Options |
+|---|---|---|
+| `affected <symbol>` | Transitive closure of symbols that could break if this symbol changes | `--max-depth <n>`<br>`-s, --scope <path>` |
+| `change-surface <file>` | Pre-change briefing: exports, consumers, and blast-radius risk | `--full` |
+| `diff-impact` | Compute changed symbols and downstream consumers from current git diff | `--base <ref>` |
 
-#### `similar-signatures`
+### Health
 
-Find functions with near-identical type signatures (same parameter types and return type).
+| Command | Description | Options |
+|---|---|---|
+| `health` | Composite codebase health report with prioritized action list | `-s, --scope <path>`<br>`--full`<br>`--json` |
+| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | `--full` |
 
-```bash
-scip-query similar-signatures --min-loc 5
-#   Signature: (email: string): Promise<Token>  (2 functions)
-#     src/auth.ts:5-20   login   (15 LOC)
-#     src/auth.ts:22-37  signup  (15 LOC)
-```
+### Maintenance
 
-**Options:**
-- `-s, --scope <path>` — Limit to files matching path
-- `--min-loc <n>` — Minimum LOC per function (default: 3)
-- `-n, --limit <n>` — Number of groups (default: 20)
+| Command | Description | Options |
+|---|---|---|
+| `install-skills` | Install skills (concrete-plan, scip-explore, scip-debloat, scip-verify, scip-language-playbook) into Claude Code and Codex | - |
+| `check-deps` | Check whether scip-query and the detected language indexers are actually runnable | - |
+| `init` | Create a .scipquery.json config file for this project | - |
+| `watch` | Watch for file changes and reindex automatically | `--debounce <ms>`<br>`--cooldown <ms>` |
+| `status` | Show index status for this project | - |
 
-**Value:** Different signal from callee similarity — catches "same interface, different implementation" even when the internal logic differs completely.
+<!-- END GENERATED COMMAND REFERENCE -->
 
----
 
 ## Programmatic API