codebaseiq 0.1.0

package/docs/COMMAND_REFERENCE.md

@@ -0,0 +1,294 @@
+# Command reference
+
+This syntax catalog is generated from the CLI command descriptors. Locate an
+exact root with `search`, `outline`, or `entrypoints`; project explicitly chosen
+relationships with `evidence`; then read behavior or source only for a named
+remaining gap. Compatibility views are listed but are not part of that canonical
+workflow.
+
+<!-- BEGIN GENERATED COMMAND REFERENCE -->
+
+This syntax summary is generated from the CLI command descriptors. Keep workflow guidance hand-authored, but keep command syntax, descriptions, and option flags descriptor-owned.
+
+Commands with `--json` share three structured modes: plain `--json` emits the stable public envelope, `--json --result-only` emits only the command payload, and `--json --compact` minifies either form for a program. Agents should prefer ordinary human output. See [CLI output modes](CLI_JSON_OUTPUT.md).
+
+Every command accepts `--output-page-size <characters>` and `--output-cursor <cursor>`. Run normally without choosing a page size: oversized human output stays readable text and prints one exact continuation command; oversized JSON prints the exact command that opts into versioned JSON page envelopes.
+Cross-command evidence citations are off by default. With an explicit `CODEBASEIQ_SESSION`, a complete source unit, a byte-identical exact subset of a prior exact source read, or a graph unit/edge may be replaced by a visible receipt from the same index generation. Preview coverage never suppresses an exact unit; changed bytes, changed graph content, a new generation, or global `--reemit` force full evidence.
+
+### Exploration control manual
+
+The operator chooses the material question and deliberately selects a control. These contracts describe observations; they do not infer task relevance.
+
+| Stage | Control | Question answered | Required input | Returned fact | Evidence ceiling | Does not establish | Cost | Contrast | Close a gap with |
+|---|---|---|---|---|---|---|---|---|---|
+| locate | `search <exact-text>` | Where does this exact text occur in current project text, and which aligned compiler symbol owns each line? | One exact text literal or deliberately bounded regular expression; insert \`--\` before a literal that starts with a dash. | exact cardinality, bounded identities and source, and scope commands that recover withheld matches | Exact current-text cardinality and locations within reported text coverage; compiler ownership only where aligned. | Structural source ranking orders exact matches but does not establish task relevance. A literal co-occurrence does not establish a graph relationship. | `small` | outline: search locates exact text across files; outline enumerates compiler-owned constructs in one known file. | `evidence`, `inspect`, `code` |
+| locate | `outline <file>` | What symbols and nesting exist in this file? | One exact current project file path. | symbol names, nesting, and line ranges | Exact compiler-owned constructs and ranges when the file is indexed; no invented semantic overlay. | File ownership and nesting do not establish execution or task relevance. | `small` | search: outline enumerates constructs in one known file; search locates exact text across current project text. code: outline returns identities and ranges; code materializes exact source for selected identities. | `evidence`, `inspect`, `code` |
+| locate | `entrypoints [text]` | Which detected external roots or entry-surface candidates match this text? | Optional exact text to filter candidates; otherwise the current indexed repository. | entry symbols with files, confidence, evidence, and indexed caller counts | Source/compiler-grounded entry evidence and indexed caller counts; exported-only candidates remain candidates. | A package-public export or zero indexed callers is an entry candidate, not proof of runtime ingress. Entry classification does not establish that the callable executes. | `bounded` | entry-map: entrypoints locates possible external roots; entry-map traverses static calls from one selected root. search: entrypoints classifies callable roots; search only locates exact text and ownership. | `evidence`, `inspect`, `code` |
+| project | `evidence` | Which exact execution, runtime, data, state, temporal, contract, identity, ownership, or dependency relationships surround these referents? Which related source must be read only when graph evidence leaves a named implementation gap? | One or more exact symbol, file:line, or literal roots plus explicit family, direction, depth, and output bound. | batched exact selectors and typed graph relationships; compact endpoints with exact locations and follow-up commands; coverage and recoverable omissions; exact source-recovery command when source was requested with a graph projection; explicit ambiguity failure with exact rerun commands | Typed edges only to each registered provider ceiling within the explicitly selected projection and reported coverage. | The projection does not infer which relationships are relevant to the user task. Reference, dependency, data, state, temporal, contract, and identity edges do not become execution claims. | `bounded` | refs: refs enumerates direct reference sites; evidence traverses explicitly selected typed relationships. call-graph: call-graph specializes in static calls; evidence can combine execution with other selected families. value-flow: value-flow specializes in proved transfers; evidence projects bounded dataflow alongside other families. dependence-slice: dependence-slice computes a program-dependence slice; evidence performs bounded graph projection. | `inspect`, `code` |
+| read | `inspect` | Which related source units across several known text, symbol, or location anchors should be read together? | One or more exact text, symbol, or file:line selectors naming the unresolved behavior. | one ranked, deduplicated semantic packet plus exact selector cardinality and explicit expansion coverage | Complete current source for every materialized syntax unit; bounded selector and packet coverage remain explicit. | A source packet does not choose which implementation details are relevant to the user task. A reference mention does not establish executable reachability. | `potentially-large` | code: inspect batches bounded behavior or source gaps; code materializes complete exact source. evidence: inspect reads implementation units; evidence projects typed relationships without source. | - |
+| read | `code <selectors...>` | What exact source defines these symbols, ranges, or file surfaces? | One or more exact symbols, file:line ranges, or file paths. | per-selector resolution, complete definition source, exact ranges with statically attributed same-file call closure, file export surfaces, omitted-local ledgers, and line ranges | Exact current source bytes for every resolved selector, with omitted file-local constructs disclosed. | Source materialization does not establish callers, runtime reachability, or task relevance by itself. | `potentially-large` | inspect: code materializes complete exact source; inspect batches bounded behavior or source gaps. outline: code reads selected implementations; outline enumerates file structure without reading every body. | - |
+
+### Relationship question manual
+
+| Material question | Family | Direction | Establishes | Reported strengths | Provider ceilings | Does not establish |
+|---|---|---|---|---|---|---|
+| Who can call or reach this? | `execution` | `incoming` | Static may-call reachability between resolved program constructs. | `exact`, `derived`, `mixed` | `partial` | A may-call edge does not prove that a runtime invocation occurred. |
+| What can this call or reach? | `execution` | `outgoing` | Static may-call reachability between resolved program constructs. | `exact`, `derived`, `mixed` | `partial` | A may-call edge does not prove that a runtime invocation occurred. |
+| Where can this value come from? | `dataflow` | `incoming` | A value, definition, argument, parameter, return, or statically resolved value may flow to another construct. | `exact`, `derived`, `mixed`, `candidate` | `partial`, `candidate` | Current partial providers do not establish general interprocedural definition-use coverage. |
+| Where can this value go? | `dataflow` | `outgoing` | A value, definition, argument, parameter, return, or statically resolved value may flow to another construct. | `exact`, `derived`, `mixed`, `candidate` | `partial`, `candidate` | Current partial providers do not establish general interprocedural definition-use coverage. |
+| Which producer and consumer rendezvous? | `runtime` | `both` | A source-grounded handoff between producer and consumer participants through a runtime mechanism. | `exact`, `derived`, `candidate`, `mixed` | `partial` | An unresolved or candidate join does not prove a runtime handoff. |
+| What resource is observed or changed? | `state` | `both` | A construct reads, writes, creates, deletes, or otherwise changes an identified state resource. | `exact` | `partial` | A state edge does not prove transactionality, durability, or exclusive ownership unless qualified. |
+| What occurs before or after this? | `temporal` | `both` | One observed construct is locally ordered before or after another under the reported source evidence. | `exact`, `derived`, `mixed` | `partial` | Source order does not imply cross-process happens-before or durability. |
+| What interface constrains this? | `contract` | `both` | A program construct implements, constrains, or is typed by an identified contract. | `exact`, `derived`, `mixed` | `exact` | Contract identity does not prove runtime invocation or conformance outside reported checks. |
+| Are these observations the same entity? | `identity` | `both` | Two observations refer to the same compiler-owned or source-owned program entity. | `exact`, `derived`, `mixed` | `exact` | Shared identity does not establish execution or value transfer. |
+| What contains or owns this? | `ownership` | `both` | A source construct, symbol, runtime observation, or state resource is contained or owned by another program entity. | `exact`, `derived`, `mixed` | `exact` | Structural ownership does not establish lifetime, singleton scope, or runtime execution unless qualified. |
+| What does this statically rely on? | `dependencies` | `outgoing` | A file, module, or symbol statically relies on another indexed entity. | `exact`, `derived`, `mixed` | `partial` | A dependency edge does not establish that the depended-on code executes. |
+
+### Evidence strength legend
+
+| Strength | Meaning |
+|---|---|
+| `exact` | Direct compiler or source evidence establishes this relationship within the provider's reported coverage. |
+| `derived` | A deterministic analysis computed this relationship from reported input facts; it was not directly observed. |
+| `candidate` | Ambiguous or heuristic evidence identifies a lead that requires exact graph or source confirmation. |
+| `mixed` | The relationship combines evidence of different strengths; its constituent methods and strengths remain disclosed. |
+| `unknown` | The relationship has no calibrated evidence strength and cannot support a stronger claim than its raw observation. |
+
+### Agent operation catalogue
+
+| Operation | Commands |
+|---|---|
+| Locate exact roots | `search <exact-text>`, `outline <file>`, `fan-in [symbol]`, `entrypoints [text]` |
+| Project typed relationships | `evidence`, `entry-map <entry>` |
+| Read selected behavior/source | `inspect`, `code <selectors...>` |
+| Analyze declared result units | `stats`, `files <pattern>`, `methods <className>`, `refs <symbol>`, `trace <symbol>`, `deps <file>`, `rdeps <file>`, `system <module>`, `surface <module>`, `dead [scope]`, `hotspots`, `imports <file>`, `imported-by <symbol>`, `unused-imports <file>`, `members <symbol>`, `fan-out [file]`, `coupling [file1] [file2]`, `cycles`, `architecture`, `bottlenecks`, `isolated`, `by-kind <kind>`, `kind-counts`, `dependency-depth`, `hierarchy <symbol>`, `call-graph <symbol>`, `similar [symbol] [other]`, `similar-files [file]`, `react-component-duplicates [file]`, `react-hook-candidates [file]`, `react-large-component-pressure [file]`, `vue-component-duplicates [file]`, `vue-composable-candidates [file]`, `vue-large-view-pressure [file]`, `similar-chains`, `extract-candidates`, `locality-candidates [symbol-or-file]`, `affected <symbol>`, `change-surface <file>`, `cleanup-plan`, `co-change [file]`, `recent-duplicates`, `doc-drift [doc]`, `unused-params`, `incomplete-migration`, `context <target>`, `drift [module]`, `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `complexity-hotspots`, `self-audit`, `complexity <symbol>`, `reference-neighborhood <symbol>`, `value-flow <symbol>`, `dependence-slice <symbol-or-location>`, `reference-reachability <symbol>`, `redundant-reexports`, `duplicate-bodies`, `twin-drift`, `twin-ab <symbolA> <symbolB>`, `not-implemented`, `decorative-checkers`, `test-quality`, `similar-signatures`, `diff-impact`, `check-deps`, `capabilities`, `config-validate`, `doctor`, `status` |
+| Maintain repository/tool state | `reindex`, `augment-sources`, `augment-vue`, `session`, `tla <operation> [spec]`, `health`, `install-skills`, `init`, `suppress <id>`, `setup`, `setup-agent`, `uninstall`, `watch` |
+
+### Typed relationship meanings
+
+| Family | Establishes | Does not establish | Providers |
+|---|---|---|---|
+| `execution` | Static may-call reachability between resolved program constructs. | A may-call edge does not prove that a runtime invocation occurred. | SCIP/compiler identity and source ownership, parser-proved intraprocedural control dependence, TypeScript compiler identities, control-flow graph, and reaching definitions |
+| `runtime` | A source-grounded handoff between producer and consumer participants through a runtime mechanism. | An unresolved or candidate join does not prove a runtime handoff. | source-grounded runtime-boundary joins |
+| `dataflow` | A value, definition, argument, parameter, return, or statically resolved value may flow to another construct. | Current partial providers do not establish general interprocedural definition-use coverage. | source-grounded runtime-boundary joins, compiler callsites and bounded static value evaluation, TypeScript compiler identities, control-flow graph, and reaching definitions, parser-proved local state and temporal facts |
+| `state` | A construct reads, writes, creates, deletes, or otherwise changes an identified state resource. | A state edge does not prove transactionality, durability, or exclusive ownership unless qualified. | parser-proved local state and temporal facts |
+| `temporal` | One observed construct is locally ordered before or after another under the reported source evidence. | Source order does not imply cross-process happens-before or durability. | source-grounded runtime-boundary joins, parser-proved local state and temporal facts |
+| `contract` | A program construct implements, constrains, or is typed by an identified contract. | Contract identity does not prove runtime invocation or conformance outside reported checks. | SCIP/compiler identity and source ownership |
+| `identity` | Two observations refer to the same compiler-owned or source-owned program entity. | Shared identity does not establish execution or value transfer. | SCIP/compiler identity and source ownership |
+| `ownership` | A source construct, symbol, runtime observation, or state resource is contained or owned by another program entity. | Structural ownership does not establish lifetime, singleton scope, or runtime execution unless qualified. | SCIP/compiler identity and source ownership |
+| `dependencies` | A file, module, or symbol statically relies on another indexed entity. | A dependency edge does not establish that the depended-on code executes. | SCIP/compiler identity and source ownership |
+
+### Typed relationship providers
+
+| Provider | Family / subtype | Directions | Support ceiling | Establishes | Does not establish |
+|---|---|---|---|---|---|
+| `indexed-program-identity` | `execution/call` | `incoming`, `outgoing`, `both` | `partial` | The source construct may call the resolved target. | Static may-call reachability does not prove that an invocation occurred at runtime. |
+| `indexed-program-identity` | `execution/result-callback` | `incoming`, `outgoing`, `both` | `partial` | The referenced callable can produce the result consumed by this path. | A callback relationship does not prove invocation order or runtime selection. |
+| `indexed-program-identity` | `contract/uses-contract-symbol` | `incoming`, `outgoing`, `both` | `exact` | The source construct refers to the identified contract symbol. | Contract identity does not prove runtime invocation or behavioral conformance. |
+| `indexed-program-identity` | `identity/references` | `incoming`, `outgoing`, `both` | `exact` | The occurrence resolves to the identified compiler-owned symbol. | A reference does not establish execution or value transfer. |
+| `indexed-program-identity` | `ownership/contains` | `incoming`, `outgoing`, `both` | `exact` | The owner contains the identified program construct. | Structural containment does not establish runtime lifetime or sharing scope. |
+| `indexed-program-identity` | `ownership/contains-*` | `incoming`, `outgoing`, `both` | `exact` | The owner contains the identified program construct. | Structural containment does not establish runtime lifetime or sharing scope. |
+| `indexed-program-identity` | `ownership/owns-*` | `incoming`, `outgoing`, `both` | `exact` | The owner owns the identified source or runtime observation. | Observation ownership does not establish singleton lifetime or exclusive ownership. |
+| `indexed-program-identity` | `dependencies/imports` | `incoming`, `outgoing`, `both` | `partial` | The source file or module statically imports the indexed target. | An import does not establish that imported code executes. |
+| `indexed-program-identity` | `dependencies/imports-external` | `incoming`, `outgoing`, `both` | `partial` | The source region statically imports an external package. | An external import does not establish which package behavior executes. |
+| `runtime-boundary-join` | `runtime/runtime-handoff` | `incoming`, `outgoing`, `both` | `partial` | A producer and consumer share a source-grounded runtime rendezvous. | A candidate or unresolved join does not prove a runtime handoff. |
+| `runtime-boundary-join` | `runtime/discriminator-dispatch` | `incoming`, `outgoing`, `both` | `partial` | A serialized discriminator selects the reported consumer. | The dispatch edge does not prove delivery, retry, or successful handling. |
+| `runtime-boundary-join` | `dataflow/serialized-discriminator-transfer` | `incoming`, `outgoing`, `both` | `partial` | The producer serializes the discriminator consumed by dispatch. | This edge does not establish the flow of every payload field. |
+| `runtime-boundary-join` | `temporal/enqueue-before-consume` | `incoming`, `outgoing`, `both` | `partial` | The reported enqueue precedes a possible consume through the queue. | Queue order does not establish delivery time, uniqueness, retry count, or durability. |
+| `parser-control-dependence` | `execution/predicate-consequence` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/predicate-alternative` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/predicate-fallthrough` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/predicate-case` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/predicate-default` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/predicate-return` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/predicate-throw` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/loop-iteration` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/loop-exit` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/exception-handler` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/finally-cleanup` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/handler-return` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/handler-throw` | `incoming`, `outgoing`, `both` | `partial` | The outcome is control-dependent on the reported predicate or handler. | Local control dependence does not establish that the containing function executes. |
+| `parser-control-dependence` | `execution/returns` | `incoming`, `outgoing`, `both` | `partial` | The selected construct contains the reported return terminal. | A local return terminal does not establish that the containing callable executes. |
+| `parser-control-dependence` | `execution/throws` | `incoming`, `outgoing`, `both` | `partial` | The selected construct contains the reported throw terminal. | A local throw terminal does not establish propagation, handling, or callable execution. |
+| `bounded-static-value-flow` | `dataflow/argument-to-parameter` | `incoming`, `outgoing`, `both` | `partial` | The reported value may reach the target through the evidenced callsite transfer. | This provider does not establish general local definition-use, alias, field, or heap flow. |
+| `bounded-static-value-flow` | `dataflow/constant-to-parameter` | `incoming`, `outgoing`, `both` | `partial` | The reported value may reach the target through the evidenced callsite transfer. | This provider does not establish general local definition-use, alias, field, or heap flow. |
+| `bounded-static-value-flow` | `dataflow/property-to-parameter` | `incoming`, `outgoing`, `both` | `partial` | The reported value may reach the target through the evidenced callsite transfer. | This provider does not establish general local definition-use, alias, field, or heap flow. |
+| `bounded-static-value-flow` | `dataflow/return-to-parameter` | `incoming`, `outgoing`, `both` | `partial` | The reported value may reach the target through the evidenced callsite transfer. | This provider does not establish general local definition-use, alias, field, or heap flow. |
+| `bounded-static-value-flow` | `dataflow/return-to-call-result` | `incoming`, `outgoing`, `both` | `partial` | The reported value may reach the target through the evidenced callsite transfer. | This provider does not establish general local definition-use, alias, field, or heap flow. |
+| `typescript-local-dependence` | `dataflow/definition-to-use` | `incoming`, `outgoing`, `both` | `partial` | The definition reaches the reported read on a feasible local control-flow path. | Local reaching definitions do not establish heap aliasing, exceptional flow, or the runtime order of closure invocation. |
+| `typescript-local-dependence` | `dataflow/value-to-definition` | `incoming`, `outgoing`, `both` | `partial` | The reported right-hand-side read supplies the assigned local definition. | A local assignment edge does not establish field or heap points-to flow. |
+| `typescript-local-dependence` | `dataflow/closure-capture` | `incoming`, `outgoing`, `both` | `candidate` | The nested callable reads the reported binding from an enclosing callable. | Closure capture does not establish whether or when the nested callable executes. |
+| `typescript-local-dependence` | `dataflow/field-definition-to-use` | `incoming`, `outgoing`, `both` | `partial` | The reported same-owner field definition can reach the field read. | Field-name identity does not establish whole-program heap aliasing or cross-instance flow. |
+| `typescript-local-dependence` | `execution/control-dependence` | `incoming`, `outgoing`, `both` | `partial` | Execution of the reported statement depends on the outcome of the predicate. | Intraprocedural control dependence does not establish that the containing callable executes. |
+| `parser-state-temporal` | `dataflow/captured-value-to-state` | `incoming`, `outgoing`, `both` | `partial` | The reported source value is assigned into the identified state resource. | The edge does not establish alias, heap, or later read flow. |
+| `parser-state-temporal` | `dataflow/constant-to-state` | `incoming`, `outgoing`, `both` | `partial` | The reported source value is assigned into the identified state resource. | The edge does not establish alias, heap, or later read flow. |
+| `parser-state-temporal` | `dataflow/expression-to-state` | `incoming`, `outgoing`, `both` | `partial` | The reported source value is assigned into the identified state resource. | The edge does not establish alias, heap, or later read flow. |
+| `parser-state-temporal` | `dataflow/property-to-state` | `incoming`, `outgoing`, `both` | `partial` | The reported source value is assigned into the identified state resource. | The edge does not establish alias, heap, or later read flow. |
+| `parser-state-temporal` | `dataflow/return-to-state` | `incoming`, `outgoing`, `both` | `partial` | The reported source value is assigned into the identified state resource. | The edge does not establish alias, heap, or later read flow. |
+| `parser-state-temporal` | `dataflow/value-to-state` | `incoming`, `outgoing`, `both` | `partial` | The reported source value is assigned into the identified state resource. | The edge does not establish alias, heap, or later read flow. |
+| `parser-state-temporal` | `state/writes-resource` | `incoming`, `outgoing`, `both` | `partial` | The reported construct performs the named operation on the identified resource. | A state operation does not establish transactionality, durability, or exclusive ownership. |
+| `parser-state-temporal` | `state/deletes-resource` | `incoming`, `outgoing`, `both` | `partial` | The reported construct performs the named operation on the identified resource. | A state operation does not establish transactionality, durability, or exclusive ownership. |
+| `parser-state-temporal` | `state/reads-resource` | `incoming`, `outgoing`, `both` | `partial` | The reported construct performs the named operation on the identified resource. | A state operation does not establish transactionality, durability, or exclusive ownership. |
+| `parser-state-temporal` | `state/enqueues-resource` | `incoming`, `outgoing`, `both` | `partial` | The reported construct performs the named operation on the identified resource. | A state operation does not establish transactionality, durability, or exclusive ownership. |
+| `parser-state-temporal` | `state/consumes-resource` | `incoming`, `outgoing`, `both` | `partial` | The reported construct performs the named operation on the identified resource. | A state operation does not establish transactionality, durability, or exclusive ownership. |
+| `parser-state-temporal` | `temporal/await-completion-before` | `incoming`, `outgoing`, `both` | `partial` | The reported source constructs have the named local ordering relationship. | Local source order does not establish cross-process happens-before or durable completion. |
+| `parser-state-temporal` | `temporal/awaits-completion` | `incoming`, `outgoing`, `both` | `partial` | The reported source constructs have the named local ordering relationship. | Local source order does not establish cross-process happens-before or durable completion. |
+| `parser-state-temporal` | `temporal/inside-lock-scope` | `incoming`, `outgoing`, `both` | `partial` | The reported source constructs have the named local ordering relationship. | Local source order does not establish cross-process happens-before or durable completion. |
+| `parser-state-temporal` | `temporal/lexical-successor` | `incoming`, `outgoing`, `both` | `partial` | The reported source constructs have the named local ordering relationship. | Local source order does not establish cross-process happens-before or durable completion. |
+
+### Explicitly unavailable relationship analyses
+
+An unavailable frontier is a relationship class for which no registered analyzer can provide complete evidence. Its absence from a graph is therefore not evidence that the relationship does not exist.
+
+| Frontier | Families | Unavailable capability | Consequence | Recover selected paths with |
+|---|---|---|---|---|
+| `general-interprocedural-value-flow` | `dataflow` | Whole-program definition-use flow through arbitrary calls and returns is unavailable. | Missing dataflow edges cannot establish that a value never crosses an unmodeled call. | `value-flow`, `dependence-slice`, `inspect`, `code` |
+| `heap-aliasing` | `dataflow`, `state` | Heap points-to and cross-instance alias analysis are unavailable. | Missing field or state edges cannot establish that two references never reach the same object. | `value-flow`, `dependence-slice`, `inspect`, `code` |
+| `exceptional-flow` | `execution`, `dataflow`, `temporal` | Interprocedural exception propagation and finally completion flow are unavailable. | Normal-path reachability and ordering do not establish behavior after a throw or rejection. | `dependence-slice`, `inspect`, `code` |
+| `reflection` | `execution`, `runtime`, `identity`, `dependencies` | Reflective lookup, dynamic loading, and name-computed invocation are unavailable without exact evidence. | Missing static edges cannot establish that a construct is unreachable through reflection. | `search`, `inspect`, `code` |
+| `generated-dispatch` | `execution`, `runtime`, `identity` | Dispatch tables or names created only by generated or unavailable source are unavailable. | Missing dispatch edges cannot establish that no generated consumer exists. | `search`, `inspect`, `code` |
+| `unsupported-framework-adapters` | `runtime`, `dataflow`, `state`, `temporal` | Framework runtime crossings without a registered source adapter are unavailable. | Missing boundary edges cannot establish that no producer, consumer, state effect, or ordering exists. | `search`, `inspect`, `code` |
+
+### Indexing
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `reindex` | Index the codebase and convert to SQLite | variable | - | `-l, --language <lang>`<br>`--pnpm-workspaces`<br>`--force`<br>`--allow-partial`<br>`--trust-project-tools`<br>`--install-missing`<br>`--indexer-concurrency <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `augment-sources` | Add source files skipped by upstream SCIP indexers to the SQLite documents table | variable | - | - |
+| `augment-vue` | Add compiler-resolved Vue SFC references to the SQLite index using Volar | variable | - | `--project <tsconfig>` |
+
+### Core
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `stats` | Show index statistics | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+
+### Navigation
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `files <pattern>` | Find current project files matching a path pattern | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `session` | Show evidence already delivered in this agent exploration session | variable | - | `--reset` |
+| `inspect` | Batch related searches, symbols, and source locations into one deduplicated source packet | potentially-large | - | `--search <text>`<br>`--symbol <symbol>`<br>`--at <file:line>`<br>`-s, --scope <path>`<br>`-C, --context <n>`<br>`-n, --limit <n>`<br>`--max-units <n>`<br>`--max-characters <n>`<br>`--view <view>`<br>`--allow-large-source`<br>`--allow-large-behavior`<br>`--unit-lines <n>`<br>`--total-lines <n>`<br>`--include <part>`<br>`--evidence-budget <channel=n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `search <exact-text>` | Count current project text matches and preview a bounded, recoverable identity and source manifest | small | `evidence`, `inspect`, `code` | `-s, --scope <path>`<br>`-C, --context <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--regexp`<br>`-i, --ignore-case`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `methods <className>` | List methods of one exactly resolved class; ambiguity and missing targets fail explicitly | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `refs <symbol>` | Find all files referencing a symbol | bounded | `inspect`, `code` | `--full`<br>`-n, --limit <n>`<br>`--cursor <cursor>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `trace <symbol>` | Trace a symbol: definition + all references | bounded | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `evidence` | Traverse selected typed relationships around exact referents; recover source separately when needed | bounded | `inspect`, `code` | `--symbol <symbol>`<br>`--at <file:line>`<br>`--search <literal>`<br>`--view <view>`<br>`--edge <family>`<br>`--direction <direction>`<br>`--subtype <subtype>`<br>`--connecting`<br>`--inventory-only`<br>`--fold <id>`<br>`--depth <n>`<br>`--max-edges <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `deps <file>` | Files this file depends on (internal) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `rdeps <file>` | Files that depend on this file/module | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `system <module>` | One-hop module summary: matched files, documented symbols, and file reference dependencies | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `surface <module>` | What symbols consumers actually use from this module | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `imports <file>` | What symbols does this file import? | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `imported-by <symbol>` | Which files import this symbol? | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `outline <file>` | Tree view of symbols in a file, with line ranges | small | `evidence`, `inspect`, `code` | `--signatures`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `members <symbol>` | All children of a symbol (methods, fields, nested types) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `by-kind <kind>` | Find symbols by SCIP kind (class, interface, enum, function, etc.) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `kind-counts` | Histogram of symbol kinds in the codebase | bounded | `inspect`, `code` | `-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `hierarchy <symbol>` | Show a symbol's ancestry chain (method → class → module) | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `code <selectors...>` | Read exact definitions, ranges with local call closure, or file export surfaces | potentially-large | - | `-C, --context <n>`<br>`--members <exported|all>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `reference-neighborhood <symbol>` | Show definition/reference sites and incoming/outgoing static calls without value-flow claims | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `value-flow <symbol>` | Show only proved argument/parameter and bounded static-value transfers around a symbol | variable | `inspect`, `code` | `--depth <n>`<br>`--max-edges <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `dependence-slice <symbol-or-location>` | Directional slice over proved data/control dependencies with explicit supporting call edges | variable | `inspect`, `code` | `--forward`<br>`--depth <n>`<br>`--max-edges <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `reference-reachability <symbol>` | Traverse legacy callee or reference-owner reachability without calling it a program slice | variable | `inspect`, `code` | `--forward`<br>`--depth <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Cleanup
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `dead [scope]` | Find repository-dead code, file-internal symbols, and implicit-usage signals | variable | `inspect`, `code` | `--min-loc <n>`<br>`--include-tests`<br>`--skip-barrels`<br>`--include-members`<br>`--only-dead`<br>`--only-internal`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `unused-imports <file>` | Find imports not referenced in the same file | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `isolated` | Find completely orphaned symbols (no references at all) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `similar [symbol] [other]` | Find heuristic function similarity candidates from callee fingerprints | variable | `inspect`, `code` | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-callees <n>`<br>`--cross-file-only`<br>`--plan`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `similar-files [file]` | Find heuristic similar-file candidates from dependency profiles | variable | `inspect`, `code` | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-deps <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `react-component-duplicates [file]` | Find heuristic duplicated React component structure candidates from JSX tags, props, events, and bindings | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `react-hook-candidates [file]` | Find heuristic React hook extraction candidates from shared state, effects, requests, and handlers | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `react-large-component-pressure [file]` | Find heuristic large React component pressure candidates from component lines, JSX structure, and hook behavior | variable | `inspect`, `code` | `--min-component-lines <n>`<br>`--min-file-lines <n>`<br>`--min-jsx-tokens <n>`<br>`--min-behavior-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `vue-component-duplicates [file]` | Find heuristic duplicated Vue component structure candidates from template tags, bindings, slots, and directives | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-tokens <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `vue-composable-candidates [file]` | Find heuristic Vue composable extraction candidates from shared state, effects, requests, and template bindings | variable | `inspect`, `code` | `--min-similarity <n>`<br>`--min-shared-behaviors <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `vue-large-view-pressure [file]` | Find heuristic large Vue view pressure candidates from template, script, style, and external script line counts | variable | `inspect`, `code` | `--min-total-lines <n>`<br>`--min-template-lines <n>`<br>`--min-script-lines <n>`<br>`--min-style-lines <n>`<br>`--review-thresholds`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `similar-chains` | Find heuristic similar-chain candidates from dependency flows | variable | `inspect`, `code` | `--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-length <n>`<br>`--max-length <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `extract-candidates` | Find heuristic extraction candidates from isolated callee clusters | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--min-callees <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `locality-candidates [symbol-or-file]` | Find directory-locality and ancestry candidates from consumer ownership | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-consumers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `cleanup-plan` | Ordered, batched deletion plan: graph-fact dead code plus the cascade candidates it unlocks | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-depth <n>`<br>`--verify`<br>`--patch`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `recent-duplicates` | Directional duplicate candidates: recent code that re-implements established callable, React, or Vue code | variable | `inspect`, `code` | `--window <n>`<br>`--min-similarity <n>`<br>`-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `doc-drift [doc]` | Stale-doc candidates: code the doc references or co-changed with kept changing after the doc stopped | variable | `inspect`, `code` | `-n, --limit <n>`<br>`--min-coupling <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `unused-params` | Speculative-generality candidates: trailing parameters no body ever uses (TS/JS) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `drift [module]` | Detect drift candidates: unused imports and declared architecture violations; pass --architecture for boundary context | variable | `inspect`, `code` | `--min-deviation <n>`<br>`--patterns`<br>`--architecture`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `wrapper-candidates` | Find heuristic wrapper candidates only called by one consumer (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `passthrough-candidates` | Find heuristic passthrough candidates that forward to one callee | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--max-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `stale-abstractions` | Find heuristic stale abstraction candidates with 0-1 consumers (high false-positive rate on codebases with intentional layering/ambient types — treat as exploration, not findings) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--include-low-confidence`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `complexity-hotspots` | Find heuristic complexity hotspot candidates from LOC x fan-in x fan-out | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `redundant-reexports` | Find barrel re-exports that nobody imports through | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `duplicate-bodies` | Find exact duplicate small-body candidates across files | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--max-loc <n>`<br>`--min-loc <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `twin-drift` | Twin drift candidates: same-name (or near-name) functions across files with diverged bodies | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-similarity <n>`<br>`--include-homonyms`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `twin-ab <symbolA> <symbolB>` | Generate a behavioral A/B scaffold comparing two same-concept twins (cleanup integrity scenario) — a ready-to-fill vitest file, not an auto-executor | bounded | `inspect`, `code` | `--out <path>`<br>`--force`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `not-implemented` | Reachable placeholder stub candidates (throw-stub, TODO+return-default, empty body) — production callers can actually reach these; an unreachable stub is dead's job, not this one's | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `decorative-checkers` | Decorative checker candidates: validate*/verify*/check*/assert*/is*/has* callables with no reachable failure exit anywhere in their body | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `test-quality` | Test-quality candidates: assertion-free it/test bodies, a skipped-test ledger with git-blame age, and mock-echo tests that assert the same literal they stubbed into a mock | variable | `inspect`, `code` | `-s, --scope <path>`<br>`-n, --limit <n>`<br>`--rot-days <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `similar-signatures` | Find functions with near-identical type signatures (same shape) | variable | `inspect`, `code` | `-s, --scope <path>`<br>`--min-loc <n>`<br>`--max-shape-frequency <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Graph
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `hotspots` | Rank symbols by cross-file reference count; a reference metric, not runtime contention | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `fan-in [symbol]` | Count files referencing an exact symbol; top JSON rows include exact symbol identity | small | `evidence`, `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `fan-out [file]` | How many external symbols a file uses (or top fan-out across codebase) | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `coupling [file1] [file2]` | Count shared-symbol coupling between two files, or rank file pairs by that metric | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `cycles` | Find every cyclic file-dependency component and show one deterministic witness for each | bounded | `inspect`, `code` | `-s, --scope <path>`<br>`--imports-only`<br>`--max-depth <n>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `architecture` | Evaluate project-owned architectural boundaries and dependency rules | bounded | `inspect`, `code` | `-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `bottlenecks` | Rank coordination hubs by incoming evidence files × outgoing cross-file callable targets | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-fan-in <n>`<br>`--min-fan-out <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `dependency-depth` | Find longest paths through the SCC-condensed file dependency graph | variable | `inspect`, `code` | `-n, --limit <n>`<br>`-s, --scope <path>`<br>`--min-depth <n>`<br>`--imports-only`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `entrypoints [text]` | Find callables where control may enter from outside the indexed call graph | bounded | `evidence`, `inspect`, `code` | `-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `entry-map <entry>` | Map the complete indexed call graph from one detected entry point, collapsed by file | bounded | `inspect`, `code` | `--expand <region-id>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `call-graph <symbol>` | Show static may-call edges with exact/candidate evidence and explicit blind spots | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Impact
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `affected <symbol>` | Conservative reverse caller/reference closure of symbols that may be impacted by a change | variable | `inspect`, `code` | `--full`<br>`--max-depth <n>`<br>`-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `change-surface <file>` | Pre-change briefing: consumers, published API, operational roots, and explained change risk | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `co-change [file]` | Files that change together in git history without a dependency edge — hidden coupling candidates | variable | `inspect`, `code` | `--min-together <n>`<br>`-n, --limit <n>`<br>`--all`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `incomplete-migration` | Partially-completed extraction candidates: new helpers in the diff wired into some sites while similar un-migrated sites remain | variable | `inspect`, `code` | `--base <ref>`<br>`--min-containment <n>`<br>`--max-helpers <n>`<br>`-n, --limit <n>`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `diff-impact` | Map changed symbols and downstream consumers from the current git diff | variable | `inspect`, `code` | `--base <ref>`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Formal Models
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `tla <operation> [spec]` | TLA+ model workflow: verify a model and mapping contract, scaffold a draft model from indexed code, generate a trace recorder, or check a recorded trace against the next-state relation | variable | - | `--map <file>`<br>`--config <file>`<br>`--checker <mode>`<br>`--tla-tools <jar>`<br>`--apalache <binary>`<br>`--length <n>`<br>`--timeout-ms <n>`<br>`--trace <file>`<br>`--next <operator>`<br>`--coverage`<br>`--allow-unknown`<br>`--out <path>`<br>`--module-name <name>`<br>`--force`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Exploration
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `context <target>` | Compiler-backed context for a symbol, file, or module | bounded | `inspect`, `code` | `--impact-depth <n>`<br>`--slice-depth <n>`<br>`-s, --scope <path>`<br>`-n, --limit <n>`<br>`--detail`<br>`--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Health
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `self-audit` | Score cheap evidence paths against the best available semantic/source oracle on sampled symbols | variable | `inspect`, `code` | `--samples <n>`<br>`-s, --scope <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `complexity <symbol>` | Per-symbol complexity: branches, cyclomatic estimate, fan-in/out, callees | variable | `inspect`, `code` | `--full`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `health` | Composite repository health report with React, Vue, and general cleanup findings | variable | - | `-s, --scope <path>`<br>`--full`<br>`--baseline`<br>`--write-baseline`<br>`--json`<br>`--result-only`<br>`--compact` |
+
+### Maintenance
+
+| Command | Description | Cost | Closes disclosed gaps with | Options |
+|---|---|---|---|---|
+| `install-skills` | Install skills (codebaseiq, codebaseiq-explore, concrete-plan) into Claude Code, Codex, and shared agent roots | variable | - | - |
+| `check-deps` | Check whether codebaseiq and the detected language indexers are runnable | bounded | `inspect`, `code` | - |
+| `capabilities` | Report which mapping and analysis capabilities are available in this project | bounded | `inspect`, `code` | `--matrix`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `init` | Create a .codebaseiq.json configuration file for this project | variable | - | - |
+| `config-validate` | Validate .codebaseiq.json, structured suppressions, architecture, and coupling groups | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `suppress <id>` | Record an accepted finding under .codebaseiq/suppressions with a required reason | variable | - | `--reason <text>`<br>`--reason-code <code>`<br>`--evidence <kind:referent>`<br>`--check <check>`<br>`--file <path>`<br>`--expires-at <iso>`<br>`--replace <revision>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `doctor` | Diagnose configuration, index freshness, dependencies, and project capabilities | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+| `setup` | Install skills, write agent guidance, refresh the index, and report repository health | variable | - | `--guided`<br>`--yes`<br>`--no-skills`<br>`--no-parsers`<br>`--install-missing`<br>`--no-health`<br>`--dossier-dir <path>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `setup-agent` | Write concise codebaseiq mapping and cleanup guidance to AGENTS.md and CLAUDE.md | variable | - | - |
+| `uninstall` | Remove selected codebaseiq-owned skills or project guidance | variable | - | `--global`<br>`--project`<br>`--dry-run`<br>`--verbose`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `watch` | Watch in the foreground or manage the project refresh service | variable | - | `--daemon`<br>`--status`<br>`--stop`<br>`--debounce <ms>`<br>`--cooldown <ms>`<br>`--git-poll <ms>`<br>`--idle-timeout <ms>`<br>`--json`<br>`--result-only`<br>`--compact` |
+| `status` | Show index status for this project | bounded | `inspect`, `code` | `--json`<br>`--result-only`<br>`--compact` |
+
+<!-- END GENERATED COMMAND REFERENCE -->

package/docs/CONFIGURATION_WRITE_SAFETY.md

@@ -0,0 +1,131 @@
+# Configuration and setup write safety
+
+codebaseiq updates files that people and other agents may edit at the same
+time: `.codebaseiq.json`, `.git/info/exclude`, `AGENTS.md`, `CLAUDE.md`, and
+structured suppression records. A conflict-aware writer is a file updater that transforms one
+identified revision and refuses to claim success if an independent revision
+wins before commit. Its defining behavior is preservation: it either applies
+its narrow change to the newest valid input or leaves the newest input
+untouched and reports why.
+
+## Revision and commit protocol
+
+Every participating writer:
+
+1. acquires a short, token-owned process lock beside the target;
+2. reads a stable snapshot and records its SHA-256 hash plus file identity;
+3. computes only the domain change it owns;
+4. rereads the target immediately before commit;
+5. retries the merge when the revision changed and retry is safe, or reports a
+   conflict when it is not;
+6. stages and flushes complete bytes, atomically publishes them, and flushes
+   the parent directory where the platform exposes that operation.
+
+The lock serializes codebaseiq processes. Editors do not need to participate:
+their byte or identity change is detected by the optimistic revision check.
+The lock record is token-owned and carries process identity, so a live owner
+cannot be displaced and a dead owner can be reclaimed by the shared process
+lock protocol.
+
+First creation uses a flushed staging inode plus an exclusive public hard
+link. This is stronger than `exists` followed by replacement: only one creator
+can publish, and a reader sees no public file until every byte is present.
+
+## JSON merge rules
+
+Project setup rereads the latest valid object and changes only the requested
+field. Unknown current and future fields survive. A three-way check compares
+the caller's observed value, the latest value, and the requested value:
+
+- an unrelated latest edit is preserved and the owned field is updated;
+- the requested value already present is idempotent;
+- a different latest value for the same field is an explicit stale-field
+  conflict.
+
+Malformed latest JSON is never repaired by replacement because doing so could
+erase information the writer cannot classify. The command reports the parse
+failure and leaves the exact bytes in place.
+
+### Project-config format boundary
+
+The project configuration is a durable policy record whose `schemaVersion`
+determines the meaning of its other fields. Current writers publish version 2
+and include a `$schema` URI reference to
+`docs/schemas/project-config.schema.json` in the installed package.
+Unversioned files and explicit `schemaVersion: 1` files have the same readable
+legacy meaning. They are migrated in memory and written as version 2 only when
+`init` creates a file or a setup action enters an authorized mutation path.
+
+The schema migration is part of the no-op decision. If the requested field is
+already correct but the durable record is legacy or lacks its editor-schema
+hint, the writer still publishes a current record and reports `changed: true`.
+Unknown root and nested fields survive because migration begins from the
+latest complete object and removes only the owned legacy discriminator.
+
+A collaboration domain is the merge-intended family of repository copies that
+share durable project decisions. Its real-world referents are branches,
+clones, linked worktrees, and contributor forks whose records are expected to
+rejoin; the committed `collaborationDomainId` distinguishes that family
+without confusing a filesystem path, host, or mutable remote URL for its
+identity. `init` and `setup` create one opaque UUID when it is missing. A
+concurrent winner is adopted, and later runs never rotate an established ID.
+
+A non-integer discriminator, non-object top level, invalid `$schema` hint, or
+unsupported older/future version fails before options are exposed to runtime
+consumers. The loader names the supported legacy/current versions. A setup
+writer applies the same decoder to its latest stable snapshot and leaves
+rejected bytes byte-for-byte unchanged, so upgrading the CLI—not a blind
+rewrite—is the recovery path for a future version.
+
+## Suppression policy rules
+
+A suppression identity is the stable finding ID, or the deterministic hash of
+a check-and-file target when no finding ID exists. It is a policy conflict
+domain: decisions for different identities occupy different files, while two
+decisions for the same identity must be reconciled.
+
+The first decision uses exclusive durable creation. An identical replay
+returns the existing revision without rewriting metadata. A different reason,
+expiry, check, or file requires `--replace <revision>`, where the revision is
+the full SHA-256 hash reported when the existing decision was rejected or
+created. Replacement succeeds only if those exact reviewed bytes still occupy
+the path. A stale token, a malformed record, an unsupported future schema, or
+an edit at the commit boundary leaves the latest bytes untouched.
+
+New records use suppression schema version 1 and include the
+`codebaseiq-suppression` discriminator, their stable identity, and the
+`codebaseiq` writer version. Unversioned legacy records and v1 records written
+before the discriminator was added remain readable. They remain byte-for-byte
+unchanged on an idempotent replay and are upgraded only by an explicit
+compare-and-replace policy change. Incompatible files are reported by
+`config-validate`; they never authorize a suppression.
+
+## Managed text rules
+
+Agent guidance changes only the text between the exact
+`codebaseiq:agent-setup` markers. Text before and after the block is preserved.
+Missing markers permit first installation, but incomplete, duplicated, or
+reordered markers are a conflict because the intended ownership boundary is
+ambiguous.
+
+Managed Markdown uses a strict final revision check rather than silently
+recomputing across an intervening edit. The command
+reports the expected and latest revision hashes and does not write.
+`.git/info/exclude` can safely retry because its exact owned marker block is
+recomputed from the newest text.
+
+## Recovery
+
+When a command reports a conflict:
+
+1. open the named file and preserve the latest independent edit;
+2. repair malformed JSON or marker structure deliberately, if reported;
+3. for a suppression policy change, review the latest decision and rerun
+   `suppress` with the reported `--replace <revision>`;
+4. for setup/configuration, rerun the command so it reads the new revision.
+
+Do not delete a live `.codebaseiq-write.lock`. If its owner crashed, the next
+writer reclaims it only after the shared lock protocol proves the recorded
+process identity is no longer live. A crash before publication leaves the
+previous target intact; a failed first publication leaves no partial public
+file.

package/docs/DETECTOR_GUIDE.md

@@ -0,0 +1,46 @@
+# Detector guide
+
+A detector is a repository analysis that selects source locations with a
+shared evidence pattern. Compiler-graph detectors report resolved program
+relationships. Heuristic detectors report candidates that require source
+confirmation.
+
+## Repository overview
+
+```bash
+codebaseiq health --full
+```
+
+The health report combines graph structure, duplication, drift, complexity,
+history, suppressions, coverage contracts, and React and Vue analyses. Its
+score is a summary, not proof of correctness.
+
+## Focused detector families
+
+| Concern | Commands |
+| --- | --- |
+| Exact or near duplication | `duplicate-bodies`, `similar`, `recent-duplicates` |
+| Parallel implementations | `twin-drift`, `incomplete-migration`, `drift` |
+| Unused or disconnected code | `dead`, `isolated`, `unused-params` |
+| Excess indirection | `wrapper-candidates`, `passthrough-candidates`, `stale-abstractions`, `redundant-reexports` |
+| Change pressure | `complexity-hotspots`, `co-change`, `cycles` |
+| Documentation | `doc-drift` |
+| React | `react-component-duplicates`, `react-hook-candidates`, `react-large-component-pressure` |
+| Vue | `vue-component-duplicates`, `vue-composable-candidates`, `vue-large-view-pressure` |
+| Team structure policy | `architecture` |
+
+Run focused commands through the `codebaseiq` CLI. Add `--full` only when that
+command supports it and exhaustive command coverage can change the decision.
+
+## Acting on findings
+
+1. Read the cited source.
+2. Identify the shared concept or violated rule.
+3. Preserve intentional variation.
+4. Make one coherent edit.
+5. Run native checks and the relevant detector again.
+6. Use `codebaseiq diff-impact` when downstream consumers may have changed.
+
+Suppress a false or accepted finding with `codebaseiq suppress <id>` and a
+specific reason. A suppression addresses one finding; it must not disable an
+unrelated detector family.