akm-cli 0.9.0-rc.8 → 0.9.0

package/dist/workflows/validator.js

@@ -2,49 +2,36 @@
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
 /**
- * Cross-cutting semantic checks over an assembled WorkflowDocument draft.
+ * Cross-cutting semantic checks over an assembled `WorkflowDocument` draft
+ * that need the whole document (not just one frontmatter key) at once.
  *
- * The parser handles per-line shape checks; this module runs rules that need
- * the whole document or the raw frontmatter at once: duplicate step IDs,
- * step-id format, and the frontmatter key whitelist.
+ * Per-key structural checks (unknown keys, id/param-name patterns, timeout
+ * format, retry taxonomy, route target ordering, duplicate ids, gate/body
+ * binding) all live in `parser.ts`, where line-anchored errors are cheapest to
+ * produce. The workflow-only closed frontmatter allowlist that used to live
+ * here (`ALLOWED_FRONTMATTER_KEYS`/`checkFrontmatterKeys`) is GONE —
+ * `schemas/akm-workflow.json` (`additionalProperties: false` over the shared
+ * asset envelope ∪ the workflow keys) is the closed-key authority now; this
+ * module only runs checks the schema cannot express (canonical xref shape,
+ * resource limits).
  */
-import { isBundleSlug } from "../core/asset/asset-ref.js";
-import { conceptIdFromTypeName, parseRefInput } from "../core/asset/resolve-ref.js";
+import { bundleRefToString, parseBundleRef } from "../core/asset/asset-ref.js";
 import { utf8Bytes, WORKFLOW_MAX_INSTRUCTION_BYTES, WORKFLOW_MAX_PARAMS, WORKFLOW_MAX_STEPS } from "./resource-limits.js";
-const STEP_ID_REGEX = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
-const ALLOWED_FRONTMATTER_KEYS = new Set(["description", "tags", "params", "name", "updated", "when_to_use", "xrefs"]);
 export function runSemanticChecks(draft, frontmatterData, frontmatterEndLine, errors) {
-    checkFrontmatterKeys(frontmatterData, frontmatterEndLine, errors);
     checkXrefs(frontmatterData.xrefs, frontmatterEndLine, errors);
-    checkStepIdFormat(draft, errors);
-    checkDuplicateStepIds(draft, errors);
     checkResourceLimits(draft, errors);
 }
 function checkXrefs(value, line, errors) {
     if (value === undefined)
         return;
-    if (!Array.isArray(value)) {
-        errors.push({ line, message: 'Workflow frontmatter "xrefs" must be an array of canonical asset refs.' });
-        return;
-    }
+    if (!Array.isArray(value))
+        return; // shape already flagged by parser.ts's checkXrefs
     for (const ref of value) {
         try {
             if (typeof ref !== "string")
                 throw new Error("non-canonical ref");
-            // Canonicity accepts BOTH grammars during the transition (WI-8.5a flipped
-            // the content writers to the new grammar; existing content still carries
-            // legacy xrefs — the dual-reader arm stays alive until WI-8.5b): the new
-            // bare `conceptId` (or slug-clean `bundle//conceptId`) that lint/mv now
-            // recognize, OR the legacy `[origin//]type:name` round-trip.
-            const p = parseRefInput(ref);
-            const conceptId = conceptIdFromTypeName(p.type, p.name);
-            const newCanonical = p.origin !== undefined && p.origin !== "local" && p.origin !== "stash"
-                ? isBundleSlug(p.origin)
-                    ? `${p.origin}//${conceptId}`
-                    : `${p.origin}//${p.type}:${p.name}`
-                : conceptId;
-            const legacyCanonical = p.origin ? `${p.origin}//${p.type}:${p.name}` : `${p.type}:${p.name}`;
-            if (ref !== newCanonical && ref !== legacyCanonical)
+            const parsed = parseBundleRef(ref);
+            if (parsed.conceptId.includes(":") || ref !== bundleRefToString(parsed))
                 throw new Error("non-canonical ref");
         }
         catch {
@@ -59,49 +46,21 @@ function checkResourceLimits(draft, errors) {
     if (draft.steps.length > WORKFLOW_MAX_STEPS) {
         errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_STEPS} steps.` });
     }
-    if ((draft.parameters?.length ?? 0) > WORKFLOW_MAX_PARAMS) {
+    if (Object.keys(draft.params ?? {}).length > WORKFLOW_MAX_PARAMS) {
         errors.push({ line: 1, message: `Workflow must contain at most ${WORKFLOW_MAX_PARAMS} parameters.` });
     }
     for (const step of draft.steps) {
-        if (utf8Bytes(step.instructions.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
+        if (step.instructions && utf8Bytes(step.instructions.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
             errors.push({
                 line: step.instructions.source.start,
                 message: `Step "${step.id}" instructions exceed the 256 KiB resource limit.`,
             });
         }
-    }
-}
-function checkFrontmatterKeys(data, fmEndLine, errors) {
-    for (const key of Object.keys(data)) {
-        if (ALLOWED_FRONTMATTER_KEYS.has(key))
-            continue;
-        errors.push({
-            line: fmEndLine,
-            message: `Workflow frontmatter "${key}" is not supported. Use only: description, tags, params, name, updated, when_to_use, xrefs.`,
-        });
-    }
-}
-function checkStepIdFormat(draft, errors) {
-    for (const step of draft.steps) {
-        if (STEP_ID_REGEX.test(step.id))
-            continue;
-        errors.push({
-            line: step.source.start,
-            message: `Step ID "${step.id}" is invalid. Use letters, numbers, ".", "_" or "-" (e.g. "deploy-job").`,
-        });
-    }
-}
-function checkDuplicateStepIds(draft, errors) {
-    const firstSeenLine = new Map();
-    for (const step of draft.steps) {
-        const previous = firstSeenLine.get(step.id);
-        if (previous !== undefined) {
+        if (step.gateRubric && utf8Bytes(step.gateRubric.text) > WORKFLOW_MAX_INSTRUCTION_BYTES) {
             errors.push({
-                line: step.source.start,
-                message: `Step ID "${step.id}" is already used on line ${previous}. Step IDs must be unique within a workflow.`,
+                line: step.gateRubric.source.start,
+                message: `Step "${step.id}" gate rubric exceeds the 256 KiB resource limit.`,
             });
-            continue;
         }
-        firstSeenLine.set(step.id, step.source.start);
     }
 }

package/docs/README.md

@@ -0,0 +1,68 @@
+# Documentation
+
+Each subdirectory has its own README indexing everything inside it.
+
+## [Guides](https://github.com/itlackey/akm/blob/main/docs/guides/README.md)
+
+Task-oriented guides for using akm.
+
+- [Getting Started](https://github.com/itlackey/akm/blob/main/docs/guides/getting-started.md) -- Quick setup guide
+- [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) -- Bundles, adapters, asset types, and refs
+- [Stash Maker's Guide](https://github.com/itlackey/akm/blob/main/docs/guides/stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
+- [Wikis](https://github.com/itlackey/akm/blob/main/docs/guides/wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
+- [Local Development](https://github.com/itlackey/akm/blob/main/docs/guides/local-development.md) -- Dogfooding akm while editing its own source
+- [Claude Code workflows vs. akm workflows](https://github.com/itlackey/akm/blob/main/docs/guides/claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
+- Command tours: [search & discovery](https://github.com/itlackey/akm/blob/main/docs/guides/search-discovery.md), [sources & registries](https://github.com/itlackey/akm/blob/main/docs/guides/sources-registries.md), [knowledge management](https://github.com/itlackey/akm/blob/main/docs/guides/knowledge-management.md), [the improvement loop](https://github.com/itlackey/akm/blob/main/docs/guides/improvement-loop.md), [agent integration](https://github.com/itlackey/akm/blob/main/docs/guides/agent-integration.md)
+
+## [Reference](reference/README.md)
+
+- [CLI](reference/cli.md) -- All `akm` commands and flags
+- [Configuration](reference/configuration.md) -- Engines, strategies, bundles, and settings
+- [Workflows](reference/workflows.md) -- Unified Markdown workflow schema, run state, and native orchestration engine
+- [Wiki Snapshot Fetchers](https://github.com/itlackey/akm/blob/main/docs/reference/wiki-snapshot-fetchers.md) -- The pluggable fetcher API for URL-based knowledge reads
+- [Registry](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md) -- Registries, search, hosting, and managing sources
+- [Data & Telemetry](reference/data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
+- [akm-eval](https://github.com/itlackey/akm/blob/main/docs/reference/akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
+- [Roadmap](https://github.com/itlackey/akm/blob/main/docs/reference/roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
+
+## [Agents](https://github.com/itlackey/akm/blob/main/docs/agents/README.md)
+
+- `akm help agents` (short guide by default; `akm help agents --full` for the complete guide) -- The CLI reference agents load to use akm; always the embedded corpus at `src/assets/hints/cli-hints-{full,short}.md`
+- [Agent Install Guide](https://github.com/itlackey/akm/blob/main/docs/agents/agent-install.md) -- Step-by-step automated install for agents
+- [Curate Workmap](https://github.com/itlackey/akm/blob/main/docs/agents/curate-workmap.md) -- Read before changing `akm curate` ranking or output
+
+## [Architecture](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md)
+
+System overview, normative specs, decision history, and subsystem internals.
+
+- [Architecture](https://github.com/itlackey/akm/blob/main/docs/architecture/architecture.md) -- How akm's bundles, cache, index, and registries fit together
+- [Core Principles](https://github.com/itlackey/akm/blob/main/docs/architecture/akm-core-principles.md) -- Design principles and constraints
+- [Specs](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#specs-specs) -- Normative specifications (bundle/adapter model, ref grammar, stash conventions)
+- [Internals](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, search, indexing, improve, health)
+- [Testing](https://github.com/itlackey/akm/blob/main/docs/architecture/README.md#testing-testing) -- Testing workflow and pre-release checklist
+
+## [Migration](migration/README.md)
+
+- [v0.8 -> v0.9 migration guide](migration/v0.8-to-v0.9.md) -- Current-cycle breaking changes
+- [Release notes](migration/release-notes/) -- The short per-release notes `akm help migrate <version>` prints
+
+## [Posts](https://github.com/itlackey/akm/blob/main/docs/posts/README.md)
+
+Source articles for the dev.to publishing pipeline (historical record).
+
+## Official Ecosystem Repositories
+
+- [itlackey/akm-stash](https://github.com/itlackey/akm-stash) -- the official onboarding stash with ready-made assets you can install with `akm bundle add`
+- [itlackey/akm-registry](https://github.com/itlackey/akm-registry) -- the official registry index that powers built-in discovery
+- [itlackey/akm-plugins](https://github.com/itlackey/akm-plugins) -- optional integrations for tools like OpenCode
+- [itlackey/akm-bench](https://github.com/itlackey/akm-bench) -- the standalone benchmark and evaluation repo for akm
+
+---
+
+New docs, in five lines: keep one current-truth doc per subsystem, don't fork a
+second one. Planning, review, and analysis material lives in the untracked
+`.plans/` directory, never under `docs/` -- promote conclusions into the
+current-truth doc or drop them. Normative specs live in
+`docs/architecture/specs/`. Cite code by symbol and memories by search-terms --
+not line numbers or exact refs, both rot. Nothing in `docs/` may reference
+`.plans/`.

package/docs/migration/README.md

@@ -0,0 +1,8 @@
+# Migration
+
+Upgrade guides and per-release migration notes.
+
+- [v0.8 -> v0.9 migration guide](v0.8-to-v0.9.md) -- Current-cycle breaking changes
+- [v0.7 -> v0.8 migration guide](v0.7-to-v0.8.md) -- Task schema and 0.8-era changes
+- [v0.5 -> v0.6 migration guide](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes
+- [Release notes](release-notes/) -- The short per-release notes `akm help migrate <version>` prints (bundled with the npm package)

package/docs/migration/release-notes/0.7.0.md

@@ -8,12 +8,12 @@ landed via PR #275.
 
 The CLI surface, configuration schema, provider interfaces, and ref
 grammar continue to match the v1 architecture spec
-([`docs/technical/v1-architecture-spec.md`](../../technical/v1-architecture-spec.md)).
+([`docs/technical/v1-architecture-spec.md`](https://github.com/itlackey/akm/blob/v0.7.0/docs/technical/v1-architecture-spec.md)).
 0.7.0 commits to maintaining those surfaces through the 0.8.x / 0.9.x
 pre-releases — the formal freeze itself happens at 1.0 GA.
 
 If you are coming from 0.6.x, the
-[archived pre-1.0 migration plan](../../archive/pre-1.0-migration.md) covers the historical per-surface delta and is the
+[archived pre-1.0 migration plan](https://github.com/itlackey/akm/blob/be3a6a632b0cbe7a63ce71b7d093d8ac266e857c/docs/archive/pre-1.0-migration.md) covers the historical per-surface delta and is the
 canonical upgrade reference. This file is the executive summary of
 what's new in 0.7.0.
 
@@ -55,9 +55,9 @@ writable source. See the archived pre-1.0 migration spec §11 at
 Three new commands produce proposals into the queue:
 
 ```sh
-akm reflect [ref] [--task ...]           # reflection proposals
-akm propose <type> <name> --task "..."   # generation proposals
-akm distill <ref>                        # bounded LLM → `lesson` proposal
+akm reflect [ref] [--task ...]           # reflection proposals — doclint:ignore (0.7.0-era, folded into `akm improve` later)
+akm propose <type> <name> --task "..."   # generation proposals — doclint:ignore (0.7.0-era spelling; moved to `akm proposal new` in 0.9.0)
+akm distill <ref>                        # bounded LLM → `lesson` proposal — doclint:ignore (0.7.0-era, folded into `akm improve` later)
 ```
 
 `reflect` and `propose` shell out via the agent CLI (`agent.*` config,
@@ -131,7 +131,7 @@ Bench grows beyond the 0.6.x smoke run into a paired-utility framework:
   workflow that lands in 0.8.
 
 The bench technical reference lives in
-[`docs/technical/benchmark.md`](../../technical/benchmark.md).
+[`docs/technical/benchmark.md`](https://github.com/itlackey/akm/blob/v0.7.0/docs/technical/benchmark.md).
 
 ### Removed legacy fields
 
@@ -142,7 +142,7 @@ The bench technical reference lives in
 - Earlier 0.7.x pre-release work (#220–#223) finalised the registry
   curation surface removal, classification pipeline rewrites, and
   error envelope shape that 0.7.0 ships. Operators upgrading from a
-  0.6.x baseline should read the [archived pre-1.0 plan](../../archive/pre-1.0-migration.md) for
+  0.6.x baseline should read the [archived pre-1.0 plan](https://github.com/itlackey/akm/blob/be3a6a632b0cbe7a63ce71b7d093d8ac266e857c/docs/archive/pre-1.0-migration.md) for
   the per-surface migration recipe.
 
 ### CLI surface as of 0.7.0
@@ -251,17 +251,17 @@ If you want to use the new surfaces:
 akm setup                                  # detects installed agent CLIs;
                                            # persists `agent.default`
 akm config set llm.features.feedback_distillation true
-akm distill memory:my-debugging-notes      # produces a lesson proposal
+akm distill memory:my-debugging-notes      # produces a lesson proposal — doclint:ignore (0.7.0-era command + ref grammar, folded into `akm improve` / bundle refs later)
 akm proposal list
 akm proposal accept <id>
 ```
 
 ## Full migration guides
 
-- [Archived pre-1.0 migration plan](../../archive/pre-1.0-migration.md) — per-surface delta from any 0.6.x
+- [Archived pre-1.0 migration plan](https://github.com/itlackey/akm/blob/be3a6a632b0cbe7a63ce71b7d093d8ac266e857c/docs/archive/pre-1.0-migration.md) — per-surface delta from any 0.6.x
   baseline. The canonical reference for upgrading.
-- [v0.5 → v0.6](../v0.5-to-v0.6.md) — the older terminology cut and
+- [v0.5 → v0.6](https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md) — the older terminology cut and
   registry schema v3.
-- [v1 architecture spec](../../archive/v1-architecture-spec.md) —
+- [v1 architecture spec](https://github.com/itlackey/akm/blob/be3a6a632b0cbe7a63ce71b7d093d8ac266e857c/docs/archive/v1-architecture-spec.md) —
   the architecture contract that 0.7.0 commits to maintain through
   1.0 GA.

package/docs/migration/release-notes/0.9.0.md

@@ -13,28 +13,71 @@ and minor releases. See STABILITY.md for the full policy.
 
 Key operator-facing changes:
 
-- **This release is the format-neutral bundle-adapter refactor.** The flat
-  asset-type registry is replaced by per-format adapters, and refs move from the
-  old `type:name` grammar to `[bundle//]conceptId` — a subdir-qualified concept
-  id such as `skills/code-review`, `memories/vpn-note`, or `env/prod`, with an
-  optional `bundle//` installation prefix and an optional `#fragment`. Durable
-  state is stored fully-qualified; the short bundle-omitted form is input sugar
+- **This release is the format-neutral bundle-adapter refactor — for
+  recognition, indexing, presentation, and validation.** The flat asset-type
+  registry is replaced by per-format adapters that decide what a file *is*
+  (11 adapters behind a static registry), how it is indexed and shown, and
+  how it validates. Refs move from the old `type:name` grammar to
+  `[bundle//]conceptId` — a subdir-qualified concept id such as
+  `skills/code-review`, `memories/vpn-note`, or `env/prod`, with an optional
+  `bundle//` installation prefix and an optional `#fragment`. Durable state
+  is stored fully-qualified; the short bundle-omitted form is input sugar
   (resolved against `defaultBundle`, then installation-priority order).
-  `akm migrate apply` re-keys all durable state, folds the former `workflow.db`
-  into `state.db` (three databases: `state.db` / `index.db` / a separate
-  `logs.db`, down from four), and migrates config from the flat `stashDir` /
-  `sources` / `installed` / `wikiName` keys to `bundles` / `defaultBundle`.
-  `index.md` / `log.md` are reserved structural files — never indexed as
-  concepts and never valid write targets.
+  `akm migrate apply` re-keys all durable state, folds the former
+  `workflow.db` into `state.db` (three tracked databases: `state.db` /
+  `index.db` / a separate `logs.db`, down from four — `logs.db` itself sits
+  outside migration control entirely, see
+  [the migration guide](../v0.8-to-v0.9.md#what-migration-control-does-not-cover)),
+  and migrates config from the flat `stashDir` / `sources` / `installed` /
+  `wikiName` keys to `bundles` / `defaultBundle`. In AKM stashes, `index.md` /
+  `log.md` are reserved structural files — never indexed as items and never
+  valid item-write targets. Other bundle formats use their adapter's own
+  structural-file rules.
+  **What this refactor does not (yet) touch: placement.**
+  `adapter.placeNew()` is defined on the interface
+  (`src/core/adapter/bundle-adapter.ts`) as an optional capability method and
+  already implemented by 8 of the built-in adapters, but nothing in the write
+  path calls it in 0.9.0 — writes still route through AKM's native flat
+  type→directory placement table (`stashDirFor` in
+  `src/core/asset/asset-placement.ts`). That wiring is deferred to 0.10 as
+  its own change (see
+  [STABILITY.md](../../../STABILITY.md#on-the-horizon) and
+  [D12](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010));
+  placement is already correct for every existing bundle today, this only
+  changes which code computes it. `adapter.validate()`, by contrast, is a
+  REQUIRED interface member and each adapter owns its own checks in 0.9.0:
+  `akm lint` dispatches to the bundle's own adapter rather than
+  re-implementing its rules. One caveat worth knowing: the proposal
+  pre-commit path also runs `validate()`, but **advisory only** — it reports
+  findings via a warning and does not reject the write. Making it blocking
+  needs the adapter and legacy ref resolvers reconciled first, so a proposal
+  that trips an adapter diagnostic still applies in 0.9.0.
+  The adapter layer's `index()`/`affectedItems()` capability hooks also have
+  no implementors yet — every 0.9.0 adapter is scanned through the shared
+  core walk. None of this blocks normal use; it means "adapter-driven" in
+  this release now covers reading and validating a bundle, but not yet
+  writing to one.
 - **Installed non-akm bundles reclassify on your next `akm index`.** The
   indexer now dispatches each installed bundle's *detected* adapter instead of
   recognizing everything with the akm-stash adapter. No action needed — the
   index is a regenerable cache — but searches/saved refs into those bundles may
   resolve to new ref spellings afterwards.
+- **OKF and llm-wiki are both consumer/read-only in 0.9.0.** Arbitrary OKF
+  `type` values remain searchable and showable with heading fragments, while
+  the selected adapter decides which types receive specialized behavior.
+  AKM-authored Markdown now emits its native `type` field and remains
+  OKF-compatible; commands, scripts, workflows, tasks, environments, and
+  secrets retain AKM's progressively enhanced native handling. Both the `okf`
+  adapter and the `llm-wiki` adapter are consumer-only in 0.9.0 — AKM-native
+  write commands (`akm remember`, `akm import`, proposal-accept, …) reject
+  OKF **and llm-wiki** targets before modifying them. Author llm-wiki `pages/`
+  content the way the Karpathy pattern always intended: your agent writes the
+  files directly, and akm indexes and serves the result.
 - The published npm package requires Node.js >= 22 as its cross-platform
-  bootstrap. When a working Bun >= 1.0 is also on `PATH`, the launcher prefers
-  Bun after bootstrap; old, unusable, or absent Bun installations fall back to
-  Node.js. The standalone binaries are runtime-free.
+  bootstrap. The `akm` launcher prefers a working Bun >= 1.0 and otherwise
+  falls back to Node.js; `akm-migrate` follows the same model, with Bun optional
+  and preferred.
+  The standalone binaries are runtime-free.
 - The legacy `vault` asset type and `akm vault ...` command family are gone.
   Use `env/<name>` for whole `.env` groups and `secrets/<name>` for a single
   sensitive value.
@@ -42,12 +85,15 @@ Key operator-facing changes:
   pushes, and `akm events` is replaced by `akm log`.
 - The entire `akm wiki ...` command family and the `wiki` asset type are gone.
   The Karpathy-style LLM wiki structure (`schema.md` + `pages/`) is now a
-  first-class **bundle format** recognized directly by `akm index`/`akm
-  search`/`akm lint` — no dedicated verb surface needed.
-- `akm-migrate-storage` still ships and still performs the non-destructive
+  first-class **bundle format** recognized and indexed directly by `akm
+  index`/`akm search`/`akm show` — no dedicated verb surface needed. `akm
+  lint` still runs, now dispatching to the adapter's own wiki-shaped checks
+  through `validate()` (see above); it is a read surface in 0.9.0, not a
+  write target — placement isn't wired to the adapter until 0.10.
+- `akm-migrate storage` performs the non-destructive
   `vaults/` -> `env/` copy for older stashes. Run it before indexing if you are
   upgrading from a stash that still stores `.env` files only under `vaults/`.
-- Proposal workflow is fully consolidated around `akm improve`, `akm propose`,
+- Proposal workflow is fully consolidated around `akm improve`, `akm proposal new`,
   and `akm proposal ...`. Update any old `akm reflect`, `akm distill`,
   `akm accept`, `akm reject`, or `akm proposals` usage.
 - LLM-backed sustaining work is opt-in in the shipped presets: improve-stage
@@ -59,17 +105,83 @@ Key operator-facing changes:
 - Config, `state.db`, and `workflow.db` are now classified independently by the
   explicit `akm migrate` coordinator. Normal commands refuse old, future, or
   divergent durable schemas instead of attempting migration as a side effect.
+- **`akm-migrate` derives the 0.9 config from your 0.8 keys** instead of
+  demanding a hand-authored one: the first `apply` with no `--config` writes a
+  validated starter config under the backup root and stops; a second `apply`
+  performs the cutover. Engine settings are never guessed — they are reported
+  in `droppedKeys` for you to re-add. Fresh 0.8 installs (whose configs carry
+  no `configVersion` key) now classify as `old` instead of being blocked, and
+  `migrate` reports `not-applicable` (exit 0) when there is nothing to migrate.
+- **The experimental `akm workflow brief` / `akm workflow report`
+  external-driver protocol is removed.** `akm workflow run` is the single
+  execution surface. A legacy `experimental.workflowEngine` config key is
+  accepted and ignored; scripts calling `brief`/`report` must move to `run`.
+- **Engine-less installs fall back to `opencode-sdk`** for `workflow run`,
+  prompt tasks, `akm agent`, `propose`, and `improve` reflect — when the
+  `opencode` binary is on PATH, akm synthesizes a config-free engine that
+  resolves provider, model, and auth from opencode's own configuration
+  instead of failing closed with exit 78. The fallback is always announced
+  (result `warnings`, task run log, or stderr). An operator-configured
+  engine always wins.
+- **RSS, Bluesky, and X URLs are recognized by `akm bundle add`** and
+  snapshotted as knowledge assets instead of being crawled as ordinary web
+  pages. X needs `X_BEARER_TOKEN` (or `X_RSS_TEMPLATE`); store it as an akm
+  secret and inject it per-invocation with `akm secret run`. Website crawls
+  now respect `robots.txt` by default (`"respectRobots": false` opts out),
+  have a hard `crawlTimeoutMs` cap, and extract the page's main content —
+  existing website snapshots will get shorter and cleaner on their next
+  refresh.
 
 Primary public command family for 0.9.0:
 
 - `akm improve <ref> [--task "..."]`
-- `akm propose <type> <name> (--task "..." | --file <path>)`
+- `akm proposal new <type> <name> (--task "..." | --file <path>)`
 - `akm proposal list`
 - `akm proposal show <id>`
 - `akm proposal diff <id>`
 - `akm proposal accept <id>`
 - `akm proposal reject <id> --reason "..."`
 
+## Release validation
+
+> Unit/integration test counts below are point-in-time snapshots from the
+> validation passes named next to each figure, not a promise about the count
+> on any later commit — the suite keeps growing after each pass. Run
+> `bun run check` yourself for the current count; do not treat a number below
+> as still accurate.
+
+Release validation was repeated on 2026-07-31. An isolated manual pass covered
+114 first-run, CLI, indexing, search/show, output-format, strict-flag,
+tools-only agent classification, multi-bundle write/lint, workflow, task,
+llm-wiki, env/secret, feedback/log, config/migration, health, upgrade, and
+registry checks with no failures. `bun run release:check`, as run on
+2026-07-31, verified the packed npm installation, Node fallback and Bun
+launcher paths, migration and task execution from published 0.8.14, the Linux
+standalone scheduler artifact, its then-current unit/integration test counts,
+and all seven Docker install targets. The gated semantic-search suite passed
+9 tests; Node 24 passed all 9 fallback smoke steps and 25 compatibility tests.
+
+The post-release checklist audit added a separate 125-check deterministic pass
+for cross-bundle identity, write fidelity, output destinations, lint/task
+behavior, env secrecy, durable log cursors, workflow transitions, proposal
+dry-runs, setup recovery, fresh health initialization, and source-install
+safety. It passed 125/125 on Linux. The branch as of that same pass also
+passed `bun run check` and `bun run build`.
+
+A container-isolated follow-up passed 188 destructive crash/recovery checks,
+including real `SIGKILL` windows across proposal, workflow, and lock journals,
+plus deterministic interruption replay across phase-free migration sentinels.
+The container also passed `release:check --skip-docker`, the seven-image
+Docker install matrix, 9 semantic-search tests, all 9 Node 22 smoke steps, all
+25 Node compatibility tests, and the offline full gate. This pass exposed and
+fixed host-scheduler and co-located Node/Bun assumptions in three tests; no
+production behavior changed.
+
+Live credential-backed agent/LLM calls and native macOS/Windows execution were
+not run from this Linux host. Their deterministic paths remain covered by the
+full unit/integration suite; release artifacts still require their normal
+platform CI/release checks.
+
 Required upgrade checks:
 
 - Before crossing from 0.8 to 0.9, create an independent filesystem backup and
@@ -81,20 +193,89 @@ Required upgrade checks:
   the target.
 - Do not continue when status reports `blocked`. Preserve the reported backup
   run and resolve the named artifact or active-operation error first.
-- Restore is explicit and destructive: `akm backup restore --for 0.9.0 --run
+- Restore is explicit and destructive: `akm-migrate restore --for 0.9.0 --run
   <backup-run-id> --confirm`. It creates and verifies a rescue backup before
   replacing current artifacts.
 - Run `akm help migrate 0.9.0` for the storage and command-surface checklist.
-- Run `akm-migrate-storage --yes` once if the stash ever used `vaults/`.
+- Run `akm-migrate storage --yes` once if the stash ever used `vaults/`.
 - Rebuild derived search data with `akm index` only after migration status is
   `current`; indexing does not migrate config or durable schemas.
 - Review agent instructions and docs for old `vault`, `reflect`, and `distill`
   examples.
 - Review scheduled improve invocations if they relied on inherited extract or
-  proactive-maintenance enablement. Standalone extraction remains available,
-  but every command must select `--type <harness>` or `--auto`; bare
-  `akm extract` is invalid. Update any installed bare extract task to
-  `akm extract --auto` for all-harness discovery. The bundled template remains
-  an unselected opt-in and now uses that valid command.
+  proactive-maintenance enablement. Standalone extraction remains available
+  as `akm proposal extract`, but every invocation must select
+  `--type <harness>` or `--auto`; a bare invocation is invalid. Update any
+  installed extract task to `akm proposal extract --auto` for all-harness
+  discovery. The bundled template remains an unselected opt-in and now uses
+  that valid command.
+
+## 0.9.0 command-surface overhaul (hard break, no aliases)
+
+The 0.9.0 CLI surface was restructured in full. Known retired spellings fail
+with `UNKNOWN_COMMAND` and a replacement hint. Update assets,
+scripts, task YAML, prompts, and agent instructions (CLAUDE.md quick
+references) using this table, then run `akm task sync --rebind` once so
+installed schedules re-emit the new spellings. `akm hints` prints the complete
+agent guide (`--detail brief` selects the compact version), while `akm help
+agents` is short by default; the root `akm --help` groups the surviving surface
+into AGENT LOOP / ASSETS / AUTOMATION / SYSTEM sections, including `migrate`
+under SYSTEM. For migration usage details rather than the bare `--help`
+listing, see [the migration guide](../v0.8-to-v0.9.md).
+
+Command renames and moves:
+
+| Old spelling | 0.9.0 replacement |
+| --- | --- |
+| `akm init` | `akm bundle create` |
+| `akm add <source>` | `akm bundle add <source>` |
+| `akm list` | `akm bundle list` |
+| `akm remove <source>` | `akm bundle remove <source>` |
+| `akm update` | `akm bundle update` (self-update stays `akm upgrade`) |
+| `akm tasks <sub>` | `akm task add\|run\|sync\|doctor\|history` (singular; `list`, `show`, `remove`, `init`, `enable`, and `disable` are removed) |
+| `akm extract` | `akm proposal extract` |
+| `akm propose` | `akm proposal new` |
+| `akm log list` | `akm log` (now a single command) |
+| `akm registry search <q>` | `akm search <q> --from registry` |
+| `akm workflow template` | `akm workflow create --print` |
+| `akm workflow validate` | `akm lint --type workflows` (add `--fail-on-flagged` to keep CI-gate exit semantics) |
+| `akm config show` | `akm config list` |
+
+Removed outright (with the supported replacement procedure):
+
+| Removed | Use instead |
+| --- | --- |
+| `akm history` | `akm log --ref <ref>` |
+| `akm graph` (all subcommands) | counts in `akm health`; refresh via `akm improve --strategy graph-refresh` |
+| `akm lessons coverage` / `strength` | lesson strength is indexed; `akm search --type lesson` |
+| `akm mv` | move the file, then `akm index` + `akm lint`; optional `bun scripts/rekey-asset-ref.ts <old-ref> <new-ref>` (source checkout) carries ranking signal |
+| `akm log tail` | poll `akm log --since @offset:<id>` (durable cursor) |
+| `akm workflow watch` | `akm log --run <run-id>` |
+| `akm env set` / `env unset` | edit the `.env` file directly; akm loads it as-is |
+| `akm config validate` | config is validated on every load |
+| `akm task enable` / `disable` | edit `enabled:` in the task YAML, then `akm task sync` |
+| `akm task init` | `akm setup` seeds the default schedules |
+| `akm improve canary` | `bun scripts/refresh-canary-set.ts [--refresh]` (from a source checkout — helper scripts are not shipped in the npm package) |
+| `akm registry build-index` | `bun scripts/build-registry-index.ts` (maintainer tooling) |
+| `akm index --background` | removed (the flag never backgrounded; use `--quiet`) |
+| `akm setup --detect-only` / `--reset-recommended` | removed; environment detection runs inside `akm setup`, and `akm info` reports the *configured* capabilities |
+| `extract --watch` / `--debounce-ms` | schedule `akm proposal extract --auto` as a task |
+
+Flag and value renames:
+
+| Old | New |
+| --- | --- |
+| `search`/`curate` `--source stash\|registry\|both` | `--from local\|registry\|all` |
+| `remember`/`clone`/`improve`/the `task` group `--target <bundle>` | `--bundle <bundle>` (`import`, `proposal accept`, `env create`, `env remove`, `secret set` keep `--target`) |
+
+Environment and JSON-payload renames ("stash" is retired; the noun is
+"bundle" everywhere):
+
+| Old | New |
+| --- | --- |
+| `AKM_STASH_DIR` | `AKM_BUNDLE_DIR` |
+| `akm info` field `stashDir` | `bundleDir` |
+| `akm config path --all` key `stash` | `bundle` |
+| `bundle create` result `defaultStashUpdated` / `previousStashDir` | `defaultBundleUpdated` / `previousBundleDir` |
 
 Full changelog: https://github.com/itlackey/akm/blob/main/CHANGELOG.md