scip-query 0.7.1 → 0.8.0

package/README.md

@@ -1,1228 +1,267 @@
-# scip-query
+<p align="center">
+  <img src="docs/assets/scip-query-logo.png" alt="scip-query logo" width="120">
+</p>
 
-Language-agnostic code intelligence CLI powered by [SCIP](https://github.com/sourcegraph/scip) indexes. Index a codebase once, then ask direct questions about symbols, references, dependencies, dead code, similarity, coupling, impact, and health without keeping an IDE or language server running.
+<h1 align="center">scip-query</h1>
 
-Works with every language that has a SCIP indexer: TypeScript, JavaScript, Vue, Java, Scala, Kotlin, Rust, Python, Ruby, Go, C/C++, C#, Visual Basic, Dart, PHP.
+<p align="center">
+  <strong>Structural code intelligence for AI agents and engineers.</strong>
+</p>
 
-## Purpose
+<p align="center">
+  Ask compiler-backed questions about how a codebase is wired together, find what's rotting, and delete it with a compiler proof in hand.
+</p>
 
-`scip-query` exists to make codebase understanding operational. A large codebase is a collection of source files, symbols, and dependency paths that people need to change without accidentally breaking users. This project turns compiler-produced code intelligence into terminal commands that answer the questions engineers and agents ask before they edit:
+<p align="center">
+  <a href="https://www.npmjs.com/package/scip-query"><img alt="npm version" src="https://img.shields.io/npm/v/scip-query.svg"></a>
+  <a href="https://www.npmjs.com/package/scip-query"><img alt="npm downloads" src="https://img.shields.io/npm/dm/scip-query.svg"></a>
+  <a href="package.json"><img alt="Node version" src="https://img.shields.io/node/v/scip-query.svg"></a>
+  <a href="https://www.apache.org/licenses/LICENSE-2.0"><img alt="License" src="https://img.shields.io/npm/l/scip-query.svg"></a>
+</p>
 
-- What is defined here?
-- Who uses this symbol?
-- What depends on this file?
-- What changes if I modify this API?
-- Which cleanup findings are backed by real reference evidence?
-- Where is the architecture drifting, duplicating work, or hiding complexity?
+<p align="center">
+  <a href="https://www.npmjs.com/package/scip-query"><img alt="Install from npm" src="https://img.shields.io/badge/install-npm-cb3837?style=for-the-badge&logo=npm&logoColor=white"></a>
+  <a href="docs/AGENT_GUIDE.md"><img alt="Agent guide" src="https://img.shields.io/badge/agent-guide-2563eb?style=for-the-badge"></a>
+  <a href="docs/COMMAND_REFERENCE.md"><img alt="Command reference" src="https://img.shields.io/badge/command-reference-111827?style=for-the-badge"></a>
+</p>
 
-The vision is a reliable code-intelligence layer for both humans and coding agents: fast enough to use during ordinary development, accurate enough to trust for planning, and explicit about confidence when an analysis moves beyond compiler-backed facts.
+`scip-query` answers precise questions about how a codebase is wired together — where a symbol is defined, who references it, what calls it, what breaks if it changes — and turns those answers into something rarer: **cleanup you can trust**. Findings are ranked by evidence quality, validated against your repo's own git history, and (for deletions) proven safe by your own compiler before you touch anything.
 
-## Problems It Solves
+Works with every language that has a [SCIP](https://github.com/sourcegraph/scip) indexer: TypeScript, JavaScript, Vue, Java, Scala, Kotlin, Rust, Python, Ruby, Go, C/C++, C#, Visual Basic, Dart, PHP.
 
-- **Navigation without IDE state.** Query definitions, references, outlines, members, call graphs, and source snippets from a terminal or automation loop.
-- **Change planning.** Use `affected`, `change-surface`, and `diff-impact` to identify downstream consumers before and after a change.
-- **Architecture visibility.** Use `deps`, `rdeps`, `system`, `surface`, `coupling`, `cycles`, and `deep-chains` to see how modules actually relate.
-- **Codebase cleanup.** Use `dead`, `stale-abstractions`, `wrapper-candidates`, `passthrough-candidates`, `similar`, `similar-signatures`, `extract-candidates`, and `drift` to find removal or consolidation opportunities.
-- **Health reporting.** Use `health` to aggregate cleanup signals into one prioritized report instead of running dozens of commands by hand.
-- **Agent workflows.** Install the bundled Codex/Claude skills so agents can explore, plan, de-bloat, and verify changes with a consistent command vocabulary.
-
-## Accuracy Model
-
-A SCIP index is a database-shaped record of code facts produced by language-aware indexers: the source files they read, the symbols they define, and the references they resolve. Because these facts come from compilers, type checkers, or language servers, direct definition and reference queries are much stronger evidence than text search.
-
-`scip-query` separates three kinds of evidence:
-
-- **Compiler-backed facts** come from the SCIP database. Commands like `symbols`, `refs`, `trace`, `deps`, `rdeps`, `surface`, and most symbol-level counts start here.
-- **Semantic augmentation** adds language-specific checks when available. TypeScript projects use `ts-morph` to verify references, import usage, callers, callees, and signatures when SCIP alone is incomplete.
-- **Source-backed heuristics** use parsed source text or ASTs to keep higher-level cleanup commands useful when an indexer omits call-site details. These findings are designed as investigation leads, not blind deletion instructions.
-
-The goal is not to replace compiler facts with regexes. The goal is to use the strongest available evidence first, fall back only when needed, and keep cleanup commands conservative enough that speed does not trade away accuracy.
-
-## Workflows
-
-For goal-oriented usage guides (not just command reference), see **[Agent Guide](docs/AGENT_GUIDE.md)**:
-
-- **[Understand a system](docs/AGENT_GUIDE.md#workflow-1-understand-a-system-before-making-changes)** — map a module, trace symbols, check blast radius
-- **[Write an implementation plan](docs/AGENT_GUIDE.md#workflow-2-write-a-concrete-implementation-plan)** — identify contracts, map dependencies, find reusable code
-- **[De-bloat a codebase](docs/AGENT_GUIDE.md#workflow-3-clean-up-and-de-bloat-a-codebase)** — prioritized cleanup from dead code to pattern drift
-- **[Assess code quality](docs/AGENT_GUIDE.md#workflow-4-assess-code-quality-and-risk)** — health score, complexity hotspots, coupling risks
-- **[Verify change impact](docs/AGENT_GUIDE.md#workflow-5-understand-impact-after-making-changes)** — diff impact, transitive blast radius, consumer blast radius
-
-Historical implementation plans and completed cleanup notes live in [`docs/plans/`](docs/plans/).
-
-## Install From npm
-
-Install the published CLI globally from npm:
+## Install
 
 ```bash
 npm install -g scip-query@latest
-scip-query --version
-```
-
-You can also run it without a global install:
-
-```bash
-npx scip-query@latest --version
-npx scip-query@latest reindex
-```
-
-The npm package is published at [`scip-query`](https://www.npmjs.com/package/scip-query). `@latest` should resolve to the newest published version.
-
-## Quick Start
-
-```bash
-# Install
-npm install -g scip-query@latest
-scip-query --version
-scip-query check-deps                # verify optional indexers and parser support
-scip-query install-skills            # install built-in Codex/Claude skills
-
-# Index your project (auto-detects language)
-scip-query reindex
-
-# Start querying
-scip-query stats
-scip-query health                        # full codebase health report
-scip-query symbols src/auth.service.ts
-scip-query refs login
-scip-query affected login                # transitive blast radius
-scip-query dead --min-loc 10
-scip-query similar --min-similarity 0.5
-scip-query diff-impact                   # what did my changes affect?
-```
-
-## Prerequisites
-
-- **Node.js** >= 18
-- **scip** CLI - [Install from releases](https://github.com/sourcegraph/scip/releases) (converts index data to SQLite)
-- A language-specific SCIP indexer for your project:
-
-| Language | Indexer | Install |
-|---|---|---|
-| TypeScript / JavaScript / Vue | scip-typescript | `npm install -g @sourcegraph/scip-typescript` |
-| Java / Scala / Kotlin | scip-java | [releases](https://github.com/sourcegraph/scip-java/releases) |
-| Rust | rust-analyzer | Ships with rust-analyzer (`rust-analyzer scip`) |
-| Python | scip-python-plus | `npm install -g scip-python-plus` |
-| Go | scip-go | `go install github.com/sourcegraph/scip-go@latest` |
-| Ruby | scip-ruby | [releases](https://github.com/sourcegraph/scip-ruby/releases) |
-| C / C++ | scip-clang | [releases](https://github.com/sourcegraph/scip-clang/releases) |
-| C# / VB | scip-dotnet | [releases](https://github.com/sourcegraph/scip-dotnet/releases) |
-| Dart | scip-dart | [releases](https://github.com/nicovince/scip-dart/releases) |
-| PHP | scip-php | [releases](https://github.com/nicovince/scip-php/releases) |
-
-For Python, the npm package is `scip-python-plus`. Depending on which version you installed, the executable on your `PATH` may be `scip-python`, `scip-python-plus`, or both. `scip-query` accepts either name.
-
-Vue single-file components (`.vue`) are handled by the JavaScript/TypeScript indexer. `scip-query` extracts the `<script>` block (or `<script setup>`, picking the language from the `lang=` attribute) and parses it as TS/JS so symbol, reference, and import queries cover Vue components alongside regular `.ts`/`.js` files.
-
-## How It Works
-
-1. A SCIP indexer analyzes your source code using the actual compiler/type checker and produces a `index.scip` protobuf file containing symbols, definitions, and references.
-2. The `scip` CLI converts the protobuf to a SQLite database (`index.db`).
-3. `scip-query` runs SQL queries and language-aware source augmentation against that database to answer questions about your codebase.
-
-Because the index comes from real language tooling, direct symbol, definition, and reference queries are precise, not grep-based approximations. When a language index is missing enough call-site detail for higher-level analyses, `scip-query` can fall back to AST parsing, semantic providers, and identifier recovery so those commands stay useful while still reporting conservative results.
-
-## Configuration
-
-### Per-project config
-
-Run `scip-query init` to generate a `.scipquery.json` in your project root:
-
-```json
-{
-  "languages": ["typescript"],
-  "watch": {
-    "enabled": false,
-    "debounceMs": 30000,
-    "cooldownMs": 60000
-  },
-  "indexer": {
-    "typescript": {
-      "pnpmWorkspaces": true
-    }
-  }
-}
-```
-
-### Environment variables
-
-| Variable | Purpose |
-|---|---|
-| `SCIP_QUERY_PROJECT_ROOT` | Override the project root directory |
-| `SCIP_QUERY_INDEX_DB` | Override the SQLite database path |
-| `SCIP_QUERY_INDEX_SCIP` | Override the SCIP protobuf path |
-| `SCIP_QUERY_CACHE_DIR` | Override the cache directory |
-
-### Index storage
-
-By default, indexes are stored in `~/.cache/scip-query/projects/<hash>/` (following XDG conventions). This keeps your project directory clean. Override with the `dbPath` field in `.scipquery.json` or the `SCIP_QUERY_CACHE_DIR` environment variable.
-
-### Gitignore integration
-
-All query results are filtered through your project's `.gitignore`. Build artifacts (`dist/`, `target/`, `__pycache__/`), dependency directories (`node_modules/`, `vendor/`), and virtual environments (`.venv/`) are automatically excluded. If no `.gitignore` exists, sensible defaults are applied.
-
----
-
-## Command Reference
-
-### Index Management
-
-#### `reindex`
-
-Index (or re-index) the codebase. Auto-detects which languages are present, runs the appropriate SCIP indexer, and converts the output to SQLite.
-
-```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.
-
-```bash
-scip-query init
-```
-
----
-
-### 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
+scip-query reindex          # index the current project
+scip-query health           # see where you stand
 ```
 
-**Value:** Complete module overview in one command. Shows the module's interface, its internal structure, and its position in the dependency graph.
+Or without a global install: `npx scip-query@latest reindex`.
 
----
+## The Problem
 
-#### `surface <module>`
+Two problems, actually.
 
-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.
+**Agents lose the thread.** A codebase is files connected by definitions, references, imports, calls, and dependency paths. Reading files gives local text, not verified structure. Search finds matching words, not real references. Before editing one unit you need to know what it is, who uses it, and what depends on it — with evidence, not vibes.
 
-```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()
-```
+**AI-generated code rots in specific ways.** Agents re-implement helpers they didn't know existed. They leave parallel half-wired implementations behind. They add parameters and options "for later" that never come. And the standards docs you write *for* them drift away from the code — so the next agent implements against a dead spec. Generic linters don't see any of this, because none of it is visible in a single file.
 
-**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.
+`scip-query` attacks both: structural questions with evidence-backed answers, and rot detectors tuned to how code actually decays — each one validated, and each one honest about its own confidence.
 
----
+## Three Sources of Evidence
 
-#### `imports <file>`
+Most code tools have one lens. `scip-query` has three, and tells you which one each answer came from:
 
-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
+```mermaid
+flowchart LR
+  A["Reference graph<br/>(SCIP: compilers & language servers)"] --> D["scip-query"]
+  B["Change graph<br/>(git history: co-change, churn, fix density)"] --> D
+  C["Verification oracles<br/>(tsc / cargo check / ts-morph)"] --> D
+  D --> E["Evidence-ranked answers<br/>graph-fact · change-graph · heuristic · compiler-verified"]
 ```
 
----
-
-#### `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
-```
+1. **The reference graph** — who defines, references, calls, imports what. Built from SCIP indexes produced by real compilers and language servers, not text search.
+2. **The change graph** — what git history knows that no compiler can: files that always change together without any dependency edge (one concept scattered across artifacts), churn-weighted complexity (gnarly code nobody touches costs nothing), and whether flagged files actually attract fix commits.
+3. **Verification oracles** — your own toolchain as ground truth. Deletion plans are applied in a throwaway worktree and run through `tsc`/`cargo check` before being stamped `COMPILER-VERIFIED`. The tool even audits *itself*: `self-audit` scores its cheap evidence paths against the TypeScript compiler and reports precision/recall as a tracked number.
 
-**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]`)
+## At a Glance
 
-**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.
+| Ask this | Run this |
+|---|---|
+| What is in this module? | `scip-query system src/auth` |
+| Who uses this symbol? | `scip-query trace login` |
+| What might break if I change it? | `scip-query affected login` |
+| Everything I need before editing this | `scip-query plan-context login` |
+| What did my git diff affect? | `scip-query diff-impact` |
+| How healthy is this codebase, really? | `scip-query health` |
+| What can I delete — *prove it* | `scip-query cleanup-plan --verify` |
+| What new code duplicates old code? | `scip-query recent-duplicates` |
+| Which docs lie about the code now? | `scip-query doc-drift` |
+| What changes together but isn't linked? | `scip-query co-change` |
+| Gate an agent's diff before merging | `scip-query diff-gate` |
+| Did the findings get worse? (CI gate) | `scip-query health --baseline` |
 
----
+## Cleaning Up AI-Generated Code
 
-#### `deep-chains`
+This is the workflow the tool is built around. Each detector targets a specific way AI-assisted development rots a codebase:
 
-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.
+**1. Find the echoes.** Agents re-implement helpers they didn't know existed. `recent-duplicates` makes similarity *directional* using git file ages — which side is the established original, which is the recent echo:
 
-```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
+91%  ECHO  src/components/ProjectCardVisual.tsx  ProjectCardVisual()  (added 62 commits ago)
+     duplicates established  src/pages/HomePage.tsx  RecentProjectRow()
+100% TWIN  src/workflows/a.ts ensureAccessible() / src/workflows/b.ts ensureAccessible()
+     (both new — one agent session duplicated itself; consolidate before they diverge)
 ```
 
-**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.
-
----
+**2. Catch your standards docs lying.** If you keep in-repo standards for agents to read before implementing, a stale standard is worse than none. `doc-drift` reads every doc's file citations *and* its co-change history, then flags docs whose code moved on without them — including **broken references** to files that no longer exist:
 
-#### `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
+staleness 94  product/domain-model.md
+  BROKEN REFERENCE: cites src/api/servicePlans.ts — that file no longer exists
+  22 change(s) since doc update  src/workflows/serviceTasks.ts  (referenced by doc)
 ```
 
-**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.
+**3. Delete with proof.** `cleanup-plan` runs dead-code analysis to a *fixpoint* — deleting batch 0 makes batch 1 dead, and the plan shows the cascade. `--verify` applies each batch in a throwaway git worktree and runs your own compiler (differentially, so pre-existing errors don't drown the signal):
 
-```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
+── Batch 0: deletable now (graph-fact, 67 LOC) ──
+── Batch 1: dead once batch 0 lands (cascade, 21 LOC) ──
+Batch 0: COMPILER-VERIFIED
 ```
 
-**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.
+When verification *fails*, the errors name the exact references the static evidence missed — that failure has caught real detector mistakes and stopped build-breaking deletions.
 
----
+**4. Trim speculative generality.** `unused-params` finds trailing parameters no body ever uses (the classic "options for later"), scoped to removals that are type-safe by construction.
 
-#### `extract-candidates`
+**5. Surface hidden coupling.** `co-change` finds file pairs that repeatedly change in the same commits with *no* dependency edge — schema ↔ generated inventory ↔ doc triangles, backend schemas ↔ frontend stores, `.env.example` ↔ its parser. The reference graph cannot see these; the change graph can.
 
-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.
+**6. Gate every diff.** `diff-gate` runs the whole suite scoped to what a change *introduces* — echoes of established code, missing co-change partners, docs that cite the changed files, fresh unused params, new dead symbols, baseline regressions — in seconds, exit-code friendly, with a remediation per finding an agent can act on without human triage:
 
-```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
+[co-change-partner] schema.prisma changed, but scripts/scope-inventory.mjs did not — they change together 12x (86% of the time)
+  -> Update scripts/scope-inventory.mjs alongside this change, or confirm the coupling no longer holds.
 ```
 
-**Options:**
-- `--max-depth <n>` — Maximum traversal depth (default: 5)
-- `-s, --scope <path>` — Limit to files matching path
+**7. Ratchet it in CI.** `health --write-baseline` snapshots finding identities into a committable file; `health --baseline` exits 1 on any *new* finding. "Don't get worse" is an objective gate that no score arithmetic can game.
 
-**Value:** "If I change this, what's the full blast wave?" Goes beyond direct `rdeps` to show consumers-of-consumers.
+Before any edit, `plan-context <target>` bundles the structural picture — definitions, references, call graph, blast radius — plus a HISTORY section: churn, fix-commit density, and the files that usually change together with the target ("editing this usually means editing these").
 
----
+## A Health Score You Can Argue With
 
-#### `change-surface <file>`
+`scip-query health` refuses to be a vanity number:
 
-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]
 ```
+Codebase Health Score: 95/100
+  Risk:    95/100  (validated predictors: graph facts + change graph)
+  Hygiene: 100/100 (tidiness candidates)
 
-**Value:** One command before modifying any file. Shows what's exported, who uses it, and which symbols carry the largest downstream blast radius.
-
----
+Score Breakdown (100 minus the following):
+  - 5  hidden-coupling: 5 co-changing pair(s) without a dependency edge
 
-#### `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
+Axes:
+  Deletable:            1,027 LOC across 89 symbols
+  Change amplification: 5 files/commit median, 23 p90
+  Evidence quality:     5 graph-fact, 150 heuristic, 0 user-suppressed
+  Validation:           flagged fix-density 0.12 vs baseline 0.20 (0.6x)
 ```
 
-**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]`
+- **Risk vs. Hygiene** are separate claims: risk components are empirically fix-predictive; hygiene components are tidiness. Blending them is how scores become meaningless.
+- **Every deduction is itemized** — the scalar is auditable, not vibes.
+- **The validation axis is a falsifiability loop**: it measures whether flagged files actually attract more fix commits than the rest *in your repo*, per detector. On some codebases passthrough findings predict fixes at 6× baseline; on others they're noise — the tool reports which, instead of assuming.
+- **Suppressions are data**: every `// scip-query: ignore-*` comment is a precision label, counted and reported.
 
-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.
+## Accuracy Model
 
----
+Evidence tiers are kept explicit, strongest first:
 
-#### `wrapper-candidates`
+1. **Compiler-backed facts** from the SCIP database (`trace`, `refs`, `deps`, `outline`, ...).
+2. **Semantic augmentation** via `ts-morph` for TypeScript — verified references, callers, callees when SCIP alone is incomplete.
+3. **Source-backed heuristics** (AST/text) for cleanup signals. Always labeled: *"these are candidates, not exact compiler facts."*
+4. **Compiler verification** for deletions — the only tier that earns the word "safe."
 
-Find symbols only called by one consumer — potential premature abstractions.
+And because accuracy you don't measure is a feeling, `self-audit` samples symbols and scores the cheap paths against the TypeScript compiler:
 
-```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)
+references  precision 1.0  recall 0.9   (the cheap path doesn't fabricate; it occasionally misses)
 ```
 
-**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).
+Heuristic detectors carry guardrails learned from real codebases: published `package.json` surfaces are exempt from "unused" advice, `contracts/` and `types/` modules are exempt from "definer never uses it," test files and component-sibling files don't count as hidden coupling, and changelogs-by-policy aren't drift.
 
----
+## Agent Skills
 
-#### `stale-abstractions`
+`scip-query install-skills` symlinks ready-made skills into Claude Code, Codex, and shared agent roots — workflows for exploring (`scip-explore`), debloating (`scip-debloat`), maintainability review (`scip-maintainability`), claim verification (`scip-verify`), per-language guidance (`scip-language-playbook`), and grounded planning (`concrete-plan`).
 
-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.
+## Quick Start
 
 ```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.
+scip-query check-deps        # verify indexers are runnable
+scip-query install-skills    # optional: agent skills
+scip-query reindex
 
-```bash
+scip-query stats
+scip-query system src/auth
+scip-query plan-context login
 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
+scip-query cleanup-plan --verify
+scip-query health --write-baseline   # start the ratchet
 ```
 
-**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.
-
----
+## Prerequisites
 
-#### `slice <symbol>`
+- Node.js >= 18
+- `scip` CLI, from [Sourcegraph SCIP releases](https://github.com/sourcegraph/scip/releases)
+- A language-specific SCIP indexer for your project
 
-Reference-level program slicing: what affects a symbol (backward) or what it affects (forward).
+| Language | Indexer | Install |
+|---|---|---|
+| TypeScript / JavaScript / Vue | scip-typescript | `npm install -g @sourcegraph/scip-typescript` |
+| Java / Scala / Kotlin | scip-java | [releases](https://github.com/sourcegraph/scip-java/releases) |
+| Rust | rust-analyzer | Ships with rust-analyzer: `rust-analyzer scip` |
+| Python | scip-python-plus | `npm install -g scip-python-plus` |
+| Go | scip-go | `go install github.com/sourcegraph/scip-go@latest` |
+| Ruby | scip-ruby | [releases](https://github.com/sourcegraph/scip-ruby/releases) |
+| C / C++ | scip-clang | [releases](https://github.com/sourcegraph/scip-clang/releases) |
+| C# / VB | scip-dotnet | [releases](https://github.com/sourcegraph/scip-dotnet/releases) |
+| Dart | scip-dart | [releases](https://github.com/nicovince/scip-dart/releases) |
+| PHP | scip-php | [releases](https://github.com/nicovince/scip-php/releases) |
 
-```bash
-scip-query slice login               # backward: what feeds in
-scip-query slice login --forward     # forward: what this feeds into
-```
+For Python, the executable may be `scip-python`, `scip-python-plus`, or both. `scip-query` accepts either name.
 
-**Options:**
-- `--forward` — Forward slice instead of backward (default: backward)
-- `--depth <n>` — Max transitive depth for backward slice (default: 3)
+Vue single-file components are handled through the JavaScript/TypeScript indexer. `scip-query` also extracts the `<script>` or `<script setup>` block so symbol, reference, and import queries cover Vue components alongside regular `.ts` and `.js` files.
 
-**Value:** Backward slice shows inputs/dependencies. Forward slice shows outputs/effects. Useful for tracing data flow through error handling and concurrency paths.
+## How It Works
 
----
+1. A SCIP indexer analyzes source code with the actual compiler, type checker, or language server and produces `index.scip`.
+2. The `scip` CLI converts that protobuf file to a SQLite database: `index.db`.
+3. `scip-query` runs SQL queries, language-aware source augmentation, and git-history analysis against it.
 
-### Additional Cleanup
+By default, indexes live in `~/.cache/scip-query/projects/<hash>/`, keeping project directories clean. Override paths with `.scipquery.json` or `SCIP_QUERY_*` environment variables.
 
-#### `redundant-reexports`
+## Configuration
 
-Find barrel file re-exports that nobody imports through.
+Run this in a project root:
 
 ```bash
-scip-query redundant-reexports
-# No redundant re-exports found.
+scip-query init
 ```
 
-**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.
-
----
-
-#### `similar-signatures`
-
-Find functions with near-identical type signatures (same parameter types and return type).
+It creates `.scipquery.json`:
 
-```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)
+```json
+{
+  "languages": ["typescript"],
+  "watch": {
+    "enabled": false,
+    "debounceMs": 30000,
+    "cooldownMs": 60000
+  },
+  "indexer": {
+    "typescript": {
+      "pnpmWorkspaces": true
+    }
+  }
+}
 ```
 
-**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)
-
-**Value:** Different signal from callee similarity — catches "same interface, different implementation" even when the internal logic differs completely.
-
----
-
-## Programmatic API
-
-Every CLI command is also a TypeScript function. The `queries` namespace exports cover all of them — including the `top*` variants of `fan-in`, `fan-out`, and `coupling`, plus `similarAll` for the cross-codebase mode of `similar`:
-
-```typescript
-import {
-  ScipDatabase, createGitignoreFilter,
-} from 'scip-query';
-import {
-  health, affected, changeSurface, diffImpact,
-  hotspots, similar, dead, convergence,
-} from 'scip-query/queries';
-
-const filter = createGitignoreFilter('/path/to/project');
-const db = new ScipDatabase({
-  dbPath: '/path/to/index.db',
-  indexPath: '/path/to/index.scip',
-  projectRoot: '/path/to/project',
-}, filter);
+Useful environment variables:
 
-// Full health report
-const report = health(db);
-console.log(`Score: ${report.score}/100`);
-console.log(`Actions: ${report.actions.length}`);
+| Variable | Purpose |
+|---|---|
+| `SCIP_QUERY_PROJECT_ROOT` | Override the project root directory |
+| `SCIP_QUERY_INDEX_DB` | Override the SQLite database path |
+| `SCIP_QUERY_INDEX_SCIP` | Override the SCIP protobuf path |
+| `SCIP_QUERY_CACHE_DIR` | Override the cache directory |
 
-// Impact analysis
-const blast = affected(db, 'login', { maxDepth: 3 });
-const brief = changeSurface(db, 'auth.service.ts');
-const impact = diffImpact(db, { base: 'main' });
+Query results are filtered through the project's `.gitignore`. If none exists, common generated directories such as `dist/`, `target/`, `node_modules/`, and `.venv/` are excluded by default.
 
-// Consolidation
-const pairs = similar(db, 'myFunction', { minSimilarity: 0.5 });
-const recipe = convergence(db, 'funcA', 'funcB');
+## Documentation
 
-db.close();
-```
+- [Agent Guide](docs/AGENT_GUIDE.md): goal-oriented workflows for tracing, planning, cleanup, quality checks, and change verification.
+- [Command Reference](docs/COMMAND_REFERENCE.md): generated command syntax, descriptions, and options.
+- [Programmatic API](docs/API.md): using the query functions from TypeScript.
+- [Historical plans](docs/plans/): implementation notes and completed cleanup plans.
 
 ## License