scip-query 0.19.5 → 0.19.8

package/skills/scip-setup/SKILL.md

@@ -1,222 +1,110 @@
 ---
 name: scip-setup
-description: Set up or repair scip-query in a repository. Use for bootstrapping, onboarding, refreshing indexes, project-local hooks, agent guidance, capability diagnostics, health dossiers, .scipquery.json, or setup cleanup handoff.
+description: Use to adopt, onboard, repair, or diagnose scip-query ITSELF in a repo — first index, config, capability and dependency checks, installing or uninstalling agent skills, agent guidance blocks, project hooks, CI wiring. Wins over scip-verify for first-time adoption; calibration comes afterward.
 commands:
-  - template: 'scip-query setup --json'
-    when: 'Run setup: install skills, refresh the index, report health.'
-  - template: 'scip-query doctor'
-    when: 'Resolve blockers: human diagnostic for config, index, and dependencies.'
-  - template: 'scip-query status --json'
-    when: 'Resolve blockers: machine surface for freshness and config.'
-  - template: 'scip-query capabilities --matrix'
-    when: 'Resolve blockers: which evidence/verification capabilities are available.'
-  - template: 'scip-query config-validate --json'
-    when: 'Resolve blockers: validate .scipquery.json.'
-  - template: 'scip-query init'
-    when: 'Calibrate config: create .scipquery.json only when absent and needed.'
+  - template: "scip-query setup --json"
+    when: "Bootstrap or repair the complete repository setup."
+  - template: "scip-query doctor"
+    when: "Diagnose configuration, index, dependency, or capability failures."
+  - template: "scip-query status --capabilities"
+    when: "Confirm freshness and the exact evidence capabilities available."
 ---
 
 # scip-setup
 
-Use this skill to make a repository a reliable scip-query workspace: indexed, diagnosed, documented for agents, and honest about unavailable capabilities.
+## Purpose
 
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md).
+Make a repository a reliable scip-query workspace: indexed, diagnosed,
+documented for agents, and honest about unavailable capabilities. Covers
+first-time adoption, repair after drift, capability/dependency diagnosis, and
+the lifecycle commands that install, refresh, or remove scip-query's footprint
+(skills, agent guidance, hooks, CI).
+
+Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md). Use
 
 <!-- BEGIN GENERATED SKILL COMMANDS -->
 ## Commands for this skill
 
 | Command | Purpose | Returns | Coverage | When |
 | --- | --- | --- | --- | --- |
-| `scip-query setup --json` | Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health | setup step outcomes, files, capabilities, smoke tests, and warnings | `complete` | Run setup: install skills, refresh the index, report health. |
-| `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | config, freshness, dependency, and capability diagnostics | `complete` | Resolve blockers: human diagnostic for config, index, and dependencies. |
-| `scip-query status --json` | Show index status for this project | freshness, generation, language shards, watcher, and optional capabilities | `complete` | Resolve blockers: machine surface for freshness and config. |
-| `scip-query capabilities --matrix` | Report which evidence and verification capabilities are available in this project | capability matrix with availability and reasons | `complete` | Resolve blockers: which evidence/verification capabilities are available. |
-| `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | validation diagnostics with config paths | `complete` | Resolve blockers: validate .scipquery.json. |
-| `scip-query init` | Create a .scipquery.json config file for this project | configuration path and creation outcome | `complete` | Calibrate config: create .scipquery.json only when absent and needed. |
+| `scip-query setup --json` | Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health | setup step outcomes, files, capabilities, smoke tests, and warnings | `complete` | Bootstrap or repair the complete repository setup. |
+| `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | config, freshness, dependency, and capability diagnostics | `complete` | Diagnose configuration, index, dependency, or capability failures. |
+| `scip-query status --capabilities` | Show index status for this project | freshness, generation, language shards, watcher, and optional capabilities | `complete` | Confirm freshness and the exact evidence capabilities available. |
 
 Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
 <!-- END GENERATED SKILL COMMANDS -->
+this skill's own command shortlist first; open the shared file only when it is
+insufficient.
 
-## Per-Repo Triage (once, after setup)
-
-New repos surface standing findings that are intentional. Encode them once so
-every later gate run is precise:
-
-1. Sweep initial findings (`health --json`, `diff-gate --json`) and, for each accepted one, `suppress <id> --reason <why>` — reasons are required and audited.
-2. Declare files that legitimately change together in `.scipquery.json` `declaredCouplings`.
-3. List dated snapshot docs (benchmarks, validation ledgers, historical plans/reviews) in `docs.snapshotPaths` so doc checks skip them with a labeled exclusion instead of recurring findings.
-4. Seed `coverageContracts` for every hand-maintained enumeration (policy maps, capability tables, registry lists) so enumeration rot fails the gate the day it happens.
-5. Set a hygiene cadence: run `scip-twin-drift` and `scip-claim-audit` after large refactor campaigns or quarterly — the gate only sees diffs; these lenses see accumulated state.
-
-This step is complete only when a clean working tree produces a finding-free `diff-gate` and every suppression carries a reason a reviewer would accept.
-
-## Rules
-
-1. Prefer the single setup command over hand-running its internals.
-2. Do not run `scip-query setup-ci` unless the user explicitly asks for CI setup.
-3. Treat unavailable capabilities as unproven, not clean.
-4. Keep `.scipquery.json` minimal and evidence-backed.
-5. Let setup install detected AST parser packages and supported indexers; do not
-   make users reproduce package-manager commands unless setup reports a blocker.
-6. A demand-started service or Rust helper in `stopped` state can still be
-   correctly configured. Availability comes from capabilities; lifecycle state
-   only says whether work currently keeps the helper awake.
-
-## What Setup Owns
-
-`scip-query setup` is the bootstrap orchestrator. In a terminal it opens an
-interactive checklist by default. For an agent or script, `scip-query setup
---json` runs the recommended non-interactive path and returns every result.
-
-The command:
-
-- detects supported project languages and lets a terminal user select them;
-- installs or repairs supported language indexers when a safe installer exists;
-- installs the Tree-sitter runtime and detected language grammars from the
-  versions pinned by the installed scip-query package;
-- installs bundled agent skills and checkout-local Codex/Claude hooks unless
-  explicitly skipped;
-- enables demand-started automatic incremental indexing unless the repository
-  has or selects an explicit opt-out;
-- builds or reuses language/project shards and publishes one atomic SQLite
-  generation with recovery state;
-- starts or reuses the clean-idle project service and verifies its lifecycle;
-- checks TypeScript and Rust semantic readiness, compiler/checker readiness,
-  representative commands, and optional health output;
-- reports repository, checkout, user-environment, and rebuildable runtime state
-  separately.
-
-Do not manually install AST grammar packages before trying setup. If npm uses
-script approval and native packages remain unavailable, report the pending
-packages and ask the user to approve them; a package must not approve its own
-install scripts.
+## Triage: which scenario applies
 
-## Workflow
+| Situation | Go to |
+| --- | --- |
+| First time running scip-query in this repo, or repairing a broken setup | [Bootstrap workflow](references/bootstrap-workflow.md) — `setup` |
+| `setup` reported a blocker, or index/capabilities look wrong | [Bootstrap workflow §3](references/bootstrap-workflow.md#3-resolve-blockers) — `doctor`, `status`, `capabilities`, `config-validate` |
+| Confirming TypeScript/Vue or Rust semantic readiness specifically | [Language verification](references/language-verification.md) |
+| Need to (re)install skills, agent guidance, hooks, or CI without a full bootstrap | [Lifecycle commands](references/lifecycle-commands.md) |
+| Removing scip-query's footprint from a repo | [Lifecycle commands § uninstall](references/lifecycle-commands.md#uninstall) |
+| New repo has standing findings that are intentional (naming conventions, snapshot docs, coupled files) | [Per-repo triage](references/per-repo-triage.md) |
+| Setup is done and clean; user wants a cleanup report or autonomous cleanup | Hand off to `scip-audit` (report) or `scip-improve` (autonomous) |
 
-### 1. Confirm the root
+## The core scenario
 
-```bash
-pwd
-git rev-parse --show-toplevel
-scip-query --version
-```
-
-This step is complete only when the repository root and runnable `scip-query` command are known, or the install/link blocker is reported.
-
-### 2. Run setup
+When a repository is new to scip-query, or its setup is suspect, run:
 
 ```bash
 scip-query setup --json
 ```
 
-When a human is operating the terminal, prefer plain `scip-query setup` so they
-can review the checklist with arrow keys and Space. Use `scip-query setup --yes`
-to accept recommended defaults without prompting. JSON mode is intentionally
-non-interactive and suitable for agents.
-
-Use `scip-query setup --no-hooks --json` when project-local Codex or Claude Code lifecycle hooks should not be written. Use `scip-query setup --git-hook --json` only when the user wants the local pre-commit diff gate.
-
-This step is complete only when setup reports ready, partial, or blocked and names every written, skipped, or blocked artifact.
-
-### 3. Resolve blockers
-
-```bash
-scip-query doctor
-scip-query status --json
-scip-query capabilities --matrix
-scip-query config-validate --json
-```
-
-`doctor` is the human diagnostic surface. `status --json` is the machine surface for freshness and config. Fix missing indexers, stale indexes, invalid config, or unavailable verification only when the fix is safe; otherwise record the exact external action.
-
-This step is complete only when each blocker is fixed, unavailable with reason, or waiting on a named external action.
-
-### 4. Verify the language-specific optimal path
-
-#### TypeScript, JavaScript, and Vue
-
-Require all applicable capability rows to explain their state:
-
-- `scip-typescript` is runnable for SCIP indexing;
-- the detected Tree-sitter TypeScript/JavaScript parser is available for source
-  facts;
-- ts-morph semantic readiness is available for TypeScript;
-- the demand-started service is enabled and status exposes TypeScript semantic
-  and TypeScript index session counters.
-
-For a real multi-project TypeScript monorepo, set
-`indexer.typescript.projectMode: "workspace"`. This makes project/tsconfig
-boundaries the sub-shards: a changed project and its project-reference,
-workspace-package, or tsconfig-path dependents rebuild while unrelated project
-shards are reused. Use `indexer.typescript.projects` only when automatic
-discovery is too broad; a non-empty list is authoritative. Do not enable
-workspace mode for a single-project repository merely to seek speed—the normal
-incremental document producer and persistent ts-morph service already reuse
-unchanged work.
-
-#### Rust
-
-Require these distinct facts:
-
-- `rust-analyzer` is runnable and supports `rust-analyzer scip` for indexing;
-- the Tree-sitter Rust grammar is available for source facts;
-- Rust semantic readiness is available for compiler-backed references,
-  callees, signatures, and module/use evidence;
-- status reports the durable Rust transport with worker fallback. `stopped` is
-  healthy when no semantic request currently needs the clean-idle helper.
-
-If rust-analyzer is missing and rustup is available, setup can run `rustup
-component add rust-analyzer`. `SCIP_RUST_SEMANTIC_DURABLE_SESSION=0` is an
-explicit worker-only fallback, not the optimal default.
-
-#### Other languages
-
-Trust the capability matrix, not a language name. Setup may install supported
-indexers automatically (for example Python or Go), may provide only source
-facts through a detected Tree-sitter grammar, or may report a manual install
-URL. A missing semantic provider must be reported as unsupported, never as a
-clean semantic analysis.
-
-Verification:
-
-```bash
-scip-query status --capabilities
-scip-query reindex --json
-scip-query watch --status --json
-```
-
-This step is complete only when every selected language has an explicit
-indexing/source/semantic/checker verdict and the published generation is fresh.
-
-### 5. Calibrate config only when needed
-
-Run `scip-query init` only when `.scipquery.json` is absent and the project needs config. Add settings only for observed repo facts: explicit languages, indexer projects, entry roots, declared couplings, locality boundaries, or accepted suppressions.
-
-For TypeScript monorepos, prefer `indexer.typescript.projectMode: "workspace"` when multiple project shards are real. Add `indexerConcurrency` only when measured cold-index timing or memory pressure justifies it. Keep `watch.enabled: true` for the designed demand-started lifecycle unless the user explicitly opts out.
-
-This step is complete only when config validates and every setting has a reason.
-
-### 6. Hand off cleanup
-
-After setup, invoke `scip-cleanup-audit` when the user wants a report or `scip-cleanup-improve` when the user wants autonomous cleanup.
+`setup` is the bootstrap orchestrator: it installs/repairs language indexers,
+installs Tree-sitter grammars, installs bundled agent skills and hooks,
+enables demand-started incremental indexing, builds SQLite shards, starts the
+project service, checks semantic readiness, and reports repository/checkout/
+environment/runtime state separately. Prefer this single command over
+hand-running its internals. Full step-by-step handling — including what to do
+when it reports `partial` or `blocked` — is in
+[Bootstrap workflow](references/bootstrap-workflow.md).
+
+Do not manually install AST grammar packages before trying `setup`. If npm's
+script-approval gate blocks a native package, report the pending packages and
+ask the user to approve them — a package must not approve its own install
+scripts.
+
+## Rules (apply across every scenario)
+
+1. Prefer the single `setup` command over hand-running its internals.
+2. Do not run `scip-query setup-ci` unless the user explicitly asks for CI
+   setup.
+3. Treat unavailable capabilities as unproven, not clean. A missing semantic
+   provider is "unsupported," never "clean semantic analysis."
+4. Keep `.scipquery.json` minimal and evidence-backed — add a setting only for
+   an observed repo fact, with a reason.
+5. Let `setup` install detected AST parser packages and supported indexers; do
+   not make users reproduce package-manager commands unless `setup` reports a
+   blocker.
+6. A demand-started service or Rust helper in `stopped` state can still be
+   correctly configured. Availability comes from capabilities; lifecycle state
+   only says whether current work keeps the helper awake.
 
-Report:
+## Report template
 
 ```markdown
 Setup: ready/partial/blocked
 Capabilities:
-
 - available:
 - unavailable:
-  Health:
+Health:
 - score:
 - dossier:
-  Written or changed:
+Written or changed:
 - files:
-  Runtime:
+Runtime:
 - automatic indexing:
 - TypeScript project/index sessions:
 - Rust semantic transport/lifecycle:
-  Next:
+Next:
 - cleanup audit/improve, CI setup, or external blocker
 ```
+
+Fill this in as the closing report for any bootstrap or repair pass — it is
+the fixed template regardless of which reference scenario you used.

package/skills/scip-setup/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
-  display_name: "scip-query setup"
-  short_description: "Bootstrap or repair scip-query indexing, diagnostics, hooks, guidance, and health dossiers"
-  default_prompt: "Set up or repair scip-query in this repository, report readiness and blockers, and hand off the next cleanup step."
+  display_name: "SCIP Setup"
+  short_description: "Bootstrap or repair scip-query in a repo"
+  default_prompt: "Use $scip-setup to adopt, repair or diagnose scip-query itself in this repository."

package/skills/scip-setup/references/bootstrap-workflow.md

@@ -0,0 +1,120 @@
+# Bootstrap workflow
+
+Six ordered steps. Each has a completion condition — do not treat the step as
+done until the condition is met.
+
+## 1. Confirm the root
+
+```bash
+pwd
+git rev-parse --show-toplevel
+scip-query --version
+```
+
+Complete only when the repository root and a runnable `scip-query` command
+are known, or the install/link blocker is reported.
+
+## 2. Run setup
+
+```bash
+scip-query setup --json
+```
+
+`scip-query setup` is the bootstrap orchestrator. In a terminal it opens an
+interactive checklist by default. For an agent or script, `scip-query setup
+--json` runs the recommended non-interactive path and returns every result —
+JSON mode is intentionally non-interactive and suitable for agents. When a
+human is operating the terminal, prefer plain `scip-query setup` (no `--json`)
+so they can review the checklist with arrow keys and Space. Use `scip-query
+setup --yes` to accept recommended defaults without prompting.
+
+Use `scip-query setup --no-hooks --json` when project-local Codex or Claude
+Code lifecycle hooks should not be written. Use `scip-query setup --git-hook
+--json` only when the user wants the local pre-commit diff gate.
+
+The command, in full:
+
+- detects supported project languages and lets a terminal user select them;
+- installs or repairs supported language indexers when a safe installer
+  exists;
+- installs the Tree-sitter runtime and detected language grammars from the
+  versions pinned by the installed scip-query package;
+- installs bundled agent skills and checkout-local Codex/Claude hooks unless
+  explicitly skipped;
+- enables demand-started automatic incremental indexing unless the repository
+  has or selects an explicit opt-out;
+- builds or reuses language/project shards and publishes one atomic SQLite
+  generation with recovery state;
+- starts or reuses the clean-idle project service and verifies its lifecycle;
+- checks TypeScript and Rust semantic readiness, compiler/checker readiness,
+  representative commands, and optional health output;
+- reports repository, checkout, user-environment, and rebuildable runtime
+  state separately.
+
+Complete only when `setup` reports `ready`, `partial`, or `blocked` and names
+every written, skipped, or blocked artifact.
+
+## 3. Resolve blockers
+
+```bash
+scip-query doctor
+scip-query status --json
+scip-query capabilities --matrix
+scip-query config-validate --json
+```
+
+`doctor` is the human diagnostic surface for config, index freshness, and
+dependency readiness. `status --json` is the machine surface for freshness
+and config. `capabilities --matrix` reports which evidence/verification
+capabilities are available. `config-validate --json` validates
+`.scipquery.json`.
+
+Fix missing indexers, stale indexes, invalid config, or unavailable
+verification only when the fix is safe; otherwise record the exact external
+action needed (e.g. "user must approve npm install scripts for
+tree-sitter-rust").
+
+Complete only when each blocker is fixed, reported unavailable with a reason,
+or waiting on a named external action.
+
+## 4. Verify the language-specific optimal path
+
+See [Language verification](language-verification.md) for what to check per
+language and how to interpret `stopped`/idle service states.
+
+```bash
+scip-query status --capabilities
+scip-query reindex --json
+scip-query watch --status --json
+```
+
+Complete only when every selected language has an explicit
+indexing/source/semantic/checker verdict and the published generation is
+fresh.
+
+## 5. Calibrate config only when needed
+
+Run `scip-query init` only when `.scipquery.json` is absent and the project
+needs config — it creates the config file. Add settings only for observed
+repo facts: explicit languages, indexer projects, entry roots, declared
+couplings, locality boundaries, or accepted suppressions.
+
+- For TypeScript monorepos, prefer `indexer.typescript.projectMode:
+  "workspace"` when multiple project shards are real (see
+  [Language verification](language-verification.md) for when this earns its
+  keep).
+- Add `indexerConcurrency` only when measured cold-index timing or memory
+  pressure justifies it.
+- Keep `watch.enabled: true` for the designed demand-started lifecycle unless
+  the user explicitly opts out.
+
+Complete only when config validates and every setting has a stated reason.
+
+## 6. Hand off
+
+After setup, invoke `scip-audit` when the user wants a report, or
+`scip-improve` when the user wants autonomous cleanup. If the repo is
+new to scip-query, also route through [Per-repo triage](per-repo-triage.md)
+so standing findings get encoded once rather than recurring on every gate run.
+
+Close with the report template in the top-level `SKILL.md`.

package/skills/scip-setup/references/language-verification.md

@@ -0,0 +1,61 @@
+# Language-specific verification
+
+Used in bootstrap workflow step 4, and any time an index or capability report
+looks wrong for a specific language.
+
+## TypeScript, JavaScript, and Vue
+
+Require these capability rows to explain their state:
+
+- `scip-typescript` is runnable for SCIP indexing;
+- the detected Tree-sitter TypeScript/JavaScript parser is available for
+  source facts;
+- ts-morph semantic readiness is available for TypeScript;
+- the demand-started service is enabled and status exposes TypeScript
+  semantic and TypeScript index session counters.
+
+For a real multi-project TypeScript monorepo, set
+`indexer.typescript.projectMode: "workspace"`. This makes project/tsconfig
+boundaries the sub-shards, so a changed project and its project-reference,
+workspace-package, or tsconfig-path dependents rebuild while unrelated
+project shards are reused. Use `indexer.typescript.projects` only when
+automatic discovery is too broad; a non-empty list there is authoritative.
+
+Do not enable TypeScript workspace mode for a single-project repository
+merely to seek speed — the normal incremental document producer and
+persistent ts-morph service already reuse unchanged work.
+
+## Rust
+
+Require these distinct facts:
+
+- `rust-analyzer` is runnable and supports `rust-analyzer scip` for indexing;
+- the Tree-sitter Rust grammar is available for source facts;
+- Rust semantic readiness is available for compiler-backed references,
+  callees, signatures, and module/use evidence;
+- status reports the durable Rust transport with worker fallback.
+
+A `stopped` state for the Rust transport (or any demand-started helper) is
+healthy when no semantic request currently needs the clean-idle helper —
+lifecycle state is not the same signal as capability availability.
+
+If `rust-analyzer` is missing and `rustup` is available, `setup` can run
+`rustup component add rust-analyzer`. `SCIP_RUST_SEMANTIC_DURABLE_SESSION=0`
+is an explicit worker-only fallback, not the optimal default — do not set it
+as a default recommendation.
+
+## Other languages
+
+Trust the capability matrix, not a language name. `setup` may install
+supported indexers automatically (for example Python or Go), may provide only
+source facts through a detected Tree-sitter grammar, or may report a manual
+install URL. A missing semantic provider must be reported as unsupported,
+never as a clean semantic analysis.
+
+## Verification commands
+
+```bash
+scip-query status --capabilities
+scip-query reindex --json
+scip-query watch --status --json
+```

package/skills/scip-setup/references/lifecycle-commands.md

@@ -0,0 +1,119 @@
+# Lifecycle commands
+
+`setup` runs most of these internally during a full bootstrap. Reach for one
+directly when only a slice of the footprint needs installing, refreshing, or
+removing — not a full re-bootstrap.
+
+## install-skills
+
+```bash
+scip-query install-skills
+```
+
+When: bundled skills are missing, out of date after a scip-query upgrade, or
+a new agent root (Claude Code, Codex, or a shared agent root) needs the skill
+set that another root already has. Installs `_shared`, `scip-query`,
+`scip-setup`, and the consolidated workflow family into Claude Code, Codex, and
+shared agent roots.
+
+Output to check: the list of skills written or linked per root. Confirm no
+root was silently skipped — an agent root present in the repo but absent from
+the output means that root did not get the skills.
+
+## setup-agent
+
+```bash
+scip-query setup-agent
+```
+
+When: `AGENTS.md`/`CLAUDE.md` has no block pointing agents at the scip-query
+skills and diff gate, or the block is stale relative to the installed
+version. Seeds that guidance block, plus an optional git pre-commit backstop.
+
+Output to check: the diff to `AGENTS.md`/`CLAUDE.md` — confirm the block was
+added or refreshed in place rather than duplicated.
+
+## setup-hooks
+
+```bash
+scip-query setup-hooks
+```
+
+When: project-local Codex or Claude Code lifecycle hooks are missing (never
+installed, or wiped by a settings reset) or need refreshing after a
+scip-query upgrade changed hook contracts.
+
+Output to check: which hook files were written per tool; treat a tool with no
+hook file as not covered.
+
+## setup-ci
+
+```bash
+scip-query setup-ci
+```
+
+When: the user explicitly asks for CI setup — do not run this unless asked.
+Writes a GitHub Actions workflow that runs `scip-query reindex` and
+`diff-gate` on pull requests.
+
+Output to check: the workflow file path written. Tell the user to commit it
+and confirm it triggers on the next PR; this command only writes the file, it
+does not verify the workflow runs.
+
+## check-deps
+
+```bash
+scip-query check-deps
+```
+
+When: you need a fast preflight on whether scip-query and the detected
+language indexers are actually runnable, without running the full `setup`
+sequence — for example, diagnosing a `doctor` complaint about a specific
+indexer, or confirming an environment before a CI run.
+
+Output to check: per-indexer runnable/not-runnable verdicts. A "not runnable"
+verdict here is the reason to go fix that indexer before trusting any index
+built from it.
+
+## augment-sources
+
+```bash
+scip-query augment-sources
+```
+
+When: files are missing from the index even after a clean `reindex`, because
+the upstream SCIP indexer for that language skips them (common for
+non-source files, generated files it doesn't recognize, or files outside its
+project graph). Adds those source files to the SQLite documents table
+directly so source-fact queries can see them.
+
+Output to check: the count and list of files added. If a file you expected is
+still absent, it means the indexer skip reason is not one `augment-sources`
+covers — investigate the specific file rather than re-running the command.
+
+## capability-matrix
+
+```bash
+scip-query capability-matrix
+```
+
+Deprecated alias for `capabilities --matrix`. If you see this in an older
+script or muscle memory, prefer `scip-query capabilities --matrix` directly —
+same output, current name.
+
+## uninstall
+
+```bash
+scip-query uninstall
+```
+
+When: the user wants scip-query's footprint removed from the repo —
+decommissioning, or before trying an alternative tool. Removes
+scip-query-owned skill links, project hooks, and managed agent setup blocks.
+
+Output to check: confirm the removal list covers every artifact `setup`
+reported writing (skills, hooks, agent guidance blocks). Anything `setup`
+wrote that `uninstall` doesn't list as removed needs manual follow-up — for
+example config files (`.scipquery.json`) and the SQLite index are
+intentionally left in place since they may hold data the user still wants;
+tell the user explicitly if they want those gone too.

package/skills/scip-setup/references/per-repo-triage.md

@@ -0,0 +1,24 @@
+# Per-repo triage (once, after setup)
+
+New repos surface standing findings that are intentional. Encode them once so
+every later gate run is precise, instead of re-litigating the same findings
+every time `diff-gate` runs.
+
+1. Sweep initial findings with `health --json` and `diff-gate --json`. For
+   each accepted finding, run `suppress <id> --reason <why>` — reasons are
+   required and audited.
+2. Declare files that legitimately change together in `.scipquery.json`
+   `declaredCouplings`.
+3. List dated snapshot docs (benchmarks, validation ledgers, historical
+   plans/reviews) in `docs.snapshotPaths` so doc checks skip them with a
+   labeled exclusion instead of recurring findings.
+4. Seed `coverageContracts` for every hand-maintained enumeration (policy
+   maps, capability tables, registry lists) so enumeration rot fails the gate
+   the day it happens.
+5. Set a hygiene cadence: run the twin-drift and claim scenarios in
+   `scip-audit` after
+   large refactor campaigns or quarterly. The gate only sees diffs; these
+   lenses see accumulated state.
+
+Complete only when a clean working tree produces a finding-free `diff-gate`
+and every suppression carries a reason a reviewer would accept.