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

package/CHANGELOG.md

@@ -6,6 +6,343 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+### Added
+
+- **Workflow orchestration engine (experimental).** akm can now execute
+  multi-step workflows as deterministic **YAML programs**, driven either by a
+  native engine or by any agent session. This is a new, self-contained
+  surface; classic linear **markdown workflows and the stable workflow CLI
+  contract (`start`/`next`/`complete`/`status`/`list`) are unchanged**. What
+  ships:
+  - **Authoring.** Orchestrated workflows are YAML programs
+    (`workflows/*.yaml`, `version: 2`) validated against a published JSON
+    Schema (`schemas/akm-workflow.json`) by `akm workflow validate`; scaffold
+    one with `akm workflow template --yaml` or `akm workflow create
+    <name>.yaml`. A closed `${{ … }}` expression language (exactly
+    `params.<name>`, `steps.<id>.output.<path>`, `item`, `item_index`, parsed
+    once into an AST) wires steps together. `validate` also surfaces non-fatal
+    **warnings** (a step with no typed `output:` schema; a `${{ params.<name> }}`
+    reference to a param the declared `params:` block omits) that never change
+    the frozen plan or its hash. Creating a workflow whose canonical name
+    collides with an existing asset of a **different** extension (`foo.yaml`
+    while `foo.md` exists, or vice-versa) is refused, since the two would
+    silently shadow each other.
+  - **Compilation + frozen plans.** `akm workflow start` compiles the program
+    into a backend-agnostic Workflow Plan Graph IR (`src/workflows/ir/`) and
+    freezes it on the run row (`plan_json` + `plan_hash`); a run executes the
+    plan compiled at start, and edits to the source file require a new run.
+  - **Per-step orchestration.** A step can declare an engine, model, timeout,
+    fan-out (`map`/`over` with a `concurrency` cap and a `collect` | `vote`
+    reducer), a typed `output` JSON Schema (validated via a `runStructured`
+    retry-with-feedback loop), `env` bindings (resolved through the existing
+    `akm env run` machinery — secret tokens, dangerous-key policy, keys-only
+    audit events), classify-and-dispatch `route` steps, and `depends_on`
+    ordering.
+  - **Determinism + replay.** Journaled unit identity is content-derived
+    (`<step>:<sha256(item)[:12]>`, `:solo` for a single unit), so cached
+    results survive item-list reordering; a completed unit whose recorded
+    inputs differ on replan is a hard **replay-divergence** failure naming the
+    unit, never a silent re-dispatch. Every unit is recorded in the new
+    `workflow_run_units` table behind a serialized writer queue.
+  - **Execution (`akm workflow run`).** A semaphore-bounded scheduler fans a
+    step's units out (concurrency defaults to 1 per the local-model
+    LLM-defaults rule and is the minimum of the map request, frozen workflow
+    limit, selected frozen LLM engine limit, and current host safety limit),
+    enforces per-unit
+    timeouts (default 10 m) and run **budget ceilings** (`budget.max_tokens` /
+    `budget.max_units`, seeded from the journal so they span resumes), and
+    advances the run **strictly through `completeWorkflowStep`** so completion
+    gates are never bypassed. Every dispatched unit gets a standard akm
+    preamble (run/unit ids, knowledge + env/secret + reporting contract).
+  - **Typed artifacts + honest gates.** A step's promoted artifact is
+    validated against its declared `output` schema before completion; a
+    criteria-bearing gate judges that **artifact** (canonical JSON, clipped)
+    rather than machine prose, and each engine-driven evaluation is journaled
+    as a gate unit row. `gate.max_loops` bounds an evaluator-optimizer retry
+    loop (feedback threaded into re-dispatched unit prompts); `gate.required`
+    (or the run-wide `--require-gates`) makes a gate with no available judge
+    **block** for a human instead of failing open.
+  - **Failure policy.** Per-unit `on_error: fail | continue` (fail-fast
+    default) plus bounded `retry: { max, on: [<failure_reason>…] }` keyed on
+    the persisted failure taxonomy.
+  - **Isolation + leases.** `isolation: worktree` runs each file-mutating unit
+    in a fresh detached git worktree (journaled path; clean trees
+    auto-removed, dirty ones retained). A run **lease** (`engine_lease_*`)
+    ensures a run is driven by exactly one engine or one external driver at a
+    time; manual `complete` is refused while a live engine lease is held.
+  - **Harness-neutral driver protocol.** An orchestrated run can be driven by
+    ANY agent session (Claude Code, opencode, Codex, a human at a shell), not
+    only the native engine. **`akm workflow brief <run>`** is read-only (takes
+    no lease, mutates nothing) and emits the active step's expected work-list —
+    per-unit content-derived id, resolved instructions + input hash
+    (byte-identical to the engine's dispatch), output schema, env binding
+    NAMES only, and the exact `report` command lines. **`akm workflow report
+    <run> --unit <id> --status completed|failed|running`** is the one mutating
+    verb, ingesting a unit's result through the SAME shared step semantics the
+    engine uses (idempotent same-hash re-report, replay-divergence on a
+    differing hash, budget enforcement, schema validation, and the
+    artifact-judged gate/`max_loops` completion path). `--status running`
+    claims/heartbeats a unit for stale-driver detection without advancing the
+    spine; `--rerun` records a fresh attempt for a failed unit (carrying its
+    prior token total forward). Every report command carries `--expect-step`
+    (refused if the spine has moved since the brief), and `report --settle`
+    (no `--unit`) advances a step that dispatches no reportable units — a
+    params-only route, an empty fan-out, or an all-unresolvable work-list — so
+    a driver is never wedged. The engine and the brief/report surfaces are
+    proven to produce **identical unit graphs**
+    (`tests/workflows/conformance/driver-parity.test.ts`).
+  - **Observability.** `akm workflow watch <run>` tails the run's `workflow_*`
+    / `workflow_unit_*` events as NDJSON (`--stream` foreground-polls to a
+    terminal status, no daemon); `akm workflow status --units` lists per-unit
+    diagnostics (failure reason + result/error text) without feeding them into
+    the deterministic artifact graph; unit lifecycle emits
+    `workflow_unit_started` / `workflow_unit_finished` events carrying
+    ids/status/enums only. `akm show workflow:<name>` summarizes each step's
+    orchestration.
+  - **Harness adapters.** Seven local coding-agent CLIs are first-class
+    dispatch targets — Codex, Copilot CLI, Pi, Gemini, Aider, Amazon Q, and
+    OpenHands — each registered in `HARNESS_REGISTRY` with a command builder +
+    result extractor; agent-identity detection and the session-log provider
+    list are derived from the registry, and harness-native session ids are
+    journaled opportunistically for future session reuse.
+  - **Storage.** Additive `workflow.db` migrations 004–010 (unit journal,
+    harness session ids, frozen plans + run leases, check-in heartbeats,
+    attempt counter, unit claims); migrations 001–003 are untouched and linear
+    workflows behave exactly as before.
+
+  See "Orchestrated steps" and "Driving a run from any agent" in
+  `docs/features/workflows.md`, the redesign addendum in
+  `docs/archive/akm-workflows-orchestration-plan.md`, and `STABILITY.md`
+  (Experimental).
+- **`fable` built-in model alias** — resolves to `claude-fable-5`
+  (`opencode/claude-fable-5` on opencode); recommended resolution target for
+  the `deep` workflow model tier.
+- **`akm lint` now checks the frontmatter xref channels for broken refs.**
+  The existing `missing-ref` check additionally scans the `xrefs:`,
+  `supersededBy:`, and `contradictedBy:` frontmatter keys of non-wiki markdown
+  assets (memories, knowledge, lessons, facts, agents, commands, skills,
+  workflows) — the channels the stash back-linking conventions route
+  provenance and correction links through, and previously the only ref channel
+  with zero checking. Dangling refs are flagged with a detail naming the key
+  (`missing ref: <ref> (frontmatter <key>; resolved to <relPath>)`). The
+  `refs: []` body-scan carve-out does not suppress the new pass; `lint_skip:
+  [missing-ref]` suppresses both; non-ref values (URLs, `raw/<slug>`,
+  `<placeholder>` templates, shell vars) are ignored; refs resolving in a
+  configured extra stash root stay clean. **Note for `--fail-on-flagged` CI
+  users:** stashes with already-dangling xrefs (e.g. from past renames) will
+  gain new `missing-ref` findings on upgrade — fix the refs or add
+  `lint_skip: [missing-ref]` per file. `sources:`, `source_refs:`, and
+  `evidenceSources:` are deliberately not checked (wiki `sources:` is covered
+  by `akm wiki lint`; the latter two legitimately point at merged-away
+  assets).
+- **`--xref <ref>` on `akm remember` and `akm import` — write-time
+  cross-references with validation.** The stash back-linking conventions route
+  provenance and associative links through `xrefs:` frontmatter, but neither
+  CLI write flow could express them (remember always generated its own
+  frontmatter block; import wrote content verbatim). The new repeatable flag
+  records refs in the written asset's `xrefs:` frontmatter list, which the
+  indexer folds into search hints — the new asset becomes findable from
+  searches for its source. `remember` merges the refs into its generated
+  frontmatter (composes with `--tag`/scope flags; does not trigger the
+  tags-required check); `import` dedupe-appends into the document's existing
+  frontmatter, or adds a block when the document has none — never a nested
+  second block. A document whose existing frontmatter is not a parseable YAML
+  mapping aborts the import (exit 2, nothing written) rather than being
+  rewritten lossily; importing it without `--xref` still preserves it
+  verbatim. Every ref is validated before anything is written, against the
+  write target plus all configured sources (read-only cross-stash sources
+  count): an unresolvable ref fails with the standard usage envelope (exit 2)
+  and leaves the stash untouched. The conventions' ~5-xref cap stays soft —
+  exceeding it warns on stderr but still writes. Additionally, a type-root
+  write (no `--path`, flat name) into a stash carrying convention facts now
+  returns an additive `hint` output key pointing at the stash's placement
+  conventions (`fact:conventions/organization` when that fact exists), so CLI
+  writers see the conventions that LLM flows already receive by injection.
+- **`--supersedes <ref>` on `akm remember` and `akm import` — atomic
+  correction + demotion of the superseded asset.** The stash conventions'
+  corrections pattern needs TWO writes (the new correction asset with an xref
+  to what it corrects, plus a metadata edit demoting the old asset), which
+  previously meant hand-editing the old file's frontmatter and remembering to
+  reindex it. The new repeatable flag does both: the correction is written
+  with the old ref folded into its `xrefs:` (correction provenance), and the
+  old asset gains `beliefState: superseded` +
+  `supersededBy: [<new ref>]` via the shared `writeSupersededEdge` primitive
+  (sibling of `writeContradictEdge`) — a metadata-only frontmatter edit that
+  preserves every other key and the body byte-for-byte, sorted-set-appended
+  and idempotent across re-runs. The mutated old file is reindexed by the
+  write path, so `--belief current` hides it and ranking demotes it
+  immediately. An unresolvable ref is input validation: exit 2 with the
+  standard `{ok:false,error,code}` envelope and NOTHING written or demoted
+  (no partial correction); a ref resolving to the asset being written itself
+  (self-supersede via `--force` overwrite) is rejected the same way instead
+  of letting a correction demote itself. An old asset that resolves only
+  outside the write target and the working stash (in a read-only source, or
+  in a writable source that is not this write's target) is not mutated: the
+  correction still writes, stderr warns, and the JSON output reports the
+  additive `superseded: [{ref, applied: false, reason}]` key (`applied: true`
+  on success) — the reason names the `--target` remedy when one exists. An
+  old asset whose existing frontmatter is not parseable YAML is likewise
+  skipped (`applied: false`) rather than rewritten through the lossy lenient
+  parser. On a git write target the demotion is ordered before the
+  batch-at-boundary commit, so the correction and the demoted old asset land
+  in one commit.
+- **Ref-prefix search queries — `akm search "<type>:<prefix>/"` now enumerates
+  that subtree.** A query shaped like a ref prefix (trailing slash required:
+  `memory:projectA/`; a bare `memory:` lists the whole type) translates to a
+  typed index enumeration narrowed to entry names under the prefix, instead of
+  degenerating into the AND-token FTS query its sanitized form used to produce
+  (`"memory projectA"` — noise, since `entry_type` is not an FTS column). The
+  listing is recursive and `/`-boundary exact (`projectA/` cannot leak a
+  sibling `projectAlpha/…` scope), matches names case-insensitively (the CLI
+  lowercases queries; on-disk scope directories may carry mixed case), and
+  composes with `--limit`, `--belief`, `--filter`, and named `--source`
+  narrowing exactly like the existing empty-query enumeration — hits carry the
+  fixed browse score `1` in deterministic listing order, not a relevance
+  ranking. The parsed type is explicit intent: a bare `session:` enumerates
+  sessions just like `--type session` (the default session exclusion is an
+  untyped-path policy), while an explicit `--type` flag always wins over the
+  type parsed from the query (the branch fires only on untyped searches). A
+  full ref without the trailing slash (`memory:projectA/auth-tip`) stays an
+  ordinary keyword search — resolving a single ref is `akm show`'s job.
+  **Stable-surface note:** `akm search` is Stable; this changes results for a
+  query shape that previously returned noise or nothing. A user literally
+  keyword-searching for the string `memory:x/` loses the old fuzzy token
+  behavior — accepted as negligible.
+- **The `category:` frontmatter key is now captured into the index** as
+  `entry.category` (entry_json only — no schema migration). The key already
+  drives convention-fact prompt injection (`resolveStashStandards`) and the
+  fact linter, but the indexer never captured it, so no category-keyed search
+  or ranking policy was implementable. Captured for all markdown asset types
+  alongside `beliefState` (trimmed; blank/non-string values ignored; no
+  default invented), and whitelisted through the `.stash.json` entry
+  round-trip. Search results and ranking are unchanged — this is capture
+  only (a unit test pins that `category` never enters the FTS search
+  fields). **Requires a reindex to take effect** for existing entries. The
+  companion rank-time demotion of `category: convention` facts on untyped
+  queries was NOT shipped: the prescribed measurement (full skeleton
+  convention facts plus a real `knowledge/auth` asset, untyped `auth` query,
+  semantic off) shows no crowding — FTS is exact-first, so prefix expansion
+  onto the facts' tokens only happens when nothing matches the query exactly,
+  and a real domain asset always outranks the facts. That invariant is pinned
+  by `tests/search-convention-fact-demotion.test.ts`, which becomes the
+  regression guard if a demotion contributor is ever revisited.
+- **Config-gated indexing of the self-situating body opening —
+  `index.indexBodyOpening` (default `false`).** Body prose is not indexed
+  (the FTS `content` column carries only TOC headings and parameters), which
+  is why the stash conventions route orientation into
+  `description:`/`when_to_use:`. With the new flag enabled, the metadata pass
+  captures the first prose paragraph of each markdown asset body — skipping
+  headings (ATX and setext), fenced code blocks, thematic breaks, and a
+  leading nested frontmatter block (only when its content is actually
+  frontmatter-shaped: prose wrapped in decorative `---` lines is captured,
+  not discarded); capped at 280 chars with word-boundary truncation and a
+  trailing ellipsis — into `entry.bodyOpening`, which folds into the
+  lowest-weight `content` FTS column (bm25 weight 1.0, so a name match always
+  outranks a body-opening-only match) and into the search/embedding text.
+  Secret and env files are never read for it, and session-kind memories
+  (`akm_memory_kind` in outer or nested inner frontmatter) are excluded —
+  their bodies are raw transcripts. Both indexing walks and write-path
+  indexing honor the flag (the metadata pass reads the user config directly).
+  With the flag absent or `false`, entries and search fields stay
+  byte-identical to before. **Costs of toggling (either direction):** indexed
+  text changes, so collapse-detector canary recall baselines shift — re-mint
+  via `akm improve canary --refresh` — and embeddings are NOT regenerated for
+  entries that already have one, while incremental runs re-extract only
+  changed files. Run `akm index --full` after toggling: it re-extracts every
+  entry and wipes embeddings so they rebuild from the new text; until then
+  `akm index` warns that the flag differs from the state the index was built
+  with. The conventions' `description:`/`when_to_use:` orientation routing
+  remains primary — this flag makes body openings additionally pay retrieval
+  rent, it does not replace structured metadata. See `docs/configuration.md`.
+- **`akm mv <ref> <new-name>` — rename with inbound-xref rewrite and
+  utility-history preservation (Experimental).** The stash conventions'
+  forced-rename procedure ("grep and fix inbound xrefs in the same pass") was
+  agent-executable except for the part only the CLI can do: a rename used to
+  mint a new index row, orphaning the `utility_scores` /
+  `utility_scores_scoped` / embeddings / salience rows keyed by entry id —
+  the "rename resets learned ranking" cost the conventions warn about. The
+  new verb does the whole pass: it moves the file (a memory's `.derived.md`
+  twin moves together, keeping the `entry_key + ".derived"` belief-inheritance
+  coupling), rewrites inbound refs across the writable stash's markdown files
+  — body prose, frontmatter ref-list keys (`xrefs:`/`refs:`/`supersededBy:`/
+  …), and fenced code blocks — with complete-ref boundary matching (a longer
+  ref sharing the old ref as a prefix is untouched), and re-keys the index
+  row **in place** so the row id and every id-keyed ranking table survive;
+  the moved row and rewritten citers are FTS-refreshed so search reflects the
+  new name immediately. Scope v1: flat-markdown asset types (`memory`,
+  `knowledge`, `command`, `agent`, `workflow`, `lesson`, `session`, `fact`)
+  in the primary writable stash only, and the source ref must be the
+  canonical spelling — a ref that resolves only through one of lint's
+  fallback resolutions (knowledge-subdir alias, direct-path) is rejected
+  naming the canonical ref, since a fallback-keyed move would strand the
+  index row and dangle canonical citers. Wiki refs, cross-type targets,
+  existing targets, unresolvable refs, type-root escapes, `.derived` twin
+  refs as the source (rename the base — the twin follows), and target names
+  ending in `.derived` (reserved twin suffix) are rejected with the
+  standard envelope (exit 2, nothing moved). Read-only sources are scanned
+  but never written — their citing files are reported in `readOnlyCiters` as
+  manual follow-ups. Output:
+  `{ok, from, to, rewrote: [{file, count}], readOnlyCiters, utilityPreserved}`;
+  a successful move appends an `mv` event. The operation spans FS + DB and is
+  not transactional, but its ordering (plan rewrites → apply citer edits →
+  rename last → re-key index last) makes an interrupted run safely
+  re-runnable; with no local index built, the rename still succeeds and the
+  next `akm index` picks it up, and `utilityPreserved: false` discloses when
+  an existing index could not be re-keyed (the ranking history then resets
+  on the next full index). Added to the v1 §9.4 command surface as an
+  Experimental-tier additive entry (see `STABILITY.md`).
+
+### Changed
+
+- **Directory (scope/domain) tokens now always merge into `tags` at index
+  time**, even when an asset sets explicit `tags:` frontmatter. Previously
+  explicit tags suppressed all path-derived tags, so a nested asset like
+  `memory:projectA/auth-tip` with `tags: [auth]` silently lost the exact
+  tag-match ranking boost for its scope token unless the author restated it.
+  The merged tokens come from the canonical ref subpath
+  (`extractDirTagsFromName`), which also fixes the flat-walk indexing path
+  losing directory segments in the empty-tags fallback. Filename tokens are
+  still auto-derived only when `tags` is empty (they already live in the FTS
+  name column and aliases), and the empty-tags fallback itself is unchanged.
+  **Operator notes:** the change takes effect on the next reindex and alters
+  indexed tag text for nested assets with explicit tags, so collapse-detector
+  canary recall baselines may shift — re-mint them with `akm improve canary
+  --refresh`. Embeddings are not regenerated when indexed text changes; the
+  drift here is small (the merged tokens already appear in the name field),
+  but a purge/re-embed picks up the new text exactly.
+- **Demoting belief states now cap an entry's final search score**
+  (superseded ≤ 0.25, contradicted ≤ 0.2, archived ≤ 0.15, deprecated ≤
+  0.28). The existing additive belief penalties are applied inside the
+  multiplicative boost sum on a min-max-normalized FTS base (rank-1 vs rank-2
+  base can differ by up to 0.7), so a superseded incumbent that was the best
+  keyword match stayed clamp-pinned at 1.0 above its own correction — the
+  demotion was invisible exactly when the corrections pattern needs it. The
+  ceiling is applied once at the end of the single scoring pipeline (sort
+  order and displayed scores stay consistent); demoted entries remain listed
+  under the default `--belief all`, keep their relative ordering, and the
+  `--belief` filter axis is unchanged. Semantic-only hits are judged against
+  the `search.minScore` floor by their pre-ceiling score, so a ceiling below
+  the floor (archived 0.15 < default 0.2) ranks the hit last instead of
+  silently dropping it. Ordering changes only for stashes containing
+  belief-flagged assets.
+- **`mutateFrontmatter` (belief-edge writers: supersede/contradict edges,
+  belief refresh) now preserves the body bytes verbatim** when the file
+  already has a frontmatter block, instead of re-normalizing the
+  fence-to-body separator through `assembleAsset`. A metadata edit is no
+  longer a (whitespace-level) content edit; files gaining their first
+  frontmatter block still use the canonical shape.
+
+### Fixed
+
+- **Check-in directives now survive plain-text output and `workflow
+  status`** (check-in review C2/M1): `formatWorkflowNextPlain` and
+  `formatWorkflowStatusPlain` render the `CONTINUE` directive, and every
+  run-detail response (status/start/complete) evaluates the check-in instead
+  of only `workflow next`.
+- Workflow frontmatter validator error message now lists the actually-allowed
+  keys (`name`, `updated` were missing); removed the documented-but-nonexistent
+  `akm workflow step` alias from `docs/features/workflows.md`.
+
 ## [0.9.0] — 2026-06-30
 
 ### Fixed
@@ -1675,7 +2012,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 
 ### Migration
 
-- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and [`docs/migration/v1.md`](docs/migration/v1.md) for the canonical per-surface delta from any 0.6.x baseline.
+- See [`docs/migration/release-notes/0.7.0.md`](docs/migration/release-notes/0.7.0.md) for the operator summary and the [archived pre-1.0 plan](docs/archive/pre-1.0-migration.md) for the historical per-surface delta from any 0.6.x baseline.
 
 ## [0.6.0] - 2026-04-23
 
@@ -1694,7 +2031,7 @@ See `docs/migration/v0.7-to-v0.8.md` for the user-facing migration guide.
 
 ### Changed (breaking)
 
-- **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/migration/v1.md` for the full guide.
+- **v1 architecture refactor.** The internal architecture was rebuilt around a single minimal `SourceProvider` interface (`{ name, kind, init, path, sync? }`), a unified FTS5 index that owns search and show, and a single `writeAssetToSource` helper that owns all writes. The CLI command surface and all user-visible config keys are unchanged. See `docs/archive/pre-1.0-migration.md` for the historical guide.
 - **Config key `stashes[]` renamed to `sources[]`.** Configs with the legacy key load with one deprecation warning and are auto-migrated in memory; the new key is persisted on the next `akm config` write. New configs should use `sources[]`. Configs that contain both keys are rejected with `ConfigError`.
 - **Error hints surface without `--verbose`.** Error classes own their `hint()` text; the regex-on-message hint chain in `cli.ts` is removed. Hints print to stderr inline alongside the error message.
 - **Registry providers loop through a uniform interface.** Context Hub is no longer a special-cased provider type. Add it as a regular git source (`akm add github:andrewyng/context-hub`) or include it as a kit in your registry index. Legacy `type: "context-hub"` entries normalize to `type: "git"` at load time.

package/SECURITY.md

@@ -7,9 +7,9 @@ Security fixes are made on the latest minor release line of `akm-cli`. The
 
 | Version | Supported |
 | --- | --- |
-| 0.8.x  | ✅ active |
-| 0.7.x  | ❌ no longer maintained |
-| < 0.7  | ❌ no longer maintained |
+| 0.9.x | ✅ active |
+| 0.8.x | ❌ no longer maintained |
+| < 0.8 | ❌ no longer maintained |
 
 ## Reporting a vulnerability
 
@@ -42,7 +42,7 @@ bugs, but you should be aware of them:
 
 Workflow steps run in your shell with your PATH and your environment
 variables — including any secrets you have exported or loaded via
-`akm vault load`. **Only add workflow sources you trust.** See
+`akm env run` / `akm secret run`. **Only add workflow sources you trust.** See
 [`docs/features/workflows.md` — "Security: workflow sources are executed
 code"](docs/features/workflows.md#security-workflow-sources-are-executed-code)
 for the full discussion.
@@ -61,33 +61,32 @@ maintainer could write a system prompt that instructs the LLM to read
 sensitive files in your working tree and exfiltrate them via the LLM
 response. Audit the prompt body the same way you'd audit a script.
 
-### Vaults are plaintext on disk
+### Environment and secret assets are plaintext on disk
 
-`akm vault` files are `0o600`-permissioned plaintext at
-`<stash>/vaults/<name>.env`. They are protected against other local users
-by filesystem permissions but not encrypted at rest. Do not commit vault
-files to source control — they are `.gitignore`d in the default stash
-layout for that reason. The `akm vault show` / `akm vault list` commands
-never echo values; `akm vault load` produces shell-eval output meant to be
-piped to `eval`, never displayed.
+`env` and `secret` assets are owner-permissioned plaintext under `<stash>/env/`
+and `<stash>/secrets/`. They are protected against other local users by
+filesystem permissions but are not encrypted at rest. Do not commit these
+files to source control. Normal `akm env` and `akm secret` output never echoes
+values; materialize values only at the command boundary with `akm env run`,
+`akm secret run`, or `akm secret path`.
 
 ### Improve / propose / distill send asset content to the configured LLM
 
 `akm improve`, `akm propose`, `akm distill`, `akm reflect`, and `akm
-consolidate` send asset frontmatter and body to whatever LLM endpoint is
-configured in `~/.config/akm/config.json` (under `llm.endpoint`). If you
-have configured a third-party LLM, your asset content goes to that
-third-party. Use a local model (`http://localhost:11434` via Ollama, etc.)
-for assets containing secrets or private notes.
+consolidate` can send asset frontmatter and body to the named LLM engine selected
+by the command, strategy, or current defaults. LLM connections live under
+`engines.<name>` in `~/.config/akm/config.json`. If you configure a third-party
+LLM, your asset content goes to that third party. Use a local engine endpoint
+(for example, `http://localhost:11434/v1/chat/completions` via Ollama) for assets
+containing secrets or private notes.
 
 ## Known non-issues
 
-- **`akm` requires Bun or the prebuilt binary** — Node.js is not supported
-  in 0.8.0 because Bun-specific APIs are used in hot paths. This is a
-  compatibility limitation, not a security risk; the prebuilt binary is a
-  Bun-compiled standalone executable.
+- **`akm` requires Bun, Node.js >= 20.12, or the prebuilt binary.** Older
+  Node.js versions are unsupported because required runtime APIs are missing.
+  This is a compatibility limitation, not a security risk.
 - **Workflows can read any file the akm process can read.** This is not a
   bug — see "Threat model" above.
-- **`bun install -g akm-cli` runs the preinstall hook.** The hook only
-  emits an error message and exits non-zero on Node.js; it does not phone
-  home or write outside the install directory.
+- **Installing `akm-cli` runs the preinstall hook.** The hook only validates
+  the runtime version and exits non-zero when it is unsupported; it does not
+  phone home or write outside the install directory.

package/dist/assets/help/help-improve.md

@@ -41,25 +41,25 @@ Options:
                                                  consolidation will prompt interactively on HTTP paths
                         Note: until proposals carry real confidence scores, any non-`false`
                         value behaves like the legacy "safe" mode (whole-batch auto-accept).
-  --profile <name>     Improve profile to apply. Built-ins: default, quick,
+  --strategy <name>    Improve strategy to apply. Built-ins: default, quick,
                         thorough, memory-focus, frequent, catchup, consolidate,
                         graph-refresh, synthesize, reflect-distill,
-                        proactive-maintenance, recombine-only. User-defined
-                        profiles under `profiles.improve.<name>` in config are
-                        also accepted. Profiles bundle process gating, type
+                         proactive-maintenance, recombine-only. User-defined
+                         strategies under `improve.strategies.<name>` in config are
+                         also accepted. Strategies bundle process gating, type
                         filters, and run-level autoAccept/limit defaults. Falls
-                        back to `defaults.improve` in config, then to "default".
+                         back to `defaults.improveStrategy` in config, then to "default".
                         An unknown name is a hard error listing the valid names
                         (no silent fallback to default).
-                        Sync behavior by profile: default and thorough enable
+                         Sync behavior by strategy: default and thorough enable
                         auto-commit + push; quick and memory-focus skip sync.
   --sync               Commit (and optionally push) the git-backed primary
                         stash when the run finishes. Use --no-sync to disable.
-                        Default: per profile config (enabled for default and
+                         Default: per strategy config (enabled for default and
                         thorough, disabled for quick and memory-focus).
   --push               Push after the end-of-run sync commit when the stash
                         is writable and has a remote configured. Use --no-push
-                        to commit only. Default: per profile config (true when
+                         to commit only. Default: per strategy config (true when
                         sync is enabled).
   --consolidate-recovery <mode>
                         Recovery mode for stale consolidate journals: abort (default) or clean
@@ -78,7 +78,7 @@ Examples:
   akm improve skill
   akm improve skill:code-review
   akm improve workflow:incident-response --task "reduce duplication"
-  akm improve --profile quick
-  akm improve --profile memory-focus
+  akm improve --strategy quick
+  akm improve --strategy memory-focus
   akm improve --no-sync
   akm improve --no-push

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

@@ -12,6 +12,8 @@ akm search "<query>" --source both            # Also search registries
 akm search "<query>" --source registry        # Search registries only
 akm search "<query>" --limit 10               # Limit results
 akm search "<query>" --detail full            # Include scores, paths, timing
+akm search "memory:projectA/"                 # Enumerate a typed subtree (ref-prefix; trailing slash required)
+akm search "knowledge:"                       # List every asset of a type
 ```
 
 | Flag | Values | Default |
@@ -23,6 +25,12 @@ akm search "<query>" --detail full            # Include scores, paths, timing
 | `--detail` | `brief`, `normal`, `full` | `brief` |
 | `--shape` | `human`, `agent`, `summary` (`summary` only on `show`) | `human` |
 
+Ref-prefix queries (`"<type>:<prefix>/"` or a bare `"<type>:"`) return a
+deterministic listing, not a relevance ranking. A full ref without the
+trailing slash (`memory:projectA/auth-tip`) stays an ordinary keyword search —
+resolving a single ref is `akm show`'s job — and an explicit `--type` flag
+wins over the type parsed from the query.
+
 ## Curate
 
 Combine search + follow-up hints into a dense summary for a task or prompt.
@@ -60,7 +68,7 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 | memory | `content` (recalled context) |
 | env | `keys` (key names only — values and comment text never returned) |
 | secret | `name` only (the whole file is the value — never returned) |
-| wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (defaults.agent or `--profile`) to execute the ingest workflow. |
+| wiki | `content` (same view modes as knowledge). For any wiki task, run `akm wiki list`. To ingest sources, `akm wiki ingest <name>` dispatches the configured agent (`defaults.engine` or `--engine`) to execute the ingest workflow. |
 
 ## Capture Knowledge While You Work
 
@@ -68,12 +76,16 @@ akm show knowledge:my-doc                    # Show content (local or remote)
 akm remember "Deployment needs VPN access"     # Record a memory in your stash
 akm remember --name release-retro < notes.md   # Save multiline memory from stdin
 akm remember "note" --target my-other-stash    # Route write to a named writable stash source
+akm remember "note" --xref knowledge:auth-flow # Cite provenance in frontmatter xrefs (repeatable; ref must resolve)
+akm remember "fix" --supersedes memory:old-note # Write a correction AND demote the old asset (beliefState: superseded)
 akm import ./docs/auth-flow.md                 # Import a file as knowledge
+akm import ./doc.md --xref knowledge:auth-flow # Merge provenance xrefs into the imported doc's frontmatter
+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-stash    # Route import to a named writable stash source
 akm workflow create ship-release               # Create a workflow asset in the stash
-akm workflow validate workflows/foo.md         # Validate a workflow file or ref; lists every error
+akm workflow validate workflows/foo.yaml       # Validate a YAML v2/markdown workflow or ref; lists every error
 akm workflow next workflow:ship-release        # Start or resume the next workflow step
 akm feedback skill:code-review --positive      # Record that an asset helped
 akm feedback agent:reviewer --negative         # Record that an asset missed the mark
@@ -103,15 +115,15 @@ akm wiki stash research https://example.com/paper # Fetch one URL into raw/<slug
 akm wiki stash research ./paper.md --target my-stash # Route write to a named writable stash source
 echo "..." | akm wiki stash research -         # stdin form
 akm wiki lint research                         # Structural checks: orphans, broken xrefs, uncited raws, stale index
-akm wiki ingest research                       # Dispatch defaults.agent to run the ingest workflow on this wiki
-akm wiki ingest research --profile claude --model sonnet  # Override profile and model
-akm wiki ingest research --timeout-ms 600000   # Override agent CLI timeout (default: profile setting)
+akm wiki ingest research                       # Dispatch defaults.engine to run the ingest workflow on this wiki
+akm wiki ingest research --engine claude --model sonnet  # Override engine and model
+akm wiki ingest research --timeout-ms 600000   # Override the invocation timeout
 akm wiki remove research -y                    # Delete pages/schema/index/log; preserves raw/ (--force is a deprecated alias for -y)
 akm wiki remove research -y --with-sources     # Full nuke, including raw/
 ```
 
 **For any wiki task, start with `akm wiki list`. Then `akm wiki ingest <name>`
-dispatches the configured agent (defaults.agent or `--profile`) to execute
+dispatches the configured agent (`defaults.engine` or `--engine`) to execute
 the wiki's ingest workflow end-to-end — schema read, source dedup, search,
 page create/update, log entry, lint, reindex.** Wiki pages are also addressable as
 `wiki:<name>/<page-path>` and show up in stash-wide `akm search` as
@@ -155,7 +167,7 @@ akm secret remove secret:deploy-token                       # Delete the secret
 
 ## Workflows
 
-Step-based workflows stored as `<stashDir>/workflows/<name>.md`.
+Workflows live under `<stashDir>/workflows/` as markdown or YAML v2 (`.yaml`/`.yml`).
 
 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
@@ -186,6 +198,28 @@ akm clone "npm:@scope/pkg//script:deploy.sh"  # Clone from remote package
 
 When `--dest` is provided, `akm init` is not required first.
 
+## Move / Rename (Experimental)
+
+Rename an asset within its type directory in the primary writable stash. Prefer
+NOT renaming (a ref is chosen once); when a rename is forced, `akm mv` does the
+whole convention pass: it moves the file (a memory's `.derived.md` twin moves
+together), rewrites inbound refs across the writable stash — body prose,
+frontmatter ref lists (`xrefs:`/`refs:`/`supersededBy:`), and fenced examples —
+and re-keys the index row in place so the asset's learned ranking history
+survives.
+
+```sh
+akm mv memory:projectA/old-note projectA/new-note  # Rename; subdirectories allowed in the new name
+akm mv memory:solo memory:renamed-solo             # Same-type ref-shaped target also accepted
+```
+
+Wiki refs, cross-type targets, existing targets, `../` escapes, non-canonical
+source spellings (the error names the canonical ref), `.derived` twin sources
+(rename the base — the twin follows), and `.derived`-suffixed target names are
+rejected (exit 2, nothing moved). Read-only sources are scanned but never
+written — their citing files come back in `readOnlyCiters` as manual
+follow-ups. Verify with `akm lint` (missing-ref) afterwards.
+
 ## Sync
 
 Commit local changes in a git-backed stash. Behaviour adapts automatically.
@@ -209,13 +243,13 @@ akm sync my-skills -m "Update patterns"      # Sync named stash with message
 The `--sync` / `--no-sync` and `--push` / `--no-push` flags control this:
 
 ```sh
-akm improve                                   # auto-sync per profile default (default/thorough: on; quick/memory-focus: off)
+akm improve                                   # auto-sync per strategy default (default/thorough: on; quick/memory-focus: off)
 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 profiles that disable it
+akm improve --sync                            # force sync even on strategies that disable it
 ```
 
-Profile sync defaults: `default` and `thorough` auto-commit + push; `quick` and
+Strategy sync defaults: `default` and `thorough` auto-commit + push; `quick` and
 `memory-focus` skip sync entirely. Override with `--sync` / `--no-sync` flags.
 
 The `--writable` flag on `akm add` opts a remote git stash into push-on-sync: