knodin 0.5.1 → 0.6.0

package/README.md

@@ -2,589 +2,221 @@
 
 <img src="https://cdn.jsdelivr.net/npm/knodin@latest/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 |
+> Local code intelligence that remembers how your code connects—and shows what
+> may move before you change it.
+
+knodin builds and continuously refreshes a local graph of an existing codebase.
+Engineers and coding agents use it to understand unfamiliar code, find affected
+dependencies, review changes, search by meaning or name, and assemble bounded
+source context without sending source code to a hosted service.
+
+It ships as one CLI and one operation-routed MCP tool. There is no account,
+hosted index, authentication flow, source egress, or separate database service.
+
+## Why use knodin?
+
+A code change usually starts with repeated manual work: find the definition,
+read its callers, inspect dependencies, locate tests, understand the diff, and
+assemble enough source for the next decision. knodin composes those steps over
+one persistent local graph.
+
+- **Understand before editing:** resolved symbols, verbatim source, call paths,
+  architecture communities, and execution flows.
+- **See potential impact:** upstream and downstream relationships, affected
+  tests, changed symbols, review risk, and explicit ambiguity.
+- **Give agents better context:** hybrid search and deterministic source packs
+  with hard line, byte, and token budgets.
+- **Keep evidence trustworthy:** source locations, graph freshness, lifecycle
+  health, repair commands, and truthful truncation metadata.
+- **Adopt locally:** initialize the checkout you already have and use the CLI or
+  connect one MCP gateway.
+
+The practical payoff is less manual context assembly, fewer agent round trips,
+and fewer dependencies missed during review—with no hosted-service or
+source-egress overhead.
+
+## How it compares
+
+Code-intelligence tools often specialize in one part of the workflow. knodin
+combines navigation, impact analysis, architecture, retrieval, and bounded
+context over one locally persisted index.
+
+| Job | Typical specialized tools | knodin |
 |---|---|---|
-| `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):
+| Symbol navigation | CodeGraph, Serena, Sourcegraph | Ambiguity-safe definitions, callers, callees, paths, and verbatim source |
+| Change impact and review | code-review-graph, Greptile, Graphify | Diff-aware review, impact traversal, tests, risks, and PR triage |
+| Architecture mapping | Graphify, GitNexus | Communities, hubs, boundaries, flows, wiki, and local visualization |
+| Search and context assembly | Aider repo map, Repomix, semantic search tools | Hybrid search, bounded source packs, and recoverable diagnostic compression |
+| Deployment | Hosted services or separate local tools | One local process, SQLite graph, CLI, and one MCP gateway |
+
+### Measured results
+
+On the checked-in Token Optimizer replay, knodin passed the shared correctness
+oracle for all five safe structural workflows while using fewer real tokens and
+running faster at warm p50 and p95 in every case:
+
+| Workflow | Tokens (knodin vs competitor) | Warm p50 (knodin vs competitor) | Result |
+|---|---:|---:|---:|
+| File outline | 56 vs 64 | 0.203 vs 0.478 ms | 2.4× faster |
+| Exact symbol source | 33 vs 37 | 0.258 vs 0.419 ms | 1.6× faster |
+| Symbol search | 76 vs 84 | 0.227 vs 1.112 ms | 4.9× faster |
+| Batch outline | 331 vs 377 | 0.184 vs 1.387 ms | 7.5× faster |
+| Project overview | 14 vs 127 | 0.135 vs 0.589 ms | 4.4× faster, 89% fewer tokens |
+
+Across the broader checked-in competitive replay, knodin was faster in 488 of
+713 paired cases (68.4%). It did not win every workload: competitors won 225
+cases, including the aggregate warm-latency result for several packing and
+memory tools. Cold startup is also slower in the Token Optimizer comparison.
+
+These are fixture-scoped measurements, not estimates. See the
+[replay synthesis](benchmarks/competitors/SYNTHESIS.md),
+[scorecard](docs/TOKEN-OPTIMIZER-SCORECARD.md), and raw benchmark artifacts for
+methods, pinned revisions, correctness oracles, and limitations.
+
+This table describes product scope, not a universal superiority claim. Product
+capabilities overlap, and static analysis has limits in dynamically wired or
+framework-driven code. The [comparison notes](docs/COMPARISON.md) separate
+checked-in measurements, vendor claims, setup blockers, and known gaps. The
+[competitive roadmap](roadmap/competitive-roadmap.md) records remaining
+limitations.
+
+## Install
+
+knodin requires Node.js 24 or newer.
 
 ```bash
 npm install --global --ignore-scripts knodin
 ```
 
-After the Homebrew tap migration, the macOS or Linux path will be:
+Initialize an existing repository:
 
 ```bash
-brew install knodin/tap/knodin
+cd /path/to/repository
+knodin init
+knodin status --deep
 ```
 
-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:
+`knodin init` builds the local graph, installs lifecycle hooks, and can configure
+detected coding agents. Choose an integration scope explicitly when needed:
 
 ```bash
-pnpm add --global --ignore-scripts knodin@<version>
-bun add --global --ignore-scripts knodin@<version>
+knodin init --scope personal   # local configuration; keeps the repo clean
+knodin init --scope team       # commit-ready shared agent configuration
+knodin init --scope cli-only   # graph and CLI without agent configuration
 ```
 
-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.
+See the [installation guide](docs/INSTALLATION.md) for package-manager details,
+managed registries, upgrades, and uninstall instructions.
 
-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.
+## First workflow
 
-Then initialize an existing checkout:
+Start broad, inspect the likely change surface, then review the actual diff:
 
 ```bash
-cd /path/to/repository
-knodin init
+# Orient on an unfamiliar checkout
+knodin context
+
+# Explain a symbol with source and relationships
+knodin explain createServer
+
+# Find what depends on it
+knodin query impact createServer --direction upstream
+
+# Review current changes
+knodin review --scope all
 ```
 
-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:
+For discovery and bounded context:
 
 ```bash
-knodin init --scope personal
-knodin configure --scope team
-knodin configure --scope cli-only
-knodin configure --status
+knodin search "authentication middleware"
+knodin map
+knodin pack createServer --max-tokens 4000
 ```
 
-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:
+If freshness or lifecycle checks fail:
 
 ```bash
-npm ci
-TARBALL=$(npm pack --silent)
-npm install --global --ignore-scripts "./$TARBALL"
-cd /path/to/repository
-knodin init
+knodin status --deep
+knodin repair
 ```
 
-### 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.
+## What it does
 
-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.
+| Command | Purpose |
+|---|---|
+| `knodin context` | Compact repository orientation and next-operation hint |
+| `knodin explain <symbol>` | Source, identity, callers, callees, and blast radius |
+| `knodin review` | Diff-aware risks, changed symbols, affected flows, and test gaps |
+| `knodin query …` | Impact, paths, callers, callees, tests, flows, and structured graph queries |
+| `knodin search <query>` | Hybrid semantic and keyword symbol search |
+| `knodin map` | Subsystems, communities, hubs, bridges, and boundaries |
+| `knodin pack …` | Deterministic source context under hard budgets |
+| `knodin compress …` | Bounded diagnostic output with recoverable local detail |
+| `knodin prs` | Open-PR triage using the authenticated local `gh` CLI |
+| `knodin wiki` | Static Markdown architecture documentation |
+| `knodin visualize` | Self-contained local graph visualization |
+| `knodin status --deep` | Index freshness, health, hooks, and integration status |
+| `knodin repair` | Repair or rebuild unhealthy local graph state |
 
-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.
+Run `knodin --help` or read the [CLI reference](docs/CLI.md) for complete syntax.
 
-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:
+## MCP
 
-- `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.
+`knodin init` configures supported agents automatically. A manual MCP
+configuration uses one local server:
 
-No workflow migration or hosted rollout is required.
+```json
+{
+  "mcpServers": {
+    "knodin": {
+      "command": "knodin",
+      "args": ["serve"]
+    }
+  }
+}
+```
 
-Dependency provenance, blocked-script behavior, and the scheduled upstream
-deprecation canary are documented in
-[`docs/dependency-hygiene.md`](docs/dependency-hygiene.md).
+The gateway exposes one `knodin` tool whose `operation` selects context,
+explain, review, map, search, query, pack, compress, PR, wiki, telemetry,
+repository, and lifecycle capabilities. See the [MCP guide](docs/MCP.md).
 
-### Verify the locally built distributable package
+## Local data and privacy
 
-Before tagging or publishing a release, run the clean-consumer acceptance
-gate:
+Each checkout stores its graph and lifecycle state in `.knodin/`. Shared model
+files live in the user cache rather than being duplicated per repository.
+Source and graph data stay local. Telemetry is metadata-only, disabled by
+default, and never sent by knodin.
 
-```bash
-npm run test:pack-install
-```
+The optional `prs` command invokes the user's authenticated `gh` CLI. Network
+access may also occur when installing packages, downloading the configured
+embedding model, or explicitly checking for updates.
 
-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`).
+## Evidence and limitations
 
-## License
+knodin reports ambiguity, stale indexes, incomplete language coverage, and
+budget truncation instead of presenting uncertain results as complete. Its
+checked-in tests and competitive replays measure narrower correctness, latency,
+retrieval, and response-size outcomes; they do not establish a universal
+productivity percentage or superiority over every competing product.
 
-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.
+- [Status and evidence](docs/HANDOFF.md)
+- [Comparison notes](docs/COMPARISON.md)
+- [Competitive landscape](docs/COMPETITIVE-LANDSCAPE-2026-08.md)
+- [Competitive roadmap and limitations](roadmap/competitive-roadmap.md)
+- [Systems and relationships](docs/SYSTEMS-AND-RELATIONSHIPS.md)
+- [Command-output compression](docs/COMMAND-OUTPUT-COMPRESSION.md)
 
 ## Develop
 
 ```bash
 npm ci
-npm run dev
-npm run cli -- map
-npm run cli -- visualize createServer --output .reckon/architecture.html --depth 3
+npm run build
 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"]
-    }
-  }
-}
-```
+## License
 
-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.
+[Apache-2.0](LICENSE)