akm-cli 0.9.31 → 0.10.261001-beta

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/bundles.md

@@ -250,7 +250,9 @@ akm sync my-skills -m "Update"   # Named writable git bundle
 ```
 
 Push behavior depends on configuration: if the bundle is a git repo with a
-remote and `writable: true`, sync also pushes. Otherwise it commits only.
+remote and `writable: true`, sync first fetches and merges what another host
+pushed, then pushes. A conflicting merge is aborted and the push skipped (your
+commit stays). Otherwise it commits only.
 
 Writes that land on a writable git bundle via an explicit destination flag
 (e.g. `akm remember --bundle my-skills`, proposal accept/revert, consolidate)

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

@@ -28,8 +28,9 @@ rewrite an asset's text. Once you have verified the correct fact, attach the
 exact fix: `--replace "<exact current text>" --with "<corrected text>"
 --source "<URL, command or file that shows it>"` (repeat `--replace`/`--with`
 for several edits). akm checks that each `--replace` text appears exactly once,
-records nothing if one does not, and queues the edit as a `feedback` proposal
-for review. `--positive` records that an asset helped (it raises its ranking)
+records nothing if one does not, and applies the edit at once: no review, no
+gate (the `feedback` proposal it files is accepted on the spot, so
+`akm proposal revert` undoes it). `--positive` records that an asset helped (it raises its ranking)
 and does not trigger a rewrite.
 
 ```sh
@@ -112,12 +113,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 +172,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/scheduling.md

@@ -76,9 +76,17 @@ the command is `akm improve`'s own:
 
 ```sh
 akm task add improve-team --schedule "15 3 * * *" \
-  --command "akm improve --bundle team --skip-if-locked --require-engines"
+  --command "akm improve --bundle team --require-engines"
 ```
 
+Leave `--skip-if-locked` off a once-a-night run: if a short-cadence improve task
+holds the lock when it fires, the run fails with `IMPROVE_LOCK_HELD` (exit 75) and
+is recorded, rather than being silently skipped. Put `--skip-if-locked` on the
+frequent tasks, and give them a `--timeout-ms` that ends before the nightly starts.
+The shipped `improve/akm-improve-consolidate` task does both: it runs at `:20`
+every four hours with `--timeout-ms 3600000`, so the 00:20 run is over by 01:20,
+well before the 02:00 nightly.
+
 ## Rerunning setup preserves scheduler bindings
 
 Rerunning `akm setup` preserves existing scheduler bindings by design — it

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,14 @@ 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 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
@@ -101,3 +108,28 @@ 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