scip-query 0.19.4 → 0.19.6

package/skills/scip-query/SKILL.md

@@ -1,88 +1,59 @@
 ---
 name: scip-query
-description: Route codebase work in scip-query-indexed projects. Use when exploring, planning, implementing, refactoring, debugging, verifying, cleaning up, reconciling docs, improving health, or when unsure which scip-* skill should own the workflow.
-commands:
-  - template: "scip-query status --capabilities"
-    when: "Before routing: confirm the index is fresh."
-  - template: "scip-query plan-context <target>"
-    when: "Default loop: anchor a plan for the routed skill."
-  - template: "scip-query diff-gate --json"
-    when: "Default loop: the loop is complete only when this passes or is explained."
+description: Use FIRST for codebase work that should rest on SCIP evidence. Routes understanding to scip-explore, prospective changes to scip-plan, failures to scip-diagnose, read-only problem finding to scip-audit, confirmed fixes to scip-improve, adoption or repair to scip-setup, and finished diffs to scip-verify.
 ---
 
-# scip-query Router
+# SCIP Query Router
 
-Use this skill only to route. A scip-query workflow is a codebase task whose claims should be grounded in the SCIP index: the compiler-derived map of files, symbols, references, calls, dependencies, and consumers.
+## Purpose
 
-Load shared mechanics from [`../_shared/SKILL.md`](../_shared/SKILL.md) when you need freshness, lookup, postcheck, or subagent rules.
+Choose one owning workflow before acting. An owning workflow is the bundled
+skill whose completion criterion matches the request: understanding, planning,
+diagnosis, read-only auditing, implementation, setup, or verification. The
+router does not perform that workflow itself.
 
-<!-- BEGIN GENERATED SKILL COMMANDS -->
-## Commands for this skill
-
-| Command | Purpose | When |
-| --- | --- | --- |
-| `scip-query status --capabilities` | Show index status for this project | Before routing: confirm the index is fresh. |
-| `scip-query plan-context <target>` | Pre-edit planning context for a symbol, file, or module | Default loop: anchor a plan for the routed skill. |
-| `scip-query diff-gate --json` | Gate the current diff: architecture regressions plus echo, migration, coordination, doc-drift, unused-param, and new-dead candidates; exit 1 on blocking findings | Default loop: the loop is complete only when this passes or is explained. |
-
-Use this shortlist first. Open [`../_shared/SKILL.md`](../_shared/SKILL.md) only when it is insufficient.
-<!-- END GENERATED SKILL COMMANDS -->
-
-## Default Loop
-
-For non-trivial code changes:
-
-1. Invoke `scip-concrete-plan`; the plan starts from `scip-query plan-context <target>` and designs for testability.
-2. Implement the plan in the smallest coherent slice.
-3. Invoke `scip-verify`.
-
-The loop is complete only when `scip-verify` passes or each remaining finding has a specific reason.
+Load `../_shared/SKILL.md` only after the owning workflow's shortlist proves
+insufficient. The shared reference contains the complete command vocabulary,
+coverage rules, and evidence contract; loading it before a route is selected
+adds choices without adding direction.
 
 ## Routes
 
-| Work | Skill | Anchor |
+| The request starts from… | Owning skill | Completion criterion |
 | --- | --- | --- |
-| Understand a system before answering or editing | `scip-explore` | `system`, `trace`, `call-graph`, `dataflow` |
-| Root-cause a bug or regression | `scip-debug` | `trace`, `dataflow`, `change-surface` |
-| Diagnose the design flaw behind a family of recurring bugs | `scip-root-cause` | `co-change`, `similar`, `refs` |
-| Turn a report into a fix packet | `scip-triage-issue` | `files`, `trace`, `affected` |
-| Create a code flow, dependency, or blast-radius diagram | `scip-diagram` | `call-graph`, `dataflow`, `affected` |
-| Plan a feature, fix, or refactor | `scip-concrete-plan` | `plan-context` |
-| Run a multi-phase program: plan, delegate, verify handoffs, close | `scip-conductor` | `plan-context`, `diff-gate`, `health` |
-| Assess public API, route, config, schema, CLI, or export changes | `scip-api-impact` | `surface`, `affected`, `co-change` |
-| Pick language-specific high-signal commands | `scip-language-playbook` | language row |
-| Benchmark and optimize a command, workflow, or hot path | `scip-hyper-optimization` | `bench`, `plan-context`, profiles |
-| Adopt or repair scip-query setup in a repo | `scip-setup` | `setup`, `doctor`, `capabilities` |
-| Verify any finished change | `scip-verify` | `status`, `diff-impact`, final gate |
-| Audit, rank, or confirm cleanup findings | `scip-cleanup-audit` | `health`, `cleanup-plan`, cleanup detectors |
-| Autonomously fix confirmed cleanup findings | `scip-cleanup-improve` | `health`, `cleanup-plan`, verified batches |
-| Find or resolve same-name twins that have diverged | `scip-twin-drift` | `twin-drift`, `duplicate-bodies`, `refs` |
-| Faked or half-implemented features, checkers that never fail, dead paths behind fallbacks, lying metrics | `scip-integrity-audit` |
-| Audit whether a status claim is derived, hedged, or merely asserted | `scip-claim-audit` | `refs`, `code`, `trace` |
-| Prove whether a parser/AST branch is actually reachable | `scip-probe-reachability` | `outline --signatures`, `code`, scratch probes |
-| Reconcile living docs with code | `scip-doc-reconcile` | `doc-drift` |
-| Review or migrate folder ownership | `scip-directory-architecture` | `locality-candidates`, `similar-files` |
-| Review deeper maintainability and system compression | `scip-maintainability` | `bottlenecks`, `similar-chains`, `change-surface` |
-| Review React reuse and component/hook pressure | `scip-react-maintainability` | React duplicate and pressure commands |
-| Review Vue reuse and SFC/composable pressure | `scip-vue-maintainability` | Vue duplicate and pressure commands |
-| Model a TypeScript system with TLA+ | `scip-tla-model-system` | `plan-context`, `tla verify` |
-
-Routing is complete only when one owning skill is selected or the task is small enough for the default loop alone.
-
-## Tie-Breaks
-
-- "Is this implementation real / does it actually work" → `scip-integrity-audit`; "is this well-organized" → `scip-maintainability`; same-name drifted twins specifically → `scip-twin-drift`.
-- One change → `scip-concrete-plan`; a program of changes with delegation → `scip-conductor`.
-- One failing behavior → `scip-debug`; a family of similar bugs whose fixes keep recurring, or "what is really wrong with this system" backed by bug history → `scip-root-cause`; structure smells with no bug evidence → `scip-maintainability`.
-
-- Use `scip-cleanup-audit` for reports, ranking, confirmation, or recent AI-residue triage without edits.
-- Use `scip-cleanup-improve` when the user asks to fix, improve, continue cleaning, or raise health autonomously.
-- Use `scip-maintainability`, `scip-directory-architecture`, or `scip-hyper-optimization` only when the target is architecture, file ownership, or measured speed/cost rather than cleanup.
-- Use `scip-twin-drift` for same-name/near-name consolidation questions (a specific concept copied and drifted); use `scip-cleanup-audit`/`scip-cleanup-improve` for general bloat, echoes, and duplication sweeps that are not centered on one drifted twin family.
-
-## Setup
-
-If a repository has not been bootstrapped, invoke `scip-setup`. Use `scip-query setup-agent` only to refresh agent guidance, `scip-query setup-hooks --json` only to repair project-local hooks, and `scip-query setup-ci` only when the user explicitly asks for CI setup.
+| Existing code that must be understood, traced, or diagrammed | `scip-explore` | Entry points, flow, dependencies, consumers, and remaining uncertainty are evidenced. |
+| A proposed feature, refactor, migration, API change, performance campaign, TLA+ model, or multi-phase program | `scip-plan` | Current flow, affected consumers, reuse decisions, ordered slices, validation, and risks are explicit. |
+| A failure, regression, recurring bug family, raw issue, or parser/AST reachability question | `scip-diagnose` | The observed failure is connected to a cause, rivals are rejected, and the smallest fix packet is defined. |
+| A question about whether problems exist, without permission to edit | `scip-audit` | The scoped items are classified and ranked with evidence; no code or docs are changed. |
+| Confirmed cleanup, drift, maintainability, frontend, directory, twin, or documentation findings that should be fixed | `scip-improve` | One coherent finding slice is changed and passes its routed postchecks. |
+| First adoption, broken setup, missing capabilities, skill installation, hooks, CI, or uninstall | `scip-setup` | The workspace is ready, or every unavailable capability has an explicit blocker. |
+| A finished diff that must be challenged before commit or release | `scip-verify` | Workspace, impact, applicable postchecks, gate findings, and refutation attempts are all accounted for. |
+
+## Disambiguation
+
+- Existing behavior with no symptom routes to `scip-explore`; a contradiction
+  or failure routes to `scip-diagnose`.
+- Finding and classifying problems without edits routes to `scip-audit`;
+  changing already-confirmed findings routes to `scip-improve`.
+- Prospective work routes to `scip-plan`; a concrete finished diff routes to
+  `scip-verify`.
+- Setup wins whenever the index or a required capability is missing, stale,
+  invalid, or not yet installed.
+- A request may cross workflows in sequence. Keep one owner at a time:
+  diagnose before planning a fix, audit before improving, plan before a
+  non-trivial implementation, and verify after every implemented slice.
+
+## Default non-trivial change loop
+
+1. Invoke `scip-plan`, anchored by
+   `scip-query plan-context <target>`.
+2. Implement the smallest coherent planned slice.
+3. Invoke `scip-verify`; do not declare completion until it passes or every
+   remaining finding has a specific evidence-backed disposition.
+
+Routing is complete only when exactly one owner is selected for the current
+phase, or the request is small enough that no compiler-resolved relationship
+claim is needed.
 
 <!-- BEGIN GENERATED ROUTER COMMAND PREVIEW -->
 ## Command Preview
@@ -91,27 +62,11 @@ Top commands per routed skill, generated from each skill's own `commands:` front
 
 | Skill | Top commands |
 | --- | --- |
-| `scip-api-impact` | `scip-query surface <module-or-package>`, `scip-query refs <symbol>`, `scip-query affected <symbol> --json` |
-| `scip-claim-audit` | `scip-query files <pattern>`, `scip-query refs <symbol>`, `scip-query code <symbol>` |
-| `scip-cleanup-audit` | `scip-query health --json`, `scip-query cleanup-plan --verify --json`, `scip-query duplicate-bodies --json --full` |
-| `scip-cleanup-improve` | `scip-query health --json`, `scip-query cleanup-plan --verify --json`, `scip-query cleanup-apply --verified --batch <n>` |
-| `scip-concrete-plan` | `scip-query status --capabilities`, `scip-query plan-context <target>`, `scip-query refs <symbol>` |
-| `scip-conductor` | `scip-query plan-context <target>`, `scip-query diff-gate --json`, `scip-query health --json` |
-| `scip-debug` | `scip-query files <feature-or-error-term>`, `scip-query trace <candidate-symbol>`, `scip-query call-graph <entry-symbol>` |
-| `scip-diagram` | `scip-query system <module>`, `scip-query trace <symbol>`, `scip-query call-graph <symbol>` |
-| `scip-directory-architecture` | `scip-query system <scope>`, `scip-query locality-candidates --json --full`, `scip-query similar-files --full --json` |
-| `scip-doc-reconcile` | `scip-query doc-drift --json --full`, `scip-query doc-drift <doc>`, `scip-query outline <subject-file>` |
-| `scip-explore` | `scip-query stats`, `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>` |
-| `scip-hyper-optimization` | `scip-query bench --json`, `scip-query bench --json --cold-index --include-heavy --timeout-ms 600000`, `scip-query work-audit <profile> --json` |
-| `scip-language-playbook` | `scip-query stats`, `scip-query files <feature-or-module-name>`, `scip-query outline <file>` |
-| `scip-maintainability` | `scip-query stats`, `scip-query system <scope>`, `scip-query surface <scope>` |
-| `scip-probe-reachability` | `scip-query outline <file> --signatures`, `scip-query code <symbol>`, `scip-query trace <symbol>` |
-| `scip-react-maintainability` | `scip-query react-component-duplicates --scope <scope> --full --json`, `scip-query react-hook-candidates --scope <scope> --full --json`, `scip-query react-large-component-pressure --scope <scope> --full --json` |
-| `scip-root-cause` | `scip-query trace <mechanism-symbol>`, `scip-query co-change <fix-site-file>`, `scip-query system <system-scope>` |
-| `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --json` |
-| `scip-tla-model-system` | `scip-query tla scaffold <file>`, `scip-query tla verify <spec>`, `scip-query tla instrument <spec>` |
-| `scip-triage-issue` | `scip-query files <issue-term>`, `scip-query trace <entry-or-error-symbol>`, `scip-query code <entry-or-error-symbol>` |
-| `scip-twin-drift` | `scip-query twin-drift --json --full`, `scip-query duplicate-bodies --json --full`, `scip-query code <symbol>` |
-| `scip-verify` | `scip-query doctor`, `scip-query status --capabilities`, `scip-query diff-impact --json` |
-| `scip-vue-maintainability` | `scip-query augment-vue --project <path-to-tsconfig>`, `scip-query vue-component-duplicates --scope <scope> --full --json`, `scip-query vue-composable-candidates --scope <scope> --full --json` |
+| `scip-audit` | `scip-query health --json`, `scip-query decorative-checkers --json --full`, `scip-query doc-drift --json --full` |
+| `scip-diagnose` | `scip-query files <feature-or-error-term>`, `scip-query trace <candidate-symbol>`, `scip-query call-graph <entry-symbol>` |
+| `scip-explore` | `scip-query system <module-or-scope>`, `scip-query trace <entry-symbol>`, `scip-query affected <symbol> --json` |
+| `scip-improve` | `scip-query cleanup-plan --verify --json`, `scip-query cleanup-apply --verified --batch <n>`, `scip-query diff-gate --json --compact` |
+| `scip-plan` | `scip-query plan-context <target>`, `scip-query refs <symbol>`, `scip-query affected <symbol> --json` |
+| `scip-setup` | `scip-query setup --json`, `scip-query doctor`, `scip-query status --capabilities` |
+| `scip-verify` | `scip-query doctor`, `scip-query diff-impact --json`, `scip-query diff-gate --json --compact` |
 <!-- END GENERATED ROUTER COMMAND PREVIEW -->

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

@@ -1,4 +1,4 @@
 interface:
   display_name: "SCIP Query Router"
-  short_description: "Route codebase work to SCIP skills"
-  default_prompt: "Use $scip-query to choose the right SCIP-backed workflow for this codebase task."
+  short_description: "Route a codebase task to the right SCIP skill"
+  default_prompt: "Use $scip-query first to pick the right SCIP-backed skill for this task before doing anything else."

package/skills/scip-setup/SKILL.md

@@ -1,206 +1,92 @@
 ---
 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."
+    when: "Bootstrap or repair the complete repository setup."
   - 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."
+    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 | When |
-| --- | --- | --- |
-| `scip-query setup --json` | Bootstrap this project: enable automatic indexing, install agent skills, refresh the index, verify capabilities, and report health | Run setup: install skills, refresh the index, report health. |
-| `scip-query doctor` | Diagnose config, index freshness, dependency readiness, and project capabilities | Resolve blockers: human diagnostic for config, index, and dependencies. |
-| `scip-query status --json` | Show index status for this project | Resolve blockers: machine surface for freshness and config. |
-| `scip-query capabilities --matrix` | Report which evidence and verification capabilities are available in this project | Resolve blockers: which evidence/verification capabilities are available. |
-| `scip-query config-validate --json` | Validate .scipquery.json, including structured suppressions and declared coupling groups | Resolve blockers: validate .scipquery.json. |
-| `scip-query init` | Create a .scipquery.json config file for this project | Calibrate config: create .scipquery.json only when absent and needed. |
+| 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` | 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.
+## Triage: which scenario applies
 
-## 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.
+| 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) |
 
-## What Setup Owns
+## The core scenario
 
-`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.
-
-## Workflow
-
-### 1. Confirm the root
-
-```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
@@ -219,3 +105,6 @@ Runtime:
 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`.