akm-cli 0.9.31 → 0.10.261002-beta

package/STABILITY.md

@@ -12,6 +12,47 @@ out in the CHANGELOG with a migration note. The 0.10.x series returns to bug
 fixes and tuning, and aims to restore the normal discipline of breaking
 changes only in major and minor releases.
 
+**Version floor (0.10, #1091).** 0.10 reads what 0.9.15 and later wrote: config,
+`state.db`, task sources, frozen workflow plans and scheduler rows. It does not
+convert anything older. An install on an earlier release runs `akm migrate
+apply` under akm 0.9.x first, then upgrades; a 0.10 reader that meets an older
+shape refuses with one message saying so. See
+[`docs/architecture/persisted-data-compat.md`](docs/architecture/persisted-data-compat.md).
+
+**CLI spellings merged in 0.10 (#1091).** Each of these is an unknown flag or
+command (exit 2) from 0.10, with no alias and no deprecation period; the new
+spelling is in the CHANGELOG entry and the CLI reference.
+
+| Gone | Use |
+| --- | --- |
+| `akm help agents` | `akm hints` (`--detail brief` for the short guide) |
+| `--shape agent` | `--detail agent` |
+| `--shape summary` | `--detail brief` (it only had a projection on `akm show`) |
+| `--target` on `import`, `env create`, `env remove`, `secret set`, `proposal accept`, `proposal diff`, `proposal revert` | `--bundle` |
+| `akm task validate <path>` | `akm lint --type tasks` |
+| `akm config path --all` | `akm info` |
+| `--run` / `--since` on `akm improve` | `akm improve report --run` / `--since` |
+
+**Version numbers (0.10 onward, #1089).** A 0.10 release is numbered
+`0.10.YYMMNN`: `YY` the UTC year, `MM` the month (`01` to `12`) and `NN` the
+release within that month (`01` to `99`), each two digits. Every release takes
+the next `NN`, whatever its stage: the first release of 2026-10 is `0.10.261001`
+(or `0.10.261001-alpha`), the next `0.10.261002`. A prerelease carries its stage
+only: `-alpha`, `-beta` or `-rc`, with no `.N`. A build is not promoted through
+stages under one number: each stage is its own release. Prereleases publish to
+the npm `next` tag and stable releases to `latest`; `akm upgrade --next` follows
+`next`. Versions sort by month and then `NN`, so semver ranges and `akm upgrade`
+order them correctly across months and years. The patch number no longer says
+how big a change is: read the CHANGELOG, which still marks breaking changes. The
+0.9 line keeps `0.9.N`, and `0.11` restarts on the same scheme.
+
+The 0.10 daily alphas (`0.10.26101001-alpha` through `0.10.26101202-alpha`) used
+an 8-digit patch, `YYMMDDNN`. Semver compares the patch numerically, so every
+`0.10.YYMMNN` sorts below them and `akm upgrade` does not offer it from a daily
+alpha: install the first monthly release explicitly once (for example
+`npm install -g akm-cli@0.10.261001-beta`). This is a known, accepted break and
+`tests/semver-order.test.ts` pins it.
+
 This document classifies **every** user-facing surface by stability so you can
 decide which parts of `akm` are safe to script against today and which to
 treat as still-evolving. If a surface is not listed here, that is a bug —
@@ -87,6 +128,8 @@ enumeration of the whole `proposal` noun group.
 | `akm models` | Evolving | `list` and `copy-defaults` for model intent aliases. |
 | `akm lint` | Evolving | |
 | `akm improve` | Evolving | Review-first by default; mutating lanes require `experimental.improveAutonomy` — see below. |
+| `akm improve report` | Evolving | Subcommand since 0.10 (was a magic `scope` value); owns `--run` and `--since`. |
+| `akm improve judge` | Evolving | Subcommand since 0.10 (was a magic `scope` value); reads one revision as JSON on stdin and writes nothing. |
 | `akm proposal list` | Stable | See reconciliation note above. |
 | `akm proposal show` | Evolving | |
 | `akm proposal diff` | Evolving | |
@@ -95,10 +138,9 @@ enumeration of the whole `proposal` noun group.
 | `akm proposal reopen` | Evolving | New in 0.9.19; undoes a rejection. |
 | `akm proposal revert` | Evolving | |
 | `akm proposal drain` | Evolving | |
-| `akm proposal extract` | Experimental | Former top-level `akm extract`. Session extraction quality is still being measured (0.10, #1094). |
+| `akm proposal extract` | Evolving | Former top-level `akm extract`. Promoted from Experimental in 0.10 (#1133): the extract eval measures it. Evolving, not Stable, because 0.10 is still settling the improve defaults. |
 | `akm proposal new` | Evolving | Former top-level `akm propose`. |
 | `akm help` | Stable | |
-| `akm help agents` | Stable | |
 | `akm help migrate` | Stable | Only renders release notes. |
 | `akm hints` | Stable | Format-exempt agent guide; `--detail brief` selects the compact version. |
 | `akm completions` | Stable | Format-exempt (emits shell script source). |
@@ -117,8 +159,6 @@ enumeration of the whole `proposal` noun group.
 | `akm task sync` | Evolving | |
 | `akm task doctor` | Evolving | |
 | `akm task explain` | Evolving | New in 0.9.2; secret-shaped values in provenance output are redacted on a best-effort heuristic basis (not a guarantee). |
-| `akm task validate` | Evolving | New in 0.9.11; read-only, and the only `task` subcommand that takes a bare filesystem path instead of a ref — the file need not belong to any configured bundle. |
-| `akm task list` | Evolving | New in 0.9.15 (#951); a pure delegating alias for `akm search --type task` — same envelope, no separate implementation. |
 
 ## Stable
 
@@ -157,7 +197,7 @@ enumeration of the whole `proposal` noun group.
 - **Read commands** — `akm search`, `akm show`, `akm bundle list`, `akm curate`,
   `akm info`, `akm config get`, `akm config list`, `akm config path`,
   `akm env list`, `akm secret list`, `akm proposal list` (list filters),
-  `akm help`, `akm help agents`, `akm hints`, `akm completions`.
+  `akm help`, `akm hints`, `akm completions`.
 - **Write commands core surface** — `akm bundle add`, `akm bundle update`,
   `akm bundle remove`, `akm clone`, `akm import`, `akm sync`, `akm index`,
   `akm bundle create`, `akm setup`, `akm remember`, `akm feedback`,
@@ -195,12 +235,11 @@ enumeration of the whole `proposal` noun group.
   fetch**: a registered renderer fires on the shape of the result (`akm health
   --report` carries the report dataset in the envelope, so the same data is
   available as JSON), never on the format alone.
-  `--detail` is verbosity only (`brief|normal|full`);
-  `--shape` (`human|agent|summary`) is the output-projection axis (see
-  Experimental). A small set of commands is **format-exempt** because their
+  `--detail` is `brief|normal|full` (verbosity) or `agent` (the projection of
+  `search`, `curate` and `show`; see Experimental). A small set of commands is **format-exempt** because their
   output is not a result envelope at all: `completions` (shell script source),
   child-process passthrough in `env run` / `secret run`, a bare-path payload
-  from `env path`, and document payloads from `help` (bare, `help agents`, and
+  from `env path`, and document payloads from `help` (bare and
   `help migrate`). The set is declared in
   `src/output/format-exempt.ts`, and
   passing `--format` to one of them warns rather than silently doing something
@@ -250,6 +289,7 @@ remain available across minor releases, but flag names, prompts, and
 proposal-queue shape may shift. Breaking changes will be flagged in the
 CHANGELOG with a migration note.
 
+- **Programmatic API** — `akm-cli/api` (`curate()`, for in-process recall by the akm plugins; see [`docs/reference/api.md`](docs/reference/api.md)). The export list only grows and `curate()`'s parameters and result keep their documented contract; the text it returns is `akm curate`'s agent-shaped output and changes with it. Everything else in the package remains CLI-only.
 - **Improvement loop** — `akm improve` and the proposal noun group
   `akm proposal {extract,new,list,show,diff,accept,reject,reopen,revert,drain}`
   (`extract` and `new` are the former top-level `akm extract`/`akm propose`,
@@ -259,14 +299,15 @@ CHANGELOG with a migration note.
   default and is **review-first**: the lanes that mutate assets without review
   require `experimental.improveAutonomy` — see
   [`akm improve` autonomy](#akm-improve-autonomy--opt-in-in-090).
-  `--auto-accept` was removed in 0.9.0. It is now accepted-and-warned rather
-  than silently absorbed: passing it prints a deprecation warning naming the
-  replacement, and the space-separated form (`--auto-accept 90`) no longer
-  poisons the asset-type positional — its value is discarded with a second
-  warning instead of silently reducing the run to a zero-match no-op. It
-  becomes a hard error in 0.10. The replacement is
+  `--auto-accept` was removed in 0.9.0 and is an unknown flag (a usage error,
+  exit 2) since 0.10. The replacement is
   `akm improve && akm proposal drain --promote --yes`, or a `triage` block
   with `applyMode: "promote"` in your strategy.
+  **Session extraction** (`akm proposal extract` and the improve `extract`
+  process) is Evolving as of 0.10 (#1133): the extract eval (insights saved,
+  routine sessions left empty, planted instructions refused) is its gate. It
+  is Evolving, not Stable, because 0.10 is still settling the improve
+  defaults; what it extracts and its output may still be tuned.
 - **Tasks** — `akm task` subcommand surface (`add | run | sync | doctor |
   history | explain | validate`; no alias, no
   `list`/`remove`/`init`/`enable`/`disable`); task source v4 YAML (typed
@@ -282,14 +323,7 @@ CHANGELOG with a migration note.
   construction** (the excluded data never reaches the command). `akm task
   explain` instead **redacts** secret-shaped input values on a best-effort
   heuristic basis — a value that doesn't match the heuristic can still
-  print unredacted. `akm task validate <path>` (new in 0.9.11) is the same
-  kind of zero-write introspection as `explain`, but takes a bare filesystem
-  path rather than a bundle-qualified ref — it reports whether that ONE file
-  would parse cleanly (`valid`), need `akm migrate apply` first (`blocked`:
-  task v2/v3, or a retired `schedule[].enabled`),
-  fail schema validation (`invalid`), or isn't a task source at all
-  (`not-a-task`) — exactly the diagnostic `akm task sync` would produce for
-  it, before the file is ever wired into a bundle or the scheduler.
+  print unredacted.
 - **Workflow plan** — `akm workflow plan <ref>`, new in 0.9.2: zero-write
   compile+freeze introspection (the canonical step graph, task/child
   expansion, input bindings, and lowering notices for a workflow, without
@@ -300,7 +334,7 @@ CHANGELOG with a migration note.
   both removed; `log` is now a leaf command — the former `list` surface).
 - **Bundles & the workspace model** — installed sources are *bundles*; each is
   recognized by a built-in *adapter* (native Agent Skills, Claude and OpenCode
-  commands/agents, knowledge, YAML workflows, tasks, env/secret files, scripts,
+  commands/agents, knowledge, workflows, tasks, env/secret files, scripts,
   OKF and LLM-wiki knowledge bases). Config is keyed by `bundles` and
   `defaultBundle`. The adapter set, bundle-recognition rules, and the
   `bundles` config shape may still shift; the `okf`, `llm-wiki` and
@@ -324,9 +358,14 @@ CHANGELOG with a migration note.
   `claude`, `opencode-sdk` (the primary OpenCode interface), `codex`, and the
   `opencode` CLI path, `copilot`, `pi`, `gemini`, `aider`, `amazonq`,
   `openhands`. Every harness is Evolving: the harness implementation is being
-  reworked so harnesses are easy to add, remove and update (0.10), and the
-  `opencode` CLI dispatch path is a deprecation candidate once `opencode-sdk`
-  covers it. The set will grow.
+  reworked so harnesses are easy to add, remove and update (0.10). The set will
+  grow.
+  **Deprecated:** the `opencode` CLI dispatch path (an agent engine with
+  `platform: "opencode"`, which runs `opencode run` per call). It still works on
+  OpenCode 1 and 2 throughout 0.10; use an `opencode-sdk` engine instead, which
+  covers it, including a default agent (#1098). It may be removed in 0.11 or
+  later. The rest of the OpenCode integration (session-log import, config
+  import) is not deprecated.
 - **Model aliases** — `akm models list|copy-defaults` and the intent-alias
   defaults they expose.
 - **Proposal queue** — quality classifications (`accepted`, `pending`,
@@ -357,16 +396,19 @@ for scripted use.
   workflow engine are Experimental from 0.9.28 and throughout 0.10. The 0.10
   series stabilizes the feature and trims what is not useful, then either
   promotes it out of Experimental or removes it if stabilization does not
-  produce a quality feature.
+  produce a quality feature. **Child workflows** (`unit: { workflow: … }`, a
+  step that runs another workflow and returns its last step's output) are the
+  least settled part and are kept only in that simple form; `akm workflow list
+  --children` goes with them.
 - **`akm metrics`** — new in 0.9.28. What it reports, its JSON shape and the
   `--format html` dashboard may change in any release; do not script against
   them.
 - **`lesson` asset type** — schema (`when_to_use`, `description`) is
   stable, but lesson-distillation triggers and ranking are tuning targets.
-- **`--shape agent` and `--shape summary`** — the output-projection axis
-  (`--shape human|agent|summary`). `summary` is implemented only on
-  `akm show`; `agent` is implemented on `search`, `show`, and `curate`.
-  Coverage will expand. `--detail` is verbosity only (`brief|normal|full`).
+- **`--detail agent`** — the agent projection, implemented on `search`, `show`,
+  and `curate` (other commands ignore it). Coverage will expand. It replaces
+  `--shape agent`; `--shape` (and `--shape summary`, which only `show` had) is
+  gone in 0.10 and is an unknown flag.
 - **Protected env & secret values** — `env` (a whole `.env` group; key names
   are surfaced for discoverability, values never are) and `secret` (a single
   sensitive value). Values are never written to stdout, the index, or
@@ -378,14 +420,11 @@ for scripted use.
   contradiction edges, and the consolidate journal are observable but
   the algorithm that writes them is tuning across patch releases.
 - **Improve built-in strategies and lanes** — the built-in strategies other
-  than `default` and `consolidate` (`quick`, `reflect-distill`, `thorough`,
-  `catchup`) and the proactive-maintenance and high-salience lanes. 0.10
-  measures each and keeps, folds or removes it (#1094).
-- **Session extraction** — `akm proposal extract` and the `extract` process:
-  what it extracts, its quality gates and its output may change while 0.10
-  measures it (#1094).
+  than `default` and `consolidate` and the proactive-maintenance lane. 0.10 measures each and keeps, folds or removes it
+  (#1094). `quick`, `reflect-distill`, `thorough` and `catchup` were removed
+  in 0.10 (#1130), as were `proactive-maintenance` and the high-salience lane (#1129); a user-defined strategy of the same name keeps working.
 - **Improve tuning config** — `improve.strategies.*.processes.*` (per-process
-  engines, limits, gates, and the anti-collapse / CLS / fidelity knobs) and
+  engines, limits, gates, and the CLS knobs) and
   the `index.*` per-pass config. The 0.9.x series is explicitly still settling
   the design of the improve processes, so **keys in these two families may be
   added, renamed, or dropped in any 0.9.x or 0.10.x release**. The `akm
@@ -401,7 +440,8 @@ mutate assets *without* review require an explicit opt-in:
 akm config set experimental.improveAutonomy true
 ```
 
-Without it, these three lanes are downgraded, and each downgrade is **reported,
+Without it, these three lanes are downgraded (the triage lane only when its
+judgment tier is on), and each downgrade is **reported,
 not silent**: it warns on stderr naming the lane and the key, appends an
 `improve_skipped` event with `reason: "autonomy_gated"`, is counted in
 `akm health`'s improve skip-reason summary, and is listed by `akm task doctor`
@@ -414,7 +454,13 @@ review-first config correctly shows `queue`.
 | --- | --- | --- |
 | `memoryInference` | Writes `.derived.md` children and rewrites parent frontmatter | disabled |
 | memory cleanup | Belief-state frontmatter rewrites, archive moves | analyzed but not applied |
-| `triage` `applyMode: "promote"` | Auto-accepts queued proposals into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+| `triage` `applyMode: "promote"` **with judgment on** | The judgment tier auto-accepts consolidate promotions into the bundle | downgraded to `queue` — triage still runs, it just does not auto-accept |
+
+A deterministic-only `promote` (triage with judgment off) is **not** a gated
+lane (#1143): the `default` strategy runs it without the opt-in, bounded by
+`maxAcceptsPerRun` (200), through the same deterministic gates as
+`akm proposal drain --promote`. Only a promote that turns the judgment tier on
+needs `experimental.improveAutonomy`.
 
 Consolidation remains enabled with autonomy off: both its passes (promotion,
 and the pair pass's duplicate/subsumed/supersedes judging) only ever emit a
@@ -510,7 +556,7 @@ Shipped from that record: **D1** (`#fragment` section selection),
 gone — `#fragment` is the only section selector), **D4** (conceptId /
 `bundle//` prefix browse), **D5** (`akm bundle` removed), **D6** (open `type`
 set at runtime), **D7** (all six `--format` values everywhere), **D8** (the
-`experimental.improveAutonomy` gate), **D9** (`--auto-accept` warn-and-ignore),
+`experimental.improveAutonomy` gate), **D9** (`--auto-accept` removed, a hard error since 0.10),
 and partially **D10** (an `akm-migrate` binary now exists, though the code still
 lives in this repo). **D3** shipped too, in the end: `akm mv` was removed in
 0.9.0 (see the Renames bullet above), with `scripts/rekey-asset-ref.ts` as the
@@ -518,21 +564,17 @@ Internal replacement for the one capability nothing else covered.
 
 - **0.10 — `config set`/`config unset` may drop the config dump** in favor of
   a compact `{ok, shape, key}` result; `akm config list` remains the full read.
-- **0.10 — migration extraction.** The migration machinery leaves the CLI for
-  a separately published `akm-migrate` package (see Internal above).
-- **0.10 — `--auto-accept` hard error.** It is currently accepted-and-warned;
-  see the Improvement loop entry.
-- **0.10 — `BundleAdapter.placeNew()` wiring.** The interface declares
-  `placeNew()` as an optional capability method, and 9 of the 11 built-in
-  adapters already implement it (all but `okf` and `website-snapshot`;
-  `claude` and `opencode` inherit theirs from the shared tool-dir factory),
-  but nothing in the write path calls it —
-  writes still resolve through AKM's native flat type→directory table.
-  Placement for every existing bundle is already correct today; this is a
-  deliberately sequenced routing change, not unfinished behavior. See
-  [D12](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/0.9.0-decisions.md#d12--bundleadapterplacenew-stays-unwired-until-010)
-  for why it is scoped out of 0.9.0. Nothing user-visible changes in 0.10 for
-  this alone.
+- **0.10 — migration extraction.** The migration machinery lives in its own
+  `akm-migrate` executable, which ships inside the `akm-cli` package next to
+  `akm` (no separate npm package). The task-source migrator (`task-to-v4.ts`,
+  `task-source-v3-frozen.ts`) lives with it under `scripts/akm-migrate/migrate/`,
+  out of `src/`.
+- **0.11 or later — the `opencode` CLI dispatch path may be removed.**
+  Deprecated in 0.10 (see Agent dispatch under Evolving); `opencode-sdk`
+  engines replace it.
+- **0.10 — `BundleAdapter.placeNew()` is removed.** Nothing called it; writes use AKM's fixed type→directory table.
+  Writable bundles in a non-akm layout would need per-adapter placement back
+  ([#1163](https://github.com/itlackey/akm/issues/1163)).
 - **1.0 contract freeze** — the `[bundle//]conceptId[#fragment]` ref grammar,
   the supported source model, search behavior, and write-target rules are
   frozen at 1.0. The SDK and in-process plugin story ship on top of that

package/dist/api-node.mjs

@@ -0,0 +1,20 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+
+// Node entry for `akm-cli/api` (the package `exports` map points the default
+// condition here; the `bun` condition points straight at `api.js`).
+//
+// `api.js` reaches modules that embed `.md`/`.xml` assets through
+// `with { type: "text" }` imports, which Node cannot load without the
+// text-import hook. Those imports are static and hoisted, so the hook must be
+// registered before `api.js` is evaluated: register it, then import `api.js`
+// dynamically. Same reason as `cli-node.mjs`.
+
+import { register } from "node:module";
+
+register("./text-import-hook.mjs", import.meta.url);
+
+const { curate } = await import("./api.js");
+
+export { curate };

package/dist/api.d.ts

@@ -0,0 +1,23 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+
+// Hand-written declarations for `akm-cli/api` (the build emits no .d.ts).
+// tests/contracts/api-surface.test.ts keeps this file and src/api.ts in step.
+
+export interface CurateOptions {
+  /** Maximum number of curated results (positive integer; the CLI default is 4). */
+  limit?: number;
+  /** Asset type filter, same as `--type`. */
+  type?: string;
+  /** Output format, same as `--format`. Default `"json"`, as in the CLI. */
+  format?: "text" | "json";
+}
+
+/**
+ * Returns exactly the stdout text of
+ * `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`,
+ * including its trailing newline. Rejects with the error the CLI would fail
+ * with: its message, and its error code on the `code` property.
+ */
+export function curate(query: string, options?: CurateOptions): Promise<string>;

package/dist/api.js

@@ -0,0 +1,45 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// 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/.
+/**
+ * `akm-cli/api` — the one supported programmatic entry point. Everything else
+ * in this package is CLI-only. See docs/reference/api.md for the contract.
+ *
+ * Each export runs the same code path as its CLI command and computes the
+ * document the CLI would print, in-process: no child process, no write to
+ * stdout/stderr, no `process.chdir`, no change to the host's `process.env`,
+ * and no process-level output-mode, quiet or verbose state left changed.
+ */
+import { renderOutput } from "./cli/shared.js";
+import { runCurate } from "./commands/read/search-cli.js";
+import { loadConfig } from "./core/config/config.js";
+import { UsageError } from "./core/errors.js";
+import { withQuiet } from "./core/warn.js";
+import { installLlmUsagePersistenceIfAbsent } from "./llm/usage-persist.js";
+import { resolveOutputMode } from "./output/context.js";
+import { stdoutText } from "./output/stdout.js";
+/**
+ * Returns exactly the stdout text of
+ * `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`
+ * including its trailing newline. Rejects with the error the CLI
+ * would fail with: its message, and its error code on the `code` property.
+ */
+export async function curate(query, options = {}) {
+    const format = options.format ?? "json";
+    if (format !== "text" && format !== "json") {
+        throw new UsageError(`Invalid value for --format: ${format}. Expected one of: json|text`, "INVALID_FORMAT_VALUE");
+    }
+    return withQuiet(async () => {
+        // Same startup order as the CLI: config first (an invalid config fails
+        // the call before anything runs), then the output mode from argv + config.
+        const mode = resolveOutputMode(["--detail", "agent", "--format", format], loadConfig().output ?? {});
+        const disposeLlmUsageSink = installLlmUsagePersistenceIfAbsent();
+        try {
+            const curated = await runCurate({ query, type: options.type, limit: options.limit === undefined ? undefined : String(options.limit) }, mode);
+            return stdoutText(renderOutput("curate", curated, { ...mode, format }));
+        }
+        finally {
+            disposeLlmUsageSink();
+        }
+    });
+}

package/dist/assets/hints/cli-hints-full.md

@@ -23,8 +23,7 @@ akm search "team-catalog//"                   # List every item in one bundle
 | `--from` | `local`, `registry`, `all`, or a configured bundle name | `local` |
 | `--limit` | number | `20` |
 | `--format` | `json`, `jsonl`, `text`, `yaml`, `md`, `html` | `json` |
-| `--detail` | `brief`, `normal`, `full` | `brief` |
-| `--shape` | `human`, `agent`, `summary` (`summary` only on `show`) | `human` |
+| `--detail` | `brief`, `normal`, `full`, `agent` (`agent`: search, curate and show only) | `brief` |
 
 Ref-prefix queries (a conceptId prefix ending in `/`, optionally bundle-qualified)
 return a deterministic listing, not a relevance ranking. Drop the trailing slash
@@ -90,13 +89,13 @@ akm import ./doc.md --xref knowledge/auth-flow # Merge provenance xrefs into the
 akm import ./new.md --supersedes knowledge/old # Import a correction AND demote the doc it replaces
 akm import - --name scratch-notes < notes.md   # Import stdin as a knowledge doc
 akm import https://example.com/docs/auth       # Fetch one URL and import it as knowledge
-akm import ./doc.md --target my-other-bundle    # Route import to a named writable bundle source
+akm import ./doc.md --bundle my-other-bundle    # Route import to a named writable bundle source
 akm workflow create ship-release               # Create a workflow asset in the bundle
-akm lint --type workflows                      # Parse and compile every .md/.yml workflow source; list every error
+akm lint --type workflows                      # Parse and compile every workflow source; list every error
 akm workflow run workflows/ship-release        # Start or resume and execute the workflow
 akm feedback skills/code-review --positive     # Record that an asset helped (ranks it higher; no rewrite)
 akm feedback agents/reviewer --negative --reason "says to run jest; the suite runs on vitest" # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
-akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/" # Queue an exact fix
+akm feedback knowledge/opencode-server --negative --reason "the default port is 4096, not 8000" --replace "port 8000" --with "port 4096" --source "https://opencode.ai/docs/server/" # Apply an exact fix
 akm feedback memories/deployment-notes --positive # Works for memories too
 akm feedback env/prod --positive               # Records env feedback without surfacing values
 ```
@@ -111,7 +110,7 @@ its description, title or `when_to_use` from your reason. A note that simply did
 not fit your task is not negative feedback: record nothing for it. Improve does
 not rewrite an asset's text: once you have verified the correct fact, attach the
 exact fix with `--replace "<exact current text>" --with "<corrected text>"
---source "<URL, command or file>"`, which akm checks and queues as a proposal.
+--source "<URL, command or file>"`, which akm checks and applies at once.
 A note that is outdated can be marked with `--outdated`, or
 `--superseded-by <ref>` when another note replaces it.
 `--positive` records that an asset helped (it raises its ranking) and does not
@@ -176,9 +175,8 @@ akm secret run secrets/deploy-token GITHUB_TOKEN -- gh release create v1.0.0  #
 
 ## Workflows
 
-Workflows live under `<bundle>/workflows/` as peer `.md` and `.yml` sources.
-Both compile to the same source IR; see `docs/reference/workflow-schema.md` for
-the bounded GitHub-shaped YAML subset.
+Workflows live under `<bundle>/workflows/` as `.md` sources; see
+`docs/reference/workflow-schema.md` for the frontmatter and body syntax.
 
 Ref-based workflow commands are scoped to the current project/worktree/directory,
 so one active run does not block unrelated directories from starting the same
@@ -235,7 +233,6 @@ rename instead of starting fresh, run `bun scripts/rekey-asset-ref.ts <old-ref>
 ## Sync
 
 Commit local changes in a git-backed bundle. Behaviour adapts automatically.
-(`akm save` was the pre-0.8 spelling; it was removed in 0.9.0 — use `akm sync`.)
 
 - **No `.git` directory** — no-op (silent skip)
 - **Git repo, no remote** — stage and commit only (the default bundle always falls here)
@@ -255,15 +252,13 @@ akm sync my-skills -m "Update patterns"      # Sync named bundle with message
 The `--sync` / `--no-sync` and `--push` / `--no-push` flags control this:
 
 ```sh
-akm improve                                   # auto-sync per strategy default (most strategies: on; proactive-maintenance/reflect-distill: off)
+akm improve                                   # auto-sync per strategy default (both strategies: on)
 akm improve --no-sync                         # skip the end-of-run commit
 akm improve --no-push                         # commit but skip push for this run
 akm improve --sync                            # force sync even on strategies that disable it
 ```
 
-Strategy sync defaults: `catchup`, `consolidate`, `default`, `quick`, and
-`thorough` auto-commit + push; `proactive-maintenance` and `reflect-distill`
-skip sync entirely. Override with `--sync` / `--no-sync` flags.
+Strategy sync defaults: `consolidate` and `default` auto-commit + push. Override with `--sync` / `--no-sync` flags.
 
 The `--writable` flag on `akm bundle add` opts a remote git bundle into push-on-sync:
 
@@ -313,7 +308,6 @@ akm config list                               # Show current config
 akm config get <key>                          # Read a value
 akm config set <key> <value>                  # Set a value
 akm config unset <key>                        # Remove a key
-akm config path --all                         # Show all config paths
 ```
 
 ## Other Commands
@@ -331,11 +325,10 @@ akm lint --fix                                # Auto-fix Tier 1 issues
 akm lint --fail-on-flagged                    # Exit non-zero when summary.flagged > 0 (CI-friendly)
 akm upgrade                                   # Upgrade akm using its install method, then update installed harness plugins
 akm upgrade --check                           # Report pending CLI and plugin updates, changing nothing
-akm upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" in its plugin list
+akm upgrade --next                            # Follow prereleases (@next); OpenCode needs "akm-opencode@next" (or "akm-opencode-v2@next" on OpenCode 2) in its plugin list
 akm help migrate 0.6.0                        # Print migration notes for a release (or: latest)
 akm help bundle                               # Print options and subcommands for one command
-akm help agents --full                        # Print this reference
-akm hints                                     # Print this complete agent guide
+akm hints                                     # Print this complete agent guide (--detail brief for the short one)
 akm completions                               # Print bash completion script
 akm completions --install                     # Install completions
 ```
@@ -354,7 +347,7 @@ akm proposal show <id>                                  # Render the proposal bo
 akm proposal diff <ref-or-id>                           # Diff by ref, UUID, or 8-char prefix
 akm proposal diff skills/akm-dream                      # Diff by asset ref
 akm proposal accept 7c115132                            # Accept by UUID prefix
-akm proposal accept <id> --target team-bundle            # Accept to a named writable bundle source
+akm proposal accept <id> --bundle team-bundle            # Accept to a named writable bundle source
 akm proposal reject skills/my-skill --reason "not ready" # Reject by asset ref
 akm proposal reject <id> --reason "..."                 # Archive with a reason
 akm proposal reopen <id> --reason "..."                 # Undo a rejection: back to pending (refused if the target changed)
@@ -364,11 +357,6 @@ akm proposal extract --auto                             # Mine native session fi
 akm proposal extract --type claude                 # Restrict extraction to one harness
 ```
 
-The flat verbs `akm proposals` / `akm show proposal` / `akm accept` /
-`akm reject` / `akm diff` / `akm revert` were removed in 0.9.0 — use the
-`akm proposal <verb>` forms above. `akm extract` and `akm propose` moved
-here as `proposal extract` / `proposal new`.
-
 ## Scheduled Tasks
 
 Tasks are pure-YAML assets at `<bundle>/tasks/<id>.yml`, bound to the OS
@@ -387,7 +375,7 @@ akm task doctor                                # Scheduler binding + runtime eli
 akm task history                               # Recent run rows (status, timing)
 akm task run <id>                              # Run one task immediately (works when disabled)
 akm task explain <ref>                         # Read-only: declared inputs, target, schedule — spawns nothing
-akm search --type task                         # Enumerate task assets (there is no `task list`)
+akm search --type task                         # Enumerate task assets
 ```
 
 Task files use task source v4 (`version: 4`). There is no `akm:` options bag
@@ -428,7 +416,7 @@ akm log --run <run-id>                         # Events for one workflow-engine
 
 ## Output Control
 
-Result-envelope commands accept `--format`, `--detail`, and `--shape` flags:
+Result-envelope commands accept `--format` and `--detail` flags:
 
 - `--format json` (default) — structured JSON
 - `--format jsonl` — one JSON object per line (streaming-friendly)
@@ -439,9 +427,7 @@ Result-envelope commands accept `--format`, `--detail`, and `--shape` flags:
 - `--detail brief` (default) — compact output
 - `--detail normal` — adds tags, refs, origins
 - `--detail full` — includes scores, paths, timing, debug info
-- `--shape human` (default) — standard projection
-- `--shape agent` — agent-optimized output: strips non-actionable fields
-- `--shape summary` — metadata only (no content/template/prompt), under 200 tokens; only `akm show` has a dedicated summary projection — elsewhere it falls back to `agent` with a warning
+- `--detail agent` — agent-optimized output on `search`, `curate` and `show`: strips non-actionable fields (other commands ignore it)
 
 Run `akm help <command>` or `akm <command> -h` for per-command help. Run
 `akm --help` for the sectioned command overview.

package/dist/assets/hints/cli-hints-short.md

@@ -35,13 +35,13 @@ akm remember "note" --bundle my-bundle         # Route write to a named writable
 akm remember "note" --xref knowledge/auth-flow # Cite provenance in frontmatter xrefs (repeatable)
 akm remember "fix" --supersedes memories/old-note # Write a correction AND demote the superseded asset
 akm import ./notes/release-checklist.md       # Import a knowledge doc into your bundle
-akm import ./doc.md --target my-bundle         # Route import to a named writable bundle source
+akm import ./doc.md --bundle my-bundle         # Route import to a named writable bundle source
 akm proposal diff skills/akm-dream            # Diff proposal by ref, UUID, or 8-char prefix
 akm proposal accept 7c115132                  # Accept by UUID prefix
 akm proposal reject skills/my-skill --reason "..."  # Reject by ref
 akm feedback <ref> --positive                 # Record that an asset helped (ranks it higher; no rewrite)
 akm feedback <ref> --negative --reason "..."  # Content wrong or stale: lowers its ranking; improve may repair its frontmatter
-akm feedback <ref> --negative --reason "..." --replace "<exact text>" --with "<fix>" --source "<url|cmd|file>"  # Queue an exact fix of its text
+akm feedback <ref> --negative --reason "..." --replace "<exact text>" --with "<fix>" --source "<url|cmd|file>"  # Apply an exact fix to its text
 akm bundle add <ref>                                 # Add a source (npm, GitHub, git, local dir)
 akm clone <ref>                               # Copy an asset to the working bundle (optional --dest arg to clone to specific location)
 akm sync                                      # Commit (and push if writable remote) changes in the primary bundle (--no-push to commit only)

package/dist/assets/improve-strategies/default.json

@@ -1,5 +1,5 @@
 {
-  "description": "Standard improve pass — reflect (rewrites only from negative feedback), distill, consolidation (promotion plus the reviewed pair-pass retire/supersede proposals), and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract and proactive maintenance off.",
+  "description": "Standard improve pass — reflect (rewrites only from negative feedback), distill, consolidation (promotion plus the reviewed pair-pass retire/supersede proposals), and validation. Memory inference is listed below but only runs when experimental.improveAutonomy is set; improve-stage extract off. Proactive maintenance plans up to 15 assets not reflected or distilled for 30 days.",
   "processes": {
     "reflect": {
       "enabled": true,
@@ -11,8 +11,8 @@
     "memoryInference": { "enabled": true },
     "extract": { "enabled": false, "triage": { "enabled": true, "minScore": 2 } },
     "validation": { "enabled": true },
-    "proactiveMaintenance": { "enabled": false, "dueDays": 30, "maxPerRun": 15 },
-    "triage": { "enabled": false, "applyMode": "queue", "policy": "personal-stash" }
+    "proactiveMaintenance": { "enabled": true, "dueDays": 30, "maxPerRun": 15 },
+    "triage": { "enabled": true, "applyMode": "promote", "maxAcceptsPerRun": 200 }
   },
   "sync": { "enabled": true, "push": true }
 }

package/dist/assets/prompts/consolidate-pair.md

@@ -1,19 +1,21 @@
-You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown. akm deletes one of them only when the other keeps every claim a reader would need, so your two lists decide what is safe to delete.
+You compare two assets from one person's agent-memory library (memories and knowledge notes an AI coding agent reads). Asset A is the OLDER one and asset B the NEWER one, by the dates shown, unless both carry the same date and are labelled "same age". akm deletes one of them only when the other keeps every claim a reader would need, so your two lists decide what is safe to delete.
 
 First list what each asset has that the other lacks:
-- "onlyInA": every durable claim of A that B neither states nor updates.
-- "onlyInB": every durable claim of B that A neither states nor updates.
+- "onlyInA": every durable claim of A that B does not state or replace.
+- "onlyInB": every durable claim of B that A does not state or replace.
 
 A durable claim is a fact, decision, value, command, flag, path, file name, URL, number, version, name, error message, condition or rule someone would act on. Ignore wording, headings, dates of writing, tags and boilerplate. A claim is stated when the other asset says it in any wording or format. It is not stated when the other asset is vaguer (a config file instead of the specific path) or drops a number, command, step or condition. Write each item as a short phrase that quotes its identifier. Use [] when there is nothing.
 
+B replaces a claim of A only when both are about the same named thing (the same service, integration, partner, component, region or file) and B gives a new value for it that is current: B says so (now, instead of, since, renamed, corrected, no longer) or B is created later than A. Notes about different named things never replace each other, whatever their dates: list each one's own name, value and path as its claims. A different value for the same thing with neither sign is a conflict, not a replacement: list A's value in "onlyInA" and B's value in "onlyInB".
+
 Then classify the relation as exactly one of:
 - "duplicate": both lists are empty.
 - "subsumed": exactly one list is empty. The asset with the empty list is redundant.
-- "supersedes": B updates, corrects, reverses or replaces a claim in A (a newer version, a changed decision, a fixed bug, a new value), and onlyInA is empty.
-- "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current.
+- "supersedes": B replaces a claim in A as defined above (a newer version, a changed decision, a fixed bug, a new value), and onlyInA is empty.
+- "contradicts": they make logically exclusive claims about the same thing and nothing shows which one is current: B does not say it replaces the claim and was not created later.
 - "overlap": same subject, and both lists have items.
-- "unrelated": different subjects or different facts that happen to share words.
+- "unrelated": different subjects, or different named things written to one layout (two services, partners or regions), or different facts that happen to share words.
 
 Set "redundant" to the asset that could be deleted with no loss: "A" for "duplicate", the asset with the empty list for "subsumed", "A" for "supersedes"; else null. Set "stale" to "A" when the relation is "supersedes", else null.
 
-Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words: name the asset that can be deleted and what the other asset still holds>"}
+Answer ONLY with JSON: {"onlyInA": ["..."], "onlyInB": ["..."], "relation": "...", "redundant": "A"|"B"|null, "stale": "A"|null, "confidence": 0.0-1.0, "reason": "<at most 25 words: name the asset that can be deleted and what the other asset still holds; for supersedes, quote the words of B that replace the claim or say B is created later>"}

package/dist/assets/stash-skeleton/README.md

@@ -85,7 +85,7 @@ akm feedback <ref> --positive
 # A note that simply did not fit your task gets no negative feedback.
 akm feedback <ref> --negative --reason "<what is wrong and what should change>"
 
-# Once you have verified the correct fact, attach the exact fix: it is checked and queued for review
+# Once you have verified the correct fact, attach the exact fix: it is checked and applied at once
 akm feedback <ref> --negative --reason "<what is wrong>" --replace "<exact current text>" --with "<corrected text>" --source "<URL, command or file>"
 
 # Capture a durable lesson or memory from the current session

package/dist/assets/tasks/improve/akm-improve-consolidate.yml

@@ -1,4 +1,4 @@
 version: 4
-run: akm improve --strategy consolidate --skip-if-locked --require-engines
+run: akm improve --strategy consolidate --timeout-ms 3600000 --skip-if-locked --require-engines
 description: Consolidation-only pass (every 4h at :20)
 schedule: "20 */4 * * *"