knodin 0.7.5 → 0.8.2

package/docs/COMPETITIVE-LANDSCAPE-2026-08.md

@@ -0,0 +1,267 @@
+# Reckon Graph — Competitive Landscape & Strategic Threat Assessment
+**Date:** 2026-08-01 · **Rev 2** (post-verification) · **Subject:** `reckon-graph` v0.4.3 (Docusign / DTS-Productivity-Engineering)
+**Status:** research assessment with corrections applied. Not a benchmark report. See §0 for what is verified and by whom.
+
+---
+
+## 0. Provenance and evidence discipline
+
+This document follows the attribution rule already established in `docs/COMPARISON.md`: a claim is either **verified in this repo**, **attributed to a vendor**, **independently measured**, or **unverified**. Rev 2 applies corrections from a verification pass run in a networked environment.
+
+### Four classes of claim, marked throughout
+
+| Mark | Meaning |
+|---|---|
+| **[repo]** | Read directly from the `reckon-graph` checkout. Highest confidence. |
+| **[independent]** | Measured by a third party with published methodology (JetBrains, arXiv preprints). |
+| **[vendor]** | The vendor's own claim. Not reproduced. |
+| **[survey]** | Observed in this research pass. **Absence of a finding is not proof of absence in the market.** |
+
+### Network limitation — scoped correctly
+
+The GitHub REST API was **unreachable from this research environment**, returning HTTP 403 with an explicit sandbox-policy body (`"GitHub access to this repository is not enabled for this session"`) — a network policy on my side, **not a GitHub outage and not a universal condition**. Rev 1 stated the caveat as though it were a fact about the world. It was a fact about my environment. A subsequent verification pass from a networked environment did reach the API.
+
+**Star snapshot — two sources, neither independently confirmed by me:**
+
+| Repository | Rev 1 (page reads / aggregators) | Verification pass, 2026-08-01 (live API) |
+|---|---|---|
+| `colbymchenry/codegraph` | 21,913 / 59.7k (disputed) | **63,942** |
+| `Graphify-Labs/graphify` | 30.6k / 76k (disputed) | **100,041** |
+| `Cranot/roam-code` | ~460 | **502** |
+| `GlitterKill/sdl-mcp` | ~301 | **457** |
+| `aovestdipaperino/tokensave` | ~249 | **523** |
+| `sverklo/sverklo` | ~76 | **76** |
+| `sdsrss/code-graph-mcp` | 44 | **60** |
+
+> ⚠️ **Two of these warrant a human sanity check before external use.** A 100,041-star count would place a niche code-graph MCP tool in roughly the top tier of all GitHub repositories, and 63,942 for a repo created in January 2026 is an extraordinary four-month trajectory. Both may well be correct — the AI-tooling hype cycle produces real outliers — but I could not confirm either, and Rev 1's assertion that the *lower* codegraph figure was "more credible" was an unsupported guess and is withdrawn. **Star counts move daily; timestamp any figure you reuse.**
+
+The separate warning about **AI-generated comparison spam in this category remains valid and unretracted** — aggregator blogs published figures differing from each other by 10–1000× (one checked case: `sdsrss/code-graph-mcp` cited at 16,000, actual double digits). That warning was about source quality, not API reachability.
+
+### Corrections applied in Rev 2
+Codebase-Memory paper figures (transposition + a fabricated detail) · MCP operation count (13 → 19) · cross-substrate impact demoted from capability to opportunity · all market-wide superiority claims rescoped to the surveyed set · TACO characterization softened and "peer-reviewed" removed · Amazon Q retirement narrowed · Claude Code "absorbed nothing" narrowed · Graphify version/license refreshed · vendor-percentage generalization narrowed.
+
+---
+
+## 1. What Reckon Graph is **[repo]**
+
+**A local, MIT-licensed code-intelligence MCP server that fuses four normally-separate jobs over one fresh SQLite graph, behind a single operation-routed MCP tool.**
+
+| Layer | Detail |
+|---|---|
+| **Deployment** | One local Node.js 24+ process. No account, hosted index, credential flow, source egress, or mandatory database/vector daemon. `.reckon/db.sqlite` per checkout; shared MiniLM ONNX model in the user cache. |
+| **MCP surface** | **Exactly one tool** (`reckon`) with **19 operation values** — verified in `src/context.ts:17-36` and `src/tools/reckon-tools.ts:216`: `explain`, `review`, `map`, `search`, `query`, `prs`, `context`, `wiki`, `docs`, `doctor`, `pack`, `compress`, `status`, `wait`, `worktrees`, `repair`, `repositories`, `system`, `telemetry`. *(Rev 1 listed 13, taken from the README rather than source.)* |
+| **Core jobs** | `explain` (edit-ready verbatim source + call paths + blast radius) · `review` (risk-scored diff context, four explicit scopes) · `map` (Louvain communities + hubs + betweenness bridges) · `context`/`search`/`pack`/`compress` (bounded retrieval and export). |
+| **Distinctive contracts** | Serialized **`responseBudget`** on every operation — byte/token/item limits, serialized size, truncation state, totals, continuation instruction; deterministic 4-bytes-per-token estimate, tested in `src/__tests__/unit/response-budget.spec.ts:35`. Explicit availability states (`no-match`, `not-initialized`, `empty-index`, `repair-needed`, `indexing`, `lifecycle-degraded`) that fail closed. Per-query freshness probe measured at **~30–50ms**, honestly qualified in `docs/COMPARISON.md:17`. |
+| **`compress` / `compress diagnose`** | Bounded, recoverable compression of build/test output under hard line + content-byte budgets, preserving exit metadata and detected signals with exact omission reporting — then mapping a retained failure back through the graph to owning symbols, tests, callers, and bounded source. |
+| **Parsers** | TS/JS, Python, Java, C#, **Apex**, SQL/PLSQL, Prisma, XML; structural indexers for **Salesforce metadata, Terraform/HCL, Dockerfile, dbt manifests, Workday Studio XML, LSIF**. Gaps: Go, Rust, PHP, Ruby, Kotlin, Swift, Bash, PowerShell — per `docs/LANGUAGE-SUPPORT.md`. |
+| **Scale-out** | `reckon repos discover/init/status/doctor`, `reckon system`, `reckon.yaml`. Live 61-repository bounded certification recorded in `roadmap/competitive-roadmap.md:100`. |
+| **Release posture** | npm + Homebrew tap + digest-pinned GHES assets. Signed-update machinery implemented; ceremony/drills open as C62–C67. |
+
+---
+
+## 2. The four-way squeeze
+
+| Category | Reckon surface | 2026 pressure |
+|---|---|---|
+| Symbol navigation | `explain`, `query`, `search` | 🔴 **Commoditized.** Many free local OSS servers. Serena still strongest via LSP. |
+| Change impact & review | `review`, `impact`, `tests_for`, `prs` | 🔴 **Squeezed both ends.** Free OSS ships risk-scored diff review; Greptile and CodeRabbit give away SaaS review at the free tier. |
+| Architecture mapping | `map`, `community`, `flows`, `wiki`, `visualize` | 🟠 **Being absorbed into products teams already buy.** SonarQube shipped Architecture (beta) inside its **$34/mo Team plan** [vendor]. DeepWiki is free for public repos. |
+| Retrieval & context | `context`, `pack`, `compress` | 🟢 **Bifurcated.** Packers are symbol-blind; graph servers never see a build log. **No tool in the surveyed set crosses that line.** |
+| **Platform substrates** *(not in the README taxonomy)* | Apex, SF metadata, Terraform, Workday XML | 🟢 **Least contested surface found**, and the one the docs undersell — `LANGUAGE-SUPPORT.md` frames it as a *limitations* matrix. |
+
+---
+
+## 3. Known competitors — what moved
+
+| Tool | Status change (2026) | Implication |
+|---|---|---|
+| **codegraph** (colbymchenry) | 🔴 **Converged on the one-tool thesis.** Lists `codegraph_explore` as its single default MCP tool with seven others functional-but-unlisted behind `CODEGRAPH_MCP_TOOLS`. Hosted-platform waitlist opened. Stars: see §0 snapshot. | **"Single operation-routed MCP tool" is no longer differentiating.** It is a shared design pattern. |
+| **codebase-memory-mcp** | 🔴 Now ships **Louvain community detection** and `detect_changes` (git diff → affected symbols with risk classification). **Published preprint** — arXiv:2603.27277, verbatim from the abstract: *"parsing **66 languages**… Evaluated across **31 real-world repositories**, Codebase-Memory achieves **83% answer quality versus 92%** for a file-exploration agent, at **ten times fewer tokens** and **2.1 times fewer tool calls**."* [independent, preprint — not peer-reviewed] | Two Reckon headline features replicated in a tracked competitor — **with a published methodology Reckon has not matched.** *(Rev 1 said "31 languages, 12 question categories." Both wrong: figures transposed, and "12 question categories" does not appear in the paper.)* |
+| **Graphify** | YC S26. **v0.9.31 (published 2026-07-30), Apache-2.0** per repository API. Leiden communities; `EXTRACTED`/`INFERRED`/`AMBIGUOUS` confidence tags; multi-modal ingest. Star figure disputed — see §0. | Its confidence-tier model is the closest analogue found to Reckon's evidence labeling. |
+| **GitNexus** | PolyForm Noncommercial; migrated to LadybugDB; 17 MCP tools; enterprise SaaS tier. | License remains the cleanest wedge here. Unchanged. |
+| **grepai** | Last release v0.35.0 (Mar 2026) — ~5 months quiet. | Deprioritize. |
+| **Serena** | Reference LSP-over-MCP implementation; no token budgets. | Unchanged: better freshness and compiler accuracy, no graph analytics. |
+| **Repomix** | v1.17.0 (Jul 2026). Tree-sitter "Code Compression" (**[vendor]** ~70% reduction), `--include-diffs`/`--include-logs`, `--token-count-tree`, `--split-output`, Agent Skills generation, two CVE fixes. ~26k★ / ~255k npm downloads/mo. | **`pack` alone is a commodity.** Repomix converged on nearly Reckon's `pack` feature set at far greater distribution. |
+| **Aider repo-map** | Algorithm essentially unchanged since 2023. | Still the reference design; still not an MCP surface. |
+
+---
+
+## 4. New entrants not tracked in-repo
+
+### Tier 1 — direct architectural twins
+
+| Tool | Threat | Why |
+|---|---|---|
+| **Sverklo** (76★, MIT, TS) | 🔴 Critical | **Closest competitor found.** Independently arrived at Reckon's *exact* stack — SQLite + `sqlite-vec` + local `all-MiniLM-L6-v2` ONNX — and its analytics set: `review_diff` risk-scores by symbol importance × coverage × churn; `audit` finds god nodes and hub files; `ctx_peek`/`ctx_slice` slice context. Adds bi-temporal memory Reckon lacks. **Its only clear weakness vs Reckon is 37 flat MCP tools.** [vendor] 180-task benchmark, F1 0.58 vs grep 0.34. |
+| **sdl-mcp** (457★, source-available) | 🔴 Critical | Ships an explicit **gateway mode (6 tools)** alongside 38 flat ones — attacks the one-tool differentiator directly. Its **"Iris Gate Ladder"** (four-rung context escalation with proof-of-need gating before raw source is released) is a more legible, productized articulation of Reckon's response-budget idea. |
+| **roam-code** (502★, Apache + open-core) | 🟠 High | `preflight` = blast radius + tests; `critique` consumes `git diff`; PageRank reranking (explicitly rejects embeddings); signed exportable index bundles. **145 MCP tools** — the best foil for the one-tool argument. Uniquely detects algorithmic anti-patterns (O(n²), N+1). |
+| **sdsrss/code-graph-mcp** (60★, Rust) | 🟠 High | SQLite + `sqlite-vec`, BM25+vector RRF, optional local Candle embeddings, **BLAKE3 Merkle incremental reindex**, dead code, impact analysis with risk classification, explicit "context compression for LLM token budgets." **A double-digit-star project matches the capability list.** |
+| **Code-Graph-RAG** (~2.3k★, MIT, Python) | 🟠 High | Restored and active at v0.0.535 after its GitHub-account outage. Its opt-in `READS_FROM`, `WRITES_TO`, and `FLOWS_TO` graph models environment variables, files, databases, sockets, network endpoints, and standard streams across nine language registries. This is a real gap versus Knodin's bounded TS/JS statement flow, but its Memgraph + Docker + optional Qdrant/model stack conflicts with Knodin's compact local architecture. The analysis is conservatively intra-procedural plus one argument/return handoff, not path-sensitive, and source-order limited across files. C78's local disposable prototype retained 100% precision but reached only 62.5% recall on its labeled TS/JS oracle, so Knodin retained C8 unchanged rather than persisting a partial static reachability graph. |
+
+### Tier 2 — adjacent, high momentum
+
+**CocoIndex** (~10.2k★) — incremental pipeline framework now shipping a code MCP with AST-aware incremental index, call graph, blast radius; per-row provenance, hash-of-code invalidation. **The most credible competitor found to Reckon's freshness/reconciliation story.** · **Semble** (~5.7k★, MIT) — 2 MCP tools, **static Model2Vec embeddings, no transformer**; [vendor] 250ms full index, 1.5ms query, NDCG@10 0.854. · **tokensave** (523★, Rust) — composite code-health score (acyclicity, Gini, modularity, DSM); **per-branch graph DBs with cross-branch diff**, no equivalent in Reckon. · **Axon** (~709★, stalled Mar 2026) — Leiden communities, symbol-level branch diffing, **change-coupling from 6 months of git history**; on archived KuzuDB. · **RTK** — PreToolUse-hook binary compressing Bash output across 15 agents; **closest competitor to `compress`**, and independently benchmarked — see §5. · **build-output-tools-mcp** — the only other tool found with **artifact-ID drill-back** from compressed build output, but LLM-summarized (non-deterministic), no hard budget, no omission accounting, and drill-back returns raw log text rather than owning symbols.
+
+**CodeFlow** (~3.7k★, MIT) — client-side interactive architecture map with
+dependency/blast-radius views and raw JSON export. Its README explicitly calls
+dependency resolution heuristic and warns that dynamic imports and runtime
+renames may be missed. A LinkedIn summary further claims that individual edges
+identify whether they came from Tree-sitter, a language parser, or regex, but
+that finer per-edge extractor identity was not found in the current repository
+or README and remains unverified. Knodin already returns edge provenance,
+confidence, exact-versus-heuristic labels, source evidence, and source lines;
+C77 adds a like-for-like replay to test communication and export fidelity rather
+than assuming a product gap.
+
+### Tier 3 — ecosystem facts
+🔴 **Kuzu is dead** — archived without notice Oct 2025; an EC filing revealed an Apple acqui-hire. Successors: LadybugDB, FalkorDB Lite, Lance Graph. **Reckon's plain-SQLite choice is now a concrete talking point.** · 🟠 **SCIP moved to independent open governance (Mar 2026)** with a Meta/Uber/Sourcegraph steering committee. It is the durable interchange format and the precision upgrade path competitors are taking. **Reckon supports LSIF, which SCIP supersedes — a closable gap.**
+
+### Dead / stalled
+er77/code-graph-rag-mcp (archived) · mcp-language-server (last release May 2025) · VectorCode · code2prompt · files-to-prompt · **CodeSee** (→GitKraken 2024, sunset) · **Structure101** (→Sonar Oct 2024, explicitly no longer sold).
+
+---
+
+## 5. The commercial tier restructured
+
+| Player | 2026 state | Egress | Floor |
+|---|---|---|---|
+| **Sourcegraph** | Split from **Amp** into separate companies (Dec 2025). **Cody Free/Pro deleted.** MCP server GA (Feb 2026) with SCIP-precise navigation; **Code Finder** [vendor] 2.19× faster, up to 40% fewer tokens than agents searching locally. | Self-hosted = none | **$16K/yr** |
+| **Augment** | Pivoted to **Cosmos** orchestration; killed completions Mar 2026; individual plans eliminated. Context Engine survives ([vendor] 33% fewer tokens). | SaaS, indexed on their infra | $100/mo flat |
+| **Greptile** | $25–30M raised, Benchmark-led. Explicit graph-based context → impact analysis. MCP server. Reads `CLAUDE.md`. | Self-host incl. air-gapped (Ent.) | Free tier / $30 seat |
+| **Qodo** | **DeepCodeBench** [vendor] (1,144 PR-derived questions): Qodo 80% fact recall vs Claude Code 64%, Gemini CLI 45%. | **On-prem supported** | ~$0.012/credit |
+| **CodeRabbit** | [vendor] $40M ARR, ~700% YoY, 8,000+ paying customers. Weakest graph story — no published architecture. | SaaS; self-host Ent. only | Free / $24 user |
+| **Cursor** | Trained its **own embedding model** on agent session traces: [vendor] +12.5% accuracy, +2.6% code retention on 1,000+ file repos. **Explicitly says it does not replace grep.** | SaaS, server-side chunking | $20/mo |
+| **Windsurf** | Cognition acquired the remnant; **became Devin Desktop (Jun 2026)**. Cascade retired; Devin Local rewritten in Rust. | SaaS + VPC Ent. | Free / $20 |
+| **Amazon Q Developer** | **IDE plugins and paid subscriptions** are being retired — new signups blocked May 2026, support ends Apr 30 2027, replaced by **Kiro**. **AWS explicitly states Q Developer in the AWS console and other first-party experiences is unaffected.** *(Rev 1 said "being retired" flatly — overbroad.)* | — | — |
+| **DeepWiki** | Free, no auth, every public GitHub repo. MCP server. | Hosted only | **$0** |
+
+> **The wedge, precisely.** In the surveyed set, nobody paid competes below $30/seat except the agent vendors themselves. **Reckon's "free + local + no-egress" wedge holds against the commercial tier** — and is gone against OSS, where it is the baseline every entrant leads with.
+
+### Adjacent tiers
+Every DSM/architecture vendor MCP-enabled within ~6 months: Lattix 2026.0, NDepend (Feb 2026, open-sourced), CAST Imaging ($10.5K–$810.8K/yr), vFunction 4.5, and **Moderne** (local stdio MCP, Apr 2026 — auto-configures Claude Code/Cursor/Windsurf; [vendor] a Java 8→25 migration going 61M→30k tokens). **"Local graph + MCP server" became a checkbox in H1 2026.**
+
+**SonarQube is the most dangerous long-tail threat:** Architecture (beta) + MCP GA + AI Code Assurance inside a **$34/month** product a large share of enterprise teams — including Docusign, per this repo's own `sonar-project.properties` — already license.
+
+### Platform substrates — leg by leg
+
+| Substrate | Served? | Assessment |
+|---|---|---|
+| **Apex source graph** | 🟢 Open | Salesforce Code Analyzer v5 + Graph Engine is *violation-shaped*, not navigable — **no caller/reference API found in the surveyed set**. SFGE remains Developer Preview and its per-entry-point timeout was cut 15 min → 30 s, with Salesforce conceding "some complex code violations may be missed." |
+| **SF metadata graph** | 🟡 Contested | Elements.cloud, Salto, Panaya, Copado Agentia, Gearset Org Intelligence all claim it. **Every vendor examined in this pass requires live-org credentials**; none was found operating from a local checkout with no org connection. Window: ~12–18 months. |
+| **Terraform / HCL** | 🟢 Largely open | **No local-checkout Terraform dependency analyzer for agents found in the surveyed set.** HashiCorp's official Terraform MCP server is registry/HCP-oriented per its own reference docs. `terraform graph` emits DOT with no agent surface. |
+| **dbt** | 🔴 Solved | **Do not lead with dbt.** Official `dbt-mcp` ships local *and* remote **column-level lineage**. Reading `manifest.json` gets node-level lineage dbt already exposes better. |
+| **Workday Studio XML** | 🟡 Open | **No Studio-XML static analyzer found in this pass.** Workday's June 2026 agent launch is about *building* agents, not *understanding* existing assemblies. Tiny, shrinking market. |
+
+> **Cross-substrate impact is an opportunity, not a shipped capability. [corrected]**
+> Reckon demonstrably indexes Terraform, dbt manifests, Salesforce metadata/Apex, and Workday inputs **independently**. Rev 1 listed *"Terraform → dbt → Salesforce field → Apex trigger"* cross-substrate resolution in the implemented-differentiator matrix. **A verification pass found no implementation, test, or documentation establishing that chain.** Correct framing: *Reckon has the ingredients for cross-substrate analysis; a demonstrated end-to-end cross-substrate path remains an opportunity* — and would need a checked-in replay before it appears in any external claim. This matters because `CLAUDE.md` explicitly forbids describing the engine as planned or almost-done.
+
+---
+
+## 6. The research that should change the pitch
+
+**Three primary studies, supported by two additional preprints.** *(Rev 1 said "three studies" and then listed five.)*
+
+**① "Token Reduction Is Not Cost Reduction" — arXiv:2607.12161 (Jul 2026) [independent].** 2,908 Claude Code runs, 103 tasks, 7 repos, 3 models. Evaluated RTK, RTK-ML, Headroom, plus lexical/embedding/structural retrieval.
+- Removing **38.4% of tool-output tokens produced a +6.8% cost *increase*** (95% CI [+2.8, +11.3]).
+- Token reduction correlated with cost change at **r = 0.15** — essentially zero.
+- **Prompt cache ≈ 87% of reconstructed cost.** Compressing uncached output attacks a small slice *while invalidating the cache.*
+- **Compression destroyed verbatim edit anchors: patch application fell 27/40 → 15/40.**
+
+**② JetBrains independent RTK trial (Jul 2026) [independent].** Pre-registered, paired A/B, 86 tasks, 425 billed trials. Low effort: **+7.6% cost** (p=0.004). High effort: ~0%. Output quality statistically equivalent. **RTK's own analytics reported "96.2M tokens saved" while the bill went up.**
+
+**③ ContextBench — arXiv:2602.05892 (Feb 2026) [independent].** 1,136 tasks, 66 repos, 8 languages, human-annotated gold contexts. Headline: *"sophisticated agent scaffolding yields only marginal gains in context retrieval."* **Adverse to the entire category, Reckon included.**
+
+*Supporting:* **TACO** (arXiv:2604.19572) — *"A Self-Evolving Framework for Efficient Terminal Agents via Observational Context Compression."* Learns compression rules from execution trajectories and preserves error/failure-signal outputs unchanged — the same invariant as Reckon's "preserve detected diagnostics." **Reports task-dependent token reductions with maintained or improved success rates; the abstract was not machine-readable at verification time, so no specific percentage is quoted here, and it is a preprint, not peer-reviewed.** *(Rev 1 characterized it as "peer-reviewed" with a clean "~10% per step" figure — both overstated.)* · **"Notation Matters"** (arXiv:2605.29676) — TOON/TRON encodings buy 18–27% at 9–14pp accuracy cost; Markdown/JSON/XML is the right call.
+
+> **What to do with this.** The 27/40→15/40 patch-application collapse is a **correctness** failure caused by lossy, unrecoverable compression — the exact failure mode that bounded, recoverable, exact-omission-accounted compression is designed to prevent. That is a falsifiable, benchmark-backed pitch. A percentage is not. **Many surveyed vendor token-reduction claims are self-measured against undisclosed baselines** — that is a characterization of the sampled set, not a universal law *(Rev 1 said "every," which the report's own independent citations contradict)*.
+>
+> Two facts make `responseBudget` load-bearing: **Claude Code's ~25K-token tool-result ceiling** is documented in `anthropics/claude-code#45770` — *an issue report, not a formal product contract* — and the **MCP spec has no standardized response size limit** (open discussion `modelcontextprotocol#2211`). Every native truncation mechanism surveyed is destructive with no recovery handle.
+
+---
+
+## 7. Differentiator erosion matrix
+
+Rescoped: **✓ holds** now means *"no equivalent found in the surveyed set"*, not market-wide uniqueness.
+
+| Claimed differentiator | Status | Detail |
+|---|---|---|
+| Single operation-routed MCP tool | ✗ **Gone** | codegraph (1 default tool), sdl-mcp (gateway mode), pathfinder (7), Semble (2), probe (4). **Retire as the headline.** |
+| Local, no-auth, no-egress | ✗ **Baseline** | Nearly every OSS entrant leads with it. Still a hard moat vs. every commercial player except self-hosted Sourcegraph, self-hosted Greptile, on-prem Qodo. |
+| Diff-aware review with risk scoring | ✗ **Gone** | Sverklo `review_diff`, codebase-memory-mcp `detect_changes`, roam `preflight`/`critique`, jCodeMunch, sdsrss, Greptile. |
+| Louvain communities / subsystem mapping | ✗ **Gone** | codebase-memory-mcp, Axon & Graphify (Leiden), SonarQube Architecture, DeepWiki. |
+| Local ONNX embeddings · SQLite graph store | ✗ **Gone** | Sverklo uses the *identical* model on the identical stack. Semble's Model2Vec is faster still. |
+| Context packing (`pack`) | ✗ **Gone** | Repomix, at far greater distribution, with Tree-sitter compression, diff scopes, split output, token trees. |
+| Hub / bridge betweenness centrality | ~ **Partial** | roam (PageRank), Sverklo `audit`, tokensave (Gini/DSM), Axon. **True betweenness specifically remains uncommon in the surveyed set.** |
+| Truthful serialized response budgets | ~ **Partial — best remaining graph claim** | sdl-mcp's Iris Gate Ladder is the only close analogue found, and it is more legible. Others offer `limit`/`offset` — pagination, not a budget. **No surveyed MCP server emits truncation state + continuation instruction.** |
+| Explicit availability / freshness states | ✓ **No equivalent found** | `repair-needed`, `lifecycle-degraded`. Surveyed graph servers index and go quiet; CocoIndex has provenance but no fail-closed availability contract. |
+| Recoverable bounded command-output compression | ✓ **No equivalent found** | RTK: bounded, partial recovery, no symbol drill-back. build-output-tools-mcp: recoverable but LLM-summarized. Headroom: returns the original chunk, not symbols. |
+| `compress diagnose` — failure → owning symbols / tests / callers / source | ✓ **No equivalent found in the surveyed set** | The surveyed landscape is bifurcated: log compressors are symbol-blind; code-graph servers never see a build log. *(Rev 1 said "UNIQUE" — withdrawn as unprovable.)* |
+| Apex + SF metadata from a local checkout, no org credentials | ✓ **No equivalent found** | Every Salesforce metadata vendor examined requires a live org connection. |
+| ~~Cross-substrate impact~~ | ⚠️ **REMOVED — opportunity, not capability** | **No implementation, test, or documentation found establishing the Terraform → dbt → SF field → Apex chain.** Must not appear as a current capability until a checked-in replay demonstrates it. |
+
+> **Honest summary.** Every *individual* graph feature is replicated in free OSS. What remains uncommon in the surveyed set is **(a)** the combination in one process — no single competitor found has all six of gateway + budgets + diff-review + communities + centrality + local embeddings; **(b)** the contracts — budget truthfulness, fail-closed availability, exact omission accounting, all verifiable in-repo; and **(c)** substrate coverage. **(a) is a race. (b) and (c) are the defensible ground** — and (b) is the only one backed by checked-in tests today.
+
+---
+
+## 8. Ranked threat assessment
+
+| # | Threat | Severity | Horizon | Why |
+|---|---|---|---|---|
+| 1 | **Generic code-graph floor collapsed to $0** | 🔴 Critical | Now | codegraph, Sverklo, sdsrss, CodeGraphContext, roam all ship free, local, MCP-native graphs with impact analysis. |
+| 2 | **Competitors published methodology; Reckon hasn't** | 🔴 Critical | Now | codebase-memory-mcp has a preprint with a reproducible protocol; Qodo has DeepCodeBench. Methodology is the scarcest asset in this market — and Reckon's replay harness already exists to produce it. Self-inflicted. |
+| 3 | **SonarQube absorbs architecture mapping into $34/mo** | 🟠 High | 6–12 mo | In a product Docusign already runs. The internal adoption argument gets harder. |
+| 4 | **Sverklo-class convergence** | 🟠 High | 3–9 mo | An independent project reached the same stack and analytics set. Feature-level differentiation has a short half-life. |
+| 5 | **LSIF-only while SCIP takes over** | 🟠 High | 6–12 mo | Concrete and closable. |
+| 6 | **Salesforce metadata window closing** | 🟡 Medium | 12–18 mo | Salesforce ships DX MCP toolsets monthly; Copado shipped a Context Hub Apr 2026. |
+| 7 | **Free SaaS review from Greptile / CodeRabbit** | 🟡 Medium | Now | `review` is the most contested capability Reckon has. |
+| 8 | **ContextBench's "bitter lesson"** | 🟡 Medium | Structural | Category ceiling may be lower than assumed. Argues for narrow, provable claims. |
+| 9 | **Agent-native absorption** | 🟢 Low-Med | 12–24 mo | Asymmetric — see below. |
+| 10 | **Indexing-cost undercut (Model2Vec)** | 🟢 Low | 12 mo | Onboarding-friction perception, not correctness. |
+
+### On absorption — narrowed
+
+**Semantic retrieval over a single repo is being absorbed. Precise, persistent, cross-repo symbol graphs are not.**
+
+*For:* Cursor built and shipped its own embedding model default-on. GitHub bundles Copilot Spaces + repo overview + code review inside the seat price. Gemini Code Assist Enterprise indexes private repos. DeepWiki is free for public repos.
+
+*Against:* **Neither Claude Code nor Codex documents a persistent repository index** — Claude Code's changelog through Jul 2026 shows no codebase-indexing entries, and reporting indicates Anthropic removed an early local vector DB in favor of agentic search. *(Rev 1 said they had "absorbed nothing" — "no persistent repository index documented" is the defensible version; absence of documentation is not proof of absence.)* Sourcegraph's CodeScaleBench [vendor]: Sonnet 4.6 + Sourcegraph MCP at 0.698 / $1.02 per quality point vs a frontier model with no retrieval at 0.568 / $1.83. Every vendor standardized on **MCP as the seam**.
+
+> **Conclusion: target Claude Code and Codex users, not Cursor users.** `reckon init` already configures Claude Code, Codex, Gemini CLI, and Antigravity — that targeting is correct and should be explicit in the positioning.
+
+---
+
+## 9. Recommendations
+
+### Reposition
+1. **Retire "single operation-routed MCP tool" as the headline.** Keep it as a design fact; keep roam-code's 145 tools as the foil.
+2. **Lead with the compression↔graph join.** `compress diagnose` has no equivalent in the surveyed set and is currently buried in README paragraph 2.
+3. **Reframe "no token-percentage claims" from caveat to pitch.** Cite arXiv:2607.12161 and the JetBrains RTK trial. Lead on determinism, exact omission accounting, preserved edit anchors, recoverability.
+4. **Promote the substrate story out of the appendix** — but describe it as *coverage*, not as a demonstrated cross-substrate chain. Drop dbt from the lead.
+5. **Name the target agent explicitly:** Claude Code and Codex.
+
+### Build
+6. **Publish the benchmark.** Highest ROI available. `bench:competitive`, the replay harness, and `benchmarks/evaluations/` already exist; codebase-memory-mcp's protocol (31 repos, 66 languages, quality-vs-tokens curve) is an adaptable template.
+7. **Add SCIP import alongside LSIF.** Mechanically small, strategically disproportionate.
+8. **Run a live bake-off against Sverklo** — same bar already applied to Serena and claude-context.
+9. **Build the cross-substrate replay** — if the Terraform → dbt → SF → Apex chain is the strategic bet, it needs a checked-in oracle before it can be claimed at all. Currently it is the largest gap between the story and the evidence.
+10. **Add git-history signals to `review`** (change-coupling, churn-weighted risk).
+11. **Evaluate Model2Vec vs MiniLM ONNX**, given R44 already found batching made indexing worse.
+
+### Watch
+**Moderne** (closest strategic overlap in the commercial tier) · **SonarQube Architecture** (commoditization vector for `map`) · **sdl-mcp's Iris Gate Ladder** (better articulation of the budget idea) · **`modelcontextprotocol#2211`** (if the spec standardizes budgets, Reckon should be cited as prior art rather than made redundant).
+
+---
+
+## Appendix — verification register
+
+| Claim class | Confidence | Note |
+|---|---|---|
+| Reckon capability set, 19 operations, `responseBudget` contract, ~30–50ms probe, 61-repo certification | **High [repo]** | Read from source; operation enum confirmed at `src/context.ts:17-36` |
+| Cross-substrate impact chain | **NOT SUPPORTED** | No implementation, test, or doc found. Removed from the matrix. |
+| arXiv figures (2607.12161, 2602.05892, 2603.27277) | **High [independent]** | Transcribed from abstracts; preprints, not peer-reviewed |
+| TACO (2604.19572) | **Low** | Abstract not machine-readable at verification time; no figure quoted |
+| Star counts | **Unconfirmed by me** | Two sources in §0; GitHub API blocked from this environment. Two figures flagged as extraordinary. **Timestamp anything you reuse.** |
+| Vendor claims and percentages | **Attributed only** | Many self-measured against undisclosed baselines |
+| Commercial pricing | **Med-High** | Public pricing pages; enterprise floors directional |
+| Acquisitions / EOL | **High** | Press releases and vendor statements; Amazon Q narrowed to IDE plugins + paid subscriptions |
+| "No equivalent found" statements | **Survey-scoped** | Bounded by what this pass examined. **Not market-wide nonexistence.** |

package/docs/DIAGNOSTICS.md

@@ -8,7 +8,8 @@ service.
 ```bash
 knodin diagnostics enable --retention-days 14
 knodin diagnostics status
-knodin diagnostics collect --since 24h
+knodin diagnostics preview --since 24h
+knodin diagnostics archive --since 24h
 knodin diagnostics inspect .knodin/diagnostics/knodin-diagnostics-….json.gz
 knodin diagnostics clear
 knodin diagnostics disable
@@ -22,15 +23,35 @@ environment, username, repository path, or source paths. Records are stored in
 `.knodin/diagnostics/events.jsonl`, mode `0600`, capped at 500 events, and
 pruned to the configured 1–365 day retention window.
 
-`collect` runs local installation and deep graph diagnostics and combines their
-redacted results with recent failure envelopes, metadata-only telemetry when
-present, and at most 64 KiB/200 lines from the lifecycle indexer log. The
-default collection window is 24 hours; `--since` accepts hours or days. Bundle
-output must remain inside the repository and cannot traverse a symlink.
+`preview` runs local installation and deep graph diagnostics and returns the
+exact allowlisted payload that `archive` writes. (`collect` remains a compatible
+alias for `archive`.) The default window is 24 hours; `--since` accepts hours or
+days. Bundle output must remain inside the current checkout and cannot traverse
+a symlink. Linked worktrees therefore retain separate trace journals and
+archives even when they share Git objects.
 
-The bundle is gzip-compressed JSON, written mode `0600`, and includes a privacy
-manifest, explicit omissions, and a redaction count. `inspect` validates the
-manifest and a 10 MiB compressed-size ceiling before returning its contents.
+Preview persists a private, content-addressed snapshot and returns its
+`previewId`. Pass `--preview-id <id>` to `archive` to write those exact inspected
+contents without recollecting timestamps or health state. The checkout retains
+at most eight previews, seven days, and 2 MiB in aggregate; older or excess
+entries are pruned inside two alternating private store slots after each
+preview. Each slot is capped at 1 MiB, preserving one prior valid generation
+while keeping the aggregate at 2 MiB. Retrieval treats both generations as one
+eight-preview window. Symlinks are never followed.
+
+Private diagnostic writes use a short-lived local helper bound to the validated
+destination parent. The helper proves the parent device and inode with a random
+nonce before knodin sends any payload bytes, then bounded-writes with
+no-follow/exclusive descriptors, fsyncs, and returns an identity-bound receipt.
+Malformed, crashed, displaced, or overdue helpers fail closed; there is no
+pathname-write fallback and no network activity.
+
+The schema-v2 bundle is gzip-compressed JSON, written mode `0600`, and includes
+a human report plus logical runtime, health, repository-scale, MCP-trace, and
+failure files. Its manifest names every logical file and field, exact UTF-8 byte
+size, retention rule, explicit-allowlist policy, omissions, and unavailable
+sections. `inspect` validates the manifest and compressed/uncompressed bounds
+before returning its contents.
 Users should inspect the bundle before attaching it to Jira, GitHub, email, or
 another support channel. knodin does not transmit it.
 
@@ -41,5 +62,19 @@ Run `clear` when deletion is intended.
 
 Diagnostics are evidence, not runtime-causality proof. Message fingerprints can
 group identical sanitized failures but cannot reconstruct the original message.
-Redaction is defense in depth; users remain responsible for inspecting an
-artifact before sharing it outside their organization.
+The default bundle does not pass arbitrary doctor, graph, telemetry, lifecycle,
+or future diagnostic fields through a sanitizer. A fixed allowlist admits only
+aggregate repository scale, classified health/freshness, safe runtime versions,
+bounded failure envelopes, and C89 request/trace lifecycle fields. Source,
+diffs, raw or external paths, credentials, environment values, usernames,
+command output, Git remotes/messages, and arguments have no output slot. New
+fields fail closed until the allowlist, schema, privacy fixture, and tests are
+updated together. Automated redaction cannot certify arbitrary future fields,
+so users must still inspect the preview before sharing.
+
+The same preview/archive builder is exposed through MCP with
+`operation: "diagnostics"`, `telemetryAction: "report"` for preview or
+`telemetryAction: "export"` for archive, and an
+optional `sinceHours` that is interpreted as the evidence window in hours. Pass the
+preview's ID as `artifactId` when archiving the exact snapshot. Both surfaces are bounded, local, credential-free, and
+perform no upload or other network action.

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
@@ -36,6 +41,11 @@ manager-owned tool.
 
 Node.js 24 or newer is required:
 
+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
 knodin --version
@@ -186,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