0.9.0 release surface review — v2 (reconciled action list)

Supersedes v1 of this document. v1 was an end-to-end critical sweep of the user-facing surface (41 top-level commands, ~120 subcommands, ~230 flags, the Zod config schema, env vars, output contracts). v2 reconciles it with three inputs:

1. Owner corrections — --type is free-form by design; the global --format set must work on all commands with no bespoke shims; migration code should live outside the main tool; test-only env vars should not ship; akm bundle should be removed as duplicative; the show view modes should be replaced by #fragment section addressing.
2. The improve-autonomy review — do not gate the whole akm improve feature; gate autonomy (direct mutation, auto-promotion) behind an explicit opt-in, keep the feature and its schedules visibly alive. (Unattended push was in this list originally; D8 leaves it ungated — see the outcome note in C6.)
3. A verification pass (8 parallel read-only audits of the tree) that confirmed, refuted, or sharpened each claim. Two v1 claims were wrong and are corrected below.

Corrections to v1:

• v1 said AKM_DISABLE_PROJECT_CONTEXT=1 was the working escape hatch for the broken --no-project-context flag. False — that env var is never read anywhere in src/ (it survives only in help text at src/commands/read/search-cli.ts:68 and comments). There is currently no working way to disable the project-context boost. Same for AKM_DISABLE_SCOPED_UTILITY (comments only).
• v1 recommended validating search --type against a closed enum. Wrong direction — IndexDocument.type is an open string by contract (src/core/adapter/types.ts:156-157), the closed union was deliberately deleted (src/core/recognition-util.ts:71-77), and adapters emit types outside the placement set (website, wiki-source, open pageKind values). The fix is documentation, not validation.

Grouped by action. Ordering within groups is by cost-of-deferral.

A. Fix — defects, before anything else

A1. akm search --no-project-context is a no-op, and there is no fallback

search-cli.ts:65 declares an arg literally named no-project-context; the parser's --no-* negation makes passing it identical to omitting it. With the env var confirmed dead (see corrections), the boost cannot be disabled at all.

Action: declare project-context (boolean, default true) so --no-project-context works via native negation — the same pattern sync --push/--no-push already uses. Remove the dead AKM_DISABLE_PROJECT_CONTEXT mention from the help text (or implement it deliberately; pick one). Replace the current test (which only asserts the flag doesn't touch process.env) with one that asserts the boost is actually disabled.

A2. Fresh installs emit a fault-shaped warning on every search

Status: superseded by R-039 / X-RULING-9 — semanticSearchMode now defaults to "off" (src/core/config/schema/*.ts: .default("off")), so a bare/headless install no longer attempts semantic search or emits this warning at all; the interactive akm setup wizard still pre-selects it on, with the download warning moved ahead of the prompt. The finding below is kept as the evidence record for the default that motivated the ruling.

Verified end-to-end at the time: semanticSearchMode defaulted to auto (config.ts:108); with no embedding configured the implicit local-transformers path fails (optional dependency, or offline), verifyIndexState writes blocked (indexer.ts:1699-1715), and every subsequent search for 24h-cycles emits "Semantic search is currently blocked … until the semantic backend is healthy again" (db-search.ts:222-226) — describing a fault when the state is "not configured".

Action: split the blocked branch at db-search.ts:196-226 on the same predicate the pending branch already uses (!config.embedding?.endpoint || !config.embedding?.model, line 205):

• Unconfigured → no warning (or the existing actionable #480-style note: configure embedding or set semanticSearchMode off). The out-of-box warnings array must be empty/stable for scripted consumers.
• Configured-but-failing → keep the warning, enriched with the status ledger's reason/message (already in scope, currently discarded) and the retry instruction.

A3. --type help text: document free-form, stop implying an enum

Types are an open set by design (see corrections). But the help enum on search/curate lists 10 of the 13 placement types (omits task, session, fact), omits instruction, and omits the entire adapter-defined space; cli-hints-full.md:21 repeats the stale list; completions only complete placement types.

Action: rewrite the --type description on search and curate (and cli-hints-full.md): "Asset type filter. Built-in types: skill, command, agent, knowledge, workflow, script, memory, env, secret, lesson, task, session, fact, instruction — or any adapter-defined type (e.g. website, wiki-source, a wiki pageKind). Matching is exact; an unknown type returns no hits. Default: any." No validation added — a typo returning zero hits is the documented contract of a free-form filter.

B. One output contract — every global format on every command

Owner direction: json|jsonl|yaml|text|md|html must all work on all commands; no bespoke shims. The verification pass mapped the full gap: 37 commands silently emit JSON under --format text; md silently emits JSON everywhere except health; html throws everywhere except health; jsonl is per-item only for search; ~10 surfaces bypass output() entirely.

B1. Registry-driven renderers with generic fallbacks

The infrastructure exists — the shapes and text registries already follow the exact pattern (src/output/shapes.ts:78-99, src/output/text.ts:104-133).

Action:

• Add md and html renderer registries mirroring shapes/text. output() becomes a uniform lookup: shape → (registered renderer ?? generic renderer for that format) → deliverRendered. The html throw and the silent md JSON fallback in shared.ts:201-215 both disappear.
• Generic md renderer: key-value table for flat fields, md table for the envelope's dominant array field, fenced JSON for nested objects.
• Generic html renderer: one generic.html template (styled shell around the md rendering). resolveTemplatePath/escapeHtml already exist.
• Generic text fallback: route formatPlain's null branch through the generic md renderer instead of pretty JSON — closes the 37-command text gap in one move.
• jsonl list-awareness: replace the search-only special case (text.ts:138-148) with a declared per-shape list field (per-item lines + _kind:"trailer" envelope line — the precedent log tail already ships).
• health keeps its rich html/md output by registering its renderers (moving renderRunsDetailMd/renderWindowCompareMd and the ECharts template behind the registry); the pre-output() intercepts in cli.ts are deleted. The report layout is presentation, not contract.
• Snapshot test: every command × 6 formats produces non-empty output with the expected leading bytes.

B2. Remove akm graph export --format

Verified clean: the local flag already leaks into the global mode (one token, two parsers), the two payload formats map 1:1 to the global values with the same defaults, and payload (--out file) vs envelope (stdout) never collide.

Action: delete the local arg; the export handler reads getOutputMode().format; keep a UsageError for payload formats other than json|jsonl. This also removes the last subcommand-declared format: arg — which is what forced the citty workarounds in sync and env unset (sources-cli.ts:214-256, env-cli.ts:470-482); delete those too.

B3. Migrate raw-stdout bypasses onto output()

config path (bare), config validate success strings, and migrate status|apply (console.log(JSON.stringify(plan)), unshaped, unstamped) bypass the envelope entirely; env path/secret path print a raw scalar and ignore --format json (breaking | jq pipelines).

Action: give each a passthrough shape and route through output(). Path commands keep raw-scalar output in text mode; gain {path} envelopes under json/yaml/jsonl. (Payload values of env/secret remain excluded from structured output — that security contract is untouched.)

B4. Declare the format-exempt set

Some surfaces are exempt by nature: completions (output is a bash program), env run/secret run/agent child stdio, the interactive setup wizard branch, and document payloads (workflow template, hints, help migrate).

Action: a FORMAT_EXEMPT_COMMANDS set in src/cli/shared.ts that (a) emits a stderr note when a non-default --format is passed to an exempt command, (b) generates the exemption table in docs/reference/cli.md, and (c) powers a test asserting every command is either exempt or 6-format capable.

B5. Cleanup that falls out

Widen OutputConfigSchema.format to the full six values (users currently cannot persist jsonl|md|html); delete the vestigial distill/reflect shape+text registrations (no output() call sites exist); delete the doc-only local format: arg declarations on search/curate/show with their stale enums; fix the stale "fall back to YAML" comments.

C. Remove — deletions while 0.9.x still permits them

C1. Remove akm bundle (list/show/items)

Owner decision, and verification confirmed it is cheap: undocumented in docs/reference/cli.md, absent from STABILITY.md, zero consumers outside its own CLI file and one test.

Action: delete src/commands/bundle/ and the three passthrough shapes. Preserve the unique data additively on akm list (a passthrough shape, so all additive): default marker + top-level defaultBundle, the desired source descriptor (kind/locator/maxPages), registryId, the full lock block (resolvedRevision/integrity/manifestDigest/adapterIds/ installedAt), components, and per-bundle itemCount/byType (one getAllEntries pass grouped by bundleId). Per-bundle item enumeration lands in C2. This also retires the pre-bundle --kind local|managed|remote vocabulary (rename values to the bundle model while touching it).

C2. Replace the <type>: browse grammar with conceptId-prefix browsing

Status: SHIPPED (D4, ruled Q-02). parseRefPrefixQuery now accepts bundle//-qualified and bare conceptId-prefix slash forms; the colon grammar has no code path. See the drift register for the verified-live evidence.

Three confirmed defects in the current grammar: it resurrects the singular type: spelling the release just removed; it validates against placementTypes() so adapter-defined types can never be enumerated; and it matches namePrefix against name-space while every displayed ref is in plural conceptId-space — copying a displayed ref prefix (memories/projecta/) into a query silently degrades to keyword FTS.

Action: replace parseRefPrefixQuery with conceptId-prefix enumeration: akm search "memories/", akm search "memories/projecta/", and bundle-qualified akm search "team//" / "team//skills/". This matches the canonical bundle//conceptId grammar, covers adapter types (their conceptIds are enumerable even when their type strings are foreign), and gives C1 its bundle items replacement (akm search "team//" = all items in bundle team). Also lift the empty-query rejection when --source <bundle> names a configured source, and document named --source in the flag table (today it is prose-only).

C3. Replace akm show <ref> toc|section|lines|frontmatter|full with #fragment

Owner decision. One spec decision is required first, because the verification pass found the grammar is stable-on-paper, rejected-in-practice: STABILITY.md declares [bundle//]conceptId[#fragment] Stable, yet parseRefInput rejects every fragment at every input boundary (resolve-ref.ts:263-269), and the spec defines the fragment as an adapter-owned export selector (spec §11.3, ref.md:24) for the unimplemented Tier-B exports system — not a heading anchor.

Action:

1. Write the spec decision: for markdown-document assets the fragment resolves to a heading (GitHub-style slug match over parseMarkdownToc headings, falling back to case-insensitive raw heading text — today's extractSection semantics). Fragments remain adapter-owned selectors elsewhere; the two uses coexist per the spec's own "adapter-owned and opaque to the core" language, but written down. Amend ref.md, spec §11.3, and STABILITY.md.
2. Implement: drop the fragment rejection on the show path (add fragment to AssetRef or re-parse via parseBundleRef in show); akm show knowledge/guide#authentication renders that section. An unmatched fragment errors with the list of available fragment slugs — this absorbs toc's discovery role.
3. Delete the whole view-mode apparatus: normalizeShowArgv + the process.argv mutation in cli.ts, SHOW_VIEW_MODES, the hidden --akmView/--akmHeading/--akmStart/--akmEnd flags, the KnowledgeView threading, the renderer switch, and the view-only markdown helpers (extractLineRange, extractFrontmatterOnly, formatToc; parseMarkdownToc stays — it has non-view consumers). full is the no-fragment default. lines is dropped (every response carries path; callers can slice the file). frontmatter is dropped; if a raw-YAML projection proves needed it returns later as a --shape value, which STABILITY.md already designates as the projection axis.
4. CHANGELOG migration note (the positional view grammar was a documented Stable spelling; 0.9.x may break it, but it must be called out).

C3b. Remove akm mv

Outcome: NOT ADOPTED. akm mv ships in 0.9.0. The findings below stand — they are what classifies the command Experimental and outside the stability contract, and why the documented rename procedure is a plain filesystem move plus akm index and akm lint. The removal action list and the transaction-kind cleanup it prescribes are not being carried out. See D3 in the decision record. The rest of this section is the review as written.

Reverses this document's earlier "gate it behind experimental.mv" recommendation. A dedicated review recommended removal; every load-bearing claim in it verified against the tree, and the decisive one is that this is a correctness inversion, not a rough edge — an experimental flag would ship silent content corruption to whoever opts in.

Verified findings:

• Its primary integrity promise is inverted. Spec §11.1 names the command directly: "Lint's missing-ref scan and akm mv's inbound-xref rewriting operate only on these anchored [bundle//conceptId] forms; bare short refs in prose are not recognized as refs." buildRewritePatterns (mv-cli.ts:167-186) emits five patterns — three dead type:name spellings and two bare-conceptId spellings — and no bundle// arm at all. It rewrites exactly what the spec says is not a ref, and leaves every real prose ref dangling. The code's own comment asserts the opposite of the spec ("needs no arm here … always emitted SHORT").
• The reserved-file guard the spec requires of it does not exist. ref.md:83-91 says item writes "(placeNew, akm mv, item write-transactions) refuse a reserved-filename target". The validation block (mv-cli.ts:1205-1250) checks cross-type, .md alias, empty name, empty path segments, and the .derived suffix — there is no index.md / log.md check anywhere in the file.
• It bypasses the bundle model: seven hardcoded types (MV_SUPPORTED_TYPES, mv-cli.ts:104), primary writable stash only, paths reconstructed from type/name rather than resolved through the index.
• It can change bundle provenance: the finalizing indexWrittenAssets(stashDir, …) call omits bundleId (mv-cli.ts:1071), so the indexer re-derives identity from the stash path (index-written-assets.ts:101-108).
• Docs and code disagree on failure: cli.md:957-964 promises "the move still succeeds" with warnings; the implementation throws after the irreversible filesystem commit (mv-cli.ts:1064, 1078).
• Cost: 1,452 LOC plus ~2,190 LOC of tests, and two permanent entries in the function-size ratchet (run 294 lines, withAssetMutationLease#arg1 282) — for what its own originating spec called "the highest-effort, lowest-frequency operation".

Action:

1. Delete the command, src/commands/mv-cli.ts, its tests, its hints, and the mv event type.
2. Delete the mv transaction kind and the indexer's hook for it. index-written-assets.ts:78-81 hardcodes recoverTxnsForRoot(stashDir, j => j.kind === "mv") on every write-path index refresh, and requireKind throws on an unregistered kind (fs-txn.ts:122-125). Deleting mv-cli.ts removes the registerTxnKind("mv", …) side effect while leaving the caller — so a single leftover journal would hard-fail every subsequent index refresh. Old journals are being ignored by decision, so: remove the hook, and make recoverTxnsForRoot sweep unknown kinds instead of throwing.
3. Document renames as delete + create: move the file, update intentional refs, akm index, akm lint. The destination gets a fresh identity and fresh learned state. Cross-bundle movement is copy/import + delete, never identity-preserving.
4. Amend spec §11.2, which currently says a rename "MUST use an explicit state-rekey transaction" — that was a product choice made in the same refactor, not an independent constraint (see D3 in the decision record).
5. If real usage later shows that preserving learned state through renames matters, reintroduce a narrow same-bundle akm rename built the right way: resolve through the index, adapter-owned placement, qualified refs only, rewrite only anchored bundle//conceptId forms, one old→new state mapping, and rebuild derived index data rather than preserving row IDs.

C4. Remove akm config enable|disable

A hardcoded alias for one vendor registry (skills.sh), currently listed Stable. Action: remove; the replacement is akm registry add https://skills.sh / akm registry remove skills.sh.

C5. Remove the undocumented akm init --stashDir/--stash-dir aliases

They point at a config key 0.9.0 hard-rejects. Action: delete (stash-cli.ts:73-75).

C6. Move upgrade --skip-checksum off the flag surface

A tab-completable way to disable integrity verification on a self-updating binary. Action: remove the flag; keep the recovery hatch as AKM_UPGRADE_SKIP_CHECKSUM=1, documented as internal.

C7. Split akm add --allow-insecure

One flag authorizes two unrelated risks (plain-HTTP transport; installing bundles whose env keys — LD_PRELOAD, PATH — can hijack execution via akm env run). Action: --allow-insecure-transport and --allow-dangerous-env-keys, each gating only its own check.

C8. Scrub internal tracker IDs and retired-grammar examples from help text

"F-6:" ×8, "(F-3 / #384)", "(F-4 / #385)", "(#485)", "(#22)", "(v1 spec §4.2)" in flag descriptions; skill:akm-dream, memory:projectA/old-note, knowledge:auth-flow, npm:…//script:deploy.sh examples in ~8 help strings that use the removed type:name grammar; the stashDir mentions in init --set-default, setup --dir, config get help. Action: one help-text sweep; goldens update.

C9. Env-var hygiene (the shippable subset of "eliminate test-only vars")

Verified disposition — full elimination is not achievable (SIGKILL crash-recovery tests structurally require a real child process; the deterministic embedder exists for cross-version out-of-process benchmarks), but the surface shrinks a lot:

• Delete now: AKM_DEBUG_LLM (one read, zero setters — fold into AKM_VERBOSE); all mentions of the dead AKM_DISABLE_PROJECT_CONTEXT / AKM_DISABLE_SCOPED_UTILITY (see A1); the stale AKM_ECHARTS comment.
• Replace with DI: AKM_ABLATE_CONTRIBUTORS — the filter is already a pure function; thread an option through RankEntriesOptions and delete the env read (ranking.ts:251). Its claimed eval consumer doesn't use it.
• Compile out of release builds: the three AKM_TEST_MIGRATION_* crash/fault-injection hooks, via bun build --define (the same mechanism as AKM_VERSION) — dev/test builds keep them, shipped binaries physically lack them. (If D1 lands, they leave the core package entirely.)
• Keep but reclassify: AKM_FORCE_SETUP_TMP_STASH is not test-only — the production guard's error message instructs real operators to set it; document as supported. AKM_FORCE_INIT_TMP_STASH is inert in production (its guard only fires under a test runner) and is needed by spawned-CLI tests; keep, documented internal. AKM_EMBED_DETERMINISTIC, AKM_CLAUDE_PROJECTS_DIR, AKM_NODE_ENTRY, AKM_EVENT_SOURCE, AKM_SESSION_ID/AKM_AGENT_HARNESS — internal-documented (H3).
• Fix the stale AKM_PROFILE_<NAME>_API_KEY comment (the real pattern is AKM_ENGINE_<NAME>_API_KEY).

D. Extract — migration machinery out of the core

D1. Move apply/backup/restore into a separately published akm-migrate

Owner direction, and the audit sized it: ~8,820 LOC of production migration code + ~7,130 LOC of tests/fixtures ship inside every binary today, pinned to a one-time 0.8→0.9 cutover, spread across five surfaces (akm migrate, akm backup — which hard-rejects any --for value except the literal 0.9.0 — akm config migrate, the akm-migrate-storage bin, plus startup gates).

Action (target end-state):

• Move to akm-migrate (own repo/package): scripts/akm-migrate/migrate/**, scripts/akm-migrate/config-migrate.ts, scripts/akm-migrate/migration-backup.ts, scripts/migrate-storage.ts + launchers, and the migrate/backup command bodies, re-homed as akm-migrate status|apply|backup|restore. Vendor the frozen legacy ref grammar's four live-core imports so it becomes genuinely frozen.
• Core keeps (~1.6k LOC): the pending-operation journal gate, the migration-ledger inspect/assert + divergent-schema refusal, the config hard-reject, the skew advisory, the vaults guard, akm help migrate (release-notes rendering only), and ~40-line forwarder stubs: akm migrate / akm backup detect state and either spawn akm-migrate from PATH or print the exact npx akm-migrate@<pinned> line. Refusal messages are reworded to name the external tool.
• Version-skew is the main hazard: exact-pin peer dependency plus a generation handshake (the migrate tool refuses a CLI whose migration generation it doesn't match).
• Remove from core now regardless: the akm config migrate alias, and the akm-migrate-storage bin entry from package.json (its npm-only precedent already exists — install.sh never shipped it).
• If the extraction doesn't make 0.9.0: ship 0.9.0 with all five surfaces declared internal, removed at 0.10 in STABILITY.md and the CHANGELOG, so the later removal is a documented plan, not a break. The extraction itself can land in a 0.9.x patch (the series allows it).

E. Improve — gate autonomy, not the feature

Adopting the split model from the autonomy review; the lane audit confirmed its factual basis and added one item it missed. Verified direct-mutation lanes: consolidate (merge writes, archive+hard-delete of secondaries, contradictedBy frontmatter edges), memoryInference (.derived.md children + parent frontmatter rewrites), memory cleanup / belief-state archiving — which runs on any improve run covering memories, not gated by any strategy flag at all (eligibility.ts:500-510), triage applyMode: "promote" (real writeAssetToSource accepts; wired in reflect-distill and proactive-maintenance), extract session indexing (indexSessions default on, direct sessions/** writes), and unattended sync+push (push ?? true, enabled in 8 of 10 strategies). Reflect, distill, extract candidates, validation, and proactiveMaintenance selection are proposal-queued; graphExtraction touches only the regenerable index.

E1. akm improve stays on by default, review-first

Keep the command, the default schedules, and the proposal-generating lanes (reflect, distill, extract, validation, proactiveMaintenance selection, graphExtraction) exactly as they are. No blanket experimental gate.

E2. One autonomy gate for the mutating lanes

Action: a single config opt-in — experimental.improveAutonomy: true (mechanism per F1) — required for: consolidate's merge/delete/contradict operations (its memory→knowledge promotion proposals stay ungated), the memory cleanup + contradiction pre-pass, memoryInference's direct writes, triage applyMode: "promote" (including the judgment tier's accepts), and unattended push (commit stays; push default flips to false — an hourly cron job pushing to a remote is not a defensible default).

Outcome note (D8): the push half was NOT adopted. sync.push keeps its true default and stays outside the gate — it publishes already-committed content to a remote the user configured for that purpose, and it already has sync.push: false and --no-push. The other five lanes are gated as recommended. See D8 in the decision record.

Ship an experimental-autonomous strategy that enables all of it with the existing guardrails (bounded triage ceilings, validators, protected refs, budgets, audit events); reflect-distill and proactive-maintenance keep their promote wiring but refuse to run it without the gate.

Two deliberate scope notes: extract's indexSessions (additive-only sessions/** writes) and distill's salience frontmatter stamp (metadata-only) stay ungated but get documented as direct writes in H1.

E3. Never a silent no-op

A scheduled run that hits a gated lane emits an improve_skipped event with the exact config key to set, surfaces in akm tasks doctor, and raises a health advisory. Existing 0.8-era schedules therefore keep running review-first and tell the operator what changed.

E4. --auto-accept: remove the retired flag

The strict 0.9 runtime does not preserve a dead confidence-gate flag. Scheduled commands must remove it and use the explicit replacement when promotion is desired:

akm improve && akm proposal drain --promote --yes

(defaults: personal-stash policy, 25-accept ceiling), plus the config-only alternative (triage block with applyMode: "promote" — noting it drains the standing backlog, see E5).

E5. Close the same-run promotion gap

Verified: triage runs only as a pre-pass before generation (improve.ts:241-243); with config-only triage, run N's proposals promote at the start of run N+1. The compound command above is currently the only same-slot shape. Action: add an opt-in post-generation drain (triage.postPass: true or akm improve --drain) sharing the same policy, ceilings, and gate — so the documented replacement doesn't need shell && chaining to match 0.8 behavior.

E6. Setup: ask about schedules explicitly; align --yes with interactive

Today interactive setup installs OS scheduler entries (hourly + 4-hourly LLM-calling improve jobs) with only a "server install?" question, while --yes installs none — materially different installs. Action: one explicit question — "Install scheduled maintenance tasks? (review-first; they queue proposals for your review)" — and --yes registers the same review-first task set (autonomous variants additionally require the E2 gate). Upgrades: existing schedules continue review-first with the E3 signposting; customized 0.8 profiles get a documented manual migration.

E7. Declare the tuning config experimental

improve.strategies.*.processes.* (~60 fields, most commented "Default OFF" / "advisory in v1") and index.* (catchall pass names, retired-but- tolerated keys, "accept-any until Chunk 2" fields) are still being designed — the roadmap says so. Action: STABILITY.md declares both key families Experimental (droppable in any 0.9.x/0.10.x release); schema-reject or delete the already-deprecated symmetricValence. The akm improve command surface stays Evolving.

F. Gate — one experimental mechanism for the half-built surfaces

F1. A single experimental.* config namespace

Scattered "EXPERIMENTAL:" help-text labels gate nothing today. Action: one mechanism — experimental.<feature>: true config keys (settable via akm config set). An ungated invocation fails with a structured error naming the exact key (never a silent no-op, per E3). Features:

• experimental.workflowEngine — akm workflow run|brief|report|watch and YAML program creation (workflow create <name>.yaml currently routes users onto the experimental engine from a stable verb; live TODO(R2) markers remain in the engine). Classic markdown workflows and start/next/complete/status/list stay stable and ungated.
• experimental.improveAutonomy — E2.

(akm mv was the third candidate here; C3b recommended removal instead. That recommendation was not adopted — mv ships classified Experimental, with the documented rename procedure routed around it. See D3 in the decision record.)

akm graph needs no gate — it is read-only diagnostics — but gets classified Experimental in H1. health --format html is resolved by B1 (a registered renderer; layout documented as non-contractual).

G. Unify — naming, while breaking is still cheap

• G1. --filter (search) vs --scope (show) are the same multi-tenant narrowing with identical syntax. Pick one spelling (recommend --filter); alias-free.
• G2. --source means "bundle name/path" on graph but stash|registry|both on search/curate. Rename the latter axis to --from stash|registry|both; named-bundle narrowing stays on --source (documented, per C2).
• G3. --target = write destination on write commands (keep), but "bundle to operate on" on tasks (rename to --bundle). Positional targets on workflow/remove are fine (positionals, different axis).
• G4. claude vs claude-code: make the harness id claude canonical everywhere; extract --type accepts both, docs use claude. Fix extract --auto's description ("every available harness" = 2 of 10 registered).
• G5. Help-text spellings --dryRun/--showSimilar → --dry-run/ --show-similar (both parse already; the help is what gets scripted).
• G6. Small polish, one pass: curate --limit default "4" → numeric handling note; hints --detail shadowing the global flag with a different default; bare akm tasks → keep the doctor default but document it.

H. Document — make STABILITY.md whole

• H1. Classify the twelve unlisted top-level commands (health, graph (Experimental), upgrade, registry, migrate/backup (per D1: internal, removal scheduled), lint, extract, hints, completions, init) and every env/secret write verb. Note the two ungated direct writes kept in E2's scope notes.
• H2. Fix stale enumerations: agent backends (10, not 5), improve strategies (10, not 5), the free-form type story (A3), every stashDir and type:name mention (C8).
• H3. ✅ Shipped — STABILITY.md § "Environment variables" now carries a supported/internal-split table. Add the env-var table: supported (AKM_STASH_DIR, AKM_CONFIG_DIR, AKM_DATA_DIR, AKM_CACHE_DIR, api-key vars incl. AKM_ENGINE_<NAME>_API_KEY, AKM_VERBOSE, AKM_DEBUG, AKM_NON_INTERACTIVE, AKM_REGISTRY_URL, AKM_NPM_REGISTRY, AKM_SQLITE_JOURNAL_MODE, AKM_BIN, AKM_FORCE_SETUP_TMP_STASH) vs internal, no compatibility guarantee (AKM_NODE_ENTRY, AKM_EVENT_SOURCE, AKM_SESSION_ID/AKM_AGENT_HARNESS, AKM_EMBED_DETERMINISTIC, AKM_CLAUDE_PROJECTS_DIR, AKM_FORCE_INIT_TMP_STASH, AKM_STATE_DIR, and — until compiled out — AKM_TEST_MIGRATION_*).
• H4. Make the ref-grammar entry truthful: #fragment is consumed by akm show on markdown-document assets (heading slug) and reserved as an adapter-owned selector elsewhere (per C3's spec decision); reconcile the 1.0-freeze line, which currently spells the grammar without the fragment.

Suggested cut line for 0.9.0

1. A1–A3 — defects; A1 especially (there is currently no way to disable the boost).
2. E2 + E3 + E4's warning text — the autonomy gate and the no-silent-no-op rule are the difference between "review-first by default" being true and being marketing. E5/E6 can follow in 0.9.x.
3. C1–C3b — the four structural removals (bundle, browse grammar, show views→fragment, mv). Each gets dramatically more expensive after release; C3 requires its one-paragraph spec decision first, and C3b must land its txn-kind cleanup in the same change or the indexer breaks.
4. B1–B2 — the format contract. If the generic renderers slip, the minimum bar is: uniform UsageError for unimplemented md/html (no silent JSON), and the graph export --format removal.
5. C4–C9 — cheap deletions, all one-way doors after 0.9.x.
6. D1 — extraction can land in a 0.9.x patch, but the declaration (migrate/backup internal, removal scheduled) must ship in 0.9.0's STABILITY.md.
7. G, H — naming unification and the docs pass close the release.