akm-cli 0.9.0-rc.0 → 0.9.0-rc.13

package/CHANGELOG.md

@@ -6,7 +6,1266 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-## [0.9.0] — 2026-06-30
+## [0.9.0-rc.13] - 2026-07-31
+
+### Security
+
+- **`akm update` no longer deletes a previous install directory without
+  confirmation.** When a managed source's resolved content location moves,
+  `update` removed the old directory outright, while `akm remove` had always
+  required `--yes` in non-interactive mode. Only that destructive branch is
+  gated — a normal refresh, where the location does not move, still needs no
+  prompt and no flag, so existing CI invocations are unaffected. Pass
+  `-y`/`--yes` to allow the deletion non-interactively. A cleanup that fails
+  now warns instead of failing silently.
+
+- **The dangerous-env-key install gate now scans `env/` recursively.** It
+  previously read only the top level, so a stash carrying `LD_PRELOAD` in
+  `env/nested/inner.env` installed cleanly with no warning. Files without a
+  `.env` suffix are still not scanned — no akm code path loads them as
+  environment variables.
+
+### Added
+
+- **The `okf` adapter reads OKF v0.2's trust/provenance and lifecycle
+  frontmatter families.** `generated: {by, at}` (with `generated.at` taking
+  precedence over the legacy `timestamp` field, which remains a valid
+  fallback), `verified` (a list, or v0.2's permitted single-mapping
+  shorthand), `sources` (an object list — `resource` required; `id`/`title`/
+  `author`/`usage_count`/`last_modified` optional), `status`
+  (`draft`/`stable`/`deprecated`), and `stale_after` are now parsed leniently
+  from any OKF concept's frontmatter and surfaced on new, namespaced
+  `IndexDocument` fields (`provenance`, `lifecycleStatus`, `staleAfter`,
+  `okfVersion`) that never overload the pre-existing AKM-native `sources`
+  (wiki citation strings), `generation` (consolidation depth), or `quality`
+  fields. As with every other optional OKF field, a missing or malformed
+  value never rejects the document. The `okf` adapter remains consumer-only.
+
+- **Accepting a proposal now stamps OKF v0.2 provenance onto the written
+  asset's frontmatter**, for AKM-native writes only (never through the `okf`
+  adapter, which stays consumer-only and unaffected by this). `promoteProposal`
+  projects the proposal system's own `source`/`sourceRun`/`gateDecision`/
+  `review` bookkeeping — already tracked in `state.db` but previously never
+  written to disk. `generated: {by, at}` and `verified: [{by, at}]` are written
+  **bare at the top level**, exactly as OKF v0.2 spells them, so a third-party
+  OKF v0.2 reader pointed at an AKM stash sees conformant trust metadata;
+  `sources` alone is namespaced as `provenance: {sources}`, because a bare
+  `sources:` collides with the pre-existing wiki citation-string convention.
+  `generated.by` records whether the content came from an automated pipeline
+  (`akm/<version>`) or a human-initiated source (`human:<id>`); `verified`
+  records whether the promotion itself was an automated gate decision or a
+  direct human accept, and accumulates rather than overwriting across
+  re-promotions; `evidenceSources`, when present, projects as
+  `provenance.sources`. AKM's own adapter rereads what it wrote, so `akm show`
+  surfaces it. Every AKM-native markdown type is stamped, `workflow` included.
+
+  Two consequences worth knowing: promotion re-serializes the whole frontmatter
+  block, so YAML **comments** in a hand-written proposal's frontmatter are not
+  preserved (values and body bytes are); and for a human-attributed promotion
+  with no configured actor id, `by` falls back to `human:<OS username>`, which
+  puts that username into content you may later commit and share.
+
+- **Internal: a `capturedAtHead` integrity guard**
+  (`scripts/lint-golden-captured-at-head.ts`, wired into `bun run lint`) now
+  checks every golden fixture's recorded `capturedAtHead` commit SHA — it must
+  exist in the local object database and be reachable from at least one known
+  branch. Post-hoc review of this PR found all four new OKF format-family
+  goldens pointed at a commit that existed locally but was unreachable from
+  any ref (a pre-amend duplicate left behind by an interrupted git operation),
+  which would have 404'd on GitHub and vanished under a local `git gc`; a
+  human fixed that one by hand because nothing caught it. This guard is that
+  catch, going forward. In CI's shallow (`fetch-depth: 1`) checkout, a merely
+  *absent* commit object is inconclusive (indistinguishable from "just not
+  fetched") and only warns; a commit that *exists but is unreachable from any
+  branch* — the actual bug class above — still fails there too, since a
+  shallow clone can tell presence apart from absence just fine.
+
+- **`akm log list --limit <n>`** returns the most recent N events. The flag was
+  documented but silently ignored, and there was no limiting mechanism at all
+  in the read path — the command returned the entire events table regardless of
+  history size. The default remains unlimited.
+
+- **`--track-usage` (default on) on `akm search`, `akm curate`, and `akm show`.**
+  Pass `--no-track-usage` for a read-only lookup that does not feed usage
+  telemetry or the utility-score ranking signal. Previously a bare `akm search`
+  silently wrote a `utility_scores` row that influenced future ranking, with no
+  disclosure and no way to opt out.
+
+- **`akm show` returns the canonical `ref` in every shape.** It was present only
+  under `--shape agent`, so a `--shape summary` consumer had to make a second
+  call at a different shape just to learn which asset it was looking at.
+
+- **`akm info` gained `stashDir`, `defaultBundle`, and `indexStats.byType`.**
+  Answering "which stash is primary" previously required a separate
+  `akm sources list`.
+
+- **`instruction` is a stash-resident asset type.** It was already in
+  `KNOWN_TYPES` and had a presentation entry, but had no placement spec — so
+  there was nowhere to put one and the indexer never recognized one. `akm bundle create`
+  now creates an `instructions/` directory, `.md` files under it index as
+  `instruction`, and `--type instruction` is accepted and tab-completable
+  everywhere `--type` is. A compile-time assertion now pins
+  `placementTypes() ⊆ KnownType`, so the half-registered state this fixes
+  cannot recur silently.
+
+- **Schedule tasks from any configured bundle via `--bundle <bundle>`** (#711).
+  `akm task add`, `run`, `sync`, and `history` accept `--bundle` to
+  operate on a non-default bundle instead of only the primary stash. `add`
+  resolves through the normal writable-target rules; `run --bundle X` resolves
+  the task file and relative asset refs from bundle X. A non-default bundle is
+  recorded in the scheduler entry as `--bundle <bundle>`, so scheduled
+  `akm task run` resolves the right bundle. Scheduler ids stay bare and a
+  collision with another bundle is a hard error rather than a silent clobber.
+
+- **Orphan-GC pass for unresolvable `asset_salience` / `asset_outcome` state
+  rows** (#733). A new improve maintenance pass (`runOrphanStateGcPass`, run
+  next to the existing orphan-proposal purge) stamps `missing_since` on any
+  state row whose ref no longer resolves against `entries.item_ref`, clears
+  the stamp the moment the ref resolves again, and — only when
+  `improve.stateGc.collect` is set to `true` (**default `false`**) — deletes
+  rows whose stamp is older than a fixed 7-day grace window
+  (`STATE_GC_GRACE_MS`). The pass always runs and always reports counts via
+  the new `asset_state_gc` event (`{pending, collected, byTable}`), emitted
+  only when there is something to report, so live data can prove the report
+  clean before `collect` is ever turned on. Additive migration
+  `021-asset-state-missing-since` adds the `missing_since` column to both
+  tables. Deliberately lean by design (Workstream C): no quarantine archive,
+  no circuit breaker, no health-advisory plumbing, no new tables — "ref not
+  present in `entries.item_ref`" is trusted as the authoritative-deletion
+  predicate because the indexer already preserves a source's last-known-good
+  rows when its scan is incomplete, so a temporarily unreachable source never
+  contributes false candidates. `usage_events` is out of scope (already
+  covered by cascade-on-delete plus its own 90-day retention purge).
+
+### Changed
+
+- **The two workflow authoring formats — markdown documents and YAML
+  orchestration programs — are unified into one format**, per
+  `docs/architecture/specs/workflow-format-unification.md`. A workflow is
+  now always a single markdown asset: the standard AKM frontmatter envelope
+  carries the whole orchestration graph (`params`, `steps` with
+  `unit`/`map`/`route`, `inputs`, `output`, `gate`, `defaults`, `budget`),
+  and the body carries each step's instructions under a bare `## <step-id>`
+  heading, joined to the frontmatter by step id. `.yaml`/`.yml` workflow
+  files, the `# Workflow:` / `## Step:` / `Step ID:` markdown headings, and
+  `akm workflow create <name>.yaml` are all gone; `akm workflow create`
+  always writes the one unified template
+  (`src/assets/workflows/workflow-template.md`).
+
+  **Prose is never interpolated.** The YAML program's `${{ … }}` template
+  language, and the markdown format's decorative — and never
+  substituted — `{{ … }}` moustaches, are both removed. Data reaches a
+  dispatched unit as *attached context* instead: the run's params, its
+  item and index for a map unit, and the artifacts its step's new
+  `inputs:` key declares. Instructions refer to that context in plain
+  language ("clone the repository named by the `repo` parameter") rather
+  than splicing a value into the instruction string. Bare reference
+  strings (two roots, `params.<name>` and `steps.<id>.output…`) now appear
+  only in three frontmatter positions: `map.over`, `route.input`, and
+  `inputs:`.
+
+  **Gate rubrics move to the body.** A step's completion criteria are no
+  longer a frontmatter `gate.criteria` list or a `### Completion Criteria`
+  bullet section — they live under a step's `### gate` sub-heading, the
+  format's one reserved marker, as full prose a judge receives byte-exact.
+  Frontmatter `gate:` now carries only optional `max_loops` configuration.
+  Omitted or empty rubric text skips validation; a non-empty rubric enables
+  fail-open validation, and unavailable or malformed judges are skipped.
+
+  This is a **pre-1.0 change to an unshipped, opt-in feature** —
+  `experimental.workflowEngine` has never been enabled by default, and no
+  workflow asset has shipped outside the ten example workflows under
+  `scripts/akm-eval/example-stash/workflows/`, all rewritten to the
+  unified format in this change. There is nothing on disk to migrate and
+  no users to break.
+
+- **akm is described as a knowledge toolkit, not a package manager** (R-048).
+  The npm one-liner, the README lede, and the `concepts.md` opener all led with
+  "a package manager for AI agent capabilities", which misstates the product to
+  its distribution channel and sets package-manager expectations for verbs
+  (`update` / `upgrade` / `sync`) that don't mean what a package manager's do.
+
+- **BREAKING: a command group invoked with no subcommand is now always a usage
+  error, exit 2** (owner ruling 12). The eleven `akm <group>` groups did three
+  different things when invoked bare: `graph`, `config`, `env`, `secret`,
+  `task`, `workflow`, and `proposal` ran an implicit default action and exited
+  0 (bare `akm graph` silently rendered `graph summary`); `registry`, `log`, and
+  `lessons` printed citty's human usage banner to stdout; only `migrate` raised
+  a structured error. All eleven now emit the same
+  `MISSING_REQUIRED_ARGUMENT` envelope on stderr, naming the available
+  subcommands, and exit 2 — matching STABILITY.md's exit-code table (2 =
+  usage) and the exit code already used for unknown commands. Matching exit
+  codes alone was not enough: a script could not parse the failure uniformly
+  while three groups answered on stdout in prose.
+
+  Migration: name the subcommand. `akm graph` → `akm graph summary`,
+  `akm config` → `akm config list`, `akm env` → `akm env list`, `akm secret` →
+  `akm secret list`, `akm task` → `akm task doctor`, `akm workflow` →
+  `akm workflow list --active`, `akm proposal` → `akm proposal list` (which
+  takes the same `--status`/`--queue`/`--ref`/`--type` flags the bare form did).
+
+- **BREAKING: `akm sync` persists `eventType: "sync"`, not the legacy
+  `"save"`.** The event name now matches the command name. Historical
+  `state.db` rows are left as-is — `akm log` and `akm log tail` treat `"save"`
+  and `"sync"` as synonyms on **read**, so `akm log --type save` keeps
+  returning both old and new rows. Only newly written events use `"sync"`.
+
+  Migration: none for `akm log --type save`. A script matching raw event rows
+  by `eventType === "save"` — reading state.db directly, bypassing `akm log` —
+  should also match `"sync"` to see new syncs.
+
+- **BREAKING: dropped the dead `installedKitCount` field from the `add`,
+  `remove`, and `update` JSON envelopes.** It was a raw lockfile-entry count
+  that nothing — internal code or test — ever read.
+
+  Migration: a script parsing `.config.installedKitCount` should stop; the
+  field is gone, not renamed. `config.sourceCount` remains and is unaffected.
+
+- **BREAKING: dropped the dead `graphPath` field from every `akm graph *` JSON
+  envelope** (`summary`, `entities`, `relations`, `export`, `related`, `entity`,
+  `orphans`). It always resolved to the shared state.db path, never a
+  per-graph artifact, and carried nothing `stashPath` did not already provide.
+
+  Migration: a script reading `.graphPath` from any `akm graph` subcommand
+  should stop; `stashPath` remains.
+
+- **BREAKING: `semanticSearchMode` now defaults to `"off"`.** A bare or
+  headless install (`akm init`, `akm setup --yes`, `akm setup --config`) was
+  silently downloading the ~130 MB local embedding model on its first `akm
+  index`, because the fallback used when the key is absent was `"auto"`. The
+  interactive `akm setup` wizard still pre-selects semantic search **on** — a
+  human is present to decide — and now shows the asset/download warning
+  *before* the prompt rather than after, so the pre-checked box is an informed
+  choice. When a remote `embedding.endpoint` is configured, enabling semantic
+  search downloads nothing.
+
+  Migration: existing saved configs are unaffected — the flip only changes the
+  fallback used when the key is absent. To keep semantic search on for a
+  headless or CI install, set `semanticSearchMode: "auto"` explicitly, or point
+  `embedding.endpoint` at a remote embedder.
+
+- **BREAKING: `akm workflow run|brief|report` refuse to run until
+  `experimental.workflowEngine` is set** (0.9.0 decision Q-05). The native
+  workflow executor — including fan-out scheduling and worktree isolation —
+  is experimental, and shipping it enabled by default would have made an
+  unreviewed execution engine reachable from a plain `akm workflow run`. The
+  gated surfaces now exit `78` with a `ConfigError` naming the exact key, and
+  `akm task doctor` reports the gate's state. Authoring and linting the unified
+  markdown format, along with every other `akm workflow` subcommand, remain
+  ungated.
+
+  Migration: `akm config set experimental.workflowEngine true`.
+
+- **BREAKING: the `env:<name>` / `secret:<name>` colon ref spelling is
+  rejected** (0.9.0 decision Q-08). Refs are slash conceptIds only — `env/foo`,
+  `secrets/deploy-key`. The colon form previously resolved as an undocumented
+  alias in some places and fell through as a literal filename in others. It now
+  fails with a usage error naming the slash replacement, rather than silently
+  doing the wrong thing.
+
+  Migration: rewrite `env:<name>` as `env/<name>` and `secret:<name>` as
+  `secrets/<name>`. The error message prints the exact replacement.
+
+- **`akm improve` is review-first by default; autonomy is opt-in** (0.9.0
+  decision D8). The command stays ON — schedules, reflect/distill proposals, and
+  graph extraction are unchanged — but the lanes that mutate assets *without*
+  review now require `akm config set experimental.improveAutonomy true`:
+  memory-inference writes, the memory-cleanup pass, and triage
+  `applyMode: "promote"` (which downgrades to `queue` rather than disabling
+  triage). Consolidation remains review-oriented and is not gated.
+
+  A gated lane is never a silent no-op: it warns on stderr naming the lane and
+  the key, appends an `improve_skipped` event with `reason: "autonomy_gated"`,
+  and is counted in `akm health`'s improve skip-reason summary.
+
+  Migration: set `experimental.improveAutonomy: true` to restore the previous
+  behavior. `sync.push` is **not** affected — it keeps its `true` default and its
+  own `sync.push: false` / `--no-push` controls. Two other direct writes stay
+  ungated by design: `extract`'s additive session indexing and distill's
+  encoding-salience frontmatter stamp. Because the gate is applied before the LLM
+  preflight, a review-first workspace may now need fewer engines configured than
+  before.
+
+  Also: `akm improve` no longer rejects the global `--format`. It emits an
+  envelope through `output()` (always under `--dry-run`, otherwise under
+  `--json-to-stdout`), so `--format` applies to that envelope; progress output
+  stays on stderr. Previously it exited 2 with `INVALID_FLAG_VALUE`, which made
+  it the one command that rejected a valid global flag.
+
+- **`akm health --report` replaces the html-only full report** (D7
+  follow-through). The full health report — per-run rows, trend deltas vs the
+  prior window, and the pending proposal queue — is now a **data** flag, not a
+  side effect of asking for html: `akm health --report --format html` renders
+  the rich report, and the identical dataset comes back under `--format json`
+  (previously that data was reachable only as html). The registered md/html
+  renderers fire on the shape of the result, and `akm health` no longer reads
+  `--format` at all.
+
+  Migration: `akm health --format html` → `akm health --report --format html`
+  (the bare form now renders the plain check generically); the html-only
+  `--compare` flag is removed — use `--window-compare`, which with `--report`
+  defaults to the `--since` window so trend deltas stay like-for-like.
+
+- **Global output flags parse correctly next to positionals.** citty parses
+  each command level against only its own declared args, so a root-declared
+  global flag was unknown at the leaf and its space-separated value fell
+  through as a positional — `akm sync --format json` synced a bundle named
+  "json", and `akm env unset env:x KEY --format json` tried to unset a key
+  named "json". The global output flags (`--format`, `--detail`, `--shape`,
+  `--output`) are now declared on every leaf command so their values are
+  consumed by the parser; the two bespoke argv-inspection workarounds this
+  replaces are deleted. Three more non-exempt commands (`akm health`, `akm
+  index`, `akm lint`) now declare these flags too, purely for `--help`
+  visibility — all three already parsed `--format`/`--detail`/`--shape`/
+  `--output` correctly, since none of them has a positional a stray value
+  could fall into.
+
+- **BREAKING: unknown commands and missing required arguments now exit `2`
+  (usage), not `1`.** citty's own command-dispatch wrapper unconditionally
+  called `process.exit(1)` for any error it raised before a command's own
+  body ever ran — `akm totally-bogus` (unknown command), bare `akm log` /
+  `akm lessons` (a subcommand group invoked with no subcommand), and a
+  command missing a required positional (e.g. bare `akm import`) all exited
+  `1`, contradicting the documented exit-code table (`1` = general error /
+  not found, `2` = usage / bad input). The CLI now drives command dispatch
+  directly instead of going through that wrapper, so it can reclassify this
+  one error family as `2` while leaving `--help`, `--version`, and every
+  other exit code unchanged.
+
+  Migration: a script that treated exit `1` as "something went wrong" for a
+  mistyped command or missing argument should check for `2` instead (or
+  keep treating any non-zero exit as failure, which was already correct).
+
+- **BREAKING: `akm completions --shell <unsupported>` now exits `2` with the
+  standard JSON error envelope, not `1` with a raw stack trace.**
+  `completions` stays format-exempt (its own output is shell-script source,
+  not a result envelope — see STABILITY.md), but its body is now wrapped in
+  the same error-classification path every other command uses.
+
+  Migration: a script parsing this failure should now expect
+  `{"ok":false,"error":"...","code":"INVALID_FLAG_VALUE","hint":...}` on
+  stderr and exit code `2` in place of a stack trace and exit code `1`.
+
+- **BREAKING: `akm index --dry-run` without `--clean` now exits `2` instead
+  of running a real index.** The flag only ever gated the `--clean`
+  stale-entry removal pass — every other phase (walk, LLM enrichment,
+  embeddings, FTS, the adapter-detection config write) ran for real
+  regardless, so `akm index --dry-run` alone silently performed a full index
+  despite its name. The combination is now rejected with the standard usage
+  envelope instead of quietly doing something other than what "dry run"
+  promised.
+
+  Migration: a script or cron invoking bare `akm index --dry-run` was
+  already getting a real index, so nothing there needs to change in effect —
+  but it will now fail loudly instead. Pass `akm index --clean --dry-run` to
+  preview the stale-entry removal pass, or `akm index --clean` to apply it;
+  drop `--dry-run` entirely to keep running a plain real index.
+
+- **BREAKING: a corrupt or unparseable `akm.lock` now makes lockfile WRITES
+  throw, instead of silently destroying every entry.** The previous lenient
+  reader returned `[]` on unparseable JSON; a write path that upserted a
+  single entry onto that `[]` then overwrote the file, permanently deleting
+  every other tracked bundle's lock entry. Install/update/remove write paths
+  now use a strict reader that throws on the same corruption instead of
+  reaching the destructive overwrite.
+
+  Migration: if a write now fails with a lockfile-parse error, `akm.lock` is
+  genuinely corrupt — inspect and repair it by hand, or restore it from a
+  backup (e.g. git history), before retrying the write. Reads elsewhere are
+  unaffected; the lenient read contract is unchanged.
+
+- **BREAKING: `AKM_NPM_REGISTRY` now redirects npm package METADATA lookups,
+  not just the trusted-tarball allowlist.** Previously the override only
+  widened which tarball hosts were trusted for download while metadata
+  queries stayed hardcoded to `registry.npmjs.org`, so a configured private
+  mirror was never actually consulted for package info — the error hint that
+  points users at this variable was false. The override now also replaces
+  the metadata registry base, matching how a private npm registry is meant
+  to work (like npm's own `--registry` flag: wholesale replacement, not a
+  merge with the public registry).
+
+  Migration: an operator who set `AKM_NPM_REGISTRY` expecting only tarball
+  downloads to be redirected, with metadata still served from the public
+  registry, should confirm the mirror actually serves equivalent package
+  metadata — `akm add`/`akm update` for npm-sourced bundles now resolve
+  entirely against the configured mirror when it is set.
+
+- **`akm remember --show-similar` and `akm migrate apply --dry-run` are the
+  documented, canonical spellings** (previously `--showSimilar` /
+  `--dryRun`), matching every other multi-word flag in the CLI. Not a
+  breaking change: citty registers both the camelCase and kebab-case
+  spelling of any declared flag name automatically, so `--showSimilar` /
+  `--dryRun` keep working — they're now explicit, documented aliases instead
+  of an undocumented accident.
+
+- **`--detail` and `--shape` help text is scoped honestly.** The per-command
+  `--detail` description now names `info`, `list`, and `remember` as the
+  commands where it has no effect (verified byte-identical output at every
+  level — `akm show` is not one of these; it has three distinct
+  brief/normal/full payloads). `--shape`'s per-command help now repeats the
+  "`summary` is only valid on `akm show`" caveat the root help already
+  documented.
+
+- **All six `--format` values work on every command** (0.9.0 decision D7).
+  `json|jsonl|yaml|text|md|html` are now universal. Previously there were three
+  inconsistent behaviours: `md` silently emitted the JSON envelope everywhere
+  except `akm health`, `html` was rejected with exit 2 everywhere except
+  `akm health`, and `akm health` reached neither because it intercepted the
+  format itself. Rendering is now registry-driven — a command may register a
+  renderer for a document format, and anything unregistered falls back to a real
+  rendering of its own envelope (headings, tables for arrays of uniform objects,
+  lists otherwise). `akm health` keeps its per-run/window-compare tables and its
+  full HTML report by registering them; the output is unchanged.
+
+  Migration: none required for `json|jsonl|yaml|text`. `--format md` on a
+  non-health command previously returned JSON and now returns Markdown; a script
+  that parsed that JSON should ask for `--format json` explicitly. `--format
+  html` previously exited 2 on non-health commands and now succeeds.
+
+  Also: `akm graph export --format` is **removed** — it declared `--format`
+  locally as well as globally (one token, two parsers). The artifact payload
+  now follows the `--out` extension (`--out g.jsonl` writes JSONL, anything
+  else JSON); the global flag only renders the command's own envelope. A dead
+  local `--format` declaration on `akm history` was removed too (it was never
+  read). Commands
+  whose output is not an envelope (`completions`, `setup`, `env run`,
+  `secret run`, `agent`, `workflow template`, `help migrate`) are declared
+  format-exempt in `src/output/format-exempt.ts` and now warn when given
+  `--format` instead of ignoring it silently. `output.format` in config accepts
+  all six values.
+
+- **Subtree browse is a conceptId prefix, not `<type>:`** (0.9.0 decision D4).
+  `akm search` enumerates on `memories/`, `memories/projecta/`, `bundle//`, and
+  `bundle//skills/`; a trailing `/` is still required. The prefix now matches the
+  **conceptId** rather than the item name, so a ref copied out of search output
+  can be truncated to a prefix and pasted straight back in — previously that
+  round-trip degraded silently into a keyword search. Enumeration no longer
+  validates against the `akm` adapter's placement types, so items from every
+  adapter browse the same way, and `bundle//` lists a whole bundle (the
+  replacement for the removed `akm bundle items`).
+
+  Migration: `akm search "memory:"` → `akm search "memories/"`;
+  `akm search "memory:projectA/"` → `akm search "memories/projectA/"`;
+  `akm search "session:"` → `akm search "sessions/"`. The retired spelling is
+  now an ordinary keyword search; when it returns nothing, the tip names the
+  conceptId spelling that replaces it. `scripts/lint-shipped-assets.ts` no
+  longer exempts the old spelling, so it is an offense in agent-facing assets.
+
+- **`akm task sync [--bundle <bundle>]` reconciles a single bundle.** Sync now
+  attributes each installed scheduler entry to its bundle (parsed from the
+  `--bundle` token; absent ⇒ primary) and reconciles only the entries for the
+  bundle being synced. A plain (primary) sync never installs from, updates, or
+  removes another bundle's entries, and sync never scans all bundles — task
+  activation stays explicit (`add --bundle` or `sync --bundle`), so registering a bundle
+  still never activates code. When the target is the default bundle (or omitted),
+  installed scheduler entries are byte-identical to before, so upgrading shows no
+  spurious drift.
+
+- **The R2 salience ranking boost no longer applies to default `search`/`curate`
+  ranking** (#692). `asset_salience.rank_score` (an encoding + outcome +
+  retrieval projection, recomputed every `improve` run) previously composed
+  into every default search as a bounded multiplicative boost
+  (`salience-ranking`, ×[1.0–1.2]), loaded best-effort from `state.db` on the
+  hot path. On live data it measured as noise (max observed multiplier
+  ×1.071, mean ×1.016): the boost was retrieval-dominated with no source
+  filter — double-counting the same `usage_events` the utility-score
+  contributor already reinforces — warm-started non-zero with no outcome
+  evidence, and had zero pack coverage, so it could only ever favor
+  self-generated personal assets over an equally-relevant pack asset.
+  Removing the default `state.db` load also fixes a confirmed hot-path
+  defect: whenever `state.db` already existed, every default search
+  synchronously waited on the maintenance-activity barrier before ranking
+  could even start — up to a 5-second stall on a blocking wait loop, plus a
+  lock-file create, before the load's own 250ms SQLite `busy_timeout` ever
+  applied. No config gate was added: a key for a term being removed would be
+  dead surface for the upcoming 1.0 contract freeze to carry forever.
+  `rank_score` itself, and everything `improve` computes and does with it
+  internally, are unchanged — only its promotion into user-facing ranking is
+  removed. The contributor stays in the codebase (unwired) for a future
+  gated, outcome-backed experiment.
+
+- **Internal: `asset_salience` / `asset_outcome` state.db access moved behind
+  `src/storage/repositories/{salience,outcome}-repository.ts`** (#672 part 2).
+  Mirrors the existing state.db repository precedents
+  (`proposals-repository.ts`, `improve-runs-repository.ts`,
+  `events-repository.ts`): the raw SQL, row-mapping, and the #644
+  encoding-provenance CASE guards are extracted verbatim, only relocated —
+  `commands/improve/salience.ts` and `outcome-loop.ts` re-export the moved
+  functions, so no importer or test churns. A new `state-table-sql` rule in
+  `scripts/lint-repository-sql.ts` now fails the build if raw
+  `asset_salience`/`asset_outcome` SQL reappears outside the repository
+  directory (or `core/state/migrations.ts`). Not a user-visible behavior
+  change: `rank_score`, `outcome_score`, and everything `improve`/`health`
+  compute from them are identical.
+
+### Fixed
+
+- **The compiled standalone binary can run `akm migrate`.** Release binaries
+  compiled only `src/cli.ts`, and the migrator was resolved as a sibling file
+  and spawned — neither candidate exists inside a compiled executable, so the
+  documented `./akm-0.9 migrate status/apply` upgrade path always failed with
+  `FILE_NOT_FOUND`. Standalone builds now compile `scripts/akm-standalone.ts`,
+  a wrapper that embeds both the CLI and the migrator (src never imports
+  scripts/ — the dist build's tsc forbids it); `akm migrate` re-execs the
+  binary with an `AKM_MIGRATE_ENTRY` marker the wrapper dispatches on. The
+  repo and npm layouts keep the subprocess path.
+
+- **Quarantined migration rows are retained in full, not reduced to a count.**
+  When the 0.8→0.9 cutover met a durable ref it could not map, it recorded
+  surface/ref/count in `legacy_state` and then deleted the rows — destroying
+  proposal payloads, event and task history, fingerprints, and canary anchors,
+  contrary to the migration guide's "quarantined, not dropped". Complete rows
+  are now preserved as JSON in `legacy_state_rows` before leaving the live
+  tables.
+
+- **A failed content migration fails the apply instead of reporting success.**
+  Root discovery, sidecar folding, or the legacy-proposal import throwing was
+  swallowed and logged; the apply then advanced and cleared its journal, and —
+  because 0.9 removed the live `.stash.json` and filesystem-proposal readers —
+  the affected metadata and pending proposals became permanently inaccessible
+  behind an apparently successful upgrade. The step now fails the apply with
+  the journal intact; the committed cutover is untouched and the next apply
+  retries.
+
+- **Sidecar provenance survives the fold.** Folding a `.stash.json` into
+  frontmatter dropped `xrefs` and `sources` entirely and mapped legacy
+  `sourceRefs` to a `source_refs` key that could never fire (the validator
+  stopped copying the field) and that 0.9 never reads — then deleted the only
+  copy. `xrefs`/`sources` now fold through, and legacy `sourceRefs` merge into
+  `xrefs`.
+
+- **A reserved-filename rename re-keys durable state.** The D-R6 rename of a
+  mis-named `index.md`/`log.md` concept ran after the cutover had keyed usage,
+  salience, and proposal rows to the old conceptId, stranding that learned
+  state. The rename now feeds the same re-key engine the cutover uses, with
+  the pairs persisted before re-keying so a crash between the two stays
+  retryable.
+
+- **v1 tasks in a read-only bundle are surfaced with a remedy instead of being
+  silently skipped.** The 0.9 runtime removed the v1 task parser, so silently
+  skipping a `writable: false` bundle left tasks that would start failing after
+  an upgrade that reported current. The preflight now warns per bundle and
+  lists the stranded files in the plan (`readOnlyLegacyTasks`). It does not
+  block the apply: the migration deliberately never rewrites a read-only
+  bundle, and the fix for a lock-materialized git/npm bundle belongs upstream.
+
+- **Lock resolution metadata survives migration.** Merging the migrator's
+  sparse lock entries replaced whole rows by id, discarding
+  `resolvedVersion`/`resolvedRevision`/`integrity`/`installedAt` recorded by a
+  real install. Merge now preserves existing fields the incoming entry does
+  not define.
+
+- **Migrating a pre-0.9 config no longer silently changes source policy.**
+  Three settings were dropped by the config-shape migration: an explicit
+  `writable: false` (an omitted filesystem `writable` reads as `true` in the
+  new shape, so a source the user deliberately protected became writable), an
+  explicit `enabled: false` (resuming refreshes and indexing for content the
+  operator had turned off), and a website source's `maxDepth` (silently
+  resetting crawl depth). All three now round-trip to the runtime source entry;
+  `bundles.<id>.enabled` is a supported key.
+
+- **`akm mv` refuses a bundle marked `writable: false`.** It renamed the file
+  and rewrote citers anyway, because its preflight checked adapter
+  compatibility rather than writability — every other write command already
+  refused.
+
+- **Memory belief edges written by `--supersedes` are no longer ignored.**
+  `writeSupersededEdge` persists a fully-qualified conceptId, but the belief
+  analyzer accepted only the internal `memory:<name>` spelling, so every edge
+  from `akm remember --supersedes` / `akm import --supersedes` was dropped and
+  a superseded memory read back as active.
+
+- **`akm env run <ref> -- <cmd> --help` runs the command.** The builtin
+  help-flag scan read the child tail after `--` and printed akm's own usage
+  instead.
+
+- **`akm mv` works under an `AKM_STASH_DIR` override again.** A valid override
+  not owned by a configured bundle failed with `No configured bundle owns move
+  source`.
+
+- **An unexpected internal error exits 70 with the JSON failure envelope.** The
+  residual dispatch boundary exited 1 with an unstructured message, so
+  automation could not tell an internal defect from an ordinary failure.
+
+- **Concurrent `akm config set` processes no longer give up prematurely.** The
+  contended-lock wait budget was 500ms total, so several concurrent writers on
+  a loaded machine could exhaust it and fail with "Timed out waiting for config
+  lock" against a healthy but busy lock. Abandoned locks are still reclaimed by
+  the stale probe, which this budget does not gate.
+
+- **Config keys named in indexer output and comments now exist.** Four sites
+  pointed at a top-level `llm.*` namespace that the config schema has no such
+  key for — including the user-facing "Increase llm.timeoutMs" warning on an
+  exceeded enrichment budget. The enrichment budget lives at
+  `index.enrichment.timeoutMs` (or `index.defaults.timeoutMs`). Indexing
+  concurrency is auto-derived (2 remote / 1 local) and currently has no config
+  override on that path: `engines.<name>.concurrency` is a valid schema field
+  but the engine resolver does not forward it (documented in
+  `docs/architecture/internals/indexing.md`).
+
+- **The bundle-identity-drift warning stops naming a command that doesn't
+  exist.** It told users to "rekey it atomically via the bundle-rename
+  command"; 0.9.0 ships no such command. It now gives the two remedies that
+  work: restore the previous bundle id in `config.json`, or keep the new id and
+  `akm index --full` to re-mint, accepting the loss of learned state keyed to
+  the old id.
+
+- **The scaffolded `organization.md` convention no longer contradicts `akm
+  mv`.** It told authoring agents "there is no command that preserves an
+  asset's identity or learned state" across a rename and showed a raw `mv`.
+  `akm mv` does exactly that — it rewrites inbound refs and re-keys the index
+  row, usage history, and state.db salience/outcome rows. The convention now
+  points at it, flagged Experimental.
+
+- **`setup.taskSchedules` is no longer documented.** The key was removed from
+  the schema in 0.9.0 (nothing ever read or wrote it), but
+  `docs/reference/configuration.md` still described its two sub-keys.
+
+- **A freshly scaffolded stash passes its own `akm lint`.** All 12 shipped
+  `facts/conventions/**` convention templates carry frontmatter but none
+  carried an `updated` field, so the first `akm lint` after `akm init` flagged
+  12 `missing-updated` issues on files the user never wrote. The templates now
+  ship the field, and a regression test lints a freshly scaffolded stash and
+  requires nothing flagged.
+
+- **`akm show akm//meta` is the documented spelling for the primary stash.**
+  `docs/reference/cli.md` and `docs/guides/concepts.md` showed
+  `akm show local//meta`, which errors with `ASSET_NOT_FOUND` — `local//` is no
+  longer a scoping prefix, so it reads as a bundle named `local`.
+
+- **`akm sync` emits `shape: "sync"`.** The envelope kept the `"save"` shape
+  from the command's pre-rename name even after the persisted `eventType` was
+  renamed. Unlike the event log, the shape is per-invocation and never
+  persisted, so it needs no read-side synonym.
+
+- **`akm add <pkg> --provider npm` adds an npm source instead of a broken
+  filesystem bundle.** `--provider` was only read inside the remote-URL branch,
+  so any non-URL target fell through to the filesystem path with the flag
+  ignored, producing a bundle pointed at `<cwd>/<pkg>`. A URL target with
+  `--provider npm` is now rejected at add time rather than storing the URL as a
+  package spec and failing much later at first sync.
+
+- **`akm add --provider` no longer prints `Installed undefined`.** Two
+  incompatible result shapes reached one text formatter; each is now rendered
+  honestly, including whether a follow-up `akm update` or `akm index` is needed.
+
+- **`akm update --all` accounts for every configured source.** It previously
+  considered only registry-managed installs and reported `nothing to update`
+  for a stash full of plain sources — nothing was updated because nothing was
+  looked at. Plain git and npm sources are now synced (npm is promoted to a
+  lock-backed install on first sync) and website/filesystem sources are
+  reported through a new `skipped` field with the reason. A successful update of
+  a plain source no longer renders as `nothing to update` either.
+
+- **`akm search` with no query browses**, as `--help` has always documented,
+  instead of exiting 2.
+
+- **`akm curate --type <t>` curates within the type instead of bypassing
+  curation.** The filter skipped ranking, intent nudges, the score floor, and
+  family collapse entirely — and could return a hit of the *wrong* type while
+  dropping a higher-scoring correct one.
+
+- **`akm curate` respects `--limit` for registry hits**, which were capped at a
+  hard-coded 2 regardless.
+
+- **`akm search --no-project-context` works.** citty strips a leading `--no-`
+  before consulting declared args, so a flag *declared* as `no-project-context`
+  could never be set — the ranking boost was identical with and without it. The
+  flag users type is unchanged.
+
+- **`akm env run`, `akm secret run`, `akm migrate`, `akm agent`, `akm proposal new`,
+  `akm task run`, and `akm improve` no longer skip cleanup on exit.** They
+  called `process.exit()` directly — in two cases even on success — bypassing
+  teardown of spawned subprocesses. Exit codes, including forwarded non-zero
+  child codes, are unchanged.
+
+- **The `blocked` semantic-search warning names the cause.** It emitted one
+  fixed string for every failure and discarded the status ledger's reason, so
+  "no embedding provider configured" and "the configured endpoint is failing"
+  read identically.
+
+- **Shell completion for `--source` no longer suggests `stash|registry|both`
+  on commands where that enum doesn't apply.** `--source` means a closed
+  `stash|registry|both` enum on `akm search`/`akm curate`, but a free-form
+  stash name/path on every `akm graph` subcommand and a free-form URL/ref/
+  path on `akm remember`. The generated completion script keyed its value
+  list by flag name only, so the search/curate enum leaked onto `akm graph
+  --source <TAB>` and `akm remember --source <TAB>`. Value completion is now
+  scoped per command path; commands without a fixed value set get no
+  suggestion instead of the wrong one.
+
+- **`akm setup --config <file>` / `--from <file>` no longer silently drops
+  six valid config keys** (`index`, `search`, `feedback`,
+  `archiveRetentionDays`, `workflow`, `experimental`). The allowlist was a
+  hand-copied set that had drifted out of sync with the config schema; a
+  user handing setup a config containing any of these keys got a different,
+  silently truncated config written back, with only a warning and exit `0`.
+  The allowlist is now derived from the schema's own key list so it cannot
+  drift again. Keys that remain genuinely retired (`profiles`, `llm`,
+  `agent`, `features`, `stashes`, `bindings`, `writable`) still warn-and-drop
+  as before.
+
+  Note: a config that previously relied on one of these six keys being
+  ignored (because the drop was silent) will now have it applied — re-check
+  `--config`/`--from` inputs if you were unknowingly depending on that gap.
+
+- **`akm index` no longer persists adapter auto-detection to `config.json`
+  with zero disclosure.** Detecting and writing a bundle component's adapter
+  (`bundles.<id>.components.<component>.adapter`) previously happened
+  silently on every index run. It is now reported in the result envelope as
+  an additive `configUpdated.detectedAdapters` map and on stderr, and only
+  when a write actually happened.
+
+- **`akm add owner/repo` now resolves as GitHub shorthand instead of failing
+  with "Local path not found".** Any ref containing a `/` was treated as an
+  explicit local path, so the local-ref resolver threw before the
+  GitHub-shorthand fallback ever ran, making the advertised `owner/repo` form
+  unreachable. A bare two-segment `owner/repo` (or `owner/repo#ref`) now
+  falls through to the registry resolver when no such directory exists on
+  disk; `./`, `../`, absolute, and three-or-more-segment paths still resolve
+  as explicit local paths exactly as before.
+
+- **Internal output-shape command keys renamed `events-list`/`events-tail` →
+  `log-list`/`log-tail`**, matching the `akm log` command they back (the
+  command group used to be `akm events`, removed in 0.9.0). Internal-only:
+  the shape name is a registry lookup key that never reaches the wire (no
+  output field, no schema change), so this is not a user-visible behavior
+  change and carries no `schemaVersion` bump. The documented `[events-tail]`
+  stderr trailer text is deliberately left as-is pending a separate ruling.
+
+### Removed
+
+- **BREAKING: `akm upgrade --skip-checksum` is removed.** STABILITY.md has
+  always said checksum verification is not optional and that the recovery hatch
+  is an environment variable — but the flag shipped anyway, tab-completable,
+  while the documented variable existed nowhere in the source. The code now
+  matches the spec: set `AKM_UPGRADE_SKIP_CHECKSUM=1` if you must bypass a
+  genuinely broken `checksums.txt`. It is deliberately undiscoverable.
+
+- **BREAKING: `akm config enable|disable` is removed.** It was a hard-coded
+  toggle for one target, the skills.sh registry, and the bare `akm enable` /
+  `akm disable` aliases were already removed in 0.9.0. Use
+  `akm registry add|remove`.
+
+- **BREAKING: `akm mv` is removed.** No alias, no stub — `akm mv …` fails with
+  the standard unknown-command error. It claimed to preserve identity across a
+  rename, but its inbound-ref rewrite matched bare conceptIds rather than the
+  anchored `bundle//conceptId` prose form, so it could rewrite ordinary prose
+  while leaving real refs dangling. Renames are delete + create per
+  `STABILITY.md`: move the file, `akm index`, `akm lint`. The one capability
+  nothing else covered — carrying an asset's earned signal across the rename —
+  moves to `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` (maintainer
+  tooling, `--dry-run` supported, idempotent), which re-keys the index
+  `entries` row in place plus the `asset_salience` / `asset_outcome` /
+  `usage_events` rows. The `mv` event type and output shape are gone; the
+  script emits a `rekey` event instead. A leftover `kind:"mv"` transaction
+  journal from an rc build is now swept by the recovery scanner rather than
+  failing it — an unregistered journal kind no longer bricks index refresh or
+  proposal accept/reject.
+
+- **The CHURN alert class is removed from the collapse detector.** Its input was
+  a hard-coded `0` from the 0.9.0 confidence-gate deletion onward, so the alert
+  could never fire. The other three alert classes are unaffected. The
+  `improve_cycle_metrics.accepted_actions` column stays and is written as `0`:
+  it lives in a released migration body, and 0.8 ships `state.db`, so a deployed
+  ledger can already have sealed that body's checksum.
+
+- **`IndexResponse.graphQuality` is removed** from the `akm index` envelope — it
+  was declared but never assigned in any code path, so it was always absent.
+
+- **`akm secret path` and `akm secret remove` are removed.** The two resolved a
+  secret ref through *different* stash-selection logic — `path` through the
+  read-side, all-sources resolver and `remove` through the write-target
+  resolver — so for a ref present in more than one stash they could name
+  different files: you could inspect one secret and delete another. Rather than
+  reconcile the resolvers, both subcommands are gone; `akm secret` now exposes
+  only `list`, `run`, and `set`. Both spellings exit 2 with `Unknown command`.
+
+  Migration: a ref's file lives at `<stash>/secrets/<name>` (run `akm sources
+  list` for stash roots) — locate or delete it directly, or use `akm secret run
+  <ref> <VAR> -- <command>` to consume the value without it touching disk. `akm
+  env path` and `akm env remove` are unaffected.
+
+- Removed the dead `"backup"` output-shape registration left over from the
+  removed `akm backup` command (superseded by `akm-migrate backup`). Already
+  unreachable; no user-visible effect.
+
+- **`akm task list`, `akm task show`, and `akm task remove` are removed** as
+  redundant with the generic asset commands. List and inspect tasks with `akm
+  search` / `akm show <bundle//tasks/id>` (both already cross-bundle); to remove a
+  scheduled task, delete its file in the owning bundle and run `akm task sync`
+  (sync uninstalls the orphaned scheduler entry). Run `akm task doctor` for
+  scheduler diagnostics — bare `akm task` is a usage error, see the canonical
+  bare-group change above.
+
+- **The `akm show <ref> toc|section|lines|frontmatter|full` view-mode grammar is
+  removed** (0.9.0 decision D2). `#fragment` is now the only section selector,
+  and a positional after the ref is a usage error that names it. Migration:
+
+  | Old | New |
+  | --- | --- |
+  | `akm show knowledge/guide section "Auth"` | `akm show knowledge/guide#auth` |
+  | `akm show knowledge/guide full` | `akm show knowledge/guide` |
+  | `akm show knowledge/guide toc` | `akm show knowledge/guide#<unmatched>` — the error lists the available fragment slugs |
+  | `akm show knowledge/guide lines 10 30` | no replacement — every response carries `path`, so slice the file yourself |
+  | `akm show knowledge/guide frontmatter` | no replacement — if a raw-YAML projection proves necessary it returns as a `--shape` value |
+
+  The undocumented `--akmView` / `--akmHeading` / `--akmStart` / `--akmEnd`
+  flags the grammar injected into argv are gone with it.
+
+## [0.9.0] (planned)
+
+0.9.0 is the format-neutral **bundle / adapter** refactor: it replaces the flat
+asset-type registry with per-format adapters, adopts one canonical ref grammar,
+and consolidates the durable databases and config. This section supersedes the
+earlier `0.9.0-rc.1` / `0.9.0-beta.*` development entries below.
+
+### Breaking changes & migration
+
+- **Installed non-akm bundles reclassify on your next `akm index`.** The
+  indexer now dispatches each installed bundle's *detected* adapter (Claude
+  tool dirs, LLM wikis, website snapshots, agent-skills packs, …) instead of
+  recognizing everything with the akm-stash adapter. Entries in such bundles
+  change type and ref spelling to the owning adapter's own scheme the first
+  time you reindex. No action needed — the index is a regenerable cache and
+  rebuilds itself — but searches/saved refs into those bundles may resolve to
+  the new spellings afterwards.
+- **Ref grammar cutover — `type:name` → `[bundle//]conceptId`.** Every ref is
+  now a subdir-qualified concept id inside its bundle (`skills/code-review`,
+  `memories/vpn-note`, `env/prod`), optionally prefixed with a `bundle//`
+  installation slug and suffixed with `#fragment`. Durable state stores the
+  fully-qualified `bundle//conceptId`; the short bundle-omitted form is accepted
+  input only (resolved against `defaultBundle`, then installation-priority
+  order). The pre-0.9.0 `[origin//]type:name` grammar is removed — there is no
+  compatibility parser; the frozen migrator in `scripts/akm-migrate/migrate/`
+  is the only place it survives.
+- **Explicit, journaled, crash-resumable cutover (`akm migrate apply`).** The
+  migrator re-keys all durable state to the new spelling, folds the former
+  `workflow.db` into `state.db` (four databases down to three: `state.db` /
+  `index.db` / a separate `logs.db`), and migrates config from the flat
+  `stashDir` / `sources` / `installed` / `wikiName` keys to `bundles` /
+  `defaultBundle`. A verified, installation-scoped **backup manifest v3**
+  (covering the pre-rescue `index.db`) is taken before any ledger is sealed;
+  expected orphans are quarantined, integrity failures fail closed, and the
+  whole cutover resumes idempotently after a crash. Normal commands refuse an
+  un-migrated or divergent durable schema rather than migrating as a side effect.
+  The retired `stashDir` / `sources` / `installed` keys are **hard-rejected** by
+  the 0.9.0 config schema whenever present (the error names `akm migrate apply`);
+  registry-installed bundles keep only their desired locator (`git`/`npm` +
+  `registryId`) in config, with resolved cache state living exclusively in the
+  lockfile.
+- **`index.md` / `log.md` are reserved structural files.** Per the Open
+  Knowledge Format, `index.md` (directory listing) and `log.md` (update history)
+  are never indexed as concepts and are never valid write / `mv` targets at any
+  bundle depth. Existing stash files with those names are excluded from the
+  index (and renamed by the content migration when they hold a real concept).
+- **`vault` asset type removed.** Use `env` (a whole `.env` group; key names
+  surfaced, values never) and `secret` (a single sensitive value), addressed as
+  `env/<name>` and `secrets/<name>`. `akm-migrate storage` performs the
+  non-destructive `vaults/` → `env/` copy for older stashes.
+- **0.8-era CLI aliases removed.** The flat proposal verbs (`akm proposals`,
+  `akm accept`, `akm reject`, `akm diff`, `akm revert`, `akm show proposal`),
+  `akm save`, top-level `akm enable` / `akm disable`, `akm events`,
+  `--detail summary|agent`, `--for-agent`, `--note`, and `--source` (on
+  accept/reject/history) are gone — use the canonical spellings documented in
+  `STABILITY.md`.
+
+See `docs/migration/v0.8-to-v0.9.md` and
+`docs/migration/release-notes/0.9.0.md` for the full upgrade procedure.
+
+### Added
+
+- **Local downstream value attribution for memory inference and graph
+  extraction.** Private search-hit sidecars now write versioned, source-qualified
+  per-entry `usage_events.metadata` for emitted MI direct/surface value and the
+  active graph contributor's positive applied/capped contribution. Current plain
+  traffic is marked as control, brief/replaced MI surfaces and graph ablations do
+  not claim attribution, and nested curate reads avoid duplicate show rows. The
+  read-only `akm-eval-attribution-rollup` separates user-only exposure,
+  selection/show consumption, current controls, and historical unattributed rows
+  without emitting bodies, query text, or provenance content. Graph contribution
+  is an input attribution signal, not a causal claim that rank changed. No table,
+  migration, dashboard, or health schema was added.
+- **Explicit, crash-resumable 0.9 migration coordination.** `akm migrate
+  status` classifies config, `state.db`, and `workflow.db` independently;
+  `akm migrate apply [--config <prepared>]` creates a verified,
+  installation-scoped backup before sealing ledgers or applying pending
+  migrations. Apply and restore use authenticated phase journals, exact
+  artifact fingerprints, bounded streaming I/O, SQLite integrity checks,
+  active-writer barriers, WAL/SHM-safe publication, and idempotent recovery.
+  Routine reads and current database opens no longer depend on a historical
+  cutover bundle. See `docs/migration/release-notes/0.9.0.md`.
+- **Workflow orchestration engine (experimental).** akm can now execute
+  multi-step workflows through a native engine or any agent session. Workflow
+  assets use the unified markdown format described above; the stable manual
+  CLI contract (`start`/`next`/`complete`/`status`/`list`) and the experimental
+  engine consume the same asset. What ships:
+  - **Authoring.** A workflow is a markdown asset whose frontmatter graph is
+    validated against `schemas/akm-workflow.json` and whose `## <step-id>` body
+    sections carry instructions and gate rubrics. `akm workflow create`
+    scaffolds that format; `akm lint --type workflows` parses and compiles it.
+    Bare references (`params.<name>` and `steps.<id>.output.<path>`) wire
+    `map.over`, `route.input`, and `inputs`; prose is never interpolated.
+  - **Compilation + frozen plans.** `akm workflow start` compiles the workflow
+    into a backend-agnostic Workflow Plan Graph IR (`src/workflows/ir/`) and
+    freezes it on the run row (`plan_json` + `plan_hash`); a run executes the
+    plan compiled at start, and edits to the source file require a new run.
+  - **Per-step orchestration.** A step can declare an engine, model, timeout,
+    fan-out (`map`/`over` with a `concurrency` cap and a `collect` | `vote`
+    reducer), a typed `output` JSON Schema (validated via a `runStructured`
+    retry-with-feedback loop), `env` bindings (resolved through the existing
+    `akm env run` machinery — secret tokens, dangerous-key policy, keys-only
+    audit events), and classify-and-dispatch `route` steps.
+  - **Determinism + replay.** Journaled unit identity is content-derived
+    (`<step>:<sha256(item)[:12]>`, `:solo` for a single unit), so cached
+    results survive item-list reordering; a completed unit whose recorded
+    inputs differ on replan is a hard **replay-divergence** failure naming the
+    unit, never a silent re-dispatch. Every unit is recorded in the new
+    `workflow_run_units` table behind a serialized writer queue.
+  - **Execution (`akm workflow run`).** A semaphore-bounded scheduler fans a
+    step's units out (concurrency defaults to 1 per the local-model
+    LLM-defaults rule and is the minimum of the map request, frozen workflow
+    limit, selected frozen LLM engine limit, and current host safety limit),
+    enforces per-unit
+    timeouts (default 10 m) and run **budget ceilings** (`budget.max_tokens` /
+    `budget.max_units`, seeded from the journal so they span resumes), and
+    advances the run **strictly through `completeWorkflowStep`** so completion
+    gates are never bypassed. Every dispatched unit gets a standard akm
+    preamble (run/unit ids, knowledge + env/secret + reporting contract).
+  - **Typed artifacts + honest gates.** A step's promoted artifact is
+    validated against its declared `output` schema before completion; a
+    criteria-bearing gate judges that **artifact** (canonical JSON, clipped)
+    rather than machine prose, and each engine-driven evaluation is journaled
+    as a gate unit row. `gate.max_loops` bounds an evaluator-optimizer retry
+    loop (feedback threaded into re-dispatched unit prompts). Gates are
+    optional validation: omitted/empty rubrics and unavailable or malformed
+    judges skip validation.
+  - **Failure policy.** Per-unit `on_error: fail | continue` (fail-fast
+    default) plus bounded `retry: { max, on: [<failure_reason>…] }` keyed on
+    the persisted failure taxonomy.
+  - **Isolation + leases.** `isolation: worktree` runs each file-mutating unit
+    in a fresh detached git worktree (journaled path; clean trees
+    auto-removed, dirty ones retained). A run **lease** (`engine_lease_*`)
+    ensures a run is driven by exactly one engine or one external driver at a
+    time; manual `complete` is refused while a live engine lease is held.
+  - **Harness-neutral driver protocol.** An orchestrated run can be driven by
+    ANY agent session (Claude Code, opencode, Codex, a human at a shell), not
+    only the native engine. **`akm workflow brief <run>`** is read-only (takes
+    no lease, mutates nothing) and emits the active step's expected work-list —
+    per-unit content-derived id, resolved instructions + input hash
+    (byte-identical to the engine's dispatch), output schema, env binding
+    NAMES only, and the exact `report` command lines. **`akm workflow report
+    <run> --unit <id> --status completed|failed|running`** is the one mutating
+    verb, ingesting a unit's result through the SAME shared step semantics the
+    engine uses (idempotent same-hash re-report, replay-divergence on a
+    differing hash, budget enforcement, schema validation, and the
+    artifact-judged gate/`max_loops` completion path). `--status running`
+    claims/heartbeats a unit for stale-driver detection without advancing the
+    spine; `--rerun` records a fresh attempt for a failed unit (carrying its
+    prior token total forward). Every report command carries `--expect-step`
+    (refused if the spine has moved since the brief), and `report --settle`
+    (no `--unit`) advances a step that dispatches no reportable units — a
+    params-only route, an empty fan-out, or an all-unresolvable work-list — so
+    a driver is never wedged. The engine and the brief/report surfaces are
+    proven to produce **identical unit graphs**
+    (`tests/workflows/conformance/driver-parity.test.ts`).
+  - **Observability.** `akm workflow watch <run>` tails the run's `workflow_*`
+    / `workflow_unit_*` events as NDJSON (`--stream` foreground-polls to a
+    terminal status, no daemon); `akm workflow status --units` lists per-unit
+    diagnostics (failure reason + result/error text) without feeding them into
+    the deterministic artifact graph; unit lifecycle emits
+    `workflow_unit_started` / `workflow_unit_finished` events carrying
+    ids/status/enums only. `akm show workflow:<name>` summarizes each step's
+    orchestration.
+  - **Harness adapters.** Seven local coding-agent CLIs are first-class
+    dispatch targets — Codex, Copilot CLI, Pi, Gemini, Aider, Amazon Q, and
+    OpenHands — each registered in `HARNESS_REGISTRY` with a command builder +
+    result extractor; agent-identity detection and the session-log provider
+    list are derived from the registry, and harness-native session ids are
+    journaled opportunistically for future session reuse.
+  - **Storage.** Additive `workflow.db` migrations 004–010 (unit journal,
+    harness session ids, frozen plans + run leases, check-in heartbeats,
+    attempt counter, unit claims); migrations 001–003 are untouched and linear
+    workflows behave exactly as before.
+
+  See "Orchestrated steps" and "Driving a run from any agent" in
+  `docs/features/workflows.md`, the redesign addendum in
+  `docs/archive/akm-workflows-orchestration-plan.md`, and `STABILITY.md`
+  (Experimental).
+- **`fable` built-in model alias** — resolves to `claude-fable-5`
+  (`opencode/claude-fable-5` on opencode); recommended resolution target for
+  the `deep` workflow model tier.
+- **`akm lint` now checks the frontmatter xref channels for broken refs.**
+  The existing `missing-ref` check additionally scans the `xrefs:`,
+  `supersededBy:`, and `contradictedBy:` frontmatter keys of non-wiki markdown
+  assets (memories, knowledge, lessons, facts, agents, commands, skills,
+  workflows) — the channels the stash back-linking conventions route
+  provenance and correction links through, and previously the only ref channel
+  with zero checking. Dangling refs are flagged with a detail naming the key
+  (`missing ref: <ref> (frontmatter <key>; resolved to <relPath>)`). The
+  `refs: []` body-scan carve-out does not suppress the new pass; `lint_skip:
+  [missing-ref]` suppresses both; non-ref values (URLs, `raw/<slug>`,
+  `<placeholder>` templates, shell vars) are ignored; refs resolving in a
+  configured extra stash root stay clean. **Note for `--fail-on-flagged` CI
+  users:** stashes with already-dangling xrefs (e.g. from past renames) will
+  gain new `missing-ref` findings on upgrade — fix the refs or add
+  `lint_skip: [missing-ref]` per file. `sources:`, `source_refs:`, and
+  `evidenceSources:` are deliberately not checked (wiki `sources:` is covered
+  by `akm wiki lint`; the latter two legitimately point at merged-away
+  assets).
+- **`--xref <ref>` on `akm remember` and `akm import` — write-time
+  cross-references with validation.** The stash back-linking conventions route
+  provenance and associative links through `xrefs:` frontmatter, but neither
+  CLI write flow could express them (remember always generated its own
+  frontmatter block; import wrote content verbatim). The new repeatable flag
+  records refs in the written asset's `xrefs:` frontmatter list, which the
+  indexer folds into search hints — the new asset becomes findable from
+  searches for its source. `remember` merges the refs into its generated
+  frontmatter (composes with `--tag`/scope flags; does not trigger the
+  tags-required check); `import` dedupe-appends into the document's existing
+  frontmatter, or adds a block when the document has none — never a nested
+  second block. A document whose existing frontmatter is not a parseable YAML
+  mapping aborts the import (exit 2, nothing written) rather than being
+  rewritten lossily; importing it without `--xref` still preserves it
+  verbatim. Every ref is validated before anything is written, against the
+  write target plus all configured sources (read-only cross-stash sources
+  count): an unresolvable ref fails with the standard usage envelope (exit 2)
+  and leaves the stash untouched. The conventions' ~5-xref cap stays soft —
+  exceeding it warns on stderr but still writes. Additionally, a type-root
+  write (no `--path`, flat name) into a stash carrying convention facts now
+  returns an additive `hint` output key pointing at the stash's placement
+  conventions (`facts/conventions/organization` when that fact exists), so CLI
+  writers see the conventions that LLM flows already receive by injection.
+- **`--supersedes <ref>` on `akm remember` and `akm import` — atomic
+  correction + demotion of the superseded asset.** The stash conventions'
+  corrections pattern needs TWO writes (the new correction asset with an xref
+  to what it corrects, plus a metadata edit demoting the old asset), which
+  previously meant hand-editing the old file's frontmatter and remembering to
+  reindex it. The new repeatable flag does both: the correction is written
+  with the old ref folded into its `xrefs:` (correction provenance), and the
+  old asset gains `beliefState: superseded` +
+  `supersededBy: [<new ref>]` via the shared `writeSupersededEdge` primitive
+  (sibling of `writeContradictEdge`) — a metadata-only frontmatter edit that
+  preserves every other key and the body byte-for-byte, sorted-set-appended
+  and idempotent across re-runs. The mutated old file is reindexed by the
+  write path, so `--belief current` hides it and ranking demotes it
+  immediately. An unresolvable ref is input validation: exit 2 with the
+  standard `{ok:false,error,code}` envelope and NOTHING written or demoted
+  (no partial correction); a ref resolving to the asset being written itself
+  (self-supersede via `--force` overwrite) is rejected the same way instead
+  of letting a correction demote itself. An old asset that resolves only
+  outside the write target and the working stash (in a read-only source, or
+  in a writable source that is not this write's target) is not mutated: the
+  correction still writes, stderr warns, and the JSON output reports the
+  additive `superseded: [{ref, applied: false, reason}]` key (`applied: true`
+  on success) — the reason names the `--target` remedy when one exists. An
+  old asset whose existing frontmatter is not parseable YAML is likewise
+  skipped (`applied: false`) rather than rewritten through the lossy lenient
+  parser. On a git write target the demotion is ordered before the
+  batch-at-boundary commit, so the correction and the demoted old asset land
+  in one commit.
+- **Ref-prefix search queries — `akm search "<subdir>/<prefix>/"` now enumerates
+  that subtree.** A query shaped like a ref prefix (trailing slash required:
+  `memories/projectA/`; a bare `memories/` lists the whole type) translates to a
+  typed index enumeration narrowed to entry names under the prefix, instead of
+  degenerating into the AND-token FTS query its sanitized form used to produce
+  (`"memory projectA"` — noise, since `entry_type` is not an FTS column). The
+  listing is recursive and `/`-boundary exact (`projectA/` cannot leak a
+  sibling `projectAlpha/…` scope), matches names case-insensitively (the CLI
+  lowercases queries; on-disk scope directories may carry mixed case), and
+  composes with `--limit`, `--belief`, `--filter`, and named `--source`
+  narrowing exactly like the existing empty-query enumeration — hits carry the
+  fixed browse score `1` in deterministic listing order, not a relevance
+  ranking. The parsed type is explicit intent: a bare `sessions/` enumerates
+  sessions just like `--type session` (the default session exclusion is an
+  untyped-path policy), while an explicit `--type` flag always wins over the
+  type parsed from the query (the branch fires only on untyped searches). A
+  full ref without the trailing slash (`memories/projectA/auth-tip`) stays an
+  ordinary keyword search — resolving a single ref is `akm show`'s job.
+  **Stable-surface note:** `akm search` is Stable; this changes results for a
+  query shape that previously returned noise or nothing. A user literally
+  keyword-searching for the string `memories/x/` loses the old fuzzy token
+  behavior — accepted as negligible.
+- **The `category:` frontmatter key is now captured into the index** as
+  `entry.category` (entry_json only — no schema migration). The key already
+  drives convention-fact prompt injection (`resolveStashStandards`) and the
+  fact linter, but the indexer never captured it, so no category-keyed search
+  or ranking policy was implementable. Captured for all markdown asset types
+  alongside `beliefState` (trimmed; blank/non-string values ignored; no
+  default invented), captured directly onto the index entry. Search results
+  and ranking are unchanged — this is capture
+  only (a unit test pins that `category` never enters the FTS search
+  fields). **Requires a reindex to take effect** for existing entries. The
+  companion rank-time demotion of `category: convention` facts on untyped
+  queries was NOT shipped: the prescribed measurement (full skeleton
+  convention facts plus a real `knowledge/auth` asset, untyped `auth` query,
+  semantic off) shows no crowding — FTS is exact-first, so prefix expansion
+  onto the facts' tokens only happens when nothing matches the query exactly,
+  and a real domain asset always outranks the facts. That invariant is pinned
+  by `tests/search-convention-fact-demotion.test.ts`, which becomes the
+  regression guard if a demotion contributor is ever revisited.
+- **Config-gated indexing of the self-situating body opening —
+  `index.indexBodyOpening` (default `false`).** Body prose is not indexed
+  (the FTS `content` column carries only TOC headings and parameters), which
+  is why the stash conventions route orientation into
+  `description:`/`when_to_use:`. With the new flag enabled, the metadata pass
+  captures the first prose paragraph of each markdown asset body — skipping
+  headings (ATX and setext), fenced code blocks, thematic breaks, and a
+  leading nested frontmatter block (only when its content is actually
+  frontmatter-shaped: prose wrapped in decorative `---` lines is captured,
+  not discarded); capped at 280 chars with word-boundary truncation and a
+  trailing ellipsis — into `entry.bodyOpening`, which folds into the
+  lowest-weight `content` FTS column (bm25 weight 1.0, so a name match always
+  outranks a body-opening-only match) and into the search/embedding text.
+  Secret and env files are never read for it, and session-kind memories
+  (`akm_memory_kind` in outer or nested inner frontmatter) are excluded —
+  their bodies are raw transcripts. Both indexing walks and write-path
+  indexing honor the flag (the metadata pass reads the user config directly).
+  With the flag absent or `false`, entries and search fields stay
+  byte-identical to before. **Costs of toggling (either direction):** indexed
+  text changes, so collapse-detector canary recall baselines shift — re-mint
+  via `akm improve canary --refresh` — and embeddings are NOT regenerated for
+  entries that already have one, while incremental runs re-extract only
+  changed files. Run `akm index --full` after toggling: it re-extracts every
+  entry and wipes embeddings so they rebuild from the new text; until then
+  `akm index` warns that the flag differs from the state the index was built
+  with. The conventions' `description:`/`when_to_use:` orientation routing
+  remains primary — this flag makes body openings additionally pay retrieval
+  rent, it does not replace structured metadata. See `docs/configuration.md`.
+- **`akm mv <ref> <new-name>` — rename with inbound-xref rewrite and
+  utility-history preservation (Experimental).** The stash conventions'
+  forced-rename procedure ("grep and fix inbound xrefs in the same pass") was
+  agent-executable except for the part only the CLI can do: a rename used to
+  mint a new index row, orphaning the `utility_scores` /
+  `utility_scores_scoped` / embeddings / salience rows keyed by entry id —
+  the "rename resets learned ranking" cost the conventions warn about. The
+  new verb does the whole pass: it moves the file (a memory's `.derived.md`
+  twin moves together, keeping the `entry_key + ".derived"` belief-inheritance
+  coupling), rewrites inbound refs across the writable stash's markdown files
+  — body prose, frontmatter ref-list keys (`xrefs:`/`refs:`/`supersededBy:`/
+  …), and fenced code blocks — with complete-ref boundary matching (a longer
+  ref sharing the old ref as a prefix is untouched), and re-keys the index
+  row **in place** so the row id and every id-keyed ranking table survive;
+  the moved row and rewritten citers are FTS-refreshed so search reflects the
+  new name immediately. Scope v1: flat-markdown asset types (`memory`,
+  `knowledge`, `command`, `agent`, `workflow`, `lesson`, `session`, `fact`)
+  in the primary writable stash only, and the source ref must be the
+  canonical spelling — a ref that resolves only through one of lint's
+  fallback resolutions (knowledge-subdir alias, direct-path) is rejected
+  naming the canonical ref, since a fallback-keyed move would strand the
+  index row and dangle canonical citers. Wiki refs, cross-type targets,
+  existing targets, unresolvable refs, type-root escapes, `.derived` twin
+  refs as the source (rename the base — the twin follows), and target names
+  ending in `.derived` (reserved twin suffix) are rejected with the
+  standard envelope (exit 2, nothing moved). Read-only sources are scanned
+  but never written — their citing files are reported in `readOnlyCiters` as
+  manual follow-ups. Output:
+  `{ok, from, to, rewrote: [{file, count}], readOnlyCiters, utilityPreserved}`;
+  a successful move appends an exactly-once `mv` event. A durable mutation
+  journal stages citer rewrites and the asset publication, preserves
+  source-qualified utility/salience history, and resumes index/state
+  finalization after interruption. Divergent citers and late-created targets
+  fail closed instead of being overwritten. Added to the v1 §9.4 command
+  surface as an Experimental-tier additive entry (see `STABILITY.md`).
+
+### Changed
+
+- **Improve-stage extraction and proactive maintenance now ship opt-in.** The
+  built-in `default` and `frequent` strategies resolve extract off, while
+  `default` and `reflect-distill` resolve `proactiveMaintenance` off. The
+  dedicated `proactive-maintenance` strategy remains enabled. Built-ins such as
+  `thorough` that omit these fields inherit the new `default` off values; user
+  overrides are merged last, so explicit `enabled: true` values still win.
+  Standalone extraction remains independent of the improve-stage toggle but
+  still requires `--type <harness>` or `--auto`. The bundled, unselected
+  `core/extract` task now uses `akm extract --auto`; existing scheduled tasks
+  with invalid bare `akm extract` commands must be updated explicitly.
+- **Indexing dispatches each bundle's detected adapter.** The indexer's per-
+  directory scan now resolves the component's adapter (`adapterForId`) and runs
+  THAT adapter's `recognize`, instead of always using the `akm` adapter. A
+  component whose adapter id is unknown is skipped with a warning. Adapter-owned
+  filtering moves the AKM-stash sensitive/infra exclusions (env/secret
+  `.sensitive`-marker skips, the legacy `vaults/` skip, wiki infra files) out of
+  the core scan and into the `akm` adapter's own recognition, so each adapter
+  owns its bundle's filtering. **Reindex note:** any non-`akm` bundle that was
+  previously probed as one adapter id but still recognized by `akm` will
+  re-index under its own adapter on the next `akm index` — the index is a
+  regenerable cache, so no migration is required.
+- **Improve target identity is now end-to-end and source-qualified.** Explicit
+  targets govern reads, generated proposals, triage promotion, consolidation,
+  retrieval signals, cooldowns, and replay state. Duplicate bare refs in other
+  sources no longer affect the selected corpus. Generated lessons and
+  provenance follow stash placement conventions and canonical `xrefs`.
+- **Writable Git boundaries commit only operation-owned paths.** Improve,
+  proposal, supersedes, and direct write flows preserve unrelated staged or
+  dirty work, including files beside generated assets in `content/` layouts.
+
+- **Directory (scope/domain) tokens now always merge into `tags` at index
+  time**, even when an asset sets explicit `tags:` frontmatter. Previously
+  explicit tags suppressed all path-derived tags, so a nested asset like
+  `memories/projectA/auth-tip` with `tags: [auth]` silently lost the exact
+  tag-match ranking boost for its scope token unless the author restated it.
+  The merged tokens come from the canonical ref subpath
+  (`extractDirTagsFromName`), which also fixes the flat-walk indexing path
+  losing directory segments in the empty-tags fallback. Filename tokens are
+  still auto-derived only when `tags` is empty (they already live in the FTS
+  name column and aliases), and the empty-tags fallback itself is unchanged.
+  **Operator notes:** the change takes effect on the next reindex and alters
+  indexed tag text for nested assets with explicit tags, so collapse-detector
+  canary recall baselines may shift — re-mint them with `akm improve canary
+  --refresh`. Embeddings are not regenerated when indexed text changes; the
+  drift here is small (the merged tokens already appear in the name field),
+  but a purge/re-embed picks up the new text exactly.
+- **Demoting belief states now cap an entry's final search score**
+  (superseded ≤ 0.25, contradicted ≤ 0.2, archived ≤ 0.15, deprecated ≤
+  0.28). The existing additive belief penalties are applied inside the
+  multiplicative boost sum on a min-max-normalized FTS base (rank-1 vs rank-2
+  base can differ by up to 0.7), so a superseded incumbent that was the best
+  keyword match stayed clamp-pinned at 1.0 above its own correction — the
+  demotion was invisible exactly when the corrections pattern needs it. The
+  ceiling is applied once at the end of the single scoring pipeline (sort
+  order and displayed scores stay consistent); demoted entries remain listed
+  under the default `--belief all`, keep their relative ordering, and the
+  `--belief` filter axis is unchanged. Semantic-only hits are judged against
+  the `search.minScore` floor by their pre-ceiling score, so a ceiling below
+  the floor (archived 0.15 < default 0.2) ranks the hit last instead of
+  silently dropping it. Ordering changes only for stashes containing
+  belief-flagged assets.
+- **`mutateFrontmatter` (belief-edge writers: supersede/contradict edges,
+  belief refresh) now preserves the body bytes verbatim** when the file
+  already has a frontmatter block, instead of re-normalizing the
+  fence-to-body separator through `assembleAsset`. A metadata edit is no
+  longer a (whitespace-level) content edit; files gaining their first
+  frontmatter block still use the canonical shape.
+
+### Fixed
+
+- **Improve RC stabilization.** Restored one ownership-safe whole-run lock from
+  triage through final sync; `--skip-if-locked` is a true no-op; the run deadline
+  now starts before indexing and reaches index waits, generation, reindexing, and
+  quality judges; reflect judges the sanitized final candidate with bounded
+  changed-region context; write-target selectors no longer replace durable source
+  identity; and vLLM thinking controls cannot be overridden through `extraParams`.
+- **Proposal promotion, reversion, and rejection are durable and recoverable.**
+  Acceptance and reversion persist target ownership and content fingerprints,
+  publish atomically across filesystem layouts, index immediately, commit exact
+  Git paths, and emit idempotent lifecycle events. Crash recovery and legacy
+  accepted proposals fail closed on ambiguous targets instead of clobbering
+  another source.
+- **Engine/setup/health behavior now matches the effective improve plan.**
+  Built-in strategies compose over one baseline, setup preserves independent
+  general and LLM defaults, native OpenCode SDK execution does not require an
+  unused fallback, and health checks each enabled process and credential.
+- **Check-in directives now survive plain-text output and `workflow
+  status`** (check-in review C2/M1): `formatWorkflowNextPlain` and
+  `formatWorkflowStatusPlain` render the `CONTINUE` directive, and every
+  run-detail response (status/start/complete) evaluates the check-in instead
+  of only `workflow next`.
+- Workflow frontmatter validator error message now lists the actually-allowed
+  keys (`name`, `updated` were missing); removed the documented-but-nonexistent
+  `akm workflow step` alias from `docs/features/workflows.md`.
+
+## [0.9.0-rc.1] - 2026-06-30
 
 ### Fixed
 
@@ -145,7 +1404,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   convention, or `.meta/index.md` files. Seeding stays absent-only and never
   overwrites a user-edited file. (#646)
 
-## [0.9.0-beta.36] — 2026-06-22
+## [0.9.0-beta.36] - 2026-06-22
 
 ### Added
 
@@ -180,7 +1439,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - Corrected a prompt/validator drift where the distill system prompt asked for an
   80–200 char description while the gate enforced 20–400. (#645)
 
-## [0.9.0-beta.35] — 2026-06-21
+## [0.9.0-beta.35] - 2026-06-21
 
 ### Fixed
 
@@ -208,7 +1467,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   LLM call per processed session (the session summary); set it to `false` to halve
   per-session extract cost. Unchanged/skipped sessions still cost zero.
 
-## [0.9.0-beta.34] — 2026-06-21
+## [0.9.0-beta.34] - 2026-06-21
 
 ### Fixed
 
@@ -223,7 +1482,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   and falls back to the JSON layout. Verified end-to-end through the plugin's
   `session.idle` hook.
 
-## [0.9.0-beta.33] — 2026-06-21
+## [0.9.0-beta.33] - 2026-06-21
 
 ### Fixed
 
@@ -239,7 +1498,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   already-extracted session with zero LLM calls) and only `--force` re-extracts. This
   makes a session-end hook firing `extract --session-id <id>` precise AND idempotent.
 
-## [0.9.0-beta.32] — 2026-06-21
+## [0.9.0-beta.32] - 2026-06-21
 
 ### Added
 
@@ -265,7 +1524,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   with freshly-read timestamp maps INSIDE the lock (`filterProactiveDue`), dropping
   refs a concurrent run already reflected.
 
-## [0.9.0-beta.31] — 2026-06-20
+## [0.9.0-beta.31] - 2026-06-20
 
 ### Changed
 
@@ -278,7 +1537,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   On the live stash this turns the recombine cluster set from generic 66–171-member
   buckets into tight topical clusters (`auth`, `architecture`, `patterns`, …).
 
-## [0.9.0-beta.30] — 2026-06-20
+## [0.9.0-beta.30] - 2026-06-20
 
 ### Changed / Fixed
 
@@ -297,7 +1556,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   membership-overlap (≥ 0.7) and reuses its stable ref, so the streak accumulates
   through membership drift. First/non-overlapping induction is unchanged.
 
-## [0.9.0-beta.29] — 2026-06-20
+## [0.9.0-beta.29] - 2026-06-20
 
 ### Reverted
 
@@ -305,7 +1564,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
   `akm fact` CLI shipped in beta.28 was reverted pending rework. Phase 1 (#629, the
   `fact` asset type itself) remains in place.
 
-## [0.9.0-beta.27] — 2026-06-20
+## [0.9.0-beta.27] - 2026-06-20
 
 All new behavior is **opt-in / default-preserving** — default runs are byte-identical.
 
@@ -351,7 +1610,7 @@ All new behavior is **opt-in / default-preserving** — default runs are byte-id
   hang/timeout** (the busy-spin can rarely fire even at `--parallel=1`) and never
   on a real test failure, so genuine red tests still fail fast and are never masked.
 
-## [0.9.0-beta.26] — 2026-06-20
+## [0.9.0-beta.26] - 2026-06-20
 
 ### Added
 
@@ -368,7 +1627,7 @@ All new behavior is **opt-in / default-preserving** — default runs are byte-id
   Azure Container Apps). New docs section "Hosting AKM databases on a network share
   (NFS/SMB)" in `docs/configuration.md`.
 
-## [0.9.0-beta.25] — 2026-06-19
+## [0.9.0-beta.25] - 2026-06-19
 
 Completes the recombine / extract-efficiency / graph thread. All new improve
 passes are **opt-in (default off)**, so default behavior is unchanged.
@@ -406,20 +1665,20 @@ passes are **opt-in (default off)**, so default behavior is unchanged.
   sandbox dirs left by force-killed workers — eliminating the tmpfs accumulation
   that caused intermittent `EEXIST: epoll_ctl` test flakes.
 
-## [0.9.0-beta.20] — 2026-06-18
+## [0.9.0-beta.20] - 2026-06-18
 
 ### Fixed
 
 - **`akm update --all` no longer fails for writable `github:` entries stored as `source:"git"`**. `updateRegistryEntry` was using `synced.source` (re-derived from the ref scheme as `"github"`) instead of the existing `entry.source`, causing the config validator to reject `writable:true` on every update cycle.
 
-## [0.9.0-beta.19] — 2026-06-17
+## [0.9.0-beta.19] - 2026-06-17
 
 ### Fixed
 
 - **`akm feedback` now completes in ~0.3s** (was 3+ minutes). Root cause: the command was calling `ensureIndex` with `mode: "blocking"` inside `withIndexWriterLease`, triggering a full reindex on every feedback call. Fix: removed the `ensureIndex` call entirely (feedback only needs the index to exist, not be current — a stale index is fine for ref lookup); removed the application-level writer lock (SQLite WAL + `busy_timeout=30s` handles concurrent access with `akm improve`); added a fast DB-exists guard with a clear error for first-time users.
 - **`akm health --format html` now completes in ~11s** (was ~18s). Root cause: `akmHealth()` was called twice — once for the main result and once to get `deltas`. Fix: merged into a single call passing both `groupBy: "run"` and `windowCompare` together.
 
-## [0.9.0-beta.18] — 2026-06-17
+## [0.9.0-beta.18] - 2026-06-17
 
 ### Changed
 
@@ -871,14 +2130,16 @@ proposal and log storage, `--format html` output, and per-stage LLM telemetry.
 
 ### Added
 
-- **Cross-runtime: akm now runs on Node.js (≥ 20) in addition to Bun** (#560,
+- **Cross-runtime: akm now runs on Node.js >= 22 in addition to Bun** (#560,
   #465). A two-file runtime boundary (`src/storage/database.ts` owns SQLite via
   `bun:sqlite` on Bun / `better-sqlite3` on Node; `src/runtime.ts` owns every
   `Bun.*` API) contains all runtime-specific code, enforced by a lint guard so it
   cannot leak back out. A CI `node-smoke` matrix runs the built CLI under Node
-  20 and 22. **Minimum Node is 20** — the prompts dependency (`@clack/core`) uses
-  `node:util.styleText`, added in Node 20.12; Node 18 is EOL and unsupported.
-  Bun remains the primary/default runtime.
+  20 and 22. The prompts dependency (`@clack/core`) uses `node:util.styleText`,
+  added in Node 20.12; Node 18 is EOL and unsupported. The npm package uses Node
+  as its bootstrap and prefers a working Bun >= 1.0 for execution when both are
+  available. Old, unusable, or absent Bun installations fall back to Node.js;
+  standalone binaries remain runtime-free.
 - **`session` asset type — agent sessions are now searchable** (#561). The
   `extract` pass, after distilling memory proposals from a session, additionally
   writes the session itself as a first-class `session` asset
@@ -1487,7 +2748,7 @@ behind an interactive prompt (or `-y` / `--yes` in non-interactive use).
 
 ### Changed
 
-- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Management** — `akm` stands for Agent Knowledge Management going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
+- **Rebrand**: the full name "Agent Kit Manager" is now **Agent Knowledge Manager** — `akm` stands for Agent Knowledge Manager going forward. The binary name, npm package (`akm-cli`), and all APIs remain unchanged.
 
 - **Config layer rewrite** — single-source-of-truth Zod schema in
   `src/core/config-schema.ts` replaces the per-field parse switch AND
@@ -1675,7 +2936,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 
 ### Migration
 
-- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and [`docs/migration/v1.md`](docs/migration/v1.md) for the canonical per-surface delta from any 0.6.x baseline.
+- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and the [archived pre-1.0 plan](docs/archive/pre-1.0-migration.md) for the historical per-surface delta from any 0.6.x baseline.
 
 ## [0.6.0] - 2026-04-23
 
@@ -1694,7 +2955,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 
 ### Changed (breaking)
 
-- **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/migration/v1.md` for the full guide.
+- **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/archive/pre-1.0-migration.md` for the historical guide.
 - **Config key `stashes[]` renamed to `sources[]`.** Configs with the legacy key load with one deprecation warning and are auto-migrated in memory; the new key is persisted on the next `akm config` write. New configs should use `sources[]`. Configs that contain both keys are rejected with `ConfigError`.
 - **Error hints surface without `--verbose`.** Error classes own their `hint()` text; the regex-on-message hint chain in `cli.ts` is removed. Hints print to stderr inline alongside the error message.
 - **Registry providers loop through a uniform interface.** Context Hub is no longer a special-cased provider type. Add it as a regular git source (`akm add github:andrewyng/context-hub`) or include it as a kit in your registry index. Legacy `type: "context-hub"` entries normalize to `type: "git"` at load time.