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

package/docs/README.md

@@ -1,104 +1,68 @@
 # Documentation
 
-## Getting Started
+Each subdirectory has its own README indexing everything inside it.
 
-- [Concepts](concepts.md) -- Stashes, registries, asset types, and refs
-- [Getting Started](getting-started.md) -- Quick setup guide
-- [Local Development](local-development.md) -- Dogfooding akm while editing its own source
-- [Agent Install Guide](agents/agent-install.md) -- Step-by-step automated install for agents
-- [Stash Maker's Guide](stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
-- [Wikis](wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
-
-## Configuration & Data
-
-- [Configuration](configuration.md) -- Providers, settings, and Ollama setup
-- [Configuring Agent Profiles](configuration-agent-profiles.md) -- How akm runs a coding agent, CLI or API
-- [Data & Telemetry](data-and-telemetry.md) -- Exactly what akm reads and writes on your machine (no remote telemetry)
-
-## Features
+## [Guides](guides/README.md)
 
-- [Workflows](features/workflows.md) -- Structured, resumable multi-step procedures
-- [Search & Discovery](features/search-discovery.md) -- Finding assets without knowing their exact name
-- [Knowledge Management](features/knowledge-management.md) -- Lessons, incidents, and research as first-class assets
-- [Sources & Registries](features/sources-registries.md) -- Where assets come from and how to find more
-- [Wiki Snapshot Fetchers](features/wiki-snapshot-fetchers.md) -- Pluggable fetchers for URL-based knowledge reads
-- [Agent Integration](features/agent-integration.md) -- Wiring akm into any shell-capable coding agent
-- [The Improvement Loop](features/improvement-loop.md) -- How the stash adapts from usage and feedback
+Task-oriented guides for using akm.
 
-## Upgrading
+- [Getting Started](guides/getting-started.md) -- Quick setup guide
+- [Concepts](guides/concepts.md) -- Bundles, adapters, asset types, and refs
+- [Stash Maker's Guide](guides/stash-makers.md) -- Build and share a stash on GitHub, npm, or a network directory
+- [Wikis](guides/wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
+- [Local Development](guides/local-development.md) -- Dogfooding akm while editing its own source
+- [Claude Code workflows vs. akm workflows](guides/claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
+- Command tours: [search & discovery](guides/search-discovery.md), [sources & registries](guides/sources-registries.md), [knowledge management](guides/knowledge-management.md), [the improvement loop](guides/improvement-loop.md), [agent integration](guides/agent-integration.md)
 
-- [Roadmap](roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
-- [v1 migration guide](migration/v1.md) -- The path from 0.x to v1.0
-- [v0.8 -> v0.9 migration guide](migration/v0.8-to-v0.9.md) -- Current-cycle breaking changes
-- [Release notes (latest: 0.9.0)](migration/release-notes/0.9.0.md) -- Per-release notes; see the [release-notes index](migration/release-notes/README.md) for every version
-- [v0.5 -> v0.6 migration guide](migration/v0.5-to-v0.6.md) -- Every breaking change with before/after code, publisher checklist, and troubleshooting
-
-## Reference
+## [Reference](reference/README.md)
 
-- [CLI](cli.md) -- All `akm` commands and flags
-- [Registry](registry.md) -- Registries, search, hosting, and managing sources
-- [akm-eval](akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
+- [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](reference/wiki-snapshot-fetchers.md) -- The pluggable fetcher API for URL-based knowledge reads
+- [Registry](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](reference/akm-eval.md) -- Standalone toolkit for measuring whether `akm improve` is working
+- [Roadmap](reference/roadmap.md) -- High-level focus for the 0.9 and 1.0 releases
 
-## Agents
+## [Agents](agents/README.md)
 
-- [AGENTS.md](agents/AGENTS.md) -- The system-prompt reference agents load to use akm
+- `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](agents/agent-install.md) -- Step-by-step automated install for agents
 - [Curate Workmap](agents/curate-workmap.md) -- Read before changing `akm curate` ranking or output
 
-## Architecture
-
-- [Architecture](technical/architecture.md) -- How akm's sources, cache, index, and registries fit together
-- [Runtime Boundary Design](architecture/runtime-boundary-design.md) -- Isolating `bun:sqlite`/`Bun.*` from the core
-- [Brain Workflow (diagram)](architecture/brain-workflow.html) -- Visual map of the improve/self-learning loop
+## [Architecture](architecture/README.md)
 
-## Example Stash
+System overview, normative specs, decision history, and subsystem internals.
 
-- [Example Stash](example-stash/README.md) -- A documentation-backed example stash showing how asset types fit together
+- [Architecture](architecture/architecture.md) -- How akm's bundles, cache, index, and registries fit together
+- [Core Principles](architecture/akm-core-principles.md) -- Design principles and constraints
+- [Specs](architecture/README.md#specs-specs) -- Normative specifications (bundle/adapter model, ref grammar, stash conventions)
+- [Internals](architecture/README.md#internals-internals) -- Current-truth subsystem references (storage, search, indexing, improve, health)
+- [Testing](architecture/README.md#testing-testing) -- Testing workflow and pre-release checklist
 
-## Analysis
+## [Migration](migration/README.md)
 
-- [Indexer Vertical Slice Refactor Plan](analysis/indexer-vertical-slice-refactor-plan.md)
-- [Indexer Refactor Review (Expert Options)](analysis/indexer-refactor-expert-options.md)
-
-## Design (unshipped work)
-
-- [Self-Improvement, Self-Learning & Memory Reference Index](design/self-improvement-learning-memory-reference-index.md) -- Master index for every unshipped improve/self-learning/memory design doc, with a subsystem-to-doc status table
-
-Every doc under `docs/design/` must carry a `Status` / `Supersedes` / `Date` header (pre-existing docs are grandfathered until next touched). When a design ships, the shipping PR moves it to `docs/archive/` in the same PR.
-
-## Archive
-
-- [Archive](archive/README.md) -- Design and implementation plans whose work has already shipped, retained as ADR-style records
+- [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
 
-## Internals (technical/)
+## [Posts](posts/README.md)
 
-- [Filesystem](technical/filesystem.md) -- Directory layout plus `.stash.json` deprecation and migration notes
-- [Search](technical/search.md) -- Hybrid search architecture and scoring
-- [Indexing](technical/indexing.md) -- How the search index is built
-- [Classification](technical/classification.md) -- Matcher and renderer behavior
-- [Storage Locations](technical/storage-locations.md) -- Authoritative inventory of every on-disk read/write path
-- [Improve Workflow](technical/improve-workflow.md) -- `akm improve` command surface and pipeline reference
-- [Health Advisories](technical/health-advisories.md) -- `akm health` advisory-to-action map for operators
-- [Fresh-Host Rebuild Runbook](technical/fresh-host-rebuild-runbook.md) -- Rebuild an akm install on a new machine
-- [Ranking Ablation & Saturation Analysis](technical/ranking-ablation-and-saturation-analysis.md) -- Reproducible contributor-ablation measurement and the score-saturation trap
-- [Functional Contract Patterns](technical/functional-contract-patterns.md) -- Quick reference for contributor pipelines and small process contracts
-- [Test Coverage Guide](technical/test-coverage-guide.md) -- High-value testing areas
-- [Testing Workflow](technical/testing-workflow.md) -- End-to-end, Docker, deployment, and upgrade validation
-- [Ref Format](technical/ref.md) -- Wire format for asset references
-- [Core Principles](technical/akm-core-principles.md) -- Design principles and constraints
-- [Claude Code workflows vs. akm workflows](technical/claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
-- [Extending akm workflows into a harness-agnostic orchestration engine](technical/akm-workflows-orchestration-plan.md) -- Current formalized plan, supersedes part of the doc above
+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 add`
+- [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
 
-## Posts
-
-- [Blog posts](posts/) -- Articles and posts about akm
-
 ---
 
-New docs, in five lines: keep one current-truth doc per subsystem, don't fork a second one. Unshipped designs live in `docs/design/` with a mandatory `Status` / `Supersedes` / `Date` header. The PR that ships the design moves its doc to `docs/archive/` in that same PR. Cite code by symbol and memories by search-terms -- not line numbers or exact refs, both rot. Nothing in `docs/` may reference `.plans/` (it's scratch -- promote the content or drop the link); no new improve-analysis docs until the 30-clean-day gate.
+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](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.6.0.md

@@ -90,7 +90,7 @@ vault | wiki | enable | disable | completions | upgrade | save | help |
 hints
 
 Full migration guides:
-- https://github.com/itlackey/akm/blob/main/docs/migration/v1.md (v1
+- https://github.com/itlackey/akm/blob/main/docs/archive/pre-1.0-migration.md (pre-1.0
   architecture refactor — read this first if you are coming from 0.5.x or
   an earlier 0.6 pre-release)
 - https://github.com/itlackey/akm/blob/main/docs/migration/v0.5-to-v0.6.md

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

@@ -13,7 +13,7 @@ grammar continue to match the v1 architecture spec
 pre-releases — the formal freeze itself happens at 1.0 GA.
 
 If you are coming from 0.6.x, the
-[v1 migration guide](../v1.md) covers the per-surface delta and is the
+[archived pre-1.0 migration plan](../../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.
 
@@ -47,16 +47,17 @@ akm proposal reject <id> --reason "…"   # archive with reason
 Multiple proposals for the same `ref` coexist without filesystem
 collisions. Auto-accept is gated per-source via the source config
 (`autoAcceptProposals: true`); the default is off and requires a
-writable source. See v1 spec §11 and `docs/migration/v1.md`.
+writable source. See the archived pre-1.0 migration spec §11 at
+`docs/archive/pre-1.0-migration.md`.
 
 ### `akm reflect`, `akm propose`, `akm distill` — new CLI surfaces (#225, #226, #227)
 
 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,
@@ -141,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 [`docs/migration/v1.md`](../v1.md) for
+  0.6.x baseline should read the [archived pre-1.0 plan](../../archive/pre-1.0-migration.md) for
   the per-surface migration recipe.
 
 ### CLI surface as of 0.7.0
@@ -250,14 +251,14 @@ 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
 
-- [v1 migration guide](../v1.md) — per-surface delta from any 0.6.x
+- [Archived pre-1.0 migration plan](../../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
   registry schema v3.

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

@@ -1,39 +1,183 @@
 Migration notes for akm v0.9.0
 
-This is the final 0.9.0 cut. If you were already running a 0.9.0 beta, the
-main upgrade work is to align scripts, prompts, and stash layout with the
-released command surface.
+These notes apply to the 0.9.0 release candidates and final release. If you
+were already running a 0.9.0 beta, align scripts, prompts, and stash layout
+with the current command surface and verify every durable artifact before
+normal use.
+
+Heads-up: 0.9.x is a refactoring and clean-up release series. Patch
+releases may include breaking changes (each called out in the CHANGELOG with
+a migration note) until the remaining technical debt is paid off; the 0.10.x
+series returns to bug fixes and tuning with breaking changes only in major
+and minor releases. See STABILITY.md for the full policy.
 
 Key operator-facing changes:
 
-- Node.js is supported again for the published CLI. Install with Bun, Node.js
-  >= 20.12, or the prebuilt binary.
+- **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
+  (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`.
+  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.
+- **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 is the generic Markdown baseline.** 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. The `okf` adapter is consumer-only in 0.9.0, so
+  AKM-native write commands reject OKF targets before modifying them.
+- The published npm package requires Node.js >= 22 as its cross-platform
+  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:` for whole `.env` groups and `secret:` for a single sensitive
-  value.
-- `akm-migrate-storage` still ships and still performs the non-destructive
+  Use `env/<name>` for whole `.env` groups and `secrets/<name>` for a single
+  sensitive value.
+- `akm save` is replaced by `akm sync` for writable-stash persistence and
+  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` 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
+  extract is off in `default` and `frequent`, and `proactiveMaintenance` is off
+  in `default` and `reflect-distill`. The dedicated `proactive-maintenance`
+  strategy remains enabled as an explicit opt-in. Presets that omit these
+  fields inherit the `default` off values, while an explicit user
+  `enabled: true` override still wins.
+- 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.
 
 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 "..."`
 
-Recommended post-upgrade checks:
+## Release validation
+
+Release validation passed on 2026-07-31. `bun run release:check` 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,
+2,953 unit tests, 5,061 integration tests, and all seven Docker install targets.
 
-- Run `akm help migrate 0.9.0` on every machine where the CLI is installed.
-- Run `akm-migrate-storage --yes` once if the stash ever used `vaults/`.
-- Rebuild the index with `akm index`.
+Required upgrade checks:
+
+- Before crossing from 0.8 to 0.9, create an independent filesystem backup and
+  prepare a valid 0.9 config. The installed 0.8 binary does not know the 0.9
+  migration protocol: install or stage the 0.9 binary, then run
+  `akm migrate apply --config <prepared-0.9-config>` before any normal command.
+- On an existing 0.9 installation, run `akm migrate status`. If it reports
+  `ready`, run `akm migrate apply`; an already-current active config is used as
+  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-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/`.
+- 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
+  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.
+
+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`, `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