akm-cli 0.9.30 → 0.10.261001-beta

package/docs/maintainers/local-development.md

@@ -0,0 +1,108 @@
+# Local Development
+
+Use an explicit launcher for each kind of contributor check. This keeps live
+source, build output, packed-package behavior, and the machine-wide `akm`
+installation from being mistaken for one another.
+
+The npm package requires Node.js >= 22 and npm. A working Bun >= 1.0 is optional
+for the installed launcher and remains the repository's primary development and
+test runtime. The standalone binaries are runtime-free.
+
+## Live Source
+
+Run the working tree directly for the normal edit-test loop:
+
+```bash
+bun src/cli.ts search "deploy"
+bun src/cli.ts task doctor
+```
+
+This executes current uncommitted source. Tests that spawn the CLI should use
+the same explicit `bun src/cli.ts` form with the repository as their working
+directory rather than resolving `akm` from `PATH`.
+
+## Built Launcher
+
+Build first, then invoke the package launcher from `dist/`:
+
+```bash
+bun run build
+node dist/akm search "deploy"
+node dist/akm task doctor
+```
+
+This checks generated imports, copied assets, and launcher behavior while still
+keeping the invocation tied to this checkout. `node dist/akm` is portable across
+Windows, macOS, and Linux; on POSIX systems the executable `./dist/akm` form is
+also available.
+
+## Isolated Package Acceptance
+
+Run the repository's package acceptance command. It builds and packs the package,
+installs it under an isolated temporary prefix, and exercises that installed
+launcher without replacing the machine's global `akm`:
+
+```bash
+bun run test:package
+```
+
+The command builds, packs, installs under a temporary npm prefix, and checks the
+installed launchers. It does not run setup or test application-state isolation.
+
+## Intentional Global Checkout Install
+
+Only install the checkout globally when you deliberately want the machine-wide
+`akm` command to resolve to this checkout's package:
+
+```bash
+bun run build:install
+command -v akm
+akm --version
+```
+
+This replaces the globally resolved package and can affect agents, shells, and
+scheduled tasks that invoke `akm`. Re-run `akm task sync --rebind` only when you
+intend existing scheduler entries to capture the new installed runtime, then
+verify with `akm task doctor`.
+
+## Transitional Machine-Local Wrapper
+
+Some development machines still have a historical machine-local wrapper. Leave
+that file untouched, but treat it as transitional: do not document wrapper
+modes, depend on it in tests, or use it to choose between source and package
+behavior. Invoke `bun src/cli.ts`, `node dist/akm`, or `bun run test:package`
+explicitly instead.
+
+## Inspecting a Live Database
+
+`state.db`, `logs.db`, and `index.db` are WAL-mode SQLite databases that akm
+(or a scheduled task) may be writing at any moment. Open a live one only with
+`sqlite3 -readonly`:
+
+```bash
+sqlite3 -readonly ~/.local/share/akm/state.db "PRAGMA integrity_check;"
+sqlite3 -readonly ~/.local/share/akm/state.db ".backup /tmp/state-snapshot.db"
+```
+
+Do not open a live akm database with a plain (read-write) `sqlite3`
+connection, even just to run `.backup`. Through 0.9.17 an akm process could
+silently lose its SQLite file locks (copying the database file inside a
+process that holds it open drops them). An older `sqlite3` (< 3.51, and
+Python's `sqlite3` module on many hosts) opened read-write at that moment
+sees no other reader, takes an exclusive lock when it closes, and deletes the
+`-wal`/`-shm` files akm is still using: that produced a `state.db` with
+colliding rowids and stale index entries. `-readonly` avoids the whole class
+of risk by never taking a write connection.
+
+## Verification
+
+Use focused tests while iterating, then the repository gates before pushing:
+
+```bash
+bun test tests/<focused-file>.test.ts
+bun run check:changed
+bun run check
+```
+
+For eval scripts that accept `AKM_BIN`, point it at the exact launcher under
+test rather than relying on `PATH`.

package/docs/maintainers/release-checklist.md

@@ -0,0 +1,135 @@
+# Release Checklist
+
+Use this checklist for every release candidate. Local release validation and
+scheduled CI are useful inputs, but neither substitutes for a successful gated
+run of the exact commit that will be published.
+
+## 1. Freeze the candidate
+
+1. Finish the version, changelog, migration-note, and release-PR changes. From
+   0.10 the version is a monthly release number, `0.10.YYMMNN` (see step 4):
+   `bun scripts/release-version.ts next` prints the next free one for this
+   month (UTC). Every release, whatever its stage, takes the next number.
+   Commit it in `package.json` and cut the CHANGELOG as
+   `## [0.10.YYMMNN] - YYYY-MM-DD`. A prerelease stage is not committed: it is
+   chosen when the Release workflow runs, and the release's CHANGELOG section
+   covers it.
+2. Record `git rev-parse HEAD`. This is the full 40-character release-candidate SHA.
+3. Run `bun run release:check` locally. If Docker is unavailable, run
+   `./tests/release-check.sh --skip-docker` and rely on the gated Docker job
+   below for the container matrix.
+
+Any commit added after this point creates a new candidate and invalidates the
+gated evidence collected for the previous SHA.
+
+## 2. Collect exact-SHA gated evidence
+
+GitHub only offers a scheduled or manually dispatched workflow after its file
+exists on the default branch. When validating the commit that first introduces
+or changes this workflow, create a unique lightweight candidate tag at the
+recorded SHA:
+
+```sh
+candidate_sha="$(git rev-parse HEAD)"
+candidate_short_sha="$(git rev-parse --short=12 HEAD)"
+candidate_version="$(node -p 'require("./package.json").version')"
+candidate_tag="gated-ci/candidate-${candidate_version}-${candidate_short_sha}"
+git tag "$candidate_tag" "$candidate_sha"
+git push origin "refs/tags/$candidate_tag"
+```
+
+Verify that the tag target is the exact candidate commit recorded in step 1.
+The `gated-ci/candidate-*` trigger runs every gated suite from the workflow in
+that tagged commit. The resolver checks that the checkout equals the immutable
+event SHA, and the final evidence job records both that SHA and the tag ref.
+Never force-move or reuse a candidate tag; a changed commit needs a new tag and
+a new run.
+
+After **Gated CI** exists on the default branch, manual dispatch is an
+equivalent exact-SHA path. From the repository's Actions page, choose **Run
+workflow** and supply:
+
+- `candidate_sha`: the full 40-character SHA recorded above, never a branch or
+  tag name.
+
+Every suite runs; there is no suite selector.
+
+The manual request rejects abbreviated SHAs and checks out that immutable
+commit for every gate. Wait for all of these stable checks to succeed on either
+candidate path:
+
+- `Gated / Semantic Search`
+- `Gated / Docker Install`
+- `Gated / Native Scheduler / Linux`
+- `Gated / Native Scheduler / macOS`
+- `Gated / Native Scheduler / Windows`
+- `Gated / Release Candidate Evidence`
+
+The final evidence job records the requested and resolved SHA, the trigger ref,
+each suite's result, and a run link in the workflow summary. A weekly run is
+drift detection, not release evidence, because it may cover a different
+commit.
+
+Manual and tagged candidate runs are cache restore-only. Only a successful
+scheduled run of the workflow on the repository's default branch may save the
+HuggingFace model cache; its key identifies both the embedding model and the
+source/lock inputs. This prevents candidate-controlled workflow code from
+publishing cache entries while still avoiding repeated model downloads.
+
+Copy the successful run URL (for example,
+`https://github.com/itlackey/akm/actions/runs/<run-id>`) and the exact candidate
+SHA into both the release PR and its milestone/parent tracker. Do not publish
+from a candidate whose evidence link names a different SHA, whose final
+evidence job is skipped, or whose run was re-run after the candidate changed.
+
+## 3. Gated CI does not run on pull requests
+
+Gated CI runs on three triggers only: the weekly schedule, an exact-SHA
+`workflow_dispatch`, and a `gated-ci/candidate-*` tag. All three run every
+suite.
+
+There used to be a `Gated / Detect Changed Paths` job that also ran these on
+PRs, selecting suites by regex-matching the diff against path lists. It was
+deleted in 0.9.8: the patterns had gone stale — they still named test files a
+reorganisation had moved or deleted, so it was silently under-selecting suites
+and nobody noticed. A build-policing job that quietly stops policing is worse
+than no job, because its green status is read as coverage.
+
+Nothing about release evidence changes. Step 2 was always the requirement, and
+it never went through the PR path.
+
+The candidate-tag trigger is reserved for release evidence and workflow
+rollout: it always runs `all`, because a tag-push workflow is the path available
+before the workflow file reaches the default branch.
+
+## 4. Publish
+
+After the exact-SHA gated run and local release check are green, trigger the
+Release workflow with the version already committed in `package.json`. Keep the
+candidate SHA and Gated CI run URL in the release record so the published
+artifact's validation can be audited later.
+
+0.10 and later use monthly release numbers, `0.10.YYMMNN`: `YY` the UTC year,
+`MM` the month and `NN` the release in that month (`01` to `99`), two digits
+each (see [`STABILITY.md`](../../STABILITY.md)). The first release of 2026-10 is
+`0.10.261001`. `bun scripts/release-version.ts next` takes `NN` as one above the
+highest release already on npm for this UTC month, with or without a stage
+(`npm view akm-cli versions`), so numbering follows what was published, not
+what was committed. The retired 8-digit daily builds (`0.10.26101001-alpha` to
+`0.10.26101202-alpha`) are not counted.
+
+The workflow has two inputs:
+
+- `version`: the version committed in `package.json`, as before. The workflow
+  rejects a malformed one (`scripts/release-version.ts`, tested in
+  `tests/release-version.test.ts`): two digits each for `YY`, `MM`, `NN`, a
+  month 01 to 12, `NN` 01 to 99; the old 8-digit daily form is rejected. For
+  0.9 and older it is the `X.Y.Z` as before.
+- `stage`: `none` publishes `<version>` to the npm `latest` tag and as a GitHub
+  release. `alpha`, `beta` or `rc` publishes `<version>-<stage>` to `next` as a
+  GitHub prerelease (no `.N`: every release has its own number). There is no
+  promoting one build through stages: the next release, at any stage, commits
+  the next number (`0.10.261001-alpha`, then `0.10.261002-beta`, then
+  `0.10.261003`).
+
+`bun scripts/release-version.ts validate <version>` checks a version by hand.

package/docs/migration/README.md

@@ -2,6 +2,8 @@
 
 Upgrade guides and per-release migration notes.
 
+- [v0.9 -> v0.10 migration guide](v0.9-to-v0.10.md) -- Upgrade order for a 0.9.15+ install, every removed CLI spelling, strategy, config key and workflow feature with its replacement, changed `akm improve` defaults, the OpenCode plugins, and `0.10.YYMMNN` version numbers
+- [v0.10.0 release note](release-notes/0.10.0.md) -- Summary of the 0.10 series: the 0.9.15 version floor, `--shape`/`--target`/`help agents` removals, `default` and `consolidate` as the only built-in strategies, OpenCode 2, feedback-scaled ranking, and what is gone
 - [v0.9.1 -> v0.9.2 migration guide](v0.9.1-to-v0.9.2.md) -- Task-v2/task-v3 to task source v4 conversion, the durable-v4-family workflow boundary at executable `irVersion: 5`, and release behavior changes
 - [v0.9.2 release note](release-notes/0.9.2.md) -- Self-contained terminal upgrade summary shipped for `akm help migrate 0.9.2`
 - [v0.9.16 release note](release-notes/0.9.16.md) -- Source-bound scheduler grants, local execution authority, and split unsafe overrides
@@ -9,5 +11,5 @@ Upgrade guides and per-release migration notes.
 - [v0.9.19 release note](release-notes/0.9.19.md) -- `akm improve` scoped to the bundle it writes to (scheduled runs need one `--bundle` run per other bundle), `akm proposal reopen` and the retire-proposal diff, and fewer repeat consolidate promotions
 - [v0.8 -> current v0.9 migration guide](v0.8-to-v0.9.md) -- Package upgrade with fresh current config/state and explicit task conversion
 - [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)
+- [v0.5 -> v0.6 migration guide](v0.5-to-v0.6.md) -- Terminology cut, registry schema v3, publisher changes
+- [Release notes index](release-notes/README.md) -- The short per-release notes `akm help migrate <version>` prints, with links to every bundled note

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.0.13
+# akm v0.0.13 migration notes
 
 - Initial public release.
 - No migration steps are required for earlier akm versions.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.1.0
+# akm v0.1.0 migration notes
 
 - The package and project were rebranded from Agent-i-Kit to akm.
 - Update package references from `agent-i-kit` to `akm-cli`.

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

@@ -0,0 +1,201 @@
+# akm v0.10.0 migration notes
+
+0.10 is a clean-up and tuning release. It covers the daily alphas
+0.10.26101001 through 0.10.26101202 and the monthly releases that follow
+(`0.10.YYMMNN`). It
+removes surface that nothing used, merges CLI spellings, sets the improve
+defaults from measurements, and adds OpenCode 2 support. It adds no `state.db`
+migration and keeps `index.db` at layout 26.
+
+To upgrade from 0.9.15 or later:
+
+```sh
+akm upgrade
+akm migrate status
+akm health
+```
+
+`akm upgrade` installs the new release and runs `akm migrate apply`. Before
+you upgrade, search your scripts, tasks and agent instructions for the removed
+spellings below: they fail with exit 2 and no hint. The full ordered procedure,
+every replacement and the verification steps are in the
+[0.9 to 0.10 migration guide](../v0.9-to-v0.10.md).
+
+## Version floor
+
+0.10 reads what 0.9.15 and later wrote. It converts nothing older. A config in
+the old `stashDir` / `sources[]` / `installed[]` layout, or with an `extraParams`
+key that shadows a first-class engine field, fails to load and names
+`akm migrate apply` under akm 0.9.x. If you are on 0.9.14 or earlier, install
+0.9.31, run `akm migrate apply`, then upgrade.
+
+## Version numbers
+
+A 0.10 release is numbered `0.10.YYMMNN`: the UTC year and month, then the
+release within that month. Every release takes the next number, whatever its
+stage. A prerelease carries its stage only (`-alpha`, `-beta`, `-rc`).
+Prereleases publish to the npm `next` tag and stable releases to `latest`.
+`akm upgrade --next` follows `next`. Versions sort by month and then number, so
+the number says nothing about how big a change is. Read the CHANGELOG, which
+still marks breaking changes. The 0.9 line keeps `0.9.N`.
+
+The daily alphas used an 8-digit patch (`0.10.YYMMDDNN`), which semver sorts
+above every `0.10.YYMMNN`. If you are on one, install the first monthly release
+explicitly once (`npm install -g akm-cli@0.10.261001-beta`); `akm upgrade` will
+not offer it.
+
+## Breaking changes
+
+Each of these is an unknown flag or command (exit 2), with no alias:
+
+- `akm help agents` is gone. Use `akm hints`, or `akm hints --detail brief` for
+  the short guide.
+- `--shape` is gone. `--detail agent` replaces `--shape agent`, and `--detail
+  brief` replaces `--shape summary`. `--detail` takes `brief`, `normal`, `full`
+  or `agent`.
+- `--target` is gone from `import`, `env create`, `env remove`, `secret set`,
+  `proposal accept`, `proposal diff` and `proposal revert`. Use `--bundle`.
+- `akm task validate` is folded into `akm lint --type tasks`. `akm task list`
+  is gone; use `akm search --type task`.
+- `akm config path --all` is gone. `akm info` reports the directories.
+- `akm improve --plan` is gone; use `--dry-run`. `akm improve --auto-accept` is
+  gone; use `akm improve && akm proposal drain --promote --yes`.
+- `--run` and `--since` belong to `akm improve report`. `akm improve report` and
+  `akm improve judge` are real subcommands.
+- `akm workflow create --reset` is gone; use `--force`.
+
+Other breaking changes:
+
+- The built-in improve strategies `quick`, `reflect-distill`, `thorough`,
+  `catchup` and `proactive-maintenance` are removed. Only `default` and
+  `consolidate` are built in. A config block with one of those names still
+  loads, as a user-defined strategy that inherits `default`. A name with no
+  block makes `akm improve` fail and name `default`. The task templates
+  `akm-improve-nightly`, `akm-improve-frequent` and `akm-improve-catchup` are
+  removed; a copy in your bundle keeps its old `--strategy` and must be edited.
+- Improve config keys that measured no effect or that nothing read are removed:
+  `consolidate.antiCollapse`, `p90ChunkSecondsDefault`, `minPoolSize`,
+  `distill.fidelityCheck`, `distill.limit`, `reflect.lowValueFilter`,
+  `memoryInference.cls`, `proactiveMaintenance.limit`, `triage.policy`,
+  `improve.salience.outcomeWeightEnabled` and `salienceThreshold`. A config that
+  sets one still loads; `akm migrate apply` drops it.
+- The GitHub-shaped YAML workflow format is removed, with workflow-step
+  `uses: tasks/...`, `scripts/...` and `commands/...`. Workflows are Markdown
+  only. Top-level `outputs:`, `route` steps and `unit.isolation: worktree` are
+  removed and are lint errors.
+- `BundleAdapter.placeNew()` is removed. Nothing called it.
+- `package.json` has an `exports` map: only `akm-cli/api`, `akm-cli/package.json`
+  and `akm-cli/dist/*` resolve.
+- The runtime conversions for config older than 0.9.15 are removed, as above.
+
+## New
+
+- **OpenCode 2.** akm detects the OpenCode major from the engine's binary and
+  drives OpenCode 1 or 2 through its own adapter, for SDK dispatch, CLI
+  dispatch, session history and config import. OpenCode 1 keeps working and
+  logs one warning recommending OpenCode 2. `akm upgrade` and `akm health` know
+  the new `akm-opencode-v2` plugin.
+- **`akm-cli/api`.** `curate(query, options)` returns exactly what
+  `akm --detail agent -q curate` prints, computed in-process. It is for the
+  plugins; nothing else is a public API.
+- **Feedback changes ranking.** `akm search` and `akm curate` scale each hit by
+  your feedback on it. The effect is small and the same for every asset: about
+  +2, +3, +5 and +9 percent for 1, 2, 5 and 20 positives. Improve, task and
+  audit feedback does not count.
+- **Distill extends a lesson** that a memory repeats, as a proposal for a person
+  (`distill-update`).
+- **Child workflows** keep a simple form: `unit: { workflow: workflows/<name>,
+  with: {...} }`. A param's `default:` is now applied at run start.
+- **`akm proposal extract`** is Evolving, not Experimental.
+- **`akm improve <scope>`** warns when the scope matches no asset.
+- **Daily-build versioning** and the `next` channel, above.
+
+## Changed defaults
+
+- The `default` improve strategy now drains the proposal queue in `promote`
+  mode with judgment off, up to 200 accepts a run. It accepts what a quality
+  judge already passed and the retirements the consolidate pair pass staged.
+  The judgment tier is off in every built-in strategy and may accept only
+  consolidate promotions. Set `improve.strategies.default.processes.triage.enabled`
+  to `false` to leave every proposal for review.
+- The proactive-maintenance lane is on in `default`: up to 15 assets a run that
+  have no fresh feedback and are 30 days past their last reflect or distill. Its
+  proposals always wait for a person.
+- A manual fix (`akm feedback --replace/--with/--source`, `--superseded-by`,
+  `--outdated`) applies at once instead of queuing a proposal. `akm proposal
+  revert` undoes it.
+- `akm improve` syncs a git-backed bundle before it plans, as `akm sync` does,
+  and again at the end. A conflict warns and the run continues. `--no-sync` and
+  `--no-push` apply to both.
+- A reflect revision the judge does not pass but scores 3.5 or more goes to a
+  person as `judge-uncertain` instead of locking the asset for 14 days. A
+  missing distill judge queues for review instead of a 30-day lock.
+- `captureMode: hot` memories are consolidated like any other memory.
+- Retire proposals expire by age (`archiveRetentionDays`, default 90) like every
+  other proposal. The per-run `improve` and `index` log files are purged under
+  `improve.eventRetentionDays`.
+- A standalone `akm proposal drain` resolves to promote mode on a stock install
+  and asks for confirmation.
+
+## Removed
+
+- Reflect's retrieval regression gate. It refused 12 to 17 percent of the
+  revisions the judge had passed and lowered the defects fixed. A judge-passed
+  revision is now minted as a proposal with no further check. It had no config
+  key.
+- The high-salience improve lane.
+- The hint tables and error messages for the 0.9.0 renames, the `vault:`, `env:`
+  and `secret:` ref rejections, the `--from stash|both` error, and the bespoke
+  errors for retired config keys. They are ordinary unknown commands, flags or
+  keys now.
+- The `targetVocab` marker on `task_history` rows and the `"mcp"` package
+  keyword.
+
+## Plugins
+
+- `akm-opencode` is for OpenCode 1. `akm-opencode-v2` is for OpenCode 2. Each
+  pins one exact `akm-cli`, and `akm upgrade` holds the CLI to the pin.
+- OpenCode caches the plugin spec it resolved and does not re-check it. A new
+  build is picked up only after the plugin's cache folder is cleared. `akm
+  upgrade` does this for `@latest` (or `@next`) when no OpenCode process runs.
+  A spec pinned in your OpenCode config is left alone.
+- OpenCode 1 asks before reading or writing outside the project directory.
+  OpenCode 2 does not unless its config says `ask`, so akm's rejection of a
+  permission request only happens there once you add the rule. akm changes no
+  OpenCode default. See [Configuration](../../reference/configuration.md#engines).
+- Plugins and scripts that pass `--shape agent` must move to `--detail agent` in
+  step with the CLI. A call with `--shape agent` fails on 0.10, and one with
+  `--detail agent` fails on 0.9.
+
+## Fixes worth naming
+
+- `akm sync` fetches and merges what another host pushed before it pushes. It
+  used to exit 70 once another host had pushed.
+- The 02:00 nightly `akm improve` no longer loses its night to the consolidate
+  task's lock. The shipped consolidate task passes `--timeout-ms 3600000`.
+- Command tasks (`uses: commands/...`) get the 6-hour unattended default
+  timeout.
+- A transient reflect failure no longer uses up the feedback that planned it.
+- A run killed by its budget watchdog leaves a record and commits what it wrote.
+- The extract per-session lock is reclaimed only from a dead holder.
+- Memory inference writes to the default bundle and no longer reverts an edit
+  made to the parent memory during the model call.
+- The consolidate pair judge no longer treats a later date alone as a
+  replacement: a note replaces another only when both are about the same named
+  thing. On the eval, `gpt-oss:120b` unsafe retirements went from 1, 2, 1 to
+  0, 0, 0 over three runs.
+- A gateway that answers 5xx `format_ignored` no longer fails every schema call,
+  and a call recovered by the retry counts as one successful call in the usage
+  rows.
+- `akm proposal revert` of a retirement works after the 30-day archive purge.
+- `akm search` no longer warns "no embedding provider is configured" on a default
+  install.
+- A signal to `akm agent` now ends the CLI harness it started. An OpenCode 2 SDK
+  dispatch ends at once when akm rejects a permission request, instead of waiting
+  out its deadline.
+
+For the rules each improve process follows in 0.10, see
+[the 0.10 process rules](../../architecture/0.10-process-rules.md). For the
+entry behind each item, run `akm help migrate <build number>` (for example
+`akm help migrate 0.10.26101201`) or read the
+[CHANGELOG](https://github.com/itlackey/akm/blob/main/CHANGELOG.md).

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.2.0
+# akm v0.2.0 migration notes
 
 - Asset refs are user-facing `type:name` values; do not rely on URI-style refs.
 - The old fixed asset-type union was replaced by an extensible asset type system.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.3.0
+# akm v0.3.0 migration notes
 
 - The old `stash` and `kit` command groups were folded into the top-level CLI.
 - Use `akm add`, `akm list`, and `akm remove` instead of the older split command surfaces.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.5.0
+# akm v0.5.0 migration notes
 
 - New top-level surfaces: `akm wiki …`, `akm workflow …`, `akm vault …`, and `akm save`.
 - If you tried the unreleased single-wiki LLM prototype, move to the new `akm wiki …` workflow.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.6.0
+# akm v0.6.0 migration notes
 
 This release ships the v1 architecture refactor on top of the earlier 0.6
 terminology cut (`kit` → `stash` in the registry wire format). The CLI

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.0
+# akm v0.7.0 migration notes
 
 0.7.0 is the last pre-1.0 ship in the v1 cycle. It introduces the
 proposal queue, agent reflection commands, the `lesson` asset type, the

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.3
+# akm v0.7.3 migration notes
 
 0.7.3 includes stability improvements, security hardening, and UX refinements. Key changes include:
 
@@ -13,4 +13,4 @@ Migration notes for akm v0.7.3
 - **`.stash.json` no longer drives incremental stale detection** — editing `.stash.json` alone no longer forces directories to rescan during incremental indexing.
 - **One-shot URL ingest for `akm import` and `akm wiki stash`** — both commands now accept a single HTTP/HTTPS URL in addition to file paths and stdin. `akm import <url>` fetches the exact page, converts it to markdown, and writes it into `knowledge/` using a URL-path-derived default name. `akm wiki stash <wiki> <url>` fetches the exact page, converts it to markdown, and writes it into `wikis/<wiki>/raw/`. Neither command registers a persistent website source or crawls linked pages.
 
-For stash authors on the 0.7.x pre-release line: `.stash.json` remains supported for compatibility in this release, but it is deprecated and will be removed in v0.8.0. That timeline is intentional: during this aggressive pre-release phase-out window, compatibility shims do not stay around until 1.0 unless they still earn their cost. Prefer frontmatter for markdown assets and structured code comments for scripts, and migrate any remaining `.stash.json` metadata before taking the 0.8 upgrade.
+For stash authors on the 0.7.x pre-release line: `.stash.json` remains supported for compatibility in this release, but it is deprecated and will be removed in v0.8.0. That timeline is intentional: during this aggressive pre-release phase-out window, compatibility shims do not stay around until 1.0 unless they still earn their cost. Prefer frontmatter for markdown assets and structured code comments for scripts, and migrate any remaining `.stash.json` metadata before taking the 0.8 upgrade.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.4
+# akm v0.7.4 migration notes
 
 This is a patch release that fixes the publish process. No functional changes from v0.7.3.
 

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.7.5
+# akm v0.7.5 migration notes
 
 0.7.5 is a patch release that rolls up all changes shipped on `main` after v0.7.4.
 

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.8.0
+# akm v0.8.0 migration notes
 
 This release combines the 0.8.0 CLI/storage break with the final improve-owned
 maintenance migration work that landed before release validation closed.

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.0
+# akm v0.9.0 migration notes
 
 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

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.14
+# akm v0.9.14 migration notes
 
 The derived `index.db` generation changes from v22 to v23 to support lexical
 Markdown fragments. On the first normal read after upgrade, akm detects that

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.15
+# akm v0.9.15 migration notes
 
 `RUN_LEASE_HELD` (a workflow run-lease refusal) and the new
 `STATE_DB_CONTENDED` (state.db write contention) now exit 75 (`EX_TEMPFAIL`)

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.16
+# akm v0.9.16 migration notes
 
 Scheduled execution is now authorized by host-local config and bound to the
 specific source installed under a bundle id. Existing

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.17
+# akm v0.9.17 migration notes
 
 Run this after upgrading:
 

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.19
+# akm v0.9.19 migration notes
 
 Nothing has to run after upgrading from 0.9.18: 0.9.19 adds no config keys,
 changes no index layout, adds no state.db migration and leaves scheduler rows

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

@@ -1,4 +1,4 @@
-Migration notes for akm v0.9.2
+# akm v0.9.2 migration notes
 
 Exact-prefix additive `state.db` upgrades remain automatic. The released
 historical migration 018 is classified separately because it removes retired