Docs–code drift register and intent questions — ruled 2026-07-26 (v0.9.0-rc.10)

Status: maintainer rulings recorded 2026-07-26 — all 19 questions ruled. Re-verified 2026-07-27 against 2d2edc1 (code identical to 453a0ba; the delta is docs-only). That pass corrected three register entries that had drifted from the tree — Q-12 (landed, not open), the R-004 companion item (user-facing print already removed), and the Q-18 remediation sketch (the suggested predicate overshoots — see the amended landmine note). Note: items below cite docs/agents/AGENTS.md / AGENTS.full.md. Those files were deleted during the 0.9.0 docs sweep; their still-true content now lives in src/assets/hints/cli-hints-full.md / cli-hints-short.md, which is what akm hints prints. Companion to: 0.9.0-public-api-issue-backlog.md (implementation-only findings). This register covers the complement: places where the documentation and the code disagree, and places where the intended implementation is genuinely unclear because the project's own decision records conflict with shipped behavior.

Method: three independent audits (README + guides; architecture/specs/agent docs + STABILITY/AGENTS/SECURITY; docs/reference) compared documented claims against src/ with file:line verification, plus live CLI execution for the highest-stakes items. Items verified by actually running the CLI are marked [verified live]. Line references may drift; every item names the file and observable behavior so it can be re-verified.

Reading order: Part 1 records the intent conflicts and now carries the maintainer rulings (2026-07-26) that settle them — the rulings table is the authoritative direction; the question bodies remain as the evidence record. Parts 2–3 are mechanical now that Part 1 is decided. Part 4 records false alarms and verified-clean surfaces so future audits don't re-litigate them.

Part 1 — Decision needed (now ruled): the intent conflicts

Each question cites both sides. "Docs-as-intent" means the fix is code work; "code-as-intent" means the fix is doc work — but several of these have the decision record itself (STABILITY.md, 0.9.0-decisions.md, ref.md) on the losing side, which is why a ruling was needed first.

Maintainer rulings — 2026-07-26

Ruled by the maintainer in session review. Each ruling names the winning side and the required follow-through; the question bodies below are kept as the evidence record.

Until each follow-through lands, these rulings supersede conflicting statements in the older records — 0.9.0-decisions.md (notably D3's mv removal and D9's --auto-accept wording), STABILITY.md (the mv-removal claim, the six-format wording amended by Q-04, the missing tier entries), ref.md, and the scaffolded stash assets such as facts/conventions/organization.md. Where any of those contradicts this table, the table wins; treat the contradiction as un-swept drift, not authority.

Implementation status against the base branch (claude/0-9-0-release-review-bcjxxu @ 453a0ba)

Re-verified 2026-07-26 after merging the base branch. The questions below were written against a8464f2; the base branch has since implemented part of the ruling set. Status per ruling:

Q-04 conflict — RESOLVED 2026-07-27: keep six formats. The maintainer amended the ruling to accept D7 as shipped: six distinct formats (text for terminal rendering, md for document artifacts) plus the exemption registry. The collapse is off the table. Follow-through landed the same day: the INVALID_FORMAT_VALUE hint (errors.ts:111) and bash completions (completions.ts) now carry the six-value set, completions dropped the bogus --detail summary value and gained --shape, and the per-command --format help strings on search/curate/show were updated. Q-04's original follow-through detail in the rulings table is superseded by this note; STABILITY.md's six-format wording stands as-is. Related same-day rulings: R-029 — akm backup is removed from the CLI (the capability lives at akm-migrate backup/restore, which already existed; migration docs swept); R-047 — the scope-narrowing axis unifies on --filter for both search and show, --scope removed with no alias (the old spelling now fails loudly via the extra-positional guard, pinned by test). The paragraph below is kept as the evidence record.

Original conflict note: The ruling recorded above says "collapse text and md into a single format". The base branch instead landed D7 as six distinct formats: md gained a renderer registry plus a generic markdown fallback, explicitly so that "no command emits JSON under --format md any more" (cli/shared.ts:234-241). It also built the exemption registry D7 asked for (format-exempt.ts), which the ruling wanted. So the shipped work satisfies the ruling's first half and contradicts its second. Either the collapse is applied on top of D7 (deleting one of the two renderer paths), or the ruling is amended to accept six formats. Until that is decided, the Q-04 follow-through detail recorded in the table above is provisional.

Q-18 now collides with usesIndexedProjection — sequence the work. 453a0ba made show decide between the adapter's indexed projection and the AKM matcher by asking !placementTypes().includes(entry.type) (read/show.ts:557). Today instruction is not a placement type, so adapter-emitted CLAUDE.md/AGENTS.md items (claude/opencode adapters, tool-dir-shared.ts:110-112) take the projection and render with their indexed content — the behavior that commit was written to restore. The moment Q-18's ruling lands and instruction joins PLACEMENT_SPECS, that predicate flips to false for those items and show starts re-deriving them through recognizeMatch, reintroducing for instruction exactly the regression 453a0ba fixed for website/file. Implementing Q-18 therefore requires widening the predicate at the same time.

Amended 2026-07-27 — the sketch above overshoots. Gating on entry.adapterId !== "akm" would change behavior for four other adapters: agent-skills, akm-task, akm-workflow, and llm-wiki all publish document.content AND emit AKM-placed types (skill, task, workflow, knowledge) whose items deliberately render through AKM's bespoke type renderers today (a skill keeps its run-command action, a task its schedule view). Flipping them to the generic projection is a second regression wearing the fix's clothes. The correct shape is an explicit ownership signal rather than either inference: when instruction joins PLACEMENT_SPECS, either (a) route instruction-typed items from the claude/opencode adapters to the projection by adapter id — a two-member allowlist, honest about being one — or (b) add an adapter-declared ownsPresentation marker on the indexed document and let usesIndexedProjection read it. (b) is the durable fix; (a) is acceptable 0.9.0 scope. Either way, land a guard test pinning instruction-item show output BEFORE the PLACEMENT_SPECS change, so the flip fails a test instead of shipping silently. Ruled 2026-07-27: option (b), the ownsPresentation marker — adapters stamp presentation ownership on the documents they index and usesIndexedProjection reads the stamp; index.db being a regenerable cache, the schema addition needs only a reindex. Implement the marker together with (or before) the PLACEMENT_SPECS.instruction entry, guard test first. This remains the concrete cost of the two-registry split: placement is now load-bearing for rendering, not just for storage.

Q-01 — akm mv: decided removed, fully shipped. Which wins?

• Removed, per: 0.9.0-decisions.md D3 (:67-117), STABILITY.md:60-62, ref.md:259-286, architecture.md:110-111, docs/agents/AGENTS.full.md:215, stash-conventions-code-spec.md:189-195, and the scaffolded stash asset facts/conventions/organization.md ("A rename is delete plus create. There is no command that preserves an asset's identity or learned state").
• Shipped, per: src/cli.ts:98,529; src/commands/mv-cli.ts (1,300+ LOC) whose header states it re-keys the index row, usage_events history, and state.db salience rows in place — the exact inverse of D3's contract — and docs/reference/cli.md:888-921 documenting it as live. mv-cli.ts self-labels "Experimental — see STABILITY.md", but STABILITY.md has no mv tier entry. D3's cleanup item (delete the mv fs-txn kind) is also unexecuted (MV_TXN_KIND, mv-cli.ts:300).
• Cost of ambiguity: agents reading the shipped conventions fact avoid the safe command and hand-roll the dangerous procedure it automates.

Q-02 — Ref-prefix browse grammar: slash (decided) vs colon (implemented)

• Decided grammar (slash), per: D4, STABILITY.md:50-52 (Stable tier), ref.md:159-186, docs/guides/concepts.md:237-253 ("that spelling is gone"), docs/reference/cli.md:338,344, and akm hints output (akm search "memories/projectA/").
• Implemented grammar (colon), per: parseRefPrefixQuery (src/indexer/search/fts-query.ts:85-102) accepts exactly <singular-type>: / <singular-type>:<prefix>/; no-colon queries return null and fall through to keyword FTS. Bundle enumeration (bundle//) has no code path. search --help (search-cli.ts:36) documents the colon form; tests pin it (tests/integration/search-ref-prefix.test.ts:160,184,348).
• [verified live] akm search "memories/" → keyword search (returned an unrelated fact); akm search "memory:" → actual type enumeration.
• Note: akm hints shows BOTH spellings ("memories/projectA/" and "knowledge:") — the tool's own agent guidance is internally split.

Q-03 — akm show view modes: decided deleted, still live and advertised

• Deleted, per: D2 (0.9.0-decisions.md:44-63), ref.md:144-157 — the positional toc|section|lines|frontmatter|full grammar, normalizeShowArgv, and the hidden --akmView/--akmHeading/--akmStart/--akmEnd flags.
• Live, per: show.ts:672 (SHOW_VIEW_MODES), show.ts:695-766 (normalizeShowArgv), invoked pre-citty at src/cli.ts:605; the view modes are the headline example in show --help and in akm hints.

Q-04 — --format universality: a Stable-tier contract with no implementation

• Contract, per: D7, STABILITY.md:70-77: all six formats on every non-exempt command; exemptions "declared, documented, and warned about rather than silent".
• Code: html throws for every command except health (src/cli/shared.ts:208-215; health intercept src/cli.ts:341); md silently returns the JSON envelope except for health (shared.ts:201-207); text falls back to JSON.stringify where no renderer is registered (shared.ts:196-199); no exemption registry exists (0 hits for FORMAT_EXEMPT). USAGE_HINTS.INVALID_FORMAT_VALUE (src/core/errors.ts:111) lists only four of the six accepted values.
• Related asymmetry: persisted output.format schema accepts only json|yaml|text (src/core/config/schema/output.ts:15) while the CLI flag accepts six — a saved md preference is silently dropped.

Q-05 — experimental.workflowEngine / experimental.improveAutonomy: documented gates, zero code

• Contract, per: STABILITY.md:192-218 (gate table; "a gated lane never degrades into a silent no-op"), D8 (0.9.0-decisions.md:226), 0.9.0-release-surface-review.md:438,517,522.
• Code: zero occurrences of experimental / workflowEngine / improveAutonomy in src/ or schemas/akm-config.json; akm workflow run (workflow-cli.ts:331) is ungated. Because the top-level schema is .passthrough(), setting the keys is accepted and inert — precisely the silent no-op the contract forbids.
• Question: are the gates still intended for 0.9.0 final, or is the STABILITY.md section to be dropped?

Q-06 — Fragment refs (#fragment): implemented for show only

• D1 (0.9.0-decisions.md:19-40) and ref.md:111-142 declare the fragment production resolved. parseRefInput still throws INVALID_FLAG_VALUE on any fragment (resolve-ref.ts:255-264; docblock: "No input boundary consumes an export fragment"). show works by bypassing it (show.ts:312,370,390-397).
• Question: is "show only" the intended scope of D1, or an incomplete rollout across the other ref-consuming commands?

Q-07 — Opaque adapter conceptIds (the OKF/format-agnostic promise)

• Contract, per: okf-support.md:42-45 (item 5) and D11 (0.9.0-decisions.md:302-313): okfbundle//tables/customers must be accepted by "show and other applicable ref-consuming commands"; the leading-segment (known type dir) requirement "is therefore an OKF support bug". ref.md:33-37,84-86: conceptIds are opaque paths.
• Code: typeNameFromConceptId requires a known stash subdir and parseRefInput throws otherwise (resolve-ref.ts:230-236,265-271). Only show bypasses. Still routed through the strict parser: graph (graph.ts:634), tasks (validator.ts:46,76, runner.ts:361,578), improve (improve.ts:460), proposals repo (proposals-repository.ts:62), utility repo (index-utility-repository.ts:163), indexer walk (path-resolver.ts:25).
• Question: which commands are "applicable"? This is the single biggest blocker to the stated agent/harness/format-agnostic direction.

Q-08 — env/secret ref spelling: env/prod vs env:prod

• Code canonical: env/<name>, secrets/<name>; bare names auto-qualify (src/core/env-secret-ref.ts:55-62,128).
• Colon spellings taught by: secret --help example akm secret path secret:deploy-key (secret-cli.ts:95), env set/unset help (env-cli.ts:392,455), the vault-removal signpost itself ("use env: … or secret:", env-secret-ref.ts:49), docs/agents/AGENTS.md:44-45, and docs/migration/v0.8-to-v0.9.md (TL;DR akm env run env:<name>; "entries surface under env:").
• [verified live] akm secret path secret:deploy-key → Secret not found: secrets/secret:deploy-key; akm env path env:prod → Env not found: env/env:prod; slash and bare forms work.
• Question: should the colon forms be accepted as aliases (they are the spelling every help surface teaches), or should every emitter be swept to the slash form?

Q-09 — akm list --kind: conceptual vs provider taxonomy

• Docs: local | managed | remote used consistently (docs/guides/sources-registries.md:52-56, docs/reference/cli.md:754-764, registry.md prose).
• Code: VALID_SOURCE_KINDS = filesystem|git|npm|website (sources-cli.ts:36-47); every documented example exits 2.
• Both taxonomies are coherent (the lock-backed "managed" distinction exists in code as a behavioral split — see backlog R-015). Which is the intended user-facing axis?

Q-10 — curate --rerank: two independent references, zero implementation

• Referenced by docs/reference/cli.md:129 and live setup-wizard prose (src/setup/steps/connection.ts:365,424). No such flag exists (search-cli.ts:119-137). Designed-then-dropped, or specced-never-built?
• Resolved (0.9.15, #951): the setup-wizard reference is already gone; the remaining --rerank / "curate reranks by intent" claims (docs/reference/cli.md, docs/guides/getting-started.md, docs/guides/discover-and-load.md, and the curate command description in search-cli.ts) were deleted rather than implemented — no --rerank flag or reranking behavior exists in akm curate. A rerank engine kind (the lab's cross-encoder endpoint from the same fleet review) is real feature work, not a doc fix, and is deferred to its own issue.

Q-11 — workflow create hierarchical names

• docs/reference/cli.md:574-577: "Forward slashes are supported for hierarchical names (e.g. release/ship)."
• Code: assertFlatAssetName rejects any / in --name (workflow-cli.ts:226, asset-create.ts:44-51) — yet the post-combine validation regex explicitly permits / (workflow-cli.ts:228-229), and --path (undocumented in cli.md) reintroduces it. The regex permitting / suggests the flat guard may be the later, unintended restriction.

Q-12 — --auto-accept removal contract: two docs, two contracts, code matches neither

• D9 / 0.9.0-release-surface-review.md E4: the strict 0.9 runtime "does not parse" the flag (implies hard failure). STABILITY.md:114-116: "deprecated and ignored; becomes a hard error in 0.10."
• Code: no such arg is declared and no deprecation warning exists — citty silently drops it. Neither doc's signposting reaches the user.

Q-13 — Registry stale-fallback windows: doc'd tiers may be a code regression

• docs/reference/registry.md:325,345: static-index has a "7-day stale fallback"; skills-sh "up to 24 hours" on network failure.
• Code: no second window exists — getRegistryIndexCache returns undefined past TTL (registry-index-cache-repository.ts:80); the stale branch in fetchCachedJson (registry-cache.ts:136-141) can only fire within TTL. The numbers are too specific to be invented, and the cache helper was extracted with a "behaviour-preserving extraction" note (:95-97) — possibly lost functionality rather than doc fiction.

Q-14 — What is public surface? (the undocumented command families)

akm lint, akm extract, akm backup, akm proposal drain, akm improve canary, and the workflow exec/driver family (run/brief/report/watch/abandon) have no section in docs/reference/cli.md (which calls itself authoritative), and STABILITY.md assigns them no tier. Only mv is marked Experimental anywhere. Deliberate hiding vs. doc debt is undecidable — and it matters for a 1.0 contract freeze. A convention is needed: every registered command gets a tier (stable/experimental/internal) and the reference either documents it or explicitly lists it as internal.

Q-15 — Wiki raw/** indexing vs "never indexed"

docs/guides/wikis.md:60 (and adapter prose elsewhere) say raw/ is structural and "never indexed as pages". The llm-wiki adapter indexes raw/**.md as first-class searchable documents with type: "wiki-source" (llm-wiki-adapter.ts:82-83,271,291 — "First-class addressable + searchable"). Literally consistent ("not pages"), practically misleading. Intended behavior or over-indexing?

Q-16 — functional-contract-patterns.md §4: aspiration or contract?

7 of 12 "Recommended Contracts" have no implementation (PathResolver, MatchContributor, MetadataContributor, LintContributor, ImproveContributor, IndexPostProcessor, AgentRunner); §3.9 states the AgentRunner seam as a rule, but the actual seam is RunnerSpec/executeRunner (runner-dispatch.ts). Mark the doc as aspirational, or reconcile the seam names.

Q-17 — runtime-boundary-design.md: shipped, amended, or superseded?

Still written as an open brief with unchecked "Architect: investigate" boxes (:32-37,69-73,104-106,132-140), yet both target files exist and are complete (src/storage/database.ts, src/runtime.ts — all 11 tabled exports present). Its "3 hard-import files" no longer match the tree. Originally flagged as needing a status banner; ruled instead (see the rulings table): consolidate the still-necessary details into the other architecture docs and retire the file.

Q-18 — The instruction asset type: half-registered

Present in KNOWN_TYPES/TYPE_PRESENTATION (renderer + action builder), absent from PLACEMENT_SPECS — so it is invisible to akm info, unbrowsable, and its refs don't round-trip (recognition-util.ts:92-106 vs asset-placement.ts:89-166). Register fully or remove; either way, add a compile-time exhaustiveness check tying the two registries together.

Q-19 — Install-ref meta resolution: aspirational error message

concepts.md:343 documents akm show github:owner/repo//meta, and showStashMeta's own error says "Run: akm add ${metaRef.origin}" (show.ts:149) — but resolveSourcesForOrigin matches derived installation ids that can never equal github:owner/repo (origin-resolve.ts:18-23, installations.ts:98-110). Either the resolver lost install-ref support or the doc + error message are aspirational.

Part 2 — Verified drift register (docs describe behavior the code doesn't have)

2.1 STABILITY.md (contract-tier claims)

• D-01 ✅ Fixed (D4 landed): slash enumeration incl. bundle// is the implementation; the colon form is gone. Was: listed Stable; not implemented.
• D-02 ✅ Fixed as six formats (D7 landed): registries + generic md/html fallbacks + declared exemptions. NOTE the Q-04 collapse ruling is still unresolved against this — see the Q-04 conflict note.
• D-03 ✅ Fixed (Q-01 landed): STABILITY.md now carries the Experimental mv entry and no removal claim.
• D-04 Proposal status vocabulary wrong: doc says accepted/pending/proposed/rejected/archived (STABILITY.md:145-147); actual ProposalStatus = pending|accepted|rejected|reverted (proposal-types.ts:157, proposal-cli.ts:55). proposed is an entry quality, archived is not a status, reverted is documented nowhere.
• D-05 ✅ Fixed (Q-12 landed, 2a68c7a): warn-and-ignore implemented incl. the scope-poisoning drop; see the corrected Q-12 status row.

2.2 Root AGENTS.md (contributor guidance)

• D-06 Instructs configuring llm.maxTokens / llm.timeoutMs / llm.concurrency in config.json (AGENTS.md:46-48) — a top-level llm key is hard-rejected at load with exit 78 (config-schema.ts:157-165: "llm is retired in 0.9"). docs/architecture/internals/indexing.md:6,78-89 repeats the retired keys, as does a stale comment at indexer.ts:1601.
• D-07 Error envelope documented as {ok:false, error, code}; code also emits hint (cli/shared.ts:93). Exit-code table omits 4 (health warn, cli.ts:583) and 70 (INTERNAL, shared.ts:45); same omission in docs/agents/AGENTS.md:60-67.

2.3 docs/reference/cli.md

• D-08 ◐ Partial: the global --format table now lists all six values (cli.md:18, updated with D7); the --output global-flag row is still missing. Remaining work: one table row. (Value set may shrink again if the Q-04 collapse is chosen.)
• D-09 init dir list stale: missing tasks/, sessions/, facts/ (13 dirs via stashDirNames(), init.ts:126, asset-placement.ts:203). Note: Q-18's ruling adds an instructions/ placement dir (13 → 14) — sweep this item and D-46 after that change lands, regenerating from stashDirNames() rather than re-hardcoding.
• D-10 akm.llm indexing claim uses the retired key (see D-06).
• D-11 ◐ Partial: --report and --window-compare are now documented (health redesign, 0475870) and --compare no longer exists to document; --group-by and --windows still have no table row.
• D-12 search: --shape summary described as a silent no-op alias of brief (cli.md:365,395); code rejects it at startup and in the shape registry (cli.ts:632-634, shapes.ts:94-107). cli.md:47-51 states the correct behavior — the doc contradicts itself.
• D-13 search --type list incomplete (missing task, session, fact); undocumented flags --belief (table), --no-project-context, --include-sessions. Shape-source pointer cites src/output/shapes.ts for functions that live in src/output/shapes/helpers.ts:342,385.
• D-14 show: path/editable are always projected, not --detail full additions (helpers.ts:492-495); only schemaVersion/editHint are full-only.
• D-15 workflow: 5 of 14 subcommands undocumented (run, brief, report, watch, abandon); complete --summary (required, gate-validated, workflow-cli.ts:112-132) undocumented; start --force, status --units, complete --evidence undocumented; hierarchical-name claim false (Q-11).
• D-16 add: dangerous-env-key block exits 1, not 2 (add-cli.ts:200,221,355); key list "23 total" vs 41 literals + 2 pattern families (env-key-rules.ts:35-109); scan is top-level env/*.env only, not "every file" (add-cli.ts:87).
• D-17 list: --kind values wrong — all four documented examples exit 2 (Q-09). remove --yes/-y undocumented.
• D-18 feedback/history/log: missing --failure-mode, repeatable --tag (feedback-cli.ts:212-222); history --include-proposals, --accept-rate-by-source (sources-cli.ts:307-320); log --include-tags, --exclude-tags (observability-cli.ts:53-60).
• D-19 registry: "four subcommands" (five exist; the doc itself documents five); registry remove --yes undocumented.
• D-20 config: validate, show, enable, disable subcommands and --silent undocumented (config-cli.ts:138-260) — validate is load-bearing (startup bypass allowlist, cli.ts:575) and enable/disable are referenced by registry.md:347.
• D-21 env: subcommand table omits set/unset (both registered, env-cli.ts:509-510); create --sensitive/--path/--target never in a flag table.
• D-22 improve: archiveRetentionDays documented as improve.* with default 30 — actually top-level with default 90 (config-schema.ts:149, repository.ts:1054); --skip-if-locked, --sync/--no-sync, --push/--no-push undocumented; improve canary [--refresh] entirely undocumented (improve-cli.ts:49,96,160-163).
• D-23 proposal: drain verb undocumented while cli.md:1991 asserts a six-verb grammar (proposal-cli.ts:339-383, 8 flags); bulk --max-diff-lines/--older-than/--dry-run undocumented.
• D-24 tasks: tasks_invoked/tasks_completed events do not exist — task runs write the task_history table, surfaced by akm tasks history, not akm log (runner.ts:24, task-history-repository.ts:112,162); tasks add --disabled/--force/--rebind and init's CI skip undocumented.
• D-25 akm lint, akm extract, akm backup have no cli.md section at all (Q-14).
• D-26 Cross-reference anchors into configuration.md don't exist (#defaultwritetarget, #memory-scope, #graph-boost-search-tuning).
• D-27 agent/propose: agent --cwd, propose --path undocumented.

2.4 docs/reference/configuration.md

• D-28 11 of 18 real top-level keys undocumented: bundles, defaultBundle, defaultWriteTarget, search, feedback, archiveRetentionDays, output, semanticSearchMode, embedding, registries, setup (config-schema.ts:120-153). Several are load-bearing for the CLI reference's own flows.
• D-29 Environment table missing AKM_DATA_DIR, AKM_CACHE_DIR, AKM_STATE_DIR, XDG_*, AKM_VERBOSE, AKM_DEBUG, AKM_DISABLE_PROJECT_CONTEXT.
• D-30 ✅ Fixed (D7): output.format schema widened to all six values (schema/output.ts), schema regenerated. A saved md preference now works. (Re-shrinks if the Q-04 collapse is chosen — keep in the Q-04 blast radius.)

2.5 docs/reference/registry.md

• D-31 Teaches retired config.installed (:219-221) and sources[] (:316-317) — both hard-rejected (config-schema.ts:184-192). Should be bundles.
• D-32 Lists retired wiki asset type (:431); cites src/core/asset/asset-spec.ts as "the authority" — file does not exist.
• D-33 build-index "scans the current directory" — it does not; it fans out to manual entries + npm keyword search + GitHub topic search (build-index.ts:99-112). Its command meta also says "v2" while emitting version: 3 (registry-cli.ts:133, build-index.ts:112).
• D-34 Stale-fallback windows don't exist (Q-13). Cache layout shape wrong (provider-utils.ts:83-99; no <timestamp>-<random> component).

2.6 docs/reference/data-and-telemetry.md

• D-35 logs.db missing from the data-directory table — a third durable database (logs-db.ts:6,55-60); the "safe to delete" guidance is incomplete. (roadmap.md:39-41 names it correctly.)
• D-36 Maps events to nonexistent commands: akm distill (no such command), akm lint --repair (flag is --fix); workflow_step_completed/updated attributed to workflow next — emitted by complete (runs.ts:707-719).
• D-37 "Full event type list" (~33 rows) vs ≥53 emitted types; missing include improve_invoked (which cli.md:234 relies on), llm_usage, mv (documented at cli.md:965!), env_access, secret_access, workflow_unit_*, collapse_detector_alert, and ~15 more.
• D-38 akm log list --limit 20 — log list has no --limit (observability-cli.ts:46-61); only tail --max-events.
• D-39 Retired stashDir config override taught (:71); still says "0.8.0" (:237); lists wikis as a stash dir (:68).

2.7 docs/reference/akm-eval.md

• D-40 "Three runner types" — nine exist (scripts/akm-eval/src/types.ts:7-16); reflect-quality and planner-waste never mentioned though both ship runners and cases. improve-smoke case count "8" — 12 case files ship. Cites src/core/proposals.ts (does not exist).

2.8 docs/guides/*

• D-41 concepts.md: prefix-grammar claims (Q-02); wikis/ as a stash type dir (no wiki placement spec; llm-wiki probe is bundle-root schema.md+pages/, llm-wiki-adapter.ts:429-436); akm mv removal claim (Q-01); belief filter "default current for memory search" — default is all everywhere (search-cli.ts:62, search.ts:166).
• D-42 search-discovery.md: ref availability stated backwards — present at brief (the default), absent at normal, per the REC-03 comment (helpers.ts:366-379).
• D-43 sources-registries.md: --kind local|managed|remote examples all exit 2 (Q-09).
• D-44 knowledge-management.md: remember --name ops/prod-secrets rejected by the flat-name guard (remember-cli.ts:151, asset-create.ts:44-51) — correct form is --path ops --name prod-secrets; "akm does not edit entries" contradicted by env set/unset (and by the same doc 17 lines later); secrets documented under env/ — they live in secrets/ (asset-placement.ts:135-140).
• D-45 improvement-loop.md: feedback --negative without --reason fails (requireReason defaults true, feedback-cli.ts:271-283); log list --since 7d unsupported (strict ISO parser, time.ts:86-108; shorthand is health-only); "there is no auto-accept threshold" — false: the doc-recommended proactive-maintenance strategy ships applyMode:"promote", maxAcceptsPerRun:100 (assets/improve-strategies/proactive-maintenance.json, improve.ts:804-830), and proposal drain --apply is a second promote surface.
• D-46 getting-started.md: setup dir list includes wikis/ (never created) and omits tasks/, sessions/, facts/.
• D-47 agent-integration.md: akm show "npm:@scope/pkg//…" / "github:owner/repo//…" rejected by the bundle-slug charset (asset-ref.ts:65,156-161); concepts.md:214-215 correctly restricts install refs to add/clone — the two guides contradict each other.
• D-48 stash-makers.md: dangerous-vault-key issue code stale (actual dangerous-env-key, env-key-rules.ts:175); "and 20 others" undercounts (41 + patterns); wikis/ layout again.
• D-49 claude-code-vs-akm-workflows.md Parts B–E describe the pre-engine world: "akm does not execute workflow steps" / "strictly sequential" / "no workers" / "two tables" / "a workflow is a document, not a program" — overtaken by workflow run's native executor, fan-out scheduler with concurrency caps, worktree isolation, workflow_run_units + migrations 004/005, and YAML v2 programs. Part F lists watch (NDJSON stream) and fan-out as future work; both shipped. Subcommand list missing five verbs.
• D-50 .github/README.npm.md: "community skills from skills.sh in a single query" — the skills.sh registry ships enabled: false (config.ts:109-112). README asset-type tables list 12 types, omitting session (concepts.md says thirteen).

2.9 docs/architecture/* (architecture.md + internals)

• D-51 Dead files/symbols cited as authoritative: src/core/asset/asset-spec.ts + re-export shims src/core/asset-spec.ts, src/core/asset-ref.ts, src/core/config.ts (architecture.md:34,451-453); TYPE_DIRS (storage-locations.md:445); parseAssetRef (improve-workflow.md:199); akmManifest() (search.md:217-222); fact-asset-type.md implementation table — 5 of 9 rows dead.
• D-52 RegistryProvider documented with searchKits/searchAssets/getKit/ canHandle (architecture.md:279-287); the real contract is a single search() (registry/providers/types.ts:35-45).
• D-53 storage-locations.md documents on-disk proposal stores (.akm/proposals/<uuid>/, archive dirs) and .akm/graph.json — proposals are a state.db table ("archival is a status flip", proposal/repository.ts:16-24); graph lives in index.db tables; 0 refs to graph.json in src/. backupExistingConfig attributed to paths.ts — lives in config-io.ts:111.
• D-54 indexing.md table inventory: 6 tables documented, 14+ created (index-schema.ts — adds index_dir_state, llm_enrichment_cache, registry_index_cache, utility_scores_scoped, graph_*). The former FTS dirty queue was removed when entry mutations took ownership of their FTS projection.
• D-55 architecture.md: wiki listed as built-in type mapped to wikis/ (retired; recognition-util.ts:80-106); pushOnCommit "deprecated" — actually hard-rejected (sources-bundles.ts:31-35); renderers.ts "replaced" — still exists and self-registers (592+ lines); static-index described as v2-only (code reads v2/v3).
• D-56 akm-0.9.0-bundle-adapter-spec.md: akm bundle rename cited as first-class — the bundle group was removed by D5; the 7 optional facet methods (§2) are deliberately deferred in code (bundle-adapter.ts:113-120 "DEFERRED … FLAGGED for maintainer") with no status marker in the spec.
• D-57 fresh-host-rebuild-runbook.md: retired stashDir key (:26-27).

2.10 docs/agents/* (the agent-facing docs)

• D-58 AGENTS.full.md documents the removed akm wiki family in full (:50,64,67,131-163) — list|create|show|pages|search|stash|lint|ingest| remove, --type wiki, --wiki, show wiki:<name>, wiki exit codes. AGENTS.md repeats wiki list/stash/ingest (:21-24,46). stash-conventions-code-spec.md cites src/wiki/wiki.ts (no such dir). Note the migration guide records the intent: the family was deliberately removed in 0.9.0 in favor of the llm-wiki bundle format — these docs and the shipped hints corpus (backlog R-001) were never swept.
• D-59 AGENTS.md teaches env run env:<name> / secret run secret:<name> — both 404 (Q-08) [verified live].
• D-60 AGENTS.full.md akm search "knowledge:" works only because the retired colon grammar is still the implementation (Q-02); AGENTS.md:107 omits the reverted proposal status.
• D-61 agent-install.md: stashDir/sources listed as valid setup --config keys and akm config get stashDir shown — both hard-rejected/unresolvable (config-schema.ts:181-189,382).

2.11 docs/migration/v0.8-to-v0.9.md

• D-62 Verification snippet akm info --format=json | jq -r .stashDir fails — InfoResponse has no stashDir field (info.ts:64-78) [verified live].
• D-63 TL;DR teaches akm env run env:<name> -- <command> (404s, Q-08); "entries surface under env:" uses the retired spelling.

2.12 In-CLI doc surfaces (shipped assets, help text)

Tracked in the backlog (R-001..R-006, R-052) and repeated here for completeness because they are documentation in the product's own voice: akm hints documents the removed wiki family and drifts by install method; show --format text renders type:name feedback commands; feedback help contradicts the immediate EMA update; a hint references akm events list; the scaffolded conventions fact contradicts akm mv; bash completions advertise --detail summary and omit md/html.

Part 3 — Code that still emits the retired type:name grammar

The grammar decision (STABILITY.md:42, ref.md:106, D-R3 "nowhere after the flip") is violated by live output, not just docs:

• E-01 formatRefForMessage() returns origin//type:name (write-source.ts:1148-1158) — used in git commit subjects (knowledge.ts:786), env/secret boundary commits (env-secret-ref.ts:273), and write errors (write-source.ts:317,343).
• E-02 sources/resolve.ts:46,58,67,82 — "Stash asset not found for ref: ${type}:${name}".
• E-03 show.ts:393 — "Fragments are not supported for ${displayType}:${displayName}".
• E-04 mv-cli.ts:1052,1064,1080 — error text renders ${source.type}:${source.name}.
• E-05 The show APPLY footer (show-directives.ts:26,57,75,87) — backlog R-002.
• E-06 env/secret help examples and the vault signpost (Q-08).
• E-07 ◐ Partial (re-verified 2026-07-27): the search --help and akm hints prefix examples were swept to slash with D4. Survivors: sources-cli.ts:213 clone example (npm:@scope/pkg//script:deploy.sh), five skill:akm-dream examples in proposal-cli.ts (:98,178,271,304 + one), and init.ts:152's memory:… reference. All are one-line help-string edits — batch into the Part 5 step-2 sweep.

Part 4 — False alarms and verified-clean surfaces

Recorded so future audits don't re-litigate.

• migrate apply --dry-run is NOT broken. The arg is declared camelCase (dryRun, migrate-cli.ts:28), and an audit flagged that citty might not bind --dry-run to it — a real apply masquerading as a dry run. [verified live]: citty auto-camelizes; --dry-run binds to both args.dryRun and args["dry-run"]. However, this disproves the comment at src/output/context.ts:87-93 ("citty does not auto-camelise hyphenated arg keys") — the codebase's quoted-kebab arg convention rests on a false premise, worth a note where that comment lives.
• Verified clean: docs/reference/roadmap.md (no shipped-but-absent or future-but-present items) and docs/reference/wiki-snapshot-fetchers.md (every claim matches snapshot-fetchers/registry.ts, types.ts, website-ingest.ts).
• Verified exact: the model-alias table in agent-integration.md matches model-aliases.ts:45-76 byte-for-byte; storage paths, search/curate defaults and limits, website crawl caps (50 pages / depth 3 / 12h), tasks subcommands incl. --rebind, env run --clean, secret run <ref> <VAR> -- cmd, completions XDG install path, history oldest-first ordering, "installation is not activation" (activation-policy.ts), and workflow complete --summary gating all check out against code.
• Stale code comment that misled the audit itself: llm-wiki-adapter.ts:63-64 claims the adapter barrel is test-only; core/adapter/registry.ts:33 imports it in production. The adapter is live; the comment is wrong.

Part 5 — Suggested triage order

1. Rulings — done 2026-07-26 (all 19; see the Part 1 table). They decided whether ~40% of Part 2 is doc work or code work. Of the execute-first trio, Q-02 has landed (slash enumeration incl. bundle//, colon form gone); Q-07's renderer half landed (usesIndexedProjection) with the parser half open; Q-08 is untouched. Q-08 and Q-07's parser seam are now the highest-leverage remaining code items.
2. Sweep the agent-copy-paste surfaces (Part 3 + §2.10/2.12): everything an agent will paste from — hints, help examples, error messages, the show footer, AGENTS.md — should speak one grammar.
3. Re-tier STABILITY.md so nothing marked Stable is unimplemented and every registered command has a tier (Q-14).
4. Mechanical doc sweep for the remainder of Part 2, ideally with a CI check that executes every fenced akm … example in docs/ against a scratch stash (the --kind, --since 7d, remember --name a/b, and colon-spelling failures would all have been caught by running the docs).