knodin 0.7.6 → 0.8.2

package/README.md

@@ -35,6 +35,13 @@ 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.
 
+The checked [behavioral-contract work](docs/BEHAVIORAL-CONTRACT.md) declares
+each production operation's intended guarantees and release-gates
+composition, recovery, confidence, and locality fixtures across every production
+operation/action path and declared egress boundary. C95 is implemented and
+terminal under the checked verifier and roadmap acceptance criteria; its stated
+limitations remain product bounds, not unsupported superiority claims.
+
 ## How it compares
 
 Code-intelligence tools often specialize in one part of the workflow. knodin
@@ -82,10 +89,7 @@ limitations.
 
 ## Install
 
-knodin requires a Node.js 24 or newer runtime. A repository may remain pinned to
-Node.js 20: the launcher verifies the active runtime and automatically hands
-off to a version-checked Node installation found on the absolute entries in
-`PATH` or under a standard version-manager/Homebrew location.
+knodin requires Node.js 24 or newer.
 
 ```bash
 npm install --global --ignore-scripts knodin
@@ -111,6 +115,12 @@ knodin init --scope cli-only   # graph and CLI without agent configuration
 See the [installation guide](docs/INSTALLATION.md) for package-manager details,
 managed registries, upgrades, and uninstall instructions.
 
+If one application spans several repositories—including repositories you can
+pull locally but cannot change upstream—follow the
+[local multi-repository setup guide](docs/MULTI-REPO-LOCAL-SETUP.md). It covers
+personal-only initialization, automatic refresh after pulls, hook coexistence,
+portfolio search, and optional system composition.
+
 ## First workflow
 
 Start broad, inspect the likely change surface, then review the actual diff:
@@ -159,10 +169,10 @@ knodin repair
 | `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 visualize` | Self-contained local graph visualization: whole-repository dependency graph or a bounded call flow |
 | `knodin status --deep` | Index freshness, health, hooks, and integration status |
 | `knodin repair` | Repair or rebuild unhealthy local graph state |
-| `knodin diagnostics …` | Retain local failure evidence and create a redacted support bundle |
+| `knodin diagnostics …` | Preview and archive explicit-allowlist local support evidence |
 
 Run `knodin --help` or read the [CLI reference](docs/CLI.md) for complete syntax.
 
@@ -218,7 +228,9 @@ productivity percentage or superiority over every competing product.
 
 ### Internal GHES mirror
 
-GitHub SaaS `knodin/knodin` is the authoritative review and release repository.
+GitHub SaaS `DTS-Productivity-Engineering/knodin` is the authoritative
+review and release repository. `knodin/knodin` is the Homebrew-tap repository,
+not a source or release authority.
 The internal `github.docusignhq.com/Enterprise-Apps/knodin` repository is a
 read-only mirror for colleagues who need GHES access; work must not be opened
 or reviewed there.

package/benchmarks/competitors/SYNTHESIS.md

@@ -0,0 +1,66 @@
+# Local competitor bake-off synthesis
+
+## Outcome
+
+The program exercised 11 runnable competitors locally and recorded one
+credential/egress blocker. Across 713 paired cases, Reckon was faster in 488
+(68.4%) and competitors were faster in 225 (31.6%). That aggregate is
+directional—not a universal quality score—because packers, LSP editors, semantic
+search engines, and graph tools do different work.
+
+These are historical performance observations, not current competitive wins.
+C24's oracle-aware replay contract and
+`benchmarks/evaluations/competitive-fixture-inventory.json` identify which audit
+rows have checked-in labels and which remain blocked on a shared fixture.
+
+| Competitor | Paired cases | Reckon faster | Competitor faster | Primary competitor win |
+|---|---:|---:|---:|---|
+| GitNexus | 39 | 38 | 1 | ambiguity, directional impact, PDG, diff scopes |
+| CodeGraph | 38 | 37 | 1 | bounded multi-symbol orientation |
+| code-review-graph | 142 | 139 | 3 | filters, compact modes, explicit changes, DFS |
+| Graphify | 142 | 98 | 44 | compact hubs/neighbors and relation filters |
+| Serena | 31 | 31 | 0 | LSP navigation, diagnostics, guarded editing |
+| codebase-memory-mcp | 75 | 17 | 58 | typed tracing, layers, filters, pagination |
+| grepai | 59 | 55 | 4 | compact semantic ranking and feature paths |
+| Repomix | 74 | 25 | 49 | portable packing and incremental exact retrieval |
+| Aider repo-map | 36 | 36 | 0 | hard token budgets and ranked source maps |
+| code2prompt | 65 | 0 | 65 | deterministic source/Git export controls |
+| claude-context-mcp | 12 | 12 | 0 | extension-filtered contextual semantic chunks |
+| mcp-codebase-index | — | — | — | blocked: mandatory hosted Gemini embeddings |
+
+## Where Reckon was beaten
+
+The repeated, material gaps are now roadmap items:
+
+1. Call/reference precision, stable identities, ambiguity, and structural
+   implementations: C2 and C11.
+2. Honest byte/token/item budgets and compact top-N drill-downs: C3.
+3. Directional typed traversal, argument/data-flow facts, and architectural
+   layers/boundaries: C4 and C13.
+4. Uniform language/kind/path/relation filters and pagination: C12.
+5. Explicit change sets, staged scopes, revision pairs, and Git context: C5.
+6. Portable source-shaped exports with token metrics and per-file policies: C14.
+7. Diagnostics and broader verified symbol editing: C15 evaluation.
+8. Public index health/repair and local output telemetry: C16.
+9. DFS/feature paths, PDG, API shapes, and a bounded DSL remain evaluations:
+   C8-C10 and C17.
+
+## Defensible strengths
+
+- One composable MCP tool rather than 8-30 schemas.
+- Fully local, credential-free, source-private operation with embedded storage.
+- Strong warm latency against GitNexus, CodeGraph, code-review-graph, Serena,
+  grepai, Aider, and Claude Context.
+- Compiler-verified rename preview/apply/rollback.
+- Rich graph facts—communities, hubs, bridges, flows, impact, risk, staleness—in
+  one process.
+
+## Marketing guardrails
+
+Do not claim Reckon wins every query or every latency comparison. It lost the
+aggregate warm-latency score to codebase-memory-mcp, Repomix, and code2prompt,
+and lost specific quality/capability cases throughout the reports. Safe claims
+are evidence-linked and replay-qualified: local and credential-free only after
+the C33 gate, and measured latency only on the recorded workload.
+
+“Free” remains blocked until C1 adds an explicit permissive license.