knodin 0.5.0

package/dist/src/wait-for-fresh.js

@@ -0,0 +1,98 @@
+import childProcess from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { attachLifecycleHealth, inspectLifecycleHealth } from "./lifecycle-health.js";
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+const PROCESSOR_RETRY_MS = 500;
+function installedProcessorIsRunning(repo) {
+    try {
+        const pid = Number(fs.readFileSync(path.join(repo, ".reckon", "hooks", "refresh.lock", "pid"), "utf-8"));
+        if (!Number.isInteger(pid) || pid <= 0)
+            return false;
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function launchInstalledLifecycleProcessor(repo) {
+    const processor = path.join(repo, ".reckon", "hooks", "background-index.sh");
+    if (fs.statSync(processor).mode & 0o111) {
+        const child = childProcess.spawn(processor, [], {
+            cwd: repo,
+            stdio: "ignore",
+            detached: process.platform !== "win32",
+            windowsHide: true,
+        });
+        child.once("error", () => undefined);
+        child.unref();
+    }
+}
+function requiresStructuralRepair(graph) {
+    if (Object.values(graph.orphaned).some((count) => count > 0))
+        return true;
+    const ordinary = [
+        "indexed file no longer exists: ",
+        "indexed file is no longer eligible: ",
+        "indexed snapshot differs from disk: ",
+    ];
+    return graph.missing.records.some((record) => !ordinary.some((prefix) => record.startsWith(prefix)));
+}
+function launchQueuedProcessorIfNeeded(repo, elapsed, timeoutMs, lastAttemptAt, processQueuedEvents) {
+    if (elapsed >= timeoutMs ||
+        inspectLifecycleHealth(repo).queuedEvents === 0 ||
+        installedProcessorIsRunning(repo) ||
+        elapsed - lastAttemptAt < PROCESSOR_RETRY_MS)
+        return lastAttemptAt;
+    try {
+        processQueuedEvents(repo);
+    }
+    catch {
+        // Lifecycle health retains the queued event and wait remains truthful.
+    }
+    return elapsed;
+}
+function completedStatus(graph) {
+    if (graph.status === "healthy" && graph.freshness.state === "fresh")
+        return "fresh";
+    if (graph.status === "repair-needed" && requiresStructuralRepair(graph))
+        return "repair-needed";
+    if (graph.freshness.state === "unknown")
+        return "unknown";
+    return null;
+}
+async function reconcileOrdinaryDrift(engine, repo, graph) {
+    const shouldReconcile = (graph.status === "stale" || graph.status === "repair-needed") &&
+        graph.freshness.state !== "queued";
+    if (!shouldReconcile)
+        return graph;
+    await engine.query("stats", "", repo);
+    return attachLifecycleHealth(repo, await engine.status(repo, { audit: "deep" }));
+}
+function completedResult(status, startedAt, polls, graph) {
+    return { status, waitedMs: Date.now() - startedAt, polls, graph };
+}
+/** Wait for queued work and reconcile ordinary drift; structural repair stays explicit. */
+export async function waitForFresh(engine, repo, timeoutMs = 30_000, processQueuedEvents = launchInstalledLifecycleProcessor) {
+    const startedAt = Date.now();
+    let polls = 0;
+    let lastProcessorAttemptAt = Number.NEGATIVE_INFINITY;
+    for (;;) {
+        polls++;
+        const beforeStatusElapsed = Date.now() - startedAt;
+        lastProcessorAttemptAt = launchQueuedProcessorIfNeeded(repo, beforeStatusElapsed, timeoutMs, lastProcessorAttemptAt, processQueuedEvents);
+        let graph = attachLifecycleHealth(repo, await engine.status(repo, { audit: "cached" }));
+        let status = completedStatus(graph);
+        if (status)
+            return completedResult(status, startedAt, polls, graph);
+        graph = await reconcileOrdinaryDrift(engine, repo, graph);
+        status = completedStatus(graph);
+        if (status)
+            return completedResult(status, startedAt, polls, graph);
+        const elapsed = Date.now() - startedAt;
+        if (elapsed >= timeoutMs)
+            return { status: "timeout", waitedMs: elapsed, polls, graph };
+        await delay(Math.min(100, timeoutMs - elapsed));
+    }
+}

package/dist/src/worktree-lifecycle.js

@@ -0,0 +1,231 @@
+import childProcess from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+function git(repo, args) {
+    return childProcess.execFileSync("git", args, {
+        cwd: repo,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+function canonicalPath(target) {
+    try {
+        return fs.realpathSync(target);
+    }
+    catch {
+        return path.resolve(target);
+    }
+}
+function commonDirectory(repo) {
+    const value = git(repo, ["rev-parse", "--path-format=absolute", "--git-common-dir"]).trim();
+    return path.resolve(repo, value);
+}
+function registryPath(repo) {
+    return path.join(commonDirectory(repo), "knodin", "worktrees.json");
+}
+function emptyRegistry() {
+    return { schemaVersion: 1, graphState: "per-worktree", entries: [] };
+}
+function readRegistry(repo) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(registryPath(repo), "utf-8"));
+        return parsed.schemaVersion === 1 && Array.isArray(parsed.entries) ? parsed : emptyRegistry();
+    }
+    catch {
+        return emptyRegistry();
+    }
+}
+function writeRegistry(repo, registry) {
+    const target = registryPath(repo);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const temporary = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(registry, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(temporary, target);
+}
+function identityFor(repo, worktreePath, classification) {
+    let administrativePath = classification;
+    try {
+        administrativePath = path.resolve(worktreePath, git(worktreePath, ["rev-parse", "--path-format=absolute", "--git-dir"]).trim());
+    }
+    catch {
+        // A removed worktree retains its registry identity.
+    }
+    return crypto
+        .createHash("sha256")
+        .update(`${commonDirectory(repo)}\0${administrativePath}`)
+        .digest("hex")
+        .slice(0, 24);
+}
+function listGitWorktrees(repo) {
+    const fields = git(repo, ["worktree", "list", "--porcelain", "-z"]).split("\0");
+    const records = [];
+    for (const field of fields) {
+        if (field.startsWith("worktree ")) {
+            records.push({
+                path: path.resolve(field.slice("worktree ".length)),
+                classification: records.length === 0 ? "main" : "linked",
+                head: null,
+                branch: null,
+                locked: false,
+                prunable: null,
+            });
+            continue;
+        }
+        const current = records.at(-1);
+        if (!current)
+            continue;
+        if (field.startsWith("HEAD "))
+            current.head = field.slice(5);
+        else if (field.startsWith("branch "))
+            current.branch = field.slice(7).replace(/^refs\/heads\//, "");
+        else if (field === "detached")
+            current.branch = null;
+        else if (field.startsWith("locked"))
+            current.locked = true;
+        else if (field.startsWith("prunable "))
+            current.prunable = field.slice(9);
+    }
+    return records;
+}
+/** Register one initialized checkout in Git-common metadata without sharing its graph database. */
+export function registerInitializedWorktree(repoPath) {
+    const repo = path.resolve(repoPath);
+    const current = listGitWorktrees(repo).find((worktree) => canonicalPath(worktree.path) === canonicalPath(repo));
+    if (!current)
+        throw new Error(`knodin worktrees: ${repo} is not a registered Git worktree`);
+    const registry = readRegistry(repo);
+    const now = new Date().toISOString();
+    const identity = identityFor(repo, current.path, current.classification);
+    const existing = registry.entries.find((entry) => entry.identity === identity);
+    if (existing) {
+        existing.path = current.path;
+        existing.lastSeenAt = now;
+        delete existing.removedAt;
+    }
+    else {
+        registry.entries.push({
+            identity,
+            path: current.path,
+            classification: current.classification,
+            registeredAt: now,
+            lastSeenAt: now,
+        });
+    }
+    registry.entries.sort((left, right) => left.path.localeCompare(right.path));
+    writeRegistry(repo, registry);
+}
+export async function inspectWorktrees(repoPath, status) {
+    const repo = path.resolve(repoPath);
+    const current = listGitWorktrees(repo);
+    const registry = readRegistry(repo);
+    const livePaths = new Set(current.map((worktree) => worktree.path));
+    const worktrees = [];
+    for (const worktree of current) {
+        const identity = identityFor(repo, worktree.path, worktree.classification);
+        const registered = registry.entries.some((entry) => entry.identity === identity);
+        const graphInitialized = fs.existsSync(path.join(worktree.path, ".reckon", "db.sqlite"));
+        let indexedHead = null;
+        if (graphInitialized) {
+            try {
+                indexedHead = (await status(worktree.path)).lastIndexedHead || null;
+            }
+            catch {
+                indexedHead = null;
+            }
+        }
+        worktrees.push({
+            ...worktree,
+            identity,
+            registered,
+            graphInitialized,
+            indexedHead,
+            freshness: indexedHead === null || worktree.head === null
+                ? "unknown"
+                : indexedHead === worktree.head
+                    ? "fresh"
+                    : "stale",
+            removedAt: null,
+        });
+    }
+    for (const entry of registry.entries) {
+        if (livePaths.has(entry.path))
+            continue;
+        worktrees.push({
+            identity: entry.identity,
+            path: entry.path,
+            classification: entry.classification,
+            head: null,
+            branch: null,
+            locked: false,
+            prunable: "registered worktree is absent from Git's worktree inventory",
+            registered: true,
+            graphInitialized: fs.existsSync(path.join(entry.path, ".reckon", "db.sqlite")),
+            indexedHead: null,
+            freshness: "removed",
+            removedAt: entry.removedAt ?? null,
+        });
+    }
+    worktrees.sort((left, right) => left.path.localeCompare(right.path));
+    return { schemaVersion: 1, graphState: "per-worktree", worktrees };
+}
+/** Reconcile the durable registry with Git metadata; no checkout or graph is deleted. */
+export function reconcileWorktrees(repoPath) {
+    const repo = path.resolve(repoPath);
+    const current = listGitWorktrees(repo);
+    const registry = readRegistry(repo);
+    const now = new Date().toISOString();
+    const seen = new Set();
+    const added = [];
+    const restored = [];
+    for (const worktree of current) {
+        const identity = identityFor(repo, worktree.path, worktree.classification);
+        seen.add(identity);
+        const existing = registry.entries.find((entry) => entry.identity === identity);
+        if (!existing) {
+            registry.entries.push({
+                identity,
+                path: worktree.path,
+                classification: worktree.classification,
+                registeredAt: now,
+                lastSeenAt: now,
+            });
+            added.push(worktree.path);
+        }
+        else {
+            if (existing.removedAt)
+                restored.push(worktree.path);
+            existing.path = worktree.path;
+            existing.lastSeenAt = now;
+            delete existing.removedAt;
+        }
+    }
+    const removed = [];
+    for (const entry of registry.entries) {
+        if (!seen.has(entry.identity) && !entry.removedAt) {
+            entry.removedAt = now;
+            removed.push(entry.path);
+        }
+    }
+    registry.entries.sort((left, right) => left.path.localeCompare(right.path));
+    writeRegistry(repo, registry);
+    return { schemaVersion: 1, added, restored, removed };
+}
+/** Remove exactly one linked worktree through Git, then retain removal evidence in the registry. */
+export function removeManagedWorktree(repoPath, targetPath, dryRun) {
+    const repo = path.resolve(repoPath);
+    const target = path.resolve(targetPath);
+    const record = listGitWorktrees(repo).find((worktree) => canonicalPath(worktree.path) === canonicalPath(target));
+    if (!record)
+        throw new Error(`knodin worktrees remove: ${target} is not a registered Git worktree`);
+    if (record.classification === "main")
+        throw new Error("knodin worktrees remove: refusing to remove the main worktree");
+    if (dryRun)
+        return { schemaVersion: 1, target, dryRun: true, removed: false };
+    childProcess.execFileSync("git", ["worktree", "remove", target], {
+        cwd: repo,
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    reconcileWorktrees(repo);
+    return { schemaVersion: 1, target, dryRun: false, removed: true };
+}

package/docs/CLI.md

@@ -0,0 +1,39 @@
+# Declarative CLI contract
+
+knodin's command grammar is defined once in `src/cli-model.ts` with Commander
+15.0.0. The model owns root and nested commands, positionals, global and local
+options, numeric parsing, unknown-option rejection, and root or command help.
+`bin/cli.ts` dispatches the validated invocation to the existing product
+handlers so JSON output contracts and established commands remain compatible.
+
+Run `knodin --help` for the root command inventory or append `--help` to any
+declared command path, for example:
+
+```bash
+knodin repos search --help
+knodin update --help
+```
+
+Help uses the active terminal width. Non-TTY output uses a deterministic
+100-column layout so snapshots, documentation, and automation do not depend on
+the caller's environment. Narrow and wide formatting are covered by pure tests;
+the Unix acceptance fixture also exercises a real pseudo-terminal when the
+host provides one. Windows uses the same deterministic formatter and Commander
+model without depending on a Unix `script` executable.
+
+Commander is an exact production dependency rather than a floating range. Its
+resolved integrity is pinned by both npm and Bun lockfiles and flows through
+the normal SBOM, provenance, package-install, vulnerability, and signed-release
+gates. It adds no transitive runtime dependencies. Updating it requires the
+same lockfile review and full CLI compatibility suite as any parser change.
+
+Command-specific semantic checks remain close to their product handlers (for
+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.
+
+`knodin pack grep` evaluates user patterns with exact-pinned RE2 WebAssembly,
+not Node's backtracking regular-expression engine. Backreferences and lookaround
+are rejected because they cannot retain RE2's linear-time guarantee. Route
+matching treats application path text literally and recognizes only complete
+Express/NestJS-style `:name` or `{name}` path segments as parameters.

package/docs/COMMAND-OUTPUT-COMPRESSION.md

@@ -0,0 +1,194 @@
+# Bounded diagnostic-output compression
+
+knodin can deterministically compress already-produced build and test output
+without running the command that created it. This capability is available from
+the CLI and the single MCP gateway in post-0.3 development.
+
+knodin deliberately does **not** expose `knodin run`. Portable command
+execution remains excluded until the containment gate below can be proven.
+
+## Use it
+
+Prefer a repository-relative file or stdin so the full log does not first cross
+an agent's context boundary:
+
+```bash
+build-command > build.log 2>&1
+knodin compress build.log --exit-code 1 --lines 200
+
+build-command 2>&1 | knodin compress - --exit-code 1 --json
+```
+
+The same operation is available through the one-tool MCP gateway:
+
+```json
+{
+  "operation": "compress",
+  "artifactPath": "build.log",
+  "exitCode": 1,
+  "lineBudget": 200,
+  "compressionByteBudget": 16384
+}
+```
+
+`artifactPath` is repository-bound and must be a regular, non-symlinked file.
+Direct `text` and ordered `events` inputs support integrations and behavioral
+parity, but they do not prove context savings if the raw value has already been
+placed in the model's context.
+
+The always-loaded MCP schema advertises the common path to stay within its
+token ceiling. Advanced, still runtime-validated arguments are `events`,
+`signal`, `strategy`, `adapter`, `contextLines`, `retain`, `redactSecrets`,
+`maxInputBytes`, and `raw`. Use this canonical guide when composing them.
+
+## Contract
+
+- Strategies: `smart`, `head-tail`, and `errors-only`.
+- Adapters: generic fallback plus Vitest, Jest, pytest, Go test, Maven, Gradle,
+  .NET, and Cargo detection.
+- Preserved metadata: original exit code and terminating signal.
+- Preserved signals: detected errors, causes, stack frames, failing tests,
+  summaries, warnings, and bounded surrounding context.
+- Hard limits: rendered content never exceeds the requested line count or
+  UTF-8 content-byte budget.
+- Truthfulness: the status is `complete`, `compressed`, or
+  `insufficient-budget`; detected signals that cannot fit are listed rather
+  than silently described as preserved.
+- Accounting: every omitted range has inclusive source-line bounds and its
+  exact source bytes, including original delimiters.
+- Recovery: raw ordered events are retained locally by default and can be read
+  in bounded ranges without rerunning the command.
+
+The default compact MCP result uses documented tuples:
+
+- `exit`: `[exitCode, signal]`;
+- `budget`: `[usedLines, lineLimit, usedUtf8Bytes, byteLimit]`;
+- `fidelity`: `[detectedSignals, preservedSignals, unpreservedSignalIds]`;
+- each `omitted` entry:
+  `[inclusiveStartLine, inclusiveEndLine, exactSourceBytes]`.
+
+`artifactId` is the SHA-256 identity used with
+`compressionAction: "read"`, `"diagnose"`, or `"delete"`. Request
+`detailLevel: "standard"` for the fully named audit envelope.
+
+CLI drill-down and cleanup are explicit:
+
+```bash
+knodin compress read <artifact-id> --start 80 --end 140
+knodin compress read <artifact-id> --raw
+knodin compress delete <artifact-id>
+```
+
+Human output prints an explicit fidelity warning when a budget cannot retain
+every detected signal. `--json` emits the stable, fully named core result.
+
+## Connect a failure to code
+
+After compression, diagnose the retained artifact without rerunning the failed
+command:
+
+```bash
+knodin compress diagnose <artifact-id> --limit 10 --context 2
+knodin compress diagnose <artifact-id> --max-output-bytes 16384 --json
+```
+
+The same graph read is available through the single MCP gateway:
+
+```json
+{
+  "operation": "compress",
+  "compressionAction": "diagnose",
+  "artifactId": "<sha256>",
+  "limit": 10,
+  "contextLines": 2,
+  "compressionByteBudget": 16384,
+  "detailLevel": "standard"
+}
+```
+
+MCP callers may provide already-produced `text` instead of `artifactId`, but
+must provide exactly one. Direct text is bounded and secret-redacted before
+diagnosis. Retained artifacts are preferable because omitted regions remain
+available locally and the raw log need not first enter the agent context.
+
+Diagnosis recognizes source locations emitted by major JavaScript/TypeScript,
+Python, Java, C#, Go, and Rust toolchains. Every candidate is resolved against
+tracked files inside the current repository. Foreign CI checkout prefixes can
+map by a unique tracked suffix; basename-only matches remain unresolved when
+ambiguous. Traversal, symlinks outside the repository, untracked files, and
+missing graph records are refused rather than guessed.
+
+For each resolved location, the fully named result contains:
+
+- the reported path, line, column, and original evidence line;
+- the uniquely resolved tracked file and nearest package manifest;
+- the smallest enclosing graph symbol, stable identity, signature, and source
+  span;
+- related tests, upstream callers, and downstream dependencies;
+- recent commits touching the file;
+- a source snippet inside a hard aggregate UTF-8 byte budget; and
+- the indexed commit, current commit, and freshness state.
+
+The default compact MCP result preserves the same evidence with tuples:
+
+- `package`: `[name, manifest, ecosystem]`;
+- `owner`: `[identity, symbol, kind, startLine, endLine, signature]`;
+- relation entries:
+  `[identity, symbol, file, kind, line, confidence]`;
+- `recent`: `[shortCommit, authoredAt, subject]`; and
+- `freshness`: `[state, indexedHead, currentHead]`.
+
+`resolved` means every detected reference was mapped with complete input,
+current graph evidence, and an untruncated context bundle. `partial` identifies
+any omitted input, unresolved reference, stale graph, or exhausted context
+budget. `unresolved` means no safe repository location was established.
+
+The relationships are static diagnostic candidates, not proof of runtime
+causality. Package ownership is evidenced by the nearest tracked
+`package.json`, `pyproject.toml`, `pom.xml`, `Cargo.toml`, `go.mod`, or
+`.csproj`; malformed or unnamed manifests remain explicit. Dynamic dispatch,
+generated paths, source maps, and framework wiring can require additional
+runtime evidence.
+
+## Local retention and redaction
+
+Artifacts are stored beneath `.reckon/output/` with a private directory mode
+and `0600` files. The default returned content and bounded reads redact common
+credential forms and remove ANSI/control bytes. `--raw` is an explicit local
+request and can reveal the original secrets. Redaction is defense in depth,
+not a guarantee that every possible secret format is recognized.
+
+Input is bounded to 16 MiB by default and cannot be configured above 64 MiB.
+Oversized input is rejected rather than partially retained. Output artifacts
+are content-addressed, reads are byte-bounded, deletion requires an exact
+artifact identity, and symlinked storage paths are refused.
+
+## Command-execution security gate
+
+The safe compressor processes data only; it does not invoke a shell or child
+process. A future runner must address this threat model with executable,
+platform-specific evidence:
+
+| Threat | Required proof before shipping a runner |
+|---|---|
+| Shell injection | Argument-vector execution by default; no implicit shell |
+| Repository prompt injection | Repository text cannot alter executable or policy authorization |
+| Arbitrary filesystem access | Repository-root binding plus an enforceable filesystem sandbox |
+| Network access and exfiltration | Deny-by-default network containment where claimed |
+| Environment or credential leakage | Minimal allowlisted environment and no ambient credentials |
+| Child-process escape | Complete descendant tracking and termination |
+| Timeout | Process-tree termination, not only parent termination |
+| CPU, memory, disk, output exhaustion | Enforced resource and output caps |
+| Symlink or path traversal | Realpath containment and race-resistant file handling |
+| Destructive commands | Allowlisted profiles or per-call approval with an explicit audit record |
+| Cross-worktree effects | Authorized worktree binding and named affected roots |
+| Telemetry leakage | No command text or raw output in default telemetry; redact before opt-in export |
+| Platform differences | Separate verified guarantees and explicit unsupported cases |
+
+Node's cross-platform child-process API alone cannot impose a hard memory limit
+on an arbitrary executable, Windows job-object behavior differs from POSIX
+process groups, and portable network/filesystem containment requires more than
+an output buffer and timeout. Until a reviewed native or operating-system
+containment adapter proves the table above, command execution is an intentional
+safety non-goal. Existing trusted execution tools can write a log and pass that
+artifact to knodin for bounded compression.

package/docs/DEAD-CODE-AND-IMPACT.md

@@ -0,0 +1,27 @@
+# Dead code and impact
+
+`dead_code` reports static candidates, not deletion proof. A zero resolved
+reference count means the current indexed static graph found no supported
+reference. It does not prove that reflection, runtime dependency injection,
+framework configuration, metadata, deployed infrastructure, or external
+consumers cannot invoke the code.
+
+Impact follows source-evidenced resolved relationships. High-confidence
+incoming cross-repository relationships can make a dependency visible to
+impact and dead-code analysis. Heuristic or unresolved relationships lower
+deletion confidence; they must not falsely mark code live or safe.
+
+Salesforce Apex, Flow, metadata, LWC/Aura/Visualforce, scheduled/platform
+entrypoints, and deployed-org dependencies require platform corroboration.
+Configuration-driven frameworks and generated registries have similar limits.
+
+Before deletion:
+
+1. run `knodin query impact <symbol> --direction upstream`;
+2. inspect `tests_for`, relevant contracts, and system relationships;
+3. verify index health and freshness;
+4. investigate unresolved or heuristic incoming evidence;
+5. use platform/runtime evidence where static analysis is incomplete.
+
+An unavailable, uninitialized, empty, unhealthy, or partially omitted
+repository cannot produce an ordinary safe zero-result answer.

package/docs/DOCTOR-AND-UPDATES.md

@@ -0,0 +1,84 @@
+# Doctor and update awareness
+
+`knodin doctor` reports:
+
+- package, CLI, source, and MCP server version agreement;
+- current Node runtime and npm prefix;
+- manager ownership with confidence and evidence;
+- resolved executable, symlink/shim chain, and duplicate candidates;
+- supported agent configuration candidates;
+- a real MCP initialize/tools-list result;
+- Git-hook routing and refresh health;
+- graph health;
+- configured registry/channel;
+- cached latest **trusted** release state; and
+- the manager-safe action boundary when a signed update is known.
+
+A manager is reported as known only from manager-owned environment evidence or
+an identified shim. A path substring is labeled a medium-confidence heuristic,
+not proof.
+
+The former npm `latest` lookup has been removed from production paths. Doctor,
+CLI status, and MCP status now consume the same signed-only state as:
+
+```bash
+knodin update status
+knodin update check
+knodin update explain
+knodin update apply
+knodin update rollback
+```
+
+Until the production root ceremony embeds an independently reviewed root and
+pin, these commands report `trust-unconfigured` and make no request. A user
+configuration file containing both a root path and its digest is deliberately
+inert: accepting both from one mutable file would not be independent pinning.
+
+After activation, an interactive ordinary command may atomically claim a due
+background check. The foreground command does not wait for the network.
+Metadata requests have a 512 KiB per-role cap, a 100 ms–10 s configured
+timeout, no redirects, and remain within one approved HTTPS origin and path.
+Disable checks or all network access with:
+
+```bash
+RECKON_UPDATE_CHECK=0 knodin doctor
+RECKON_OFFLINE=1 knodin update check
+```
+
+Requests contain fixed metadata or signed target paths only. They never contain
+a repository name, source path, symbol, command, username, or telemetry. A
+failed check retains the last verified monotonic state but reports
+`check-failed`; it never turns failure into `up-to-date`.
+
+Apply is opt-in and fails closed. It verifies threshold-signed metadata,
+release age/channel/version policy, artifact length and SHA-256, a signed
+provenance digest, configured channel cross-checks, and both candidate and
+rollback artifacts before any manager action. Artifacts are quarantined with
+private permissions, fresh exclusive paths, and a symlink-rejecting quarantine
+root. Every enterprise-only primary or cross-check origin must be explicitly
+approved. Only a plain npm-owned install currently has an exact local-artifact
+adapter; mise, Volta, nvm/fnm/asdf, Homebrew, and unknown ownership remain
+`manager-action-required` until their rollback-safe adapters are certified. No
+manager is ever asked to resolve a mutable version or tag, and a rollback is not
+reported successful until the restored installation passes its health check.
+
+Automatic activation also requires a certified sandbox smoke test. None is
+enabled in the production CLI yet, so `apply-patch`/`apply-minor` policies stop
+after verified quarantine instead of executing untrusted code. C64 supplies
+the provenance/SBOM and five-channel attestation machinery; the production
+release must populate it, and C65 must supply compromised-channel and recovery
+evidence before this gate can open.
+
+Run `knodin status --deep` for graph details and `knodin repair` for surgical
+repair. Re-run `knodin init` after changing the executable owner or MCP path.
+
+## Query availability
+
+Every graph read reports an explicit availability outcome. `no-match` means a
+healthy graph was queried and produced no match. It is distinct from
+`not-initialized`, `empty-repository`, `empty-index`, `repair-needed`,
+`indexing`, and `unknown`; those states fail closed and include remediation
+instead of returning an ordinary zero. An otherwise complete graph with broken
+or displaced lifecycle hooks remains queryable but reports
+`lifecycle-degraded`, so callers can use current evidence without mistaking its
+refresh path for healthy.