knodin 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Docusign, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,590 @@
+# knodin
+
+<img src="docs/assets/knodin-favicon.svg" alt="knodin caret-beak logo" width="96" height="96">
+
+> knodin remembers how your code is connected and shows what may move when it
+> changes.
+
+knodin is a native local code-intelligence engine, CLI, and one-tool MCP
+gateway. It persists and refreshes a repository graph, resolves symbols without
+hiding ambiguity, and delivers source-evidenced impact analysis, review,
+architecture maps, hybrid search, bounded context export, and lifecycle
+health/repair behind one compact local tool.
+
+| Command | Job | Modeled on |
+|---|---|---|
+| `knodin explain <symbol>` | edit-ready verbatim source + call paths + blast radius | codegraph |
+| `knodin review [base] [--scope unstaged\|staged\|all\|compare]` | risk-scored context for a selected diff; always reports changed files separately from mapped symbols | code-review-graph |
+| `knodin map` | subsystems (communities) + confidence-tagged edges | Graphify |
+
+For context efficiency, `knodin pack` exports bounded source and
+`knodin compress` reduces already-produced build/test logs under hard line and
+UTF-8 byte budgets. Compression preserves exit metadata and detected
+diagnostics, reports exact omissions, and retains private local drill-down
+without running a command. A retained failure can then be mapped to owning
+symbols and packages, related tests, callers, dependencies, recent changes,
+bounded source, and exact graph freshness with
+`knodin compress diagnose <artifact-id>`. See the
+[compression and command-security contract](docs/COMMAND-OUTPUT-COMPRESSION.md).
+
+Its core graph runs **locally, with no auth** through standard CLI and MCP
+interfaces. A generic JSON-RPC handshake is tested; named-client compatibility
+is limited to the adapters and environments actually exercised. The optional
+`prs` operation delegates to the user's authenticated `gh` CLI. An external gateway such as
+an organization’s existing MCP gateway can optionally federate it; that
+integration is not required for knodin’s engine, CLI, or MCP server.
+
+## Show me the value
+
+knodin is for an engineer or coding agent about to change unfamiliar code. It
+answers three practical questions before the edit:
+
+1. **What does this code do?** Read-ready source and resolved relationships
+   orient the next investigation.
+2. **What else could this change affect?** Diff scope, typed traversal, and
+   bounded impact evidence make the review surface explicit.
+3. **Can I adopt it tomorrow?** Run one local CLI or MCP gateway against the
+   existing repository from this source checkout or a locally built package—no
+   account, hosted index, source egress, or workflow migration.
+
+The intended value is not “AI code intelligence.” It is fewer missed
+dependencies and less manual context assembly in the orient → edit → review
+loop. Those human/agent outcomes have not yet been established by an end-to-end
+controlled study; checked-in replays measure narrower correctness, latency,
+response-size, and retrieval outcomes. The engine,
+CLI, and MCP gateway are implemented today; knodin reports only outcomes that
+its checked-in fixtures and replays support. See
+[`roadmap/competitive-roadmap.md`](roadmap/competitive-roadmap.md) for the
+current evidence and known gaps.
+
+## What is the ROI?
+
+knodin compresses repeated “find the definition, read it, find callers, inspect
+the diff, locate tests” work into bounded, source-evidenced calls. That means
+fewer agent round trips, less duplicated context, and fewer changes reviewed
+without their reachable dependencies. Operationally, it is one local process
+with no account, hosted index, credential flow, source egress, or mandatory
+database/vector daemon. ROI is measured in correctness, latency, response size,
+safety, and effort by the checked-in replay harness—not an unsupported generic
+productivity percentage.
+
+## Where does knodin compete?
+
+There is no canonical industry standard that divides code-intelligence products
+into exactly four categories. Current products overlap. Their primary jobs do,
+however, fall into four useful categories when deciding what to give an engineer
+or coding agent:
+
+| Category | Question it answers | Representative tools | knodin surface |
+|---|---|---|---|
+| **Symbol navigation and graph exploration** | Where is this symbol, what calls it, and what does it call? | [CodeGraph](https://github.com/colbymchenry/codegraph), [Serena](https://github.com/oraios/serena), [Sourcegraph code navigation](https://sourcegraph.com/docs/code-navigation) | `explain`, `query callers_of` / `callees_of`, `shortest_path`, LSP queries |
+| **Change impact and code review** | What can this diff affect, how risky is it, and where are the test gaps? | [code-review-graph](https://github.com/tirth8205/code-review-graph), [Greptile](https://www.greptile.com/docs/introduction), Graphify’s [PR-impact tools](https://graphify.com/mcp) | `review`, `impact`, `traverse`, `tests_for`, `prs` |
+| **Architecture and dependency mapping** | What are the subsystems, hubs, boundaries, and execution flows? | [Graphify](https://graphify.com/concepts), [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | `map`, `architecture_overview`, `community`, `flows`, `wiki`, `visualize` |
+| **Retrieval and context assembly** | Which code or diagnostic evidence should the agent receive for this task and token budget? | [Aider repo map](https://aider.chat/docs/repomap.html), [Repomix](https://repomix.com/guide/), semantic-search/context engines | `context`, hybrid `search`, bounded `pack`, recoverable `compress` |
+
+This is a job-based taxonomy, not a claim that every product fits only one box.
+CodeGraph and Graphify now expose impact features, for example, while
+Sourcegraph combines search and precise navigation. knodin competes by composing
+all four jobs over one fresh local index and exposing them through one CLI and
+one operation-routed MCP tool. Breadth alone is not proof of superiority; the
+[comparison notes](docs/COMPARISON.md) and
+[competitive roadmap](roadmap/competitive-roadmap.md) distinguish checked-in
+replays, attributed vendor claims, setup blockers, and known limitations.
+The [Token Optimizer scorecard](docs/TOKEN-OPTIMIZER-SCORECARD.md) gives the
+evidence-linked disposition for every pinned capability and records where
+knodin is still weaker or intentionally different.
+
+Static application-security products such as
+[CodeQL](https://codeql.github.com/docs/codeql-overview/about-codeql/) and
+[Semgrep](https://semgrep.dev/docs/) are adjacent, not substitutes: knodin can
+report structural dead-code candidates and selected diagnostics, but it is not
+a SAST engine or a proof that dynamically wired code is unreachable. That
+distinction matters for framework and Salesforce entrypoints that static
+analysis may not fully resolve.
+
+## What happens tomorrow?
+
+Public npm remains the primary cross-platform path. The commands below become
+canonical when the first `knodin` release is published. Existing
+`reckon-graph` installs continue to work through the legacy package and
+`reckon` executable alias. Homebrew and GHES paths remain on their legacy names
+until those external repositories are renamed and their knodin artifacts pass
+the release gates.
+
+On Windows, macOS, or Linux with Node.js 24 or newer, install the public
+[npm package](https://www.npmjs.com/package/knodin):
+
+```bash
+npm install --global --ignore-scripts knodin
+```
+
+After the Homebrew tap migration, the macOS or Linux path will be:
+
+```bash
+brew install knowdin/tap/knodin
+```
+
+pnpm, Bun, mise, Volta, nvm, fnm, and asdf behavior and verification status are
+listed in the installation matrix. Commands without a recorded release gate
+are guidance, not verified support:
+
+```bash
+pnpm add --global --ignore-scripts knodin@<version>
+bun add --global --ignore-scripts knodin@<version>
+```
+
+Temporary runners are not suitable for the stable hook and MCP command paths
+created by `knodin init`. See the [installation guide](docs/INSTALLATION.md)
+for verified status, Node/version-manager behavior, registries, Homebrew,
+upgrades, and uninstall commands.
+
+P&T engineers without GitHub SaaS access can continue using the current GHES
+mirror until the knodin path is promoted. See the
+[P&T GHES procedure](docs/PT-ACCESS-RECOMMENDATION.md) for the migration gate.
+
+Then initialize an existing checkout:
+
+```bash
+cd /path/to/repository
+knodin init
+```
+
+On an interactive terminal, `knodin init` asks how agent integration should be
+scoped and configures all detected supported agents in one operation:
+
+- **Personal (recommended):** configures local Claude Code, Codex, Gemini CLI,
+  and Antigravity adapters when detected. knodin-owned untracked files are
+  listed in `.git/info/exclude`, so the repository stays clean and teammates
+  are not required to install knodin.
+- **Team:** creates merge-safe, commit-ready MCP configuration for the primary
+  agents in `.mcp.json`, `.codex/config.toml`, `.gemini/settings.json`, and
+  `.agents/mcp_config.json`, plus managed instruction blocks in `AGENTS.md` and
+  `GEMINI.md`. Commit these files so every supported agent sees the same
+  gateway. Repeated team initialization is byte-idempotent once they are
+  current.
+- **CLI-only:** builds and refreshes the graph but does not configure agents.
+  Agents will generally not discover or invoke knodin; commands must be run
+  manually.
+
+Non-interactive initialization defaults to `personal`. Select explicitly or
+change the choice later:
+
+```bash
+knodin init --scope personal
+knodin configure --scope team
+knodin configure --scope cli-only
+knodin configure --status
+```
+
+Scope changes are reversible and modify only knodin-owned configuration.
+Before adding any exclusion, knodin verifies that the path is untracked.
+Already-tracked files are never added to `.git/info/exclude` or `.gitignore`,
+and personal mode never overwrites tracked agent configuration.
+
+The package is public on npm, and consumers do not need Bun. Organizations may
+also mirror it through an approved npm-compatible registry without changing the
+CLI workflow. To test an unpublished change, build and install the exact tarball
+from a source checkout:
+
+```bash
+npm ci
+TARBALL=$(npm pack --silent)
+npm install --global --ignore-scripts "./$TARBALL"
+cd /path/to/repository
+knodin init
+```
+
+### About npm install warnings
+
+knodin’s standard CPU workflow is verified with dependency lifecycle scripts
+disabled. The `--ignore-scripts` flag makes that policy explicit and avoids
+prompting users to approve transitive install code they do not need. The native
+CPU binaries used by knodin are already supplied as platform packages.
+
+Without that flag, recent npm releases may report blocked scripts from
+`onnxruntime-node`, `sharp`, and `protobufjs`. Do not approve them blindly for a
+normal knodin installation. ONNX Runtime’s script can fetch optional Linux x64
+CUDA components; Sharp’s checks whether it needs a local source build; and
+ProtobufJS performs a dependency-version compatibility check. None is required
+by knodin’s verified CPU path.
+
+You may also see a deprecation notice for `boolean@3.2.0`. It is an upstream
+transitive dependency in the current
+`@huggingface/transformers → onnxruntime-node → global-agent` chain, not a
+package knodin calls directly. A deprecation notice is not by itself a
+vulnerability, but it is dependency debt that must be removed when the upstream
+runtime pin permits it. Use `npm audit --omit=dev` to check the installed
+production tree for current advisories.
+
+The package is verified for npm tarball consumption; registry publication is a
+separate release action documented in the
+[release runbook](docs/RELEASING.md). Use the CLI directly or connect the
+single `knodin` MCP gateway. The first useful calls are:
+
+- `knodin status --deep` to verify index health and coverage;
+- `knodin context "<task>"` for bounded orientation;
+- `knodin explain <symbol>` before an edit;
+- `knodin review --scope all` before review or handoff;
+- `knodin map`, `search`, and `query` for architecture and targeted graph facts.
+
+No workflow migration or hosted rollout is required.
+
+Dependency provenance, blocked-script behavior, and the scheduled upstream
+deprecation canary are documented in
+[`docs/dependency-hygiene.md`](docs/dependency-hygiene.md).
+
+### Verify the locally built distributable package
+
+Before tagging or publishing a release, run the clean-consumer acceptance
+gate:
+
+```bash
+npm run test:pack-install
+```
+
+The gate requires Node.js 24+, npm, `git`, `tar`, `ps`, and `expect` on the
+release host. It creates a real `npm pack` tarball, checks its compiled CLI, engine,
+MCP gateway, license, metadata, and parser WASMs, and installs that exact
+artifact globally under a temporary prefix with an isolated npm cache and a
+`PATH` that contains no Bun executable. It runs `knodin init` in two repositories,
+then exercises foreground
+post-commit, post-checkout, post-merge, and post-rewrite refreshes across
+TypeScript and Salesforce source/metadata. It also checks deep index health,
+graph query evidence, rename/deletion reconciliation, and repair output stream
+separation for plain, JSON, JSONL, silent, and automatic TTY progress modes. A
+real JSON-RPC initialize plus `tools/list` handshake proves that the packed MCP
+server exposes the single `knodin` gateway.
+
+Every child command is sequential and bounded by time, output, and a 2,750 MiB
+aggregate process-tree RSS safety limit that includes the runner, command,
+descendants, and sampler. Limit failures terminate the command process group.
+The temporary artifact, cache, consumer checkout, and local graph are removed
+whether the gate passes or fails. A passing run prints one JSON evidence record
+containing tarball size, command time, and observed peak RSS.
+
+This proves the exact locally built tarball. It does not claim registry
+publication, remote release upload, or compatibility beyond the environments
+covered by the gate.
+
+### Model and repository storage
+
+Each checkout keeps its graph in `.reckon/db.sqlite`. The local
+`Xenova/all-MiniLM-L6-v2` model is downloaded once per user account into the
+machine cache and shared by every repository:
+
+- macOS: `~/Library/Caches/knodin/models`
+- Linux: `${XDG_CACHE_HOME:-~/.cache}/knodin/models`
+- Windows: `%LOCALAPPDATA%\knodin\models`
+
+Set `RECKON_MODEL_CACHE` to use a different shared location. Repository
+initialization never places a duplicate model inside `.reckon` or the installed
+npm package. Managed networks can set `RECKON_MODEL_HOST` to an approved
+HTTP(S) mirror of the Hugging Face repository; the mirror is used only when the
+shared cache is cold.
+
+### Language and metadata support
+
+knodin does not claim universal programming-language support. Its native parser
+set currently covers TypeScript, JavaScript, Python, Java, C#, Apex, SQL/PLSQL,
+Prisma, and XML-backed formats. It also has specialized structural indexers for
+Salesforce source and selected metadata, Terraform/HCL, Dockerfiles, dbt
+manifests, Workday Studio XML, and LSIF graph imports.
+
+Coverage is not identical across those formats, and a file being parseable does
+not imply every dynamic dependency can be resolved. Go, Rust, PHP, Ruby, Kotlin,
+Swift, Perl, PowerShell, Bash, and MuleSoft/RAML are among the currently known
+native-parser gaps. See the
+[language and metadata support matrix](docs/LANGUAGE-SUPPORT.md) for exact
+extensions, capability tiers, Salesforce limitations, and the evidence-based
+Docusign coverage assessment.
+
+## What makes knodin unique? What is the secret sauce?
+
+Individual graph features are easy to copy. knodin’s differentiator is the
+combination of stable symbol resolution, source-evidenced review/impact answers,
+truthful response budgets, explicit freshness, and a local one-tool MCP surface.
+The native engine composes those constraints across orientation, editing,
+review, architecture, search, and export. That system-level combination—not a
+single algorithm—is the secret sauce. It must remain measurable,
+privacy-preserving, and compatible with ordinary Git and editor workflows.
+
+## Why an agent picks this over grep
+
+One MCP tool with operation-routed capabilities, no account to create and
+nothing sent off the machine—versus a Grep/Read loop, or a competitor that pays
+a much larger fixed context cost every session for tools it may never call. See
+[`docs/COMPARISON.md`](docs/COMPARISON.md) for the honest, claim-attributed
+comparison against codegraph, code-review-graph, graphify, and the wider field.
+
+### Review diff selection
+
+`review` supports four explicit scopes: `unstaged` compares the index to the
+working tree (and includes untracked files), `staged` compares `HEAD` to the
+index, `all` compares the supplied base through the complete working tree, and
+`compare` compares the supplied base (default `HEAD~1`) to `HEAD`. The legacy
+`knodin review [base]` call remains compatible and maps to `scope=all`.
+
+For a checkout-independent review, use `--from <older> --to <newer>` for an
+explicit revision pair, or `--files <a,b>` for an explicit repo-relative file
+list. MCP callers use `diffScope`, `from`/`toRevision`, and `reviewFiles`.
+Results return `changedFiles` for every path plus `mappedChangedFiles`,
+`unmappedChangedFiles`, and truthful counts; symbol analysis remains separate in
+`changedSymbols`.
+
+Capability alone does not win the routing decision. The compact always-on tool
+description distinguishes orientation and graph work from exact literals,
+non-code files, and recent edits where direct reads win. Full operation and
+parameter guidance is retrieved on demand with
+`{ "operation": "docs", "section": "quickstart" }`. See
+[`src/tools/knodin-tools.ts`](src/tools/knodin-tools.ts) for the exact text an
+agent sees.
+
+## Status and proof
+
+The native local engine, CLI, and MCP gateway are implemented and covered by
+hundreds of tests and labeled replays. Competitive leadership claims are
+narrower: symbol identity, diff/traversal, architecture, and context-packing
+replays are complete. C28's frozen replay records stronger dead-code precision
+and semantic relevance than pinned GitNexus on the shared oracle. C31's pinned
+codebase-memory and grepai lifecycle replay covers stale-state detection,
+documented refresh, healthy-symbol preservation, and native telemetry gaps;
+Claude Context remains a separately classified setup blocker. C32's bounded
+local API and statement-flow replay found no broader production-surface gap.
+Local graph-artifact freshness across checkout and merge events is implemented
+with bounded, auditable refresh states. See the
+[competitive roadmap](roadmap/competitive-roadmap.md) and
+[comparison notes](docs/COMPARISON.md) for the evidence rather than relying on
+feature lists.
+
+### Refresh optional graph artifacts
+
+`knodin refresh-artifacts checkout|merge|code-change` is an explicit local
+maintenance command for installed GitNexus and Graphify indexes. It prefers the
+repository's GitNexus runner when present, bounds each rebuild to 30 seconds,
+and records every artifact as `success`, `failed`, or `skipped` in
+`.reckon/artifact-refresh.jsonl`. It never runs from a commit hook and never
+reports an unavailable external index as fresh.
+
+## Stack
+
+Node.js 24+ · TypeScript · Node SQLite · `@modelcontextprotocol/sdk` · Zod ·
+Biome · Vitest · lefthook.
+Tools are registered via the low-level request-handler API (never the high-level
+`server.tool()` overload — see `CLAUDE.md`).
+
+## License
+
+knodin is open-source software licensed under the
+[MIT License](LICENSE). You may use, copy, modify, merge, publish, distribute,
+sublicense, and sell copies subject to the license terms.
+
+## Develop
+
+```bash
+npm ci
+npm run dev
+npm run cli -- map
+npm run cli -- visualize createServer --output .reckon/architecture.html --depth 3
+npm test
+npm run test:handles
+npm run lint
+npm run typecheck
+npm run test:pack-install
+```
+
+For the additional local SonarQube quality gate, see
+[docs/SONARQUBE.md](docs/SONARQUBE.md). It uses a project-scoped token outside
+Git and distinguishes the SonarQube CLI from the full repository scanner.
+
+## Use as an MCP server
+
+The installed package exposes a stdio MCP server through `knodin serve`.
+`knodin init` registers it for detected clients according to the selected
+scope. Manual registration remains available for unsupported clients or
+custom setups. The server advertises exactly one top-level tool named
+`knodin`, with capabilities selected by its `operation` argument.
+For clients that accept the common `mcpServers` JSON shape:
+
+```json
+{
+  "mcpServers": {
+    "knodin": {
+      "command": "knodin",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+If the client does not inherit the interactive shell's `PATH`, replace
+`"knodin"` with the absolute path printed by `command -v knodin`. From this
+source checkout, an uninstalled development fallback is:
+
+```json
+{
+  "mcpServers": {
+    "knodin": {
+      "command": "node",
+      "args": ["/absolute/path/to/knodin/dist/bin/cli.js", "serve"]
+    }
+  }
+}
+```
+
+Run `npm run build` in the source checkout before using that compiled fallback.
+
+After registration, an MCP `tools/list` call returns the single `knodin`
+gateway. Its operations include `context`, `explain`, `review`, `map`,
+`search`, `query`, `prs`, `wiki`, `docs`, `pack`, `status`, `repair`, and
+`telemetry`. The `prs` operation uses the caller's local authenticated `gh`
+CLI; knodin stores no GitHub credentials.
+
+## Response budgets
+
+Every gateway operation is bounded after JSON serialization and returns a
+`responseBudget` block with the effective byte/token/item limits, serialized
+size, estimated tokens, original collection totals, truncation state, and a
+continuation instruction. Token estimates are deterministic: four serialized
+UTF-8 bytes per token. Callers may override `byteBudget`, `tokenBudget`, and
+`itemBudget`; the tightest limit wins. The minimum accepted envelope is 256
+bytes (64 estimated tokens). Defaults are 64 KiB/16K tokens/100 items,
+with operation-specific ceilings of 16 KiB for minimal explain, 32 KiB for
+minimal map, 64 KiB for standard explain, and 128 KiB for standard map.
+The CLI exposes the same envelope on every JSON command as `--bytes`,
+`--tokens`, and `--items`; its compact JSON output is the exact serialization
+used for accounting. `knodin search <query> [limit]` remains supported, with
+`--limit` taking precedence when both forms are present.
+
+Minimal explain omits source by default; pass `includeSource: true` to request
+it. Standard explain retains edit-ready source and, if a requested budget is
+too small, reports an explicit continuation instead of silently dropping it.
+Minimal map contains only counts, aggregates, and bounded top summaries: it
+does not return community member arrays or full edge lists.
+
+`knodin status` audits the local index schema, embedding model, package
+version, file/symbol coverage, missing and orphaned records, and last successful
+reconciliation. It also verifies that active Git hooks still route to knodin's
+background indexer and records the last failed background execution. A healthy
+snapshot with displaced hooks or a failed refresh command carries explicit
+`lifecycle-degraded` availability metadata, with `.reckon/indexer.log` named
+for diagnosis. Graph reads may continue from an otherwise complete index while
+preserving that degraded freshness state. `knodin repair` rebuilds only damaged or missing state and then
+verifies it, preserving healthy data. MCP exposes the same `status` and
+`repair` operations. The MCP `telemetry` operation reads the process-local,
+metadata-only benchmark log (operation, latency, serialized bytes, estimated
+tokens, truncation, and detail mode) without changing existing response shapes.
+Persistence is off by default; `persistTelemetry: true`
+explicitly appends source-free records to `.reckon-telemetry.jsonl`. No telemetry
+or source is sent over the network.
+
+Graph reads never turn missing health evidence into an ordinary empty answer.
+CLI and MCP results distinguish `no-match`, `not-initialized`,
+`empty-repository`, `empty-index`, `repair-needed`, `indexing`,
+`lifecycle-degraded`, and `unknown`. Unavailable states fail closed with
+remediation; a queryable but lifecycle-degraded graph retains that state in its
+availability metadata.
+
+### Repository and system management
+
+`knodin repos discover|init|status|doctor <root...>` manages local checkouts
+without declaring them one system. Linked worktrees require the explicit
+`--linked-worktrees=include` option. Main worktrees, linked worktrees, nested
+repositories, stale metadata, and unrelated repositories remain distinct.
+`knodin repos search "<query>" --root <path>` searches those independent
+checkouts sequentially under hard item/token/byte budgets. It fails closed for
+unhealthy selected graphs unless `--allow-partial` is explicit, in which case
+every omission is named.
+`knodin fleet init` is a deprecated JSON-safe compatibility alias for two minor
+releases.
+
+Team-owned stable identities and cooperating components belong in
+`reckon.yaml`; personal checkout paths belong under XDG configuration. Use
+`knodin system list|show|validate|query`. See:
+
+- [Repositories and worktrees](docs/REPOSITORIES-AND-WORKTREES.md)
+- [Systems and relationships](docs/SYSTEMS-AND-RELATIONSHIPS.md)
+- [Indexing policy and provenance](docs/INDEXING-POLICY-AND-PROVENANCE.md)
+- [Dead code and impact](docs/DEAD-CODE-AND-IMPACT.md)
+- [MCP configuration](docs/MCP.md)
+- [Doctor and updates](docs/DOCTOR-AND-UPDATES.md)
+
+`knodin init` and `knodin index` render phase-aware, asynchronous progress on
+stderr, so terminal animation and elapsed time continue even while parsing or
+embedding keeps the main process busy. An explicit `knodin index <files...>`
+updates only files whose indexed snapshots differ from disk; files made current
+by a preceding repair finish immediately. Use `--force` only when an unchanged
+file truly needs rebuilding. Every index run ends with a forced graph-health
+audit. If an explicit file list omitted other repository drift, the command
+names the first remaining issue and exits nonzero instead of allowing a chained
+review to consume an unhealthy graph. `knodin init` enforces the same verified
+postcondition: lifecycle hooks may be installed, but initialization does not
+report success when graph issues remain. Human `status` and initialization
+errors name the first concrete inconsistency before directing the user to
+`knodin repair`. When Lefthook is present, initialization keeps its generated
+hook jobs active while disabling their implicit hook reinstall, so they do not
+replace knodin's lifecycle wrappers. Repair scopes stable-identity and reference
+rebinding to repaired files and reports embedding candidates as they complete,
+while the final human summary remains on stdout.
+
+For a Git checkout, full indexing, reconciliation, deep status, and repair use
+the same source universe: tracked files plus unignored untracked files. Generated
+files excluded by Git are not counted as missing coverage, and legacy indexed
+rows that have since become ignored are removed during reconciliation or repair.
+
+`knodin refresh-artifacts [checkout|merge|code-change]` is an explicit opt-in
+refresh for locally installed GitNexus and Graphify indexes. Each rebuild is
+bounded to 30 seconds and records only success, failure, or skipped metadata in
+`.reckon/artifact-refresh.jsonl`; it never runs from a commit hook.
+
+Search supports composable `languages`, `extensions`, `kinds`, `path`,
+`testScope`, and `includeSource` filters. Its paged response contains
+`results`, `total`, `offset`, `limit`, and `hasMore`; use `offset` to continue.
+Large-code queries accept `minLines`, `minComplexity`, `kinds`, and `path`.
+
+`knodin pack` creates portable Markdown, JSON, or XML source context with
+deterministic relative-path ordering and an explicit local four-bytes-per-token
+cost estimate. Includes, excludes, already-present/chat-file suppression, and
+per-glob `full`, `summary`, or `structure-only` policies compose under hard byte
+and token limits. Optional line numbers, a file tree, C5-compatible Git diff
+scopes, and local log context are available. `knodin pack read` retrieves at
+most 1,000 artifact lines under a byte cap; `knodin pack grep` applies an exact
+regular expression with a bounded match count. Output paths are restricted to
+the repository, and no pack operation sends code or metadata off-machine.
+
+`knodin visualize <entry> --output <path.html>` writes an optional,
+self-contained local HTML artifact from the existing persisted graph. It offers
+native subsystem drill-down, hub/bridge inspection, and a bounded downstream
+static call-flow view (`--depth 1..6`); `--identity`, `--file`, and `--kind`
+disambiguate the entry symbol. Each displayed relationship is labeled with
+bounded source evidence or an explicit heuristic label, and the artifact records
+the local source commit plus index freshness. `--max-bytes` (4–64 KiB, 32 KiB
+default) bounds generation; output paths must remain inside the repository. This
+is a CLI export only: it adds no MCP tool, network service, credentials,
+telemetry, or source egress.
+Map and community/flow/traversal drill-downs accept `topN`, `sort`,
+`relationKinds`, and `detailLevel`. The CLI exposes the same controls as
+`--languages`, `--extensions`, `--kinds`, `--path`, `--tests-only`,
+`--production-only`, `--offset`, `--min-lines`, `--min-complexity`, `--top`,
+`--sort`, and `--relations`. Traversal also accepts `--direction` and `--data-flow`
+and returns typed evidence for every hop. `architecture_overview` accepts `--facets`
+(`packages,layers,boundaries,hotspots,entryPoints,languages`) and a consistent `--path` scope.
+
+`knodin query feature_path <symbol>` follows a deterministic, downstream DFS
+over resolved source references. It is bounded by depth (1–6) and the response
+item cap, reports explicit truncation whenever either bound cuts off reachable
+nodes, includes source file/line evidence on each hop, and guards cycles. It
+is a static feature-navigation aid, not a
+runtime execution trace; dynamic dispatch and unresolved references are omitted.
+Gateway byte/token budgets can additionally crop the serialized response; that
+separate C3 condition is reported in `responseBudget.truncated`.
+
+`knodin query flow_analysis <symbol> [--variable name]` performs a compact,
+on-demand source analysis of one selected TypeScript/JavaScript function. It returns
+simple definition, use, and control facts with file/line/source evidence, is bounded
+by knodin's normal response budgets, and never persists a program-dependence graph.
+Aliases, destructuring, closures, dynamic properties, and runtime control flow are
+explicitly heuristic or unresolved rather than presented as proof.
+
+### MCP tool and handler map
+
+After indexing, `knodin query mcp_tools` lists TypeScript MCP SDK registrations and associates each tool name with its description, schema declaration, handler symbol, and source file. Use `knodin query mcp_tools <tool-name>` for an exact-name lookup. Dynamic registrations are retained with `confidence: "heuristic"` instead of being presented as exact facts.