knodin 0.7.6 → 0.8.2

package/docs/HANDOFF.md

@@ -0,0 +1,180 @@
+# knodin — Handoff
+
+Context for anyone (human or agent) picking this repo up cold. Originally
+written at scaffold time on 2026-07-15 and updated after the native engine and
+competitive program shipped. `CLAUDE.md` is the terse working-rules file; this
+is the *why*, current product truth, and adoption path.
+
+> **Current-state guardrail:** knodin is an implemented engine, CLI, and
+> MCP server. The scaffold-era backend decision is resolved. Do not describe
+> this repository as a stub, skeleton, wiring-only project, or “almost done.”
+
+## One-line pitch
+
+> **knodin — source-evidenced local code intelligence with known bounds.** Your
+> agent knodins the whole codebase instead of grepping it.
+
+A **local, no-auth core code-intelligence MCP server** that composes the three
+things you actually want from a code graph into a single `knodin` gateway tool.
+The optional `prs` operation uses the caller's authenticated `gh`; it does not
+make the graph engine credentialed.
+
+## Why this exists (the decision chain)
+
+The starting question was: we already run **codegraph** and **code-review-graph**
+locally — should we adopt **Graphify** instead of / in addition to them?
+
+The original conclusion after comparing all three was:
+
+- **Keep both incumbents.** Each wins its own slot decisively and Graphify
+  doesn't beat either at it:
+  - **codegraph** → orient→edit loop: one call returns verbatim, line-numbered,
+    edit-ready source + call paths + blast radius. Its whole value is
+    "Read-equivalent, edit-with-dependents-in-view."
+  - **code-review-graph** → review loop: risk-scored, ~200-token diff context
+    (changed functions, affected flows, test gaps) + semantic/cross-repo search.
+- **Graphify's** differentiators (Leiden community/subsystem maps, god-node
+  centrality, multimodal ingestion of SQL/Terraform/docs, EXTRACTED/INFERRED
+  edge provenance) are real but are the capabilities a *self-built* daily loop
+  needs least. They shine for **comprehending unfamiliar code**.
+
+The high-leverage product direction was a **composing MCP that assembles the
+three winning workflows**—codegraph-style explain, code-review-graph-style
+review, and Graphify-style map—behind one tool. knodin now implements those
+workflows in its own native local engine; the bullets above explain the origin,
+not an outstanding backend choice.
+
+### Build it standalone, NOT inside AtlasMCP
+
+Decided against folding this into AtlasMCP's core, and Atlas's own code voted for
+it (it already surfaces Glean via `src/client/embedded-mcp.ts` + `EmbeddedMcpTool`
+rather than reimplementing it in-core):
+
+- **Different bounded context.** Atlas is a credential-delegating gateway to
+  external SaaS (all its `src/auth/*` + `src/client/*` are OAuth'd API clients).
+  knodin is local compute: tree-sitter parsing, a per-repo on-disk graph,
+  file-watch freshness, **zero external auth**. Co-mingling two unrelated failure
+  domains in one deployable is the trap.
+- **Atlas optimizes for a small tool surface** (its stated "gateway pattern, keep
+  it to ~8 tools"). A fat code-graph tool family fights that.
+- **Standalone reuse is the point.** Like codegraph/code-review-graph, it should
+  work in *any* assistant with a local index and no auth. Burying it in Atlas
+  would only make it reachable when Atlas runs with its full OAuth apparatus.
+
+**External and optional:** Atlas can federate knodin through its existing
+embedded-MCP seam—request-scoped dispatch, same as Glean, with zero code
+co-mingled. That Atlas-side integration is outside this repository and is not a
+missing part of knodin's implemented standalone product.
+
+## The name (so nobody relitigates it)
+
+Long hunt. The lesson: this is the most naming-saturated niche in software right
+now — every transparent "code + graph / memory / map" word is already taken by a
+near-clone (codegraph, coregraph, cartograph, omnigraph, graphify, lore,
+mnemosyne, cairn, episteme — all gone, most in the exact Claude-Code-MCP niche).
+Transparency is the collision magnet.
+
+**Landed on: knodin, CLI `knodin`.** Rationale:
+- `knodin` is how engineers already talk ("I knodin it's in the auth module",
+  "ask knodin", "knodin says nothing calls this") — a verb that spreads by
+  word-of-mouth, which is the real adoption criterion.
+- Means the right thing: to figure out / judge / know.
+- `graph` gives instant category legibility for a newcomer.
+- Clean in the niche (no code-intelligence/MCP tool by this name; the AU
+  accounting co. and an old npm `knodin` weather wrapper are benign — publish
+  scoped as `@yourorg/knodin`, the `bin` stays `knodin`).
+
+Deliberately **not** themed to pair with Atlas or the Council agents — this is a
+tool, and catchy+memorable beats thematic coherence for a tool.
+
+## Implemented product surface
+
+One flat gateway, `knodin`, with an `operation` enum. Same engine backs the CLI
+and the MCP server.
+
+| Op | CLI | Job | Wraps / builds |
+|---|---|---|---|
+| `explain` | `knodin explain <symbol>` | edit-ready verbatim source + call paths + blast radius | codegraph's job |
+| `review` | `knodin review [base]` | risk-scored diff context: changed symbols, affected flows, test gaps | code-review-graph's job |
+| `map` | `knodin map` | subsystems (Leiden communities) + EXTRACTED/INFERRED edges | Graphify's job |
+
+The backend decision is closed: knodin uses a native TypeScript/tree-sitter
+engine with local SQLite persistence, incremental watchers and reconciliation,
+stable symbol identities, resolved typed edges, communities and flows, hybrid
+local search, review scopes, health/repair, and response budgets. Optional
+local integrations remain integrations; they are not the graph backend.
+
+## Show me the value
+
+knodin gives a human or coding agent edit-ready source, resolved relationships,
+blast radius, diff risk, architecture, and bounded context without manually
+assembling a Grep/Read chain. The practical outcome is fewer missed dependencies
+and less repeated context gathering in the orient → edit → review loop.
+
+## What is the ROI?
+
+- Intended outcome: fewer agent/tool round trips for definition, caller, diff,
+  test, and architecture discovery. Existing replays measure operation-level
+  correctness, latency, and size, not an end-to-end productivity percentage.
+- One MCP schema instead of a large always-loaded tool family.
+- No hosted index, account, credential flow, source egress, or required
+  database/vector daemon.
+- Measurable correctness, latency, response-size, safety, and effort gates under
+  `benchmarks/evaluations/` rather than a generic productivity claim.
+
+## What happens tomorrow?
+
+On Windows, macOS, or Linux with Node.js 24 or newer, run
+`npm install --global --ignore-scripts knodin`. pnpm, Bun, Yarn Classic,
+and Node version-manager details are in
+[the installation guide](INSTALLATION.md). Then run `knodin init` and use the
+CLI or connect the single MCP gateway to the existing checkout. Start with
+`knodin context "<task>"`,
+`knodin explain <symbol>`, and `knodin review --scope all`; use `map`, `search`,
+and structured `query` operations when the task needs architecture or graph
+drill-down. No hosted rollout or workflow migration is required.
+
+The external Homebrew tap and GHES mirror still use their legacy repository
+names. Their knodin paths become authoritative only after each external rename
+and after the renamed artifact passes the version, MCP, lifecycle, and
+uninstall smoke gate. The repository-local formula is a migration candidate,
+not evidence that a knodin tap is already live.
+
+The packed-consumer gate proves a generic MCP handshake and local CLI behavior.
+Do not generalize that evidence into compatibility with every named assistant
+or operating system without a corresponding client/platform run.
+
+## What makes knodin unique? What is the secret sauce?
+
+The moat is the constraint combination: ambiguity-safe stable symbol identity,
+source-evidenced impact/review answers, honest freshness, serialized response
+budgets, and a compact one-tool local surface. Competitors can match individual
+features; knodin's differentiated system composes them across the daily loop
+while remaining local, measurable, and explicit about unresolved evidence.
+
+## Current state
+
+The engine, CLI, and MCP server are implemented and exercised by hundreds of
+tests plus labeled competitive replays. The active roadmap records remaining
+evidence and product-surface gaps; it does not represent an unbuilt core.
+
+- `src/engine/index.ts` — native graph backend and query/review/map lifecycle.
+- `src/tools/knodin-tools.ts` — the `knodin` gateway definition (hand-written
+  JSON Schema literal) + dispatcher.
+- `src/server.ts` — MCP stdio server, **low-level** registration.
+- `bin/cli.ts` — the `knodin` CLI over the same engine.
+
+### Hard rule carried over from AtlasMCP
+
+**Never** use the SDK's high-level `server.tool()` overload — it makes `tsc`
+infer handler arg types from the Zod shape via pathologically deep types
+(TS2589) and OOMs typecheck on larger tool sets. Register via
+`setRequestHandler(ListTools…/CallTool…)` with hand-written schema literals and
+narrow args manually. Keep to the single flat gateway; add capabilities as new
+operations, not new top-level tools.
+
+## Next work
+
+Use [`roadmap/competitive-roadmap.md`](../roadmap/competitive-roadmap.md) as the
+authoritative queue. Remaining items are evidence-backed improvements or
+bounded product-surface decisions—not implementation of a missing core engine.

package/docs/INSTALLATION.md

@@ -8,6 +8,11 @@ shells, Git hooks, and MCP clients.
 
 ## Support and evidence
 
+The certified boundary is macOS. Linux and Windows are unavailable for C91
+certification; success in portable unit tests must not be promoted into a
+platform claim. Runtime-manager fixtures cover the supported directory and
+shim layouts, not every shell customization.
+
 | Installer or manager | Command | Current status |
 | --- | --- | --- |
 | npm without a Node manager | `npm install --global --ignore-scripts knodin@<version>` | Verified by the packed-consumer gate on macOS/Linux |
@@ -19,8 +24,8 @@ shells, Git hooks, and MCP clients.
 | pnpm | `pnpm add --global --ignore-scripts knodin@<version>` | Executable gate provided; release verification requires the published version |
 | Bun | `bun add --global --ignore-scripts knodin@<version>` | Executable gate provided; release verification requires the published version |
 | approved npm-compatible registry | use the npm command with approved registry configuration | Same artifact; registry authentication/promotion is organization-owned |
-| P&T GHES release asset | after migration, download the exact `.tgz` from `Enterprise-Apps/knodin`, verify SHA-256, then use the npm command with the local file | Planned knodin path; the legacy mirror remains authoritative until the external rename and release verification complete |
-| Homebrew | after migration, `brew install knodin/tap/knodin` | Planned knodin path; the legacy tap remains authoritative until the external rename and formula gate complete |
+| P&T GHES release asset | download the exact `.tgz` from `Enterprise-Apps/knodin`, verify SHA-256, then use the npm command with the local file | Read-only synchronized mirror; source changes originate in the authoritative SaaS repository |
+| Homebrew | `brew install knodin/tap/knodin` after its formula gate | `knodin/knodin` is the tap repository, not the source or release authority |
 
 “Guidance” is not a compatibility claim. The repository records the manager
 version, command, package version, platform, and result when a release gate is
@@ -34,22 +39,12 @@ manager-owned tool.
 
 ## Exact npm installation
 
-Knodin itself requires Node.js 24 or newer. The repository being analyzed may
-remain pinned to Node.js 20. When a repository-local version-manager shim
-selects Node 20, the launcher searches `PATH` and standard mise, nvm, fnm, asdf,
-Volta, and Homebrew installation locations, then relaunches the same command
-with a version-checked Node 24+ runtime. Discovery
-trusts and probes executables from absolute, user-controlled `PATH` entries and
-version-manager locations. Override discovery explicitly when a
-runtime lives elsewhere:
+Node.js 24 or newer is required:
 
-```bash
-KNODIN_NODE_RUNTIME=/absolute/path/to/node knodin status
-```
-
-The override is version-checked before execution. Installation through npm
-should still be performed from Node 24+ so package-manager engine checks remain
-truthful:
+The handoff only relaunches the knodin launcher. It does not modify the
+repository's runtime declaration (`package.json`, `.node-version`, `.nvmrc`,
+or manager configuration). If discovery is missing or conflicting, use the
+single absolute `KNODIN_NODE_RUNTIME` override named by the diagnostic.
 
 ```bash
 npm install --global --ignore-scripts knodin@0.4.3
@@ -98,7 +93,6 @@ mise which knodin
 knodin --version
 cd /path/to/node-24-project && knodin --version
 cd /path/to/node-26-project && knodin --version
-cd /path/to/node-20-project && knodin --version
 ```
 
 ## Volta
@@ -202,6 +196,15 @@ knodin status --deep
 knodin doctor
 ```
 
+`knodin doctor` is diagnostic and preview-oriented: it enumerates manager,
+duplicate executable, lifecycle, graph, and client remediation without
+executing arbitrary suggested commands. Apply only the named `init`, `repair`,
+or `configure` operation, rerun doctor, and roll agent configuration back with
+`knodin configure --scope cli-only`. Repeating those managed operations is
+idempotent. Local fixtures use zero hosted spend, no credentials, and no source
+egress. Diagnostic archives remain governed by the privacy-safe preview and
+archive contract in [`DIAGNOSTICS.md`](DIAGNOSTICS.md).
+
 Upgrade with the manager that owns the executable:
 
 ```bash

package/docs/MCP.md

@@ -17,10 +17,13 @@ recoverable hard-budget continuations. See `docs/PROGRESSIVE-EVIDENCE.md`.
 - **CLI-only:** `knodin init --scope cli-only` keeps the local graph and Git
   refresh behavior without MCP registration.
 
-knodin supports project adapters for Claude Code, Codex, Gemini CLI, and
-Antigravity. A generic MCP handshake is release-gated. Named-client status is
-reported only when its adapter/configuration is detected; it is not proof of
-every client version or platform.
+knodin supports project adapters for GitHub Copilot in VS Code, Claude Code,
+Codex, Gemini CLI, and Antigravity. A generic MCP handshake is release-gated.
+Named-client status is reported only when its adapter/configuration is
+detected; it is not proof of every client version or platform. Personal-scope
+Copilot detection requires the VS Code CLI and an installed `GitHub.copilot`
+or `GitHub.copilot-chat` extension; team scope can write the adapter without
+claiming that the local client is installed.
 
 ## Canonical command
 
@@ -48,6 +51,21 @@ Manual JSON configuration:
 }
 ```
 
+GitHub Copilot in VS Code uses `.vscode/mcp.json` and the VS Code `servers`
+shape:
+
+```json
+{
+  "servers": {
+    "knodin": {
+      "type": "stdio",
+      "command": "knodin",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
 Codex TOML:
 
 ```toml
@@ -103,10 +121,43 @@ If the handshake fails:
 MCP requests never trigger update-network checks. Cached update state is
 available through the `doctor` operation without changing stdio framing.
 When local diagnostics have been explicitly enabled for the repository, an MCP
-operation failure records the same bounded, sanitized failure envelope as the
-CLI. It never records request arguments, queries, source, or raw responses. Use
-the CLI `knodin diagnostics collect` and `inspect` workflow to review and share
-support evidence; no MCP failure is uploaded automatically.
+operation failure records the same bounded failure envelope as the CLI. It
+never records request arguments, queries, source, or raw responses. The single
+gateway also exposes `operation: "diagnostics"` with `telemetryAction: "report"`
+for preview or `"export"` for archive. It uses the exact schema-v2 explicit-allowlist builder
+as `knodin diagnostics preview|archive`; no failure or archive is uploaded
+automatically. See `docs/DIAGNOSTICS.md`.
+
+## Request reliability and recovery
+
+Every tool call has a client request ID and generated trace ID. Graph operations
+are serialized inside one warm child process per repository/worktree; no engine
+or database handle is shared across those workers. The gateway owns deadlines,
+cancellation, a 250 ms cooperative cleanup grace, hard termination, and a
+bounded three-start-per-minute restart policy. The graph-independent `docs`
+operation remains available in the gateway while a worker is being replaced.
+`KNODIN_MCP_DEADLINE_MS` may be set to a positive value up to 300000 for local
+testing of the cooperative repair path.
+
+Checked-in process replays prove a real SQLite held lock, abrupt worker exit,
+disconnect/cancellation race against a stuck worker, hard kill, bounded restart,
+warm-worker reuse, worktree isolation, and the next independent success. The
+raw CLI stdio replay also executes a real MCP status call through the child
+boundary. Memory and deadline diagnoses remain bounded signals, not proof of an
+operating-system root cause.
+
+The gateway appends metadata-only lifecycle records to
+`.knodin/mcp-reliability.jsonl`. Synchronously appended complete JSONL records
+are retained after ordinary or abrupt worker exit, rotate at 256 KiB or
+seven days (one prior generation), and contain only operation, correlation,
+timing, progress sequence, and classified state. Restart and recovery records
+link the failed predecessor trace to the next successful request.
+They never include request arguments, queries, source, responses, environment,
+credentials, remotes, or repository paths. Progress is advisory, emitted only
+when the client supplies a progress token, and bounded to the request deadline;
+the journal retains at most 64 progress records per request. Each linked
+worktree writes only inside its own `.knodin` directory. Power-loss durability
+beyond complete synchronous records is not claimed.
 
 The `review` operation serializes graph impact, test gaps, structural
 centrality, and bounded Git-history facts separately. Churn, co-change, and

package/docs/PROGRESSIVE-EVIDENCE.md

@@ -0,0 +1,37 @@
+# Progressive source evidence
+
+`knodin evidence` returns exact local source through four deterministic levels:
+
+1. `locate` — stable file identity, path, hash, size, freshness, and confidence.
+2. `outline` — top-level declaration signatures and exact line ranges.
+3. `evidence` — requested verbatim source lines with edit anchors intact.
+4. `expand` — the complete verbatim file within caller-selected hard budgets.
+
+CLI:
+
+```bash
+knodin evidence locate src/widget.ts
+knodin evidence evidence src/widget.ts --start 10 --end 30
+knodin evidence evidence src/widget.ts --continuation <evidence-handle> \
+  --baseline-hash <sha256> --baseline-bytes <bytes>
+```
+
+The single MCP gateway uses `operation: "evidence"`, `file`, and
+`evidenceLevel`. Supply a returned `continuation` to recover omitted source.
+Every response names returned and omitted material, a reason, whether more
+exists, a stable continuation and evidence handle, freshness, confidence, the
+path taken, and exact item/UTF-8-byte/local-token-estimate budgets.
+The mandatory recoverability envelope requires at least 1,600 effective bytes
+(the lower of the byte cap and four times the local token-estimate cap); smaller
+requests fail closed instead of dropping contract fields.
+
+Source omission occurs only when a server-issued evidence handle is valid and
+both `baselineHash` and `baselineBytes` equal the current complete local file.
+Missing or partial metadata/handle, a stale/tampered hash, source changed since
+a handle was issued, or a renamed path selects a named `full-*` recovery path.
+Invalid or tampered handles fail closed. Inputs
+must identify an exact repository-relative regular file; ambiguous selection,
+absolute/traversal paths, and symlinks are refused.
+
+This protocol does not summarize source and does not support token-savings or
+task-success claims. See the C83 checked-in replay and limitations for bounds.

package/docs/PT-ACCESS-RECOMMENDATION.md

@@ -0,0 +1,89 @@
+# P&T access through Docusign GitHub Enterprise Server
+
+The knodin GHES path is
+`github.docusignhq.com/Enterprise-Apps/knodin`. It is a read-only downstream
+mirror of the authoritative GitHub SaaS repository
+`DTS-Productivity-Engineering/knodin`; product changes must originate in
+that source repository, never in the mirror or the `knodin/knodin` Homebrew tap.
+
+The legacy `v0.3.0` release and its original artifact digest were verified on
+2026-08-01. That evidence does not certify a renamed knodin artifact or path.
+
+## Quick install without GitHub SaaS
+
+Node.js 24 or newer and an authenticated GHES CLI are required. Download the
+versioned release asset from GHES, verify its observed SHA-256, install it
+without dependency lifecycle scripts, and initialize the existing checkout:
+
+```bash
+mkdir knodin-install && cd knodin-install
+GH_HOST=github.docusignhq.com gh release download v0.3.0 \
+  --repo Enterprise-Apps/reckon-graph \
+  --pattern 'reckon-graph-0.3.0.tgz'
+printf '%s  %s\n' \
+  373ca7540e745915f195e51f4ed6383374e4df4a2b8663872b2f279380e60989 \
+  reckon-graph-0.3.0.tgz | shasum -a 256 --check
+npm install --global --ignore-scripts ./reckon-graph-0.3.0.tgz
+cd /path/to/existing/repository
+reckon init
+reckon doctor
+reckon status --deep
+```
+
+Unverified Windows guidance: PowerShell provides
+`Get-FileHash -Algorithm SHA256` instead of `shasum`, and the npm/CLI commands
+are intended to be portable. A native Windows named-client run has not yet been
+certified, so this is not a Windows support claim. The release page records the
+versioned filename and observed digest; do not substitute a branch archive or a
+mutable `latest` URL. GHES does not currently enforce immutable releases, which
+is why digest verification and the separate signed-update trust remain
+required.
+
+The same 0.3.0 tarball was published to Docusign Artifactory at
+`dts-productivity-engineering-npm-dev-local/knodin-0.3.0.tgz`. That raw
+artifact path requires normal corporate Artifactory authentication and is not
+an npm registry endpoint. GHES release download is the supported P&T bootstrap
+until an approved internal npm virtual repository exposes the package metadata.
+
+## Mirror operating model
+
+1. Source commits and reviewed release tags originate in the GitHub SaaS
+   repository.
+2. The GHES `main` branch and release tag are synchronized without rewriting
+   history.
+3. The exact retained release tarball is attached to the matching GHES release;
+   it is not rebuilt on GHES.
+4. A release is not certified merely because it appears on GHES. The final
+   cross-channel attestation must prove that npm, Artifactory, GitHub SaaS,
+   Homebrew, and GHES represent the same source and bytes.
+5. Developers do not dual-push feature branches. Mirror synchronization is a
+   release/operations responsibility and must eventually use a narrowly scoped
+   workload identity rather than a personal SSH key.
+
+The destination must eventually enforce repository visibility, branch
+protection, required reviews/checks, security scans, commit/tag provenance, and
+license notices. Today the repository is internal, but `main` is unprotected and
+maintainers retain push access. Those are open governance controls, not
+completed evidence. Future mirror automation must fail closed and must not
+accept changes back into the authoritative repository.
+
+## Required governance follow-up
+
+Record or complete:
+
+- repository-owner approval to disclose the source to P&T;
+- enterprise GitHub/security approval for cross-organization private forks or
+  mirrors;
+- legal/compliance confirmation for source and license visibility;
+- the exact destination GitHub organization and repository name;
+- confirmation of destination visibility and membership controls;
+- the required branch-protection, review, scan, and retention policy;
+- approval of a narrowly scoped GitHub App/workload identity, its installation
+  owners, secret store, rotation owner, and audit-log owner;
+- an owner for incident response and mirror decommissioning.
+
+The destination repository and current release asset are live. Branch
+protection, enforced read-only direction, automated mirror synchronization,
+production threshold-update trust, timed onboarding evidence, and a Windows
+named-client release certification remain open gates; the existence of this
+access path is not evidence that those separate controls are complete.

package/docs/RELEASE-0.3-EVIDENCE.md

@@ -0,0 +1,73 @@
+# Reckon Graph 0.3 evidence ledger
+
+This ledger freezes the field and competitor evidence used to define the 0.3
+release. Historical observations are not rewritten as current measurements.
+
+## Minions field observation
+
+The prior 0.1.22 field run recorded:
+
+- 3,006 source files;
+- 2,949 indexed files and 157 health findings before repair;
+- 3,006 indexed files after repair;
+- current HEAD `cbf058aa...`;
+- recorded indexed HEAD `4d45fe02...`;
+- a 16-commit distance while 0.2.0 status incorrectly reported healthy;
+- 195 repair operations, including reconciliation of stale/orphaned state and
+  regeneration of 1,874 symbol embeddings.
+
+The workload fast-forwarded main across 15 merged commits and removed 16 linked
+worktrees. The checked-in lifecycle regression recreates those lifecycle
+shapes, including additions, edits, renames, deletions, policy transitions,
+overlapping hook workers, immediate queries, and cleanup.
+
+The Minions checkout is a read-only field fixture for this release. Its current
+HEAD on 2026-07-30 was `44c91f6d013fd8d6f4e106d063a87eab94b19866`;
+the historical SHAs above belong to the original observation, not that later
+checkout state. Existing modified and untracked Minions files were left intact.
+
+## Token Optimizer observation
+
+The complete 102.8-second demo artifact has SHA-256
+`a8085ec26d56ab220f3b31578f818a911caf277e604ed9f8d46c0d9f31fbb60d`.
+It demonstrates seven named surfaces: file outline, symbol extraction, symbol
+find, batch outline, project overview, output compression, and command running.
+It describes Python AST parsing and heuristic/regular-expression coverage for
+other languages.
+
+At release time, no authorized immutable source commit, packaged executable,
+README, version, or raw measurement data was available, so the original
+observation was `demo-only`. A post-release source audit now pins the authorized
+GHES implementation at
+`a2b9cef5efdfcf0393e9e7a5ded229ffd9f613d7`. It verifies the source inventory
+and selected implementation observations, including a behavioral compression
+budget probe. Equivalent end-to-end measurements remain incomplete, and the
+displayed savings remain hypotheses: the demo showed two calls, used a bytes/4
+token estimate, and showed inconsistent 83% and 93% targeted-lookup figures.
+
+The reproducible comparison contract is
+[`../benchmarks/evaluations/token-optimizer-20260730/comparison-manifest.json`](../benchmarks/evaluations/token-optimizer-20260730/comparison-manifest.json).
+The immutable source result is
+[`../benchmarks/evaluations/token-optimizer-20260730/raw-source-audit-20260730.json`](../benchmarks/evaluations/token-optimizer-20260730/raw-source-audit-20260730.json).
+Missing behavioral measurements are `null`, never zero.
+
+The later C56 replay now executes all seven pinned workflows with shared
+fixtures, real-token counts, 20 warm samples, five cold-process samples, and
+explicit correctness oracles. Both products pass the five structural oracles.
+The result is intentionally `complete-with-gaps`: Token Optimizer is smaller
+and faster on all five small-fixture structural calls, Reckon has no output
+compressor yet, and command execution remains containment-gated. See
+[`../benchmarks/evaluations/token-optimizer-20260730/summary.md`](../benchmarks/evaluations/token-optimizer-20260730/summary.md).
+
+## Implemented and deferred
+
+Reckon now provides parser-grounded bounded file and batch outlines, compact
+source-only extraction, deterministic project overview, natural-prompt routing,
+real-token local telemetry, and a static local report through the existing
+single `reckon` gateway.
+
+`reckon run` is not shipped. A no-shell launcher alone could not prove portable
+hard memory limits and process-tree termination across POSIX and Windows. The
+full gate and adversarial fixtures remain documented in
+[`COMMAND-OUTPUT-COMPRESSION.md`](COMMAND-OUTPUT-COMPRESSION.md). This is a
+security decision, not a claim that the competitor implementation is unsafe.

package/docs/REPOSITORIES-AND-WORKTREES.md

@@ -55,14 +55,26 @@ doctor` and the single MCP gateway are unchanged.
 
 Sibling location never establishes system membership or a relationship.
 `repos init` works sequentially and performs each live repository operation in
-a disposable process with a 768 MiB RSS ceiling. A worker that exceeds the
+a disposable process. Memory is uncapped by default so a legitimate large
+repository is not killed by a product-wide guess. Operators can set an explicit
+per-repository RSS ceiling for one run with `--memory-limit-mib <mib>` or for a
+configured portfolio in `knodin.yaml`; the CLI value takes precedence:
+
+```yaml
+schemaVersion: 1
+repositoryInitialization:
+  memoryLimitMiB: 1024
+```
+
+The minimum explicit ceiling is 128 MiB. A worker that exceeds a configured
 ceiling or its deadline has its process group terminated, produces a
 repository-scoped failure, and does not prevent later repositories from being
-processed. JSON records the observed per-repository peak, enforced ceiling,
-and count of ceiling failures. The 50 ms RSS heartbeat is a bounded enforcement
-interval rather than a claim that transient allocation can never overshoot by
-one sample. Windows can terminate the worker process but cannot provide the
-same descendant process-group guarantee as macOS/Linux.
+processed. JSON records the observed per-repository peak, the enforced ceiling
+or `null` when uncapped, and the count of ceiling failures. The 250 ms RSS
+heartbeat is a bounded enforcement interval rather than a claim that transient
+allocation can never overshoot by one sample. Windows can terminate the worker
+process but cannot provide the same descendant process-group guarantee as
+macOS/Linux.
 
 Initialization supports `--dry-run` and preserves a healthy graph when only
 managed integration needs refreshing. Dry-run never starts a worker, opens a

package/docs/SCIP-IMPORT.md

@@ -0,0 +1,62 @@
+# Optional SCIP import
+
+> **Bounds are overridable.** Every limit below can be raised with a flag, and
+> each refusal names the flag and a value that would admit the file:
+> `--scip-max-bytes`, `--scip-max-files`, `--scip-max-facts`,
+> `--scip-timeout-ms`. A ceiling the operator cannot move is just a failure.
+
+knodin can add compiler-produced SCIP facts to its local graph without running a
+language server. The tier is deliberately opt-in:
+
+```sh
+knodin index --scip path/to/index.scip
+```
+
+The input must be a regular file inside the repository. knodin never discovers,
+downloads, or produces a SCIP index, and a normal `knodin init` or `knodin
+index` does not import one. Repositories without the flag keep the existing
+native and LSIF behavior byte-for-byte at the command boundary.
+
+## Evidence and conflicts
+
+Imported definitions use stable repository/file/range identities, `SCIP_*`
+kinds, a summary containing the original SCIP symbol and `scip` provenance,
+`scip_reference`, `scip_relationship_reference`, `scip_implementation`,
+`scip_type_definition`, or `scip_definition` reference kinds, and `scip_import`
+file edges. Native and LSIF facts are not deleted or overwritten. If two tiers
+define the same name, normal ambiguity-safe resolution returns all candidates
+and requires a file, kind, or identity selector. A stale SCIP input is refused
+rather than replacing fresher source-derived evidence.
+
+Every successful index result includes the producer name/version and represented
+languages from the SCIP file plus the exact limits used. Defaults are 64 MiB,
+10,000 documents, 250,000 decoded facts, and 30 seconds. Inputs that are
+missing, malformed, oversized, stale relative to a represented source file, or
+contain absolute, traversal, missing, symlink, or non-file document paths fail
+before the SCIP tier is replaced.
+
+## Known bounds and limitations
+
+- The importer supports standard SCIP `Index`, `Document`, `Occurrence`,
+  `SymbolInformation`, and `Relationship` fields needed for definitions,
+  references, source ranges, and relationships. Unknown protobuf fields are
+  skipped, but unsupported wire types and malformed ranges fail closed.
+- Precision and coverage are bounded by the producer. Checked-in coverage is
+  npm-integrity-pinned `@sourcegraph/scip-typescript@0.4.0` over TypeScript. Its
+  emitted documents omit the optional language field, so the import report says
+  `unknown`; other conforming producers and languages are not certified by C84.
+- The index mtime must be at least as new as every represented source file.
+  This is a conservative local freshness check, not a claim that the producer
+  indexed the exact Git commit or compiler configuration.
+- An import replaces the prior SCIP tier as one snapshot. It does not merge
+  multiple SCIP files, watch an index, start a daemon, or provide live LSP.
+  Live LSP requires a separately approved roadmap item.
+- SCIP local symbols are scoped by document. Relationship flags remain distinct
+  (`reference`, `implementation`, `type-definition`, or `definition`); only an
+  actual cross-file occurrence reference contributes a `scip_import` file edge.
+- The checked-in replay is synthetic and authorizes no superiority,
+  production-readiness, trusted-distribution, or cross-platform claim.
+
+The replay, verifier, raw results, and resource report live under
+`benchmarks/evaluations/c84-scip-import/`; run `npm run verify:c84` entirely
+offline to reproduce them.