knodin 0.8.2 → 0.8.4

package/dist/src/session-telemetry.js

@@ -0,0 +1,163 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const CONFIG = ".knodin/telemetry-config.json";
+const EVENTS = ".knodin/session-events.jsonl";
+const KEY = ".knodin/telemetry-key";
+function target(repo, relative) {
+    const root = fs.realpathSync(repo);
+    const value = path.resolve(root, relative);
+    if (!value.startsWith(`${root}${path.sep}`))
+        throw new Error("knodin telemetry path escaped repository");
+    let candidate = root;
+    for (const segment of path.relative(root, value).split(path.sep)) {
+        candidate = path.join(candidate, segment);
+        try {
+            if (fs.lstatSync(candidate).isSymbolicLink())
+                throw new Error("knodin telemetry refuses symlinks");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    return value;
+}
+function atomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true, mode: 0o700 });
+    const temporary = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    fs.writeFileSync(temporary, value, { mode: 0o600, flag: "wx" });
+    fs.renameSync(temporary, filePath);
+}
+function enabled(repo) {
+    try {
+        return JSON.parse(fs.readFileSync(target(repo, CONFIG), "utf8")).enabled === true;
+    }
+    catch {
+        return false;
+    }
+}
+export function enableSessionTelemetry(repo) {
+    atomic(target(repo, CONFIG), `${JSON.stringify({ schemaVersion: 1, enabled: true })}\n`);
+    const key = target(repo, KEY);
+    if (!fs.existsSync(key))
+        atomic(key, crypto.randomBytes(32).toString("hex"));
+    return { schemaVersion: 1, enabled: true, localOnly: true };
+}
+export function disableSessionTelemetry(repo) {
+    atomic(target(repo, CONFIG), `${JSON.stringify({ schemaVersion: 1, enabled: false })}\n`);
+    return { schemaVersion: 1, enabled: false, retained: readSessionEvents(repo).length };
+}
+function sessionHash(repo, sessionId) {
+    const secret = fs.readFileSync(target(repo, KEY), "utf8").trim();
+    return `session_${crypto.createHmac("sha256", secret).update(sessionId).digest("hex").slice(0, 20)}`;
+}
+export function appendSessionEvent(repo, input) {
+    if (!enabled(repo))
+        return false;
+    if (!input.sessionId || input.sessionId.length > 256)
+        return false;
+    const record = {
+        schemaVersion: 1,
+        event: input.event,
+        session: sessionHash(repo, input.sessionId),
+        at: input.at ?? new Date().toISOString(),
+        client: input.client ?? "claude",
+        ...(input.context ? { context: input.context } : {}),
+        ...(input.toolCategory ? { toolCategory: input.toolCategory } : {}),
+        ...(input.operation && /^[a-z][a-z0-9_-]{0,63}$/.test(input.operation)
+            ? { operation: input.operation }
+            : {}),
+        ...(input.freshness ? { freshness: input.freshness } : {}),
+        ...(typeof input.latencyMs === "number" ? { latencyMs: input.latencyMs } : {}),
+        ...(typeof input.cacheHit === "boolean" ? { cacheHit: input.cacheHit } : {}),
+    };
+    const filePath = target(repo, EVENTS);
+    fs.appendFileSync(filePath, `${JSON.stringify(record)}\n`, { encoding: "utf8", mode: 0o600 });
+    return true;
+}
+export function readSessionEvents(repo, retentionDays, now = new Date()) {
+    const filePath = target(repo, EVENTS);
+    if (!fs.existsSync(filePath))
+        return [];
+    const cutoff = retentionDays === undefined ? undefined : now.getTime() - retentionDays * 24 * 60 * 60 * 1000;
+    return fs
+        .readFileSync(filePath, "utf8")
+        .split(/\r?\n/)
+        .filter(Boolean)
+        .flatMap((line) => {
+        try {
+            const value = JSON.parse(line);
+            if (value.schemaVersion !== 1 || typeof value.session !== "string")
+                return [];
+            if (cutoff !== undefined) {
+                const timestamp = typeof value.at === "string" ? Date.parse(value.at) : Number.NaN;
+                if (!Number.isFinite(timestamp) || timestamp < cutoff)
+                    return [];
+            }
+            return [value];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+export function summarizeAdoption(events) {
+    const sessions = new Set(events.map(({ session }) => session));
+    const evidenceOperations = new Set(["context", "explain", "review", "map", "search", "query"]);
+    const knodinSessions = new Set(events
+        .filter(({ event, toolCategory, operation }) => event === "tool_success" &&
+        toolCategory === "knodin" &&
+        operation !== undefined &&
+        evidenceOperations.has(operation))
+        .map(({ session }) => session));
+    let fallbackTraversalAfterKnodin = 0;
+    let evidenceBeforeEdit = 0;
+    const seenKnodin = new Set();
+    for (const event of events) {
+        if (event.event === "turn_start")
+            seenKnodin.delete(event.session);
+        if (event.toolCategory === "knodin" &&
+            event.event === "tool_success" &&
+            event.operation !== undefined &&
+            evidenceOperations.has(event.operation))
+            seenKnodin.add(event.session);
+        if (event.event === "tool_success" &&
+            event.toolCategory === "manual_traversal" &&
+            seenKnodin.has(event.session))
+            fallbackTraversalAfterKnodin += 1;
+        if (event.event === "tool_success" &&
+            event.toolCategory === "edit" &&
+            seenKnodin.has(event.session))
+            evidenceBeforeEdit += 1;
+        if (event.event === "turn_end")
+            seenKnodin.delete(event.session);
+    }
+    return {
+        sessions: sessions.size,
+        contextDelivered: events.filter(({ event, context }) => event === "session_start" && context === "delivered").length,
+        contextDegraded: events.filter(({ event, context }) => event === "session_start" && context === "degraded").length,
+        knodinSessions: knodinSessions.size,
+        turns: events.filter(({ event }) => event === "turn_start").length,
+        fallbackTraversalAfterKnodin,
+        evidenceBeforeEdit,
+        correctiveRoundTrips: null,
+    };
+}
+export function sessionTelemetryStatus(repo, retentionDays) {
+    const records = readSessionEvents(repo, retentionDays);
+    return {
+        schemaVersion: 1,
+        enabled: enabled(repo),
+        localOnly: true,
+        records: records.length,
+        adoption: summarizeAdoption(records),
+    };
+}
+export function clearSessionTelemetry(repo) {
+    const filePath = target(repo, EVENTS);
+    const records = readSessionEvents(repo).length;
+    const bytes = fs.existsSync(filePath) ? fs.statSync(filePath).size : 0;
+    fs.rmSync(filePath, { force: true });
+    return { removed: bytes > 0, records, bytes };
+}

package/dist/src/tools/knodin-tools.js

@@ -116,6 +116,7 @@ const QUERY_PATTERNS = [
     "batch_outline",
     "project_overview",
     "shortest_path",
+    "cross_substrate_path",
     "impact",
     "dead_code",
     "large_functions",
@@ -127,6 +128,7 @@ const QUERY_PATTERNS = [
     "traverse",
     "feature_path",
     "flow_analysis",
+    "resource_reachability",
     "knowledge_gaps",
     "surprising_connections",
     "suggested_questions",
@@ -227,15 +229,15 @@ function buildDocumentedKnodinTools() {
                     },
                     toIdentity: {
                         type: "string",
-                        description: "shortest_path destination identity selector.",
+                        description: "shortest_path/cross_substrate_path destination identity selector.",
                     },
                     toFile: {
                         type: "string",
-                        description: "shortest_path destination file selector.",
+                        description: "shortest_path/cross_substrate_path destination file selector.",
                     },
                     toKind: {
                         type: "string",
-                        description: "shortest_path destination kind selector.",
+                        description: "shortest_path/cross_substrate_path destination kind selector.",
                     },
                     pattern: {
                         type: "string",
@@ -243,7 +245,7 @@ function buildDocumentedKnodinTools() {
                         description: "feature_path — deterministic downstream DFS over resolved source references. It is bounded by depth and item limits, source-evidenced per hop, cycle-guarded, and never claims runtime execution; dynamic dispatch and unresolved calls are omitted. " +
                             "lsp_diagnostics accepts a repo-relative TypeScript/JavaScript file; lsp_definitions, lsp_declarations, and lsp_implementations accept file:line:column. These use an optional local TypeScript language-service adapter, never start a daemon or write files, and return an explicit unavailable result when no local adapter supports the file type. " +
                             "api_contract_mismatches — bounded, source-evidenced static mismatch findings for literal Express/Fastify routes and literal fetch/Axios clients. Matching requires method and normalized path, and requires exact origin equality when a client uses an absolute origin; dynamic routes remain explicitly unresolved. mcp_tools — list indexed TypeScript MCP SDK tool registrations, or pass symbol to look up one exact tool name; returns description/schema/handler/file and exact versus heuristic confidence. import_cycles — repo-wide canonical directed file-import cycles; no symbol required, type-only imports included, non-import lineage/ORM edges excluded, and limit/truncated bounds output. " +
-                            "query: the graph pattern to run (callers_of, callees_of, imports_of, importers_of, inheritors_of, structural_implementations_of, tests_for, file_summary, shortest_path, impact, dead_code, large_functions, large_files, rename_preview, flows, flow_of, stats, traverse, knowledge_gaps, community, federated_repos). structural_implementations_of returns TypeScript structurally typed object implementations separately from nominal extends/implements results. federated_repos — discover and list all registered/configured repository paths that this engine federates queries across. community — fetch a single community's full detail (name, size, cohesion, files, and symbols) by name or substring filter; empty `symbol` = all communities. large_files — whole-file line counts (min 200), sorted descending — the file-level counterpart to large_functions, for spotting god files rather than god functions; same optional path-substring filter, empty `symbol` = all files. stats — repo-level index size + health in one call (per-repo symbol/reference/dependency/embedding/file counts, per-kind and per-language breakdowns, orphaned-embedding count, schema version, last-indexed HEAD, and cached community/hub/bridge/flow totals); federated, empty `symbol`. traverse — typed BFS from `symbol` within `depth` hops (default 3, 1–6), selectable upstream/downstream/both and explicit edge kinds; every discovered edge includes direction, kind, provenance, confidence, files, and source line, with optional Tree-sitter-grounded argument expressions honestly marked heuristic. Sets `truncated` when the `limit` cap binds; single-repo. knowledge_gaps — repo-health weaknesses in one call: thin communities (<3 symbols), single-file communities, isolated (zero-degree) symbols, and untested hub/bridge hotspots; sourced from the cached map(), federated, empty `symbol`, one row carrying a `knowledgeGaps` block. surprising_connections — resolved edges scored by a composite surprise formula (cross-community, cross-language, peripheral-to-hub, cross-test-boundary, unusual edge kind) to surface unexpected coupling; sorted highest-first, top 15 by default, federated, empty `symbol`, each row carrying a `surprise` block. suggested_questions — prioritized, human-readable review prompts synthesized from knowledge_gaps + surprising_connections (untested hotspots first, then surprising edges, then thin/single-file communities); federated, empty `symbol`, each row a `question` string citing the real symbol/file, top 10 by default. architecture_overview — a federated architecture view with scoped community coupling and independently selectable packages, layers, boundaries, hotspots, entry points, and language facets; `path` is segment-safe and applies consistently. `detailLevel` 'minimal' omits per-edge coupling; 'standard' includes it. Spring/event patterns (Java): triggers_of — the schedule edge between a @Scheduled method and its synthetic scheduler (pass the method to get its scheduler, or the scheduler to list scheduled methods). publishers_of — methods that publish a given event type (ApplicationEventPublisher.publishEvent). listeners_of — @EventListener methods that listen for a given event type. handlers_of — methods that handle a given HTTP endpoint path (Spring @*Mapping + the existing JS/Python endpoints). endpoints_for — the inverse: endpoint path(s) a given method handles. consumers_of — classes/methods consuming a given @Value config property. children_of — symbols contained in a file path (same as file_summary) or, for a class name, its member symbols by line-range containment. All seven require `symbol` (the target); single-repo, not federated.",
+                            "query: the graph pattern to run (callers_of, callees_of, imports_of, importers_of, inheritors_of, structural_implementations_of, tests_for, file_summary, shortest_path, cross_substrate_path, impact, dead_code, large_functions, large_files, rename_preview, flows, flow_of, flow_analysis, resource_reachability, stats, traverse, knowledge_gaps, community, federated_repos). cross_substrate_path proves only one static Salesforce Flow action to one uniquely resolved Apex @InvocableMethod and returns exact endpoint identities/evidence, freshness, budgets, and explicit unsupported crossings; it does not resolve Terraform, dbt, or arbitrary substrate paths. resource_reachability is a repo-wide, bounded, cached, on-demand TS/JS static heuristic for literal process.env/fs.readFileSync sources reaching console.log/fetch/db.query sinks; it reports evidence, coverage, omissions, freshness, truncation, and continuation and is never runtime reachability or exploitability proof. structural_implementations_of returns TypeScript structurally typed object implementations separately from nominal extends/implements results. federated_repos — discover and list all registered/configured repository paths that this engine federates queries across. community — fetch a single community's full detail (name, size, cohesion, files, and symbols) by name or substring filter; empty `symbol` = all communities. large_files — whole-file line counts (min 200), sorted descending — the file-level counterpart to large_functions, for spotting god files rather than god functions; same optional path-substring filter, empty `symbol` = all files. stats — repo-level index size + health in one call (per-repo symbol/reference/dependency/embedding/file counts, per-kind and per-language breakdowns, orphaned-embedding count, schema version, last-indexed HEAD, and cached community/hub/bridge/flow totals); federated, empty `symbol`. traverse — typed BFS from `symbol` within `depth` hops (default 3, 1–6), selectable upstream/downstream/both and explicit edge kinds; every discovered edge includes direction, kind, provenance, confidence, files, and source line, with optional Tree-sitter-grounded argument expressions honestly marked heuristic. Sets `truncated` when the `limit` cap binds; single-repo. knowledge_gaps — repo-health weaknesses in one call: thin communities (<3 symbols), single-file communities, isolated (zero-degree) symbols, and untested hub/bridge hotspots; sourced from the cached map(), federated, empty `symbol`, one row carrying a `knowledgeGaps` block. surprising_connections — resolved edges scored by a composite surprise formula (cross-community, cross-language, peripheral-to-hub, cross-test-boundary, unusual edge kind) to surface unexpected coupling; sorted highest-first, top 15 by default, federated, empty `symbol`, each row carrying a `surprise` block. suggested_questions — prioritized, human-readable review prompts synthesized from knowledge_gaps + surprising_connections (untested hotspots first, then surprising edges, then thin/single-file communities); federated, empty `symbol`, each row a `question` string citing the real symbol/file, top 10 by default. architecture_overview — a federated architecture view with scoped community coupling and independently selectable packages, layers, boundaries, hotspots, entry points, and language facets; `path` is segment-safe and applies consistently. Spring/event patterns (Java): triggers_of — the schedule edge between a @Scheduled method and its synthetic scheduler (pass the method to get its scheduler, or the scheduler to list scheduled methods). publishers_of — methods that publish a given event type (ApplicationEventPublisher.publishEvent). listeners_of — @EventListener methods that listen for a given event type. handlers_of — methods that handle a given HTTP endpoint path (Spring @*Mapping + the existing JS/Python endpoints). endpoints_for — the inverse: endpoint path(s) a given method handles. consumers_of — classes/methods consuming a given @Value config property. children_of — symbols contained in a file path (same as file_summary) or, for a class name, its member symbols by line-range containment. All seven require `symbol` (the target); single-repo, not federated.",
                     },
                     depth: {
                         type: "number",
@@ -292,7 +294,7 @@ function buildDocumentedKnodinTools() {
                     },
                     to: {
                         type: "string",
-                        description: "query shortest_path: destination symbol (start symbol goes in `symbol`). query rename_preview: the new name (old name goes in `symbol`). Read-only by default (returns edit sites + a unified diff); pass `apply: true` to write the rename to disk.",
+                        description: "query shortest_path/cross_substrate_path: destination symbol (start symbol goes in `symbol`). query rename_preview: the new name (old name goes in `symbol`). Read-only by default (returns edit sites + a unified diff); pass `apply: true` to write the rename to disk.",
                     },
                     apply: {
                         type: "boolean",
@@ -1569,8 +1571,8 @@ async function dispatchKnodinTool(args) {
             const repoWide = REPO_WIDE_QUERY_PATTERNS.includes(pattern);
             if (!symbol && !repoWide)
                 throw new Error(`knodin query ${pattern} requires \`symbol\``);
-            if (pattern === "shortest_path" && !to)
-                throw new Error("knodin query shortest_path requires `to`");
+            if ((pattern === "shortest_path" || pattern === "cross_substrate_path") && !to)
+                throw new Error(`knodin query ${pattern} requires \`to\``);
             if (pattern === "rename_preview" && !to)
                 throw new Error("knodin query rename_preview requires `symbol` and `to`");
             const queryHealth = GRAPH_INDEPENDENT_QUERY_PATTERNS.has(pattern)
@@ -1602,6 +1604,9 @@ async function dispatchKnodinTool(args) {
                 direction: pattern === "traverse" ? direction : undefined,
                 includeDataFlow: pattern === "traverse" ? includeDataFlow : undefined,
                 flowVariable: pattern === "flow_analysis" ? flowVariable : undefined,
+                resourceOffset: pattern === "resource_reachability" ? offset : undefined,
+                resourceMaxBytes: pattern === "resource_reachability" ? byteBudget : undefined,
+                resourceMaxTokens: pattern === "resource_reachability" ? tokenBudget : undefined,
                 architectureFacets,
                 topN,
                 sort,

package/docs/BEHAVIORAL-CONTRACT.md

@@ -16,10 +16,11 @@ action-specific response semantics fail closed when a required signal is absent.
 - **Value:** less manual context assembly and fewer missed dependencies. The
   paired task method and its bounded results are checked in under
   [`benchmarks/evaluations/c93-engineering-outcomes/`](../benchmarks/evaluations/c93-engineering-outcomes/).
-- **ROI:** fewer corrective agent round trips without hosted-service, account,
-  authentication, or source-egress overhead. C93 reports measured local task
-  outcomes and explicitly leaves billed cost and token counts unavailable when
-  the harness cannot observe them.
+- **ROI:** the intended mechanism is fewer corrective agent round trips without
+  hosted-service, account, authentication, or source-egress overhead. C93's
+  accepted two-task replay measured no round-trip benefit; both arms needed one
+  correction. It therefore authorizes no productivity claim and leaves billed
+  cost and unobserved token counts unavailable.
 - **Tomorrow:** run `knodin init`, inspect `knodin status`, then use the existing
   checkout through the CLI or the single `knodin.knodin` MCP gateway. The
   installation and client readiness evidence remains bounded by C91 below.
@@ -35,6 +36,13 @@ preserving its stable identity and evidence provenance. Stale, unavailable, or
 ambiguous graph evidence must remain explicit and cannot be promoted to a
 confident failure diagnosis, impact claim, or runtime-causality proof.
 
+`ExplainResult.callers[].kind` and `ExplainResult.omissions[]` are governed by
+the existing explain mapping: relationship kinds require source provenance and
+stable resolved endpoints, while omissions require an exact source location and
+must never be promoted into a graph edge. C99 exercises these added fields
+without adding a gateway operation or discriminator, so the C95 applicability
+matrix is unchanged.
+
 The C95 fixtures run in a linked non-default worktree. A child harness installs
 guards before importing the production dispatcher and observes global `fetch`,
 HTTP/HTTPS request and get, TCP/TLS connection, callback and promise DNS
@@ -46,6 +54,39 @@ credential forwarding, source bytes at network/subprocess boundaries, and
 native-addon loads must remain zero. Local subprocess execution is counted and
 permitted only when those observed payload checks remain clean.
 
+## C101 composition closure
+
+C101 composes four independently bounded decisions without adding an MCP tool
+or operation:
+
+- C97 retained lazy semantic residency in one local process. It does **not**
+  authorize an idle-RSS-reclamation claim.
+- C98 reports literal TS/JS source-to-sink paths as static heuristics with
+  coverage, omissions, freshness, budgets, and continuation. Truncation cannot
+  become a complete-result claim.
+- C99 persists only uniquely source-resolved Inversify/tsyringe relationships;
+  ambiguous, dynamic, factory, alias, conditional, and reflective wiring stays
+  omission evidence rather than an edge.
+- C100 proves one Salesforce Flow action to one uniquely resolved Apex
+  `@InvocableMethod`. It does not prove Terraform, dbt, arbitrary Salesforce
+  metadata, or general cross-substrate traversal.
+
+`npm run verify:c101` source-binds those decisions, checks the CLI and one-tool
+MCP query declarations, and rejects eight adversarial mutations of actual
+production responses. Stale resource/path evidence and heuristic-to-exact
+promotion fail; a truncated result cannot be presented as complete; and a DI
+ambiguity, missing source witness, or path omission cannot become a supported
+edge.
+
+## Repository stewardship
+
+An authoritative pull request starts the full test matrix and Sonar analysis,
+so it is a long, resource-intensive operation. Assistants must not automatically
+open one PR per item. Dependency-compatible, coherently scoped commits should
+normally be stacked into one reasonably sized shared PR; unrelated work must
+not be bundled merely to make the PR larger. The user or approved batch decides
+when that review unit is ready.
+
 ## Known bounds
 
 This replay proves the checked operation/action fixtures, not all repositories,
@@ -53,7 +94,8 @@ languages, frameworks, dynamic runtime behavior, clients, or deployment
 environments. Static relationships and failure correlations are candidates,
 not runtime-causality proof. Budgets can truncate results; indexes can be stale
 or unavailable; names can be ambiguous; generated code, dynamic dispatch,
-framework wiring, and language coverage can leave relationships unresolved.
+framework wiring outside C99's declared Inversify/tsyringe patterns, and
+language coverage can leave relationships unresolved.
 
 C91 remains parked pending native client, runtime-manager, Homebrew, and
 Artifactory certification evidence. C94 remains blocked on C91 and therefore

package/docs/CLI.md

@@ -32,6 +32,33 @@ example repository existence, mutually exclusive configuration modes, and
 graph-query target rules), but syntax cannot reach a handler unless the shared
 declarative model accepts it first.
 
+Optional Claude lifecycle integration is explicit and user-global:
+
+```bash
+knodin agent-hooks install --client claude --dry-run
+knodin agent-hooks install --client claude
+knodin agent-hooks status --client claude
+knodin agent-hooks uninstall --client claude
+```
+
+Installation atomically merges knodin-owned `SessionStart`, turn, tool, and
+session-end handlers into the user's Claude settings. It preserves unrelated
+settings and hooks, including aidev-track, and uninstall removes only exact
+knodin entries. SessionStart emits at most 600 tokens, 8 KiB, and 12 bounded
+orientation items. Hooks fail open and no-op outside initialized repositories.
+The internal `agent-event` command is machine-facing and consumes bounded JSON
+from stdin; it is not a general event-ingestion API.
+
+`knodin query resource_reachability --limit 100` runs cached, on-demand static
+TS/JS source-to-sink analysis. It covers literal `process.env` and
+`fs.readFileSync` reads reaching `console.log`, `fetch`, or `db.query` through
+bounded assignment, argument, and return handoff. Results include ordered source
+evidence, stable path identities, registry coverage, omissions, freshness, and
+hard truncation/continuation metadata. Depth is fixed at 6 and paths at 100;
+dynamic names, reflection, computed aliases, and unsupported languages are
+reported rather than guessed. This is a static heuristic, not runtime reachability
+or an exploitability verdict.
+
 For support evidence, `knodin diagnostics enable|status|preview|archive|inspect|clear|disable`
 manages an explicit local failure journal and redacted gzip JSON bundles.
 Collection does not upload data. See `docs/DIAGNOSTICS.md` for retention,

package/docs/COMPARISON.md

@@ -51,6 +51,16 @@ the evaluation's competitor limitations. The active
 [competitive roadmap](../roadmap/competitive-roadmap.md) links each claim to
 its acceptance criteria and replay state.
 
+The current positioning lead is the checked behavioral contract, not the raw
+capability count. C98 adds a bounded TS/JS resource-reachability heuristic; C99
+adds only uniquely source-resolved Inversify/tsyringe relationships; C100 proves
+one Salesforce Flow action to one Apex `@InvocableMethod`; and C97 retains the
+one-process semantic design without claiming idle RSS reclamation. C101 binds
+those decisions and rejects stale, truncated, ambiguous, or omission-only
+results when promoted into complete or exact claims. None of these fixtures
+supports general runtime causality, arbitrary cross-substrate paths, broad DI
+framework coverage, or universal competitor superiority.
+
 ## The quartet: knodin vs its three direct progenitors
 
 knodin exists to fuse three tools this project already used side by side

package/docs/DEMO.md

@@ -0,0 +1,49 @@
+# Bounded product walkthrough
+
+This is the maintained positioning walkthrough, not C94's pending certified
+five-minute client demonstration. C94 remains parked behind native installation
+and client evidence; this document must not be cited as completing it.
+
+## Value
+
+On an existing checkout, initialize and orient before assembling context by
+hand:
+
+```bash
+knodin init
+knodin status --deep
+knodin context "change the review submission path"
+knodin query impact submit --direction upstream
+```
+
+The intended value is less manual context assembly and fewer missed
+dependencies. C100 demonstrates one narrow improvement: a Salesforce Flow
+action can resolve to the exact local Apex `@InvocableMethod`, rather than only
+its class file. It does not demonstrate arbitrary cross-substrate analysis.
+
+## ROI
+
+Use the same local CLI or one MCP gateway against the checkout already on disk;
+no hosted index, account, authentication, or source-code egress is required.
+Fewer corrective round trips are an intended mechanism, not a measured product
+claim: C93's accepted two-task replay found no round-trip difference and both
+arms required one correction.
+
+## Tomorrow
+
+After `knodin init`, use `context`, `explain`, structured `query`, and `review`
+through the CLI or the single operation-routed MCP tool. If status reports stale
+or damaged state, repair it before relying on graph evidence.
+
+## Secret sauce and bounds
+
+Stable identity, exact source evidence, explicit freshness, and truthful
+budgets compose behind the compact local surface. C101 mutates actual production
+responses for resource reachability, TypeScript DI, and one Flow-to-Apex path;
+stale, truncated, ambiguous, or evidence-free variants must fail the contract
+oracle. C97 separately retains one-process semantic residency and authorizes no
+idle-RSS-reclamation claim.
+
+These checked fixtures do not prove runtime causality, broad DI framework
+coverage, arbitrary Salesforce/Terraform/dbt paths, every client or platform,
+or superiority over competitors.

package/docs/INSTALLATION.md

@@ -205,6 +205,17 @@ 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).
 
+Claude users may explicitly install one user-global lifecycle adapter after
+previewing its settings merge:
+
+```bash
+knodin agent-hooks install --client claude --dry-run
+knodin agent-hooks install --client claude
+```
+
+This is independent of `knodin init` and telemetry persistence. Remove only
+knodin-owned entries with `knodin agent-hooks uninstall --client claude`.
+
 Upgrade with the manager that owns the executable:
 
 ```bash

package/docs/MCP.md

@@ -4,6 +4,11 @@ knodin exposes exactly one MCP tool named `knodin`. Capabilities such as
 context, explain, review, search, docs, doctor, repositories, and systems are
 operations of that gateway, not separate top-level tools.
 
+Use `operation: "query", pattern: "resource_reachability"` for the same bounded,
+cached, repo-wide TS/JS analysis as the CLI. It requires no symbol and retains
+the gateway's freshness refusal and response budgets; returned paths remain
+source-evidenced static heuristics with explicit coverage and omissions.
+
 Use `operation: "evidence"` for deterministic `locate`, `outline`, `evidence`,
 and `expand` source delivery with a verified complete-file hash handshake and
 recoverable hard-budget continuations. See `docs/PROGRESSIVE-EVIDENCE.md`.

package/docs/TELEMETRY.md

@@ -25,13 +25,31 @@ knodin telemetry export
 knodin telemetry clear
 ```
 
+Claude adoption evidence is an independent repository-local opt-in:
+
+```text
+knodin telemetry enable
+knodin telemetry disable
+```
+
+When enabled and the optional Claude hooks are installed, knodin records HMAC'd
+session identity, lifecycle event kind, turn boundaries, coarse tool category,
+supported knodin operation, freshness, context delivery, cache state, and
+latency. It never persists prompts, transcript paths, source, raw tool input or
+output, shell command text, usernames, or absolute paths. Disable stops new
+session events without deleting retained history; `clear` removes both
+operation and session event stores.
+
 `--retention-days 1..3650` changes the read/persistence window. `--input` and
 `--output` accept only repository-contained, non-symlink paths. `clear` is the
 only command that deletes the private JSONL file; report and export never do.
 
 The default report is `.knodin/telemetry-report.html`. It includes summary,
 operation, time-series, private repository, indexing-cost, latency, freshness,
-and fidelity views with light/dark styling. The default machine-readable export
+fidelity, session adoption, evidence-before-edit, and observed fallback-traversal
+views with light/dark styling. Ordinary hooks cannot establish why a follow-up
+occurred, so corrective round trips and task success remain unavailable unless
+supplied by a controlled outcome replay. The default machine-readable export
 is `.knodin/telemetry-export.json` and labels measured, modeled, and unknown
 baselines explicitly. Neither artifact needs a daemon, hosted service,
 authentication, or source egress.

package/docs/releases/0.8.3.md

@@ -0,0 +1,47 @@
+# knodin 0.8.3
+
+This release strengthens Knodin's source-evidenced graph across repository
+lifecycle, cross-substrate analysis, and bounded organization-scale workflows.
+
+- Adds bounded repository-wide resource reachability for source-proven
+  environment, file, fetch, console, and database paths. Results retain stable
+  identities, exact evidence, explicit unsupported cases, freshness, response
+  budgets, and deterministic continuation.
+- Resolves source-proven TypeScript dependency-injection wiring for supported
+  Inversify and tsyringe forms. Framework and registry scoping, ambiguity,
+  conditional wiring, incremental refresh, and removal are represented without
+  guessing across containers or frameworks.
+- Proves exact Salesforce Flow-to-Apex paths from Flow action metadata to unique
+  `@InvocableMethod` targets, including targeted Apex refresh, source evidence,
+  omissions, freshness, and bounded responses.
+- Makes repair converge truthfully across schema migration, empty repositories,
+  final verification failure, and future-schema refusal. Scoped repairs avoid
+  unrelated TypeScript DI reads while still rebuilding affected DI evidence.
+- Strengthens the public behavioral contract and positioning with replayed
+  production CLI, MCP, and engine responses. C97-C101 evidence is independently
+  replayable and source-bound; failed performance experiments remain recorded
+  as limitations rather than superiority claims.
+- Prevents stale package and barrel-resolution caches, avoids caching transient
+  filesystem failures, and keeps independent engine instances from closing
+  resources still owned by another instance.
+- Reuses a bounded, generation-scoped resource corpus so warm reachability
+  queries do not reread every indexed source file while still failing closed on
+  disk drift.
+- Bounds cross-substrate evidence consistently with the outer response budget,
+  fixes member-call reachability false positives, and makes evidence verifiers
+  recompute their claim-bearing gates instead of trusting stored booleans.
+- Removes duplicated progress-worker and response-budget machinery, updates the
+  audited development dependency set, and fixes lifecycle evaluation owners so
+  the complete test process terminates.
+- Records that pull requests are intentionally expensive because Sonar and the
+  complete repository gates run on each review stream; compatible work should
+  be stacked into one coherent PR rather than opened automatically as many small
+  PRs.
+
+The one-process semantic-residency evaluation remains a retained no-go: neither
+in-process ONNX disposal, worker threads, quantized weights, nor vector/cache
+eviction met the repeatable memory gate without violating the local one-process
+product boundary. Knodin retains lazy loading and bounded caches rather than
+claiming unsupported reclamation.
+
+This remains an ordinary 0.x release, not a dogfood-only build and not GA.

package/docs/releases/0.8.4.md

@@ -0,0 +1,22 @@
+# knodin 0.8.4
+
+This release adds optional, bounded coding-session orientation and local
+adoption evidence while preserving knodin's freshness and privacy boundaries.
+
+- Adds an explicit, idempotent Claude hook installer for compact SessionStart
+  context. Injection is limited to 600 tokens, 8 KiB, and 12 items, reports its
+  bounds, rejects stale cached evidence, and fails open outside initialized
+  repositories.
+- Adds opt-in, repository-local session telemetry and an adoption dashboard for
+  delivered context, successful graph-evidence operations, fallback traversal,
+  and evidence-before-edit observations.
+- Persists only coarse allowlisted metadata and locally keyed session hashes;
+  prompts, source, raw tool input, commands, paths, and unhashed session IDs are
+  not retained.
+- Keeps corrective round trips explicitly unavailable because ordinary hook
+  events cannot establish why an agent made a follow-up call or prove a causal
+  productivity improvement.
+- Adds C102's preregistered paired-evaluation design so future outcome claims
+  require replay evidence rather than being inferred from adoption counters.
+
+This remains an ordinary 0.x release, not a dogfood-only build and not GA.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "knodin",
-	"version": "0.8.2",
+	"version": "0.8.4",
 	"description": "knodin — source-evidenced local code intelligence with known bounds. Stable identity, fresh evidence, truthful budgets, and recoverable bounded views.",
 	"license": "MIT",
 	"repository": {
@@ -25,6 +25,7 @@
 		"docs/DOCTOR-AND-UPDATES.md",
 		"docs/DIAGNOSTICS.md",
 		"docs/BEHAVIORAL-CONTRACT.md",
+		"docs/DEMO.md",
 		"docs/COMPARISON.md",
 		"docs/COMPETITIVE-LANDSCAPE-2026-08.md",
 		"docs/INDEXING-POLICY-AND-PROVENANCE.md",
@@ -57,6 +58,8 @@
 		"docs/releases/0.7.5.md",
 		"docs/releases/0.8.0.md",
 		"docs/releases/0.8.2.md",
+		"docs/releases/0.8.3.md",
+		"docs/releases/0.8.4.md",
 		"docs/assets/knodin-favicon.svg",
 		"docs/SYSTEMS-AND-RELATIONSHIPS.md",
 		"docs/TELEMETRY.md",
@@ -114,6 +117,16 @@
 		"bench:c93": "tsx benchmarks/evaluations/c93-engineering-outcomes/runner.ts",
 		"verify:c93": "tsx scripts/verify-c93.ts",
 		"verify:c95": "tsx scripts/verify-c95.ts && vitest run src/__tests__/unit/behavior-contract.spec.ts src/__tests__/unit/failure-diagnosis.spec.ts src/__tests__/unit/impact.spec.ts src/__tests__/unit/freshness.spec.ts",
+		"bench:c97": "tsx benchmarks/evaluations/c97-one-process-semantic-residency/runner.ts",
+		"verify:c97": "tsx scripts/verify-c97.ts",
+		"bench:c98": "tsx benchmarks/evaluations/c98-resource-reachability/runner.ts",
+		"verify:c98": "tsx scripts/verify-c98.ts && vitest run src/__tests__/unit/resource-reachability.spec.ts",
+		"bench:c99": "tsx benchmarks/evaluations/c99-typescript-di/runner.ts",
+		"verify:c99": "tsx scripts/verify-c99.ts && vitest run src/__tests__/unit/typescript-di.spec.ts",
+		"bench:c100": "tsx benchmarks/evaluations/c100-flow-apex-path/runner.ts",
+		"verify:c100": "tsx scripts/verify-c100.ts && vitest run src/__tests__/unit/salesforce-metadata.spec.ts",
+		"bench:c101": "tsx benchmarks/evaluations/c101-contract-positioning/runner.ts",
+		"verify:c101": "tsx scripts/verify-c101.ts",
 		"bench:ann": "bun scripts/ann-bench.ts",
 		"bench:perf": "tsx scripts/perf-bench.ts",
 		"bench:competitive": "tsx scripts/competitive-bakeoff.ts",