knodin 0.7.6 → 0.8.3

package/README.md

@@ -31,9 +31,32 @@ one persistent local graph.
 - **Adopt locally:** initialize the checkout you already have and use the CLI or
   connect one MCP gateway.
 
-The practical payoff is less manual context assembly, fewer agent round trips,
-and fewer dependencies missed during review—with no hosted-service or
-source-egress overhead.
+The practical value is less manual context assembly and fewer dependencies
+missed during review, with no hosted-service or source-egress overhead. Fewer
+agent round trips are an intended payoff; the narrow C93 replay measured no
+round-trip difference, so knodin does not claim a general productivity effect.
+
+Four checked answers define the product rather than a feature-count claim:
+
+- **Value:** less manual context assembly and fewer missed dependencies. C93
+  records the paired task method; C100 narrows one missed-dependency result from
+  a Salesforce class file to the exact Flow-invoked Apex method.
+- **ROI:** the intended mechanism is fewer corrective agent round trips without
+  hosted-service, authentication, or source-egress overhead. C93's accepted
+  two-task replay measured no round-trip benefit (both arms required one
+  correction), so this remains a product hypothesis rather than a measured
+  productivity claim. Billed cost and unobserved tokens remain unknown.
+- **Tomorrow:** run `knodin init`, check `knodin status`, then use the local CLI
+  or single MCP gateway against the checkout already on disk.
+- **Secret sauce:** stable identity, exact source evidence, explicit freshness,
+  and truthful budgets compose behind one compact local tool.
+
+The checked [behavioral contract](docs/BEHAVIORAL-CONTRACT.md) release-gates
+that composition. C101 binds the bounded resource-reachability, TypeScript DI,
+and Salesforce Flow-to-Apex evidence to the retained one-process semantic
+design. It rejects stale, truncated, ambiguous, or omission-only output when a
+mutation tries to promote it into a complete or exact claim. These are
+fixture-scoped guarantees with recorded limits, not universal superiority.
 
 ## How it compares
 
@@ -43,10 +66,11 @@ context over one locally persisted index.
 
 | Job | Typical specialized tools | knodin |
 |---|---|---|
-| Symbol navigation | CodeGraph, Serena, Sourcegraph | Ambiguity-safe definitions, callers, callees, paths, and verbatim source |
+| Symbol navigation | CodeGraph, Serena, Sourcegraph | Ambiguity-safe definitions, callers, callees, paths, bounded Inversify/tsyringe DI edges, and verbatim source |
 | Change impact and review | code-review-graph, Greptile, Graphify | Diff-aware review, impact traversal, tests, risks, and PR triage |
 | Architecture mapping | Graphify, GitNexus | Communities, hubs, boundaries, flows, wiki, and local visualization |
 | Search and context assembly | Aider repo map, Repomix, semantic search tools | Hybrid search, bounded source packs, and recoverable diagnostic compression |
+| Bounded resource and framework relationships | Code-Graph-RAG and framework-aware analyzers | Literal TS/JS resource paths, declared Inversify/tsyringe wiring, and one exact Salesforce Flow-to-Apex boundary, each with explicit omissions |
 | Deployment | Hosted services or separate local tools | One local process, SQLite graph, CLI, and one MCP gateway |
 
 ### Measured results
@@ -82,10 +106,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 +132,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:
@@ -149,7 +176,7 @@ knodin repair
 | Command | Purpose |
 |---|---|
 | `knodin context` | Compact repository orientation and next-operation hint |
-| `knodin explain <symbol>` | Source, identity, callers, callees, and blast radius |
+| `knodin explain <symbol>` | Source, identity, typed callers/callees, static-analysis omissions, and blast radius |
 | `knodin review` | Itemized graph impact, test gaps, centrality, and bounded Git-history evidence |
 | `knodin query …` | Impact, paths, callers, callees, tests, flows, and structured graph queries |
 | `knodin search <query>` | Explainable structural-first search with a bounded local embedding fallback |
@@ -159,10 +186,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 +245,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.