akm-cli 0.9.31 → 0.10.26101002-alpha

package/docs/guides/author-workflows.md

@@ -10,17 +10,11 @@ it's written, see [Running Workflows](../guides/run-workflows.md).
 
 ## Start from the template
 
-Authors can choose peer Markdown or GitHub-shaped YAML sources. Markdown is
-the full AKM authoring format: OKF-conformant frontmatter carries the
-orchestration graph and its body carries instructions and gate rubrics.
-GitHub-shaped YAML is a strict local subset for interoperability. Read the
-[authoritative YAML subset](../reference/workflow-schema.md#github-shaped-yaml-subset)
-before translating an Actions-shaped file; AKM does not accept arbitrary
-GitHub semantics. `.yaml` is not recognized—use `.yml`.
-
-Use `akm workflow create --print` to print a valid Markdown starter, then edit
-it and register it with `akm workflow create`. Author a YAML source directly
-under `workflows/<name>.yml` and validate either source with `akm lint`:
+A workflow is a Markdown file: OKF-conformant frontmatter carries the
+orchestration graph and the body carries instructions and gate rubrics.
+
+Use `akm workflow create --print` to print a valid starter, then edit it and
+register it with `akm workflow create`. Validate with `akm lint`:
 
 ```sh
 akm workflow create my-release --print   # Print the template, without writing
@@ -417,70 +411,46 @@ blast radius before running it.
    [Workflow Schema: Gates and verification](../reference/workflow-schema.md#gates-and-verification)),
    so this is worth confirming once per workflow rather than assuming.
 
-## Composing a task with typed inputs
+## Running a child workflow (Experimental)
 
-A `uses: tasks/<ref>` step in the GitHub-shaped YAML format can bind a task
-source v4 target's declared `inputs:` through `with:`. Given this task:
+A step can run another workflow and use its result. The step names the child
+in its `unit:` bag and binds the child's `params:` with `with:`:
 
-```yaml
-# tasks/ticket-review.yml
-version: 4
-name: Ticket review
-inputs:
-  ticket:
-    type: string
-    required: true
-  scope:
-    type: string
-    enum: [changed, all]
-    default: changed
-uses: commands/review
-```
+```markdown
+---
+type: workflow
+params:
+  topic: { type: string }
+steps:
+  - id: investigate
+    unit:
+      workflow: workflows/research
+      with:
+        topic: { from: params.topic }
+  - id: report
+    inputs: [steps.investigate.output]
+---
 
-a workflow step can bind `ticket` from an EARLIER step's output, and override
-`scope` with a literal:
+## investigate
 
-```yaml
-# workflows/nightly.yml
-name: Nightly review
-on:
-  workflow_dispatch: {}
-jobs:
-  main:
-    runs-on: [self-hosted]
-    steps:
-      - id: pick
-        run: echo T-42
-      - id: dispatch
-        uses: tasks/ticket-review
-        with:
-          ticket: { from: "steps.pick.output" }
-          scope: all
+Runs the research workflow as a child run.
+
+## report
+
+Summarise the research finding.
 ```
 
-`{from: "steps.<id>.output(.<segment>)*"}` and `{from: "params.<name>"}` are
-the only two reference roots; anything else, or an object carrying `from`
-plus any other key, is `INPUT_BINDING_INVALID` at freeze — never silently
-reinterpreted as a literal. `pick`'s output is resolved just before the
-`dispatch` unit dispatches, then validated against `ticket`'s declared
-schema; a literal (like `scope: all` here) is validated at freeze instead,
-before the plan is ever published.
-
-The composed target — `commands/review` here — receives the resolved
-bindings on whichever delivery surface matches its kind: an
-`akm/command`/`commands/<ref>` target gets a `## Task inputs` block appended
-to its prompt; a `run:` shell or `scripts/<ref>` target gets one
-`AKM_TASK_INPUTS` environment variable (canonical JSON of the resolved
-bindings). Inspect exactly what each step's `with:` would deliver, without
-running anything, with `akm workflow plan workflows/nightly --format json`
-— its per-step `inputBindings` show `dispatch`'s `scope` as the literal
-`all` and `ticket` as the unresolved reference `steps.pick.output`, the
-same shape freezing a real run would produce. `akm task explain` is not a
-substitute here: it only reflects a task's OWN CLI flags, declared
-defaults, and `schedule[].inputs` — it never reads a workflow step's
-`with:` binding at all, so pointing it at `tasks/ticket-review` prints
-`scope`'s task-level default (`changed`), not the `all` this step actually
-sends.
+A `with:` value is a literal (checked against the child's param type when the
+workflow is frozen) or `{ from: <reference> }`, where the reference is
+`params.<name>` or `steps.<id>.output(.<segment>)*`, resolved just before the
+step runs. The child's **last step output** is the composing step's output, so
+`report` reads it through `inputs:`. Inspect what a step would pass, without
+running anything, with `akm workflow plan workflows/<name> --format json`; the
+per-step `inputBindings` show each literal and each unresolved reference.
+
+Child workflows are Experimental. See
+[Workflow Schema: Child workflows](../reference/workflow-schema.md#child-workflows)
+for blocked-child recovery and the limits.
 
 ## Troubleshooting
 

package/docs/guides/capture-knowledge.md

@@ -71,7 +71,7 @@ akm import - --name scratch-notes < notes.md
 akm import https://example.com/docs/auth
 
 # Route to a named writable bundle:
-akm import ./docs/auth-flow.md --target team-bundle
+akm import ./docs/auth-flow.md --bundle team-bundle
 ```
 
 Both commands accept `--xref <ref>` to cross-reference related assets and

package/docs/guides/claude-code-vs-akm-workflows.md

@@ -5,8 +5,7 @@ out inside the current session — an in-context script or tool that spawns
 subagents, runs them concurrently, and reports back before the session ends.
 AKM workflows are a different thing: a portable procedure that any supported
 agent harness can run, with durable state, retries, gates, and resume built
-in. Peer workflow sources are Markdown `.md` and GitHub-shaped YAML `.yml`;
-both adapters lower to source IR version 1. Every run freezes the durable plan
+in. A workflow source is Markdown `.md`, lowered to source IR version 1. Every run freezes the durable plan
 v4 family's executable `irVersion: 5` before execution; pre-`irVersion`-5
 stored plans are rejected.
 Neither replaces the other — they solve different problems, and the right

package/docs/guides/discover-and-load.md

@@ -14,7 +14,7 @@ whether a script, a workflow, or a skill covers this, so it starts broad,
 narrows to a ref, and loads that ref's content:
 
 ```sh
-akm curate "deploy the app to staging" --shape agent
+akm curate "deploy the app to staging" --detail agent
 # → ranked shortlist; top hit: {"type":"script","ref":"scripts/deploy.sh","score":0.91,...}
 
 akm show scripts/deploy.sh
@@ -40,7 +40,7 @@ curate when you know what you're trying to do.
 (BM25) and semantic (vector) matches fused into one list:
 
 ```sh
-akm search "deploy" --type script --shape agent
+akm search "deploy" --type script --detail agent
 # → [{"type":"script","name":"deploy.sh","ref":"scripts/deploy.sh","score":0.0328,...}]
 ```
 
@@ -53,7 +53,7 @@ akm curate "review an architecture proposal" --type skill
 # → ranked shortlist with akm show skills/code-review as the top follow-up
 ```
 
-Use `--shape agent` on either command to get the `ref`/`path`/`editable`
+Use `--detail agent` on either command to get the `ref`/`path`/`editable`
 fields an agent needs to act on a hit. See [CLI Reference](../reference/cli.md)
 for the full flag tables and exact output-field lists per `--detail` level.
 
@@ -145,7 +145,7 @@ its ranking) and does not trigger a rewrite.
 
 ## 7. Reference links
 
-- [CLI Reference](../reference/cli.md) — full `--detail`/`--shape` flag
+- [CLI Reference](../reference/cli.md) — full `--detail` flag
   semantics, complete flag tables, and exact output-field lists for `search`,
   `curate`, `show`, and `index`
 - [Architecture](../architecture/architecture.md) — ranking and search

package/docs/guides/getting-started.md

@@ -162,7 +162,7 @@ your agent the payload; running it is a deliberate next step.
 ## 7. Tell your agent about akm
 
 ```sh
-akm help agents >> AGENTS.md
+akm hints --detail brief >> AGENTS.md
 ```
 
 **Success check:** `AGENTS.md` now has a block of agent-facing usage

package/docs/guides/improve-the-library.md

@@ -112,12 +112,12 @@ It also skips a memory whose only feedback in that window is a positive with no
 reason or note: say what helped (`--reason`), or the lesson has nothing to
 distil.
 Unless `--require-feedback-signal` is set,
-two fallback lanes pick assets with no such feedback: high-salience assets that
-were never reflected, and, in a strategy that enables proactive maintenance,
-assets due for a revisit. They only select and score assets and plan nothing,
-so improve does not rewrite on a proactive cadence. The planned assets are
-ranked by salience and cut to `--limit`.
-Improve reworks only what gets read: without fresh feedback, a fallback lane
+the proactive-maintenance lane (on in `default`) also plans assets with no such
+feedback that are due for a revisit: at most 15 per run
+(`processes.proactiveMaintenance.maxPerRun`), and only assets not reflected or
+distilled for 30 days (`dueDays`), so each comes up at most once a month. The
+planned assets are ranked by salience and cut to `--limit`.
+Improve reworks only what gets read: without fresh feedback, the lane
 picks an asset (and a memory is judged for consolidation) only if `search`,
 `curate` or `show` returned it, or feedback named it, in the last 90 days — the
 usage log's retention — or if it is new material no improve stage has processed
@@ -171,7 +171,7 @@ akm proposal diff <id>                          # Preview the change vs. the liv
 
 # Apply or discard
 akm proposal accept <uuid-or-prefix>
-akm proposal accept skills/akm-dream --target team-bundle
+akm proposal accept skills/akm-dream --bundle team-bundle
 akm proposal reject <uuid-or-prefix> --reason "duplicates existing workflow"
 ```
 

package/docs/guides/recipes/headless-install.md

@@ -31,7 +31,7 @@ akm info
 akm search "test"
 
 # 7. Install agent guidance
-akm help agents >> AGENTS.md
+akm hints --detail brief >> AGENTS.md
 
 echo "akm setup complete"
 ```
@@ -85,7 +85,7 @@ indexing.
 `indexStats.entryCount` and `semanticSearch.status`; `akm search "<query>"`
 confirms retrieval actually returns results.
 
-**Install agent guidance.** `akm help agents >> AGENTS.md` appends the
+**Install agent guidance.** `akm hints --detail brief >> AGENTS.md` appends the
 canonical usage block agents need to discover and use the library. Run this
 after indexing so the guidance matches the installed version.
 

package/docs/guides/run-workflows.md

@@ -21,7 +21,7 @@ projects.
 
 Every new run/start compiles source IR v1 and freezes the durable plan v4
 family's current executable format (`irVersion: 5`) before publishing the run.
-Markdown `.md` and GitHub-shaped `.yml` refs use the same freeze path.
+A workflow ref is a Markdown `.md` source.
 
 ```sh
 akm workflow run workflows/ship-release --version 1.2.3

package/docs/guides/use-with-any-agent.md

@@ -26,7 +26,7 @@ For a longer, agent-facing instruction block — usage patterns, flag guidance,
 the full ref format — generate one instead of hand-writing it:
 
 ```sh
-akm help agents >> AGENTS.md
+akm hints --detail brief >> AGENTS.md
 ```
 
 The output is stable across patch releases and designed for agents rather
@@ -50,7 +50,7 @@ akm show workflows/deploy-to-prod
 akm feedback workflows/deploy-to-prod --positive --reason "Completed without issues"
 ```
 
-**Get refs from search.** Agents should call `akm search --shape agent` or
+**Get refs from search.** Agents should call `akm search --detail agent` or
 `akm curate` to discover refs — not guess them. The `ref` field in search
 results is the stable token to pass to `akm show`. Feedback closes the loop.
 Record `--negative` only when the asset's content is wrong or stale; a note that
@@ -70,7 +70,7 @@ sets expectations by environment.
 
 | Environment | Core support | Optional/extended support |
 | --- | --- | --- |
-| Shell-capable coding agent | `curate` / `show` / `feedback` via the CLI | Generated prompt block (`akm help agents`) or a platform plugin |
+| Shell-capable coding agent | `curate` / `show` / `feedback` via the CLI | Generated prompt block (`akm hints`) or a platform plugin |
 | Claude/OpenCode project layout | Indexed in place through a `BundleAdapter` — no migration needed | `akm clone` selected assets into a writable bundle for editing |
 | IDE assistant without shell access | Not a direct core integration | Requires a plugin, an `akm task`, or an external bridge that can shell out on the assistant's behalf |
 
@@ -118,12 +118,57 @@ than replacing either.
   browsing, automatic context injection — but the core `akm` CLI works
   without them.
 
+## OpenCode plugins: one package per OpenCode major
+
+OpenCode 1 and OpenCode 2 load different plugin APIs, so akm ships one plugin
+package for each. Install only the one that matches the `opencode` you run; akm
+never installs or replaces the `opencode` binary, and `akm upgrade` never adds
+one plugin to the other major's config.
+
+| OpenCode | Plugin package | Config key | Plugin cache |
+| --- | --- | --- | --- |
+| 1 | `akm-opencode` | `"plugin"` | `~/.cache/opencode/packages/akm-opencode@<tag>/` |
+| 2 | `akm-opencode-v2` | `"plugins"` (the key `opencode plugin add` writes) | `~/.cache/opencode/npm/akm-opencode-v2@<tag>/<build>/` |
+
+(`$XDG_CACHE_HOME` and `$XDG_CONFIG_HOME` move both.) Both packages declare the
+same `akm-cli` dependency.
+
+**OpenCode 1.** Add `akm-opencode` to the global config
+(`~/.config/opencode/opencode.json`):
+
+```json
+{ "plugin": ["akm-opencode"] }
+```
+
+**OpenCode 2.**
+
+```sh
+opencode plugin add akm-opencode-v2
+```
+
+This installs the package and adds it to `plugins` in the global config.
+
+**Updating.** `akm upgrade` refreshes the cached plugin of each major it finds,
+holds the CLI to the `akm-cli` those plugins pin, and leaves a plugin alone
+whose config pins another spec such as `akm-opencode@0.8.0`. Use
+`akm upgrade --next` with `akm-opencode@next` / `akm-opencode-v2@next` in the
+config to follow prereleases. The exact rules are in the
+[`akm upgrade` reference](../reference/cli.md#harness-plugins). `akm health`
+warns when either plugin's bundled `akm-cli` differs from the running CLI.
+
+**Which OpenCode akm drives** is detected, not configured: an `opencode` or
+`opencode-sdk` agent engine runs the most recent OpenCode on `PATH` (or its own
+`bin`) and uses the adapters for the major that binary reports; OpenCode 1 logs a
+warning recommending OpenCode 2 (see
+[Configuration](../reference/configuration.md#engines)). It does not change
+which plugin you install, and the plugin choice does not change it.
+
 ## See also
 
 - [Configuration](../reference/configuration.md#engines) — named agent engines and model aliases
 - [Discover and Load](discover-and-load.md) — the full curate → show retrieval path
 - [Knowledge Management](knowledge-management.md) — capturing agent-generated memories
 - [Improve the Library](improve-the-library.md) — feeding back usage signals
-- [CLI Reference](../reference/cli.md) — `completions`, `agent`, and `help agents` command documentation
+- [CLI Reference](../reference/cli.md) — `completions`, `agent`, and `hints` command documentation
 - [Concepts](concepts.md) — refs, origins, and the asset type system
 - [Bundle Types](../reference/bundle-types.md) — how AKM indexes existing project layouts in place

package/docs/integration/bundling-akm.md

@@ -30,10 +30,11 @@ akm migrate apply
 In order, every run applies (or, under `status`/`--dry-run`, plans):
 
 1. **config.json in its current shape** (`configFile`): retired and unknown
-   keys dropped, legacy `extraParams` lifted onto first-class fields, the
-   legacy `stashDir`/`sources[]`/`installed` layout converted to
-   `bundles`/`defaultBundle`. Config loading already does all of this in
-   memory; this persists it under a backup.
+   keys dropped, `configVersion` set. Config loading already does this in
+   memory; this persists it under a backup. A config older than 0.9.15 (the
+   legacy `stashDir`/`sources[]`/`installed` layout, an `extraParams` key
+   that shadows a first-class field) is not converted by 0.10: it blocks
+   with a message to run `akm migrate apply` under akm 0.9.x first.
 2. **Pending `state.db` migrations**, historical-destructive ones included
    (`stateMigrations`). This is the only path (besides `akm upgrade`, which
    calls the same code) that is allowed to apply a destructive migration to an
@@ -98,7 +99,7 @@ same step names):
 `status` is one of:
 
 - **`current`** — no task-source file needs converting, and no config
-  extraParams lift is pending. A no-op boot.
+  rewrite is pending. A no-op boot.
 - **`ready`** — task sources have eligible changes and no config-lift
   conflict; a real `apply` will clear them.
 - **`blocked`** — at least one item cannot be applied automatically (a
@@ -244,7 +245,7 @@ akm-migrate apply
 
 `akm migrate status`/`apply` (under the `akm` CLI) are a thin wrapper over
 this same executable — same plan, same exit codes. Reach for `akm-migrate`
-directly when you don't want `akm`'s `--format`/`--shape`/`--detail` output
+directly when you don't want `akm`'s `--format`/`--detail` output
 handling in the way, e.g. a shell script that just wants the raw JSON line
 on stdout and a plain exit code.
 

package/docs/maintainers/curate-workmap.md

@@ -197,8 +197,7 @@ Important details:
 
 - `curate` has a dedicated output shaper now
 - `brief` still keeps `followUp` and `reason`
-- `--shape agent` trims fields down for agent use
-- `--shape summary` is rejected on `curate`
+- `--detail agent` trims fields down for agent use
 - text output prints fixed `Next steps:` guidance that assumes `akm show <ref>` is the next action
 
 ## Telemetry And Retrieval Signal

package/docs/maintainers/release-checklist.md

@@ -6,7 +6,13 @@ run of the exact commit that will be published.
 
 ## 1. Freeze the candidate
 
-1. Finish the version, changelog, migration-note, and release-PR changes.
+1. Finish the version, changelog, migration-note, and release-PR changes. From
+   0.10 the version is a daily build, `0.10.YYMMDDNN` (see step 4):
+   `bun scripts/release-version.ts next` prints the next free one for today
+   (UTC). Commit it in `package.json` and cut the CHANGELOG as
+   `## [0.10.YYMMDDNN] - YYYY-MM-DD`. A prerelease stage is not committed: it is
+   chosen when the Release workflow runs, and a stage of a build is covered by
+   that build's CHANGELOG section.
 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
@@ -101,3 +107,26 @@ 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 daily builds, `0.10.YYMMDDNN`: `YY` the UTC year, `MM` the
+month, `DD` the day and `NN` the build that day (`01` to `99`), two digits each
+(see [`STABILITY.md`](../../STABILITY.md)). The first build on 2026-10-10 is
+`0.10.26101001`. `bun scripts/release-version.ts next` takes `NN` as one above
+the highest build already on npm for today's UTC date (`npm view akm-cli
+versions`), so numbering follows what was published, not what was committed.
+
+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`, `DD`, `NN`, a
+  real calendar date, `NN` 01 to 99. For 0.9 and older it is the `X.Y.Z` as
+  before.
+- `stage`: `none` publishes the build itself 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`: the build number already differs per
+  build). Promote one build by running the workflow again with the same
+  `version` and the next stage, then with `none`. The order is
+  `-alpha` < `-beta` < `-rc` < the build.
+
+`bun scripts/release-version.ts validate <version>` checks a version by hand.

package/docs/posts/akm-command-tour.md

@@ -99,7 +99,7 @@ Use this to inspect or change settings.
 ```sh
 akm config get output.format
 akm config set output.detail full
-akm config path --all
+akm info
 ```
 
 Real-world use: your agent prefers text output in one repo and JSON in another, or you want to set a default write target for memories and imports.
@@ -404,12 +404,12 @@ akm help migrate latest
 
 Real-world use: you upgraded `akm` and want the release-specific migration notes without leaving the terminal.
 
-### `akm help agents`
+### `akm hints`
 
 Print instructions you can drop into `AGENTS.md` or `CLAUDE.md`.
 
 ```sh
-akm help agents
+akm hints
 ```
 
 Real-world use: you want every project to tell its coding agent how to use the local `akm` installation.

package/docs/product-surface.md

@@ -28,7 +28,7 @@ Every akm feature, with its status. Status meanings are in
 - [`akm improve` and proposals](guides/improve-the-library.md): reviewable changes from feedback and usage. *Evolving*
 - Improve settings and strategies other than `default` and `consolidate`. *Experimental*
 - Automatic acceptance (opt-in). *Experimental*
-- Session extraction. *Experimental*
+- Session extraction. *Evolving*
 
 ## Monitor
 

package/docs/reference/README.md

@@ -2,6 +2,7 @@
 
 Authoritative reference documentation for the akm CLI and its data.
 
+- [Programmatic API](api.md) -- `akm-cli/api`: in-process `curate()` for the akm plugins
 - [Bundle Types](bundle-types.md) -- Supported bundle formats and compatibility
 - [CLI](cli.md) -- All `akm` commands and flags
 - [Configuration](configuration.md) -- Engines, strategies, bundles, and settings

package/docs/reference/api.md

@@ -0,0 +1,65 @@
+# Programmatic API (`akm-cli/api`)
+
+`akm-cli` is a CLI package. The one supported programmatic entry point is
+`akm-cli/api`, which exists so the akm plugins (OpenCode, Claude Code, ...) can
+do their automatic recall in-process instead of starting an `akm` process per
+prompt. Everything else in the package stays CLI-only: deep imports of
+`akm-cli/dist/*` are not an API, and the CLI is still the way to run every
+other command.
+
+```ts
+import { curate } from "akm-cli/api";
+
+const text = await curate("deploy to prod", { limit: 4, type: "skill", format: "text" });
+```
+
+## `curate(query, options?)`
+
+```ts
+function curate(
+  query: string,
+  options?: { limit?: number; type?: string; format?: "text" | "json" },
+): Promise<string>;
+```
+
+- **Result.** Exactly the stdout of
+  `akm --detail agent -q curate <query> [--limit N] [--type T] --format <format>`,
+  including the trailing newline, computed in-process. `format` defaults to
+  `"json"`, as the CLI does. It runs the same code as the command (argument
+  validation, search, ranking, shaping and rendering are shared, not copied), so
+  the two cannot drift.
+- **Failure.** It rejects with an `Error` whose `message` is the CLI's error
+  text and whose `code` is the CLI's error code (`MISSING_REQUIRED_ARGUMENT`,
+  `INVALID_FLAG_VALUE`, `INVALID_CONFIG_FILE`, ...) wherever the CLI would have
+  failed. An unexpected internal failure rejects with a plain `Error` without a
+  `code`.
+- **No side effects on the host.** No child process; nothing is written to
+  stdout or stderr; `process.chdir` is never called; `process.env` and
+  `process.argv` are not modified; the host's quiet and verbose state is
+  unchanged afterwards. As with `akm curate`, the call records its usage
+  event in `state.db`.
+- **Repeated calls.** Config is re-validated against `config.json` on every
+  call (its path, size and modification time), so an edit on disk is seen by
+  the next call exactly as a separate CLI run would see it. Database handles are
+  opened and closed within each call. The local embedding model and the embedding
+  cache are kept for the life of the process, which is what makes a warm call
+  cheaper than a CLI run. Overlapping calls are safe. Under Bun the SQLite file
+  descriptors of a finished call are released when the garbage collector
+  finalizes its statements, so they can briefly outlive the call.
+
+## Loading it
+
+`package.json` `exports` maps `akm-cli/api` to `dist/api.js` under Bun and to
+`dist/api-node.mjs` under Node (which registers the loader hook for the
+package's embedded `.md`/`.xml` assets before loading `dist/api.js`), with
+`dist/api.d.ts` for types. `akm-cli/package.json` and `akm-cli/dist/*` are also
+exported, so a plugin can locate the `akm` bin with
+`require.resolve("akm-cli/package.json")` and published plugin versions that
+deep-import `akm-cli/dist/commands/read/*.js` keep working.
+
+## Stability
+
+Evolving (see [STABILITY.md](../../STABILITY.md)): the export list only grows,
+and `curate()`'s parameters and result keep the contract above; the text it
+returns is the CLI's agent-shaped output and changes whenever that does.
+`tests/contracts/api-surface.test.ts` pins the export list.

package/docs/reference/asset-types.md

@@ -40,7 +40,7 @@ my-bundle/
   instructions/   # Project guidance (.md)
   env/            # Environment files (.env) — groups of related config, loaded whole
   secrets/        # Secrets — one sensitive value per file (auth tokens, keys, certs)
-  workflows/      # Peer workflow sources (.md and .yml)
+  workflows/      # Workflow sources (.md)
   lessons/        # Distilled lessons (.md, see akm improve / proposals)
   memories/       # Recalled context fragments (.md, see Memory reference)
   facts/          # Durable bundle-level facts (.md)
@@ -60,10 +60,8 @@ Scripts and knowledge are classified by **what they are**: a `.sh` file is a
 script; a plain `.md` file is knowledge. Commands and agents are classified
 by **how an LLM should use them**: a `.md` file with `$ARGUMENTS`
 placeholders is a command template; one with `tools` in its frontmatter is an
-agent definition. Workflow assets may be `.md` or `.yml`: Markdown is
-classified by `type: workflow` or placement, while the GitHub-shaped YAML
-adapter validates the closed workflow subset. These are peer workflow sources,
-not an md-only surface. Skills are a
+agent definition. Workflow assets are `.md`, classified by `type: workflow`
+or placement. Skills are a
 **packaging convention**: a directory containing a `SKILL.md` file.
 
 See [Classification](../architecture/internals/classification.md) for the

package/docs/reference/bundle-types.md

@@ -3,8 +3,7 @@
 This page has moved. AKM's bundle-format documentation is now split in two:
 the public compatibility table lives at
 [Supported Formats](supported-formats.md), and the adapter internals — probe
-order, the `BundleAdapter` interface, `placeNew()` wiring status, and the
-write allowlists — live at
+order, the `BundleAdapter` interface, and the write allowlists — live at
 [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md).
 
 - [Supported Formats](supported-formats.md) — the format-by-format table:
@@ -13,7 +12,6 @@ write allowlists — live at
   `llm-wiki`, `claude`, `opencode`, `agent-skills`, `dotenv`,
   `akm-workflow`, `akm-task`, `website-snapshot`, `generic-files`).
 - [Architecture → Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks an
-  adapter for a bundle, the `BundleAdapter` interface contract, the current
-  `placeNew()` wiring status, the write allowlists that actually gate
+  adapter for a bundle, the `BundleAdapter` interface contract, the write allowlists that actually gate
   `akm remember`/`import`/`proposal accept`/etc., and per-adapter
   implementation caveats.