akm-cli 0.9.16 → 0.9.17-alpha.10

package/docs/reference/cli.md

@@ -104,7 +104,7 @@ with an `INVALID_SHAPE_VALUE` usage error (exit 2) — an honest rejection rathe
 than a silent fallback. It returns a compact view suitable for capability
 discovery:
 
-- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `related`
+- **show**: `type`, `name`, canonical `ref`, `description`, `tags`, `parameters`, `workflowTitle`, `action`, `run`, `origin`, `keys`, `links`
 
 ## Exit Codes and Error Envelope
 
@@ -195,8 +195,8 @@ akm setup
 The setup wizard configures AKM in two steps:
 
 **Step 1 — Small model connection** (for background processing)
-Configures the OpenAI-compatible endpoint and model used for `akm index`
-metadata enhancement and `akm remember --enrich`. Supports Ollama,
+Configures the OpenAI-compatible endpoint and model used for `akm improve`
+and `akm remember --enrich`. Supports Ollama,
 OpenAI, LM Studio, or any custom endpoint. Skipping disables enrichment features.
 
 **Step 2 — Agent connection** (for agentic commands)
@@ -219,11 +219,11 @@ Build or refresh the search index.
 
 ```sh
 akm index            # Incremental (only changed directories)
-akm index --full     # Full rebuild (reuses unchanged embeddings — see below)
+akm index --full     # Re-drain every directory (keeps unchanged embeddings — see below)
 akm index --verbose  # Print phase progress to stderr
 akm index --clean    # Normal index + remove stale entries from the DB
 akm index --clean --dry-run # Report stale entries without deleting
-akm index --reembed  # Force re-embedding of every entry
+akm index --reembed  # Discard stored vectors and re-embed every entry
 akm index --skip-if-locked  # for scheduled/opportunistic runs: skip (exit 0) if a run is already in progress
 ```
 
@@ -254,25 +254,22 @@ Use `--clean` to resolve the edge case where a deleted file in an unchanged
 directory lingers in the index across incremental runs. With `--dry-run`, reports
 which entries would be removed without modifying the database.
 
-**`--full` no longer re-embeds unchanged content (#955):** a full rebuild
-(and an index-generation bump on first open under a new binary) used to
-delete every embedding unconditionally, forcing a full re-embed of the
-whole corpus even when nothing changed. Vectors about to be discarded are
-now salvaged (keyed by a hash of their content plus the fingerprint they
-were generated under) and handed straight back to unchanged entries at the
-start of the next embedding pass, with zero provider calls for them — a
-progress line reports the split (`Reused N embeddings from the previous
-generation; embedding M new.`). Content that changed even by one byte, or
-a fingerprint that no longer matches, still goes through the provider
-normally. `--reembed` is the way to force a full re-embed regardless.
-
-**`--reembed` flag:** Forces a full purge and re-embed of every entry,
-independent of the embedding-model-rename compatibility check described
-below. Ordinary indexing already tells a config-only rename of
-`embedding.model` (e.g. a gateway that changes how it names the same model)
-apart from a genuine model change, and keeps the stored vectors when they
-are still compatible; `--reembed` skips that check and forces a rebuild
-regardless of what it would have decided.
+**`--full` does not re-embed unchanged content:** a full run re-drains and
+re-persists every directory, but entry ids are kept, so a vector stays
+attached to its entry and only entries whose search text changed go back to
+the embedding provider. An incremental run re-persists only the files that
+changed.
+
+**Embedding model changes:** every stored vector records the embedding model
+it was generated under (`embedding.model` plus dimension for a remote
+endpoint, the local model name otherwise). When the configured model
+changes, the next `akm index` re-embeds entry by entry, committing each
+batch; nothing is purged first, an interrupted run resumes where it
+stopped, and search serves only vectors from the configured model in the
+meantime.
+
+**`--reembed` flag:** Discards every stored vector and re-embeds all entries
+under the configured model.
 
 **`--skip-if-locked` flag:** Every explicit `akm index` run acquires an
 opt-in, PID-liveness-only rebuild lock and releases it on exit — this is
@@ -303,10 +300,8 @@ invokes `akm index` directly should pass `--skip-if-locked` so it steps
 aside instead of piling up behind a longer rebuild (the shipped
 `index-refresh` task does this).
 
-`akm index` always rebuilds the search index and keeps metadata in the index.
-When a selected named LLM engine (`defaults.llmEngine` or an indexing-pass
-override) is configured and the per-pass gate allows it, metadata
-enhancement runs during indexing. In text mode, the default CLI UI shows a
+`akm index` always rebuilds the search index and keeps metadata in the
+index, generated deterministically. In text mode, the default CLI UI shows a
 spinner with processed-versus-total source counts; structured output modes
 (`json`, `yaml`, `jsonl`) stay clean and machine-readable.
 
@@ -323,8 +318,10 @@ Returns a JSON object with:
 | Field | Description |
 | --- | --- |
 | `version` | Current akm version |
-| `bundleDir` | Primary bundle directory — same resolution `akm bundle list` uses |
+| `bundleDir` | Primary bundle directory — same resolution `akm bundle list` uses. Falls back to the platform-default location when no bundle resolves. |
 | `defaultBundle` | Name of the primary bundle from config, or `null` when none is configured |
+| `configError` | Present only when `config.json` exists but could not be loaded (parse or schema failure); every config-derived field falls back to the same defaults a fresh install reports |
+| `bundleDirError` | Present when a bundle IS configured (an env override or `bundles.*` in config) but its path doesn't resolve, OR when the platform-default fallback itself can't resolve (e.g. `HOME` unset) — absent for the ordinary "no bundle created yet" state, where `bundleDir` needs no explanation |
 | `dataDir` | Resolved data directory (`getDataDir()`) |
 | `configDir` | Resolved config directory (`getConfigDir()`) |
 | `cacheDir` | Resolved cache directory (`getCacheDir()`) |
@@ -334,11 +331,17 @@ Returns a JSON object with:
 | `semanticSearch` | Semantic search status: `mode`, `status`, and optional `reason`/`message` |
 | `registries` | Configured registries |
 | `sourceProviders` | Configured sources (filesystem, git, website, npm) |
-| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `lastBuiltAt`, `hasEmbeddings`, `vecAvailable` |
+| `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `links` (declared links per kind with `total` and `unresolved`; absent when the index holds none), `lastBuiltAt`, `hasEmbeddings`, `unreadable` (index.db exists but the filesystem refuses to read it — a permissions problem), `unavailable` (index.db is readable but the SQLite-level read didn't complete: locked by another akm process, a newer layout this akm can't understand, or a corrupt file) |
+
+`akm info` never refuses: an unreadable config, an unresolvable bundle
+directory, or an index.db that's locked, newer, older, corrupt, missing, or
+empty each degrade the relevant field(s) above instead of failing the
+command. It also never waits more than about 1.5s on a locked index.db,
+regardless of the shared 30s lock-wait every write command otherwise uses,
+and warns rather than refusing on an unrecognized flag.
 
 `semanticSearch.status` values:
-- `"ready-vec"` — native sqlite-vec extension active (fastest)
-- `"ready-js"` — pure JS fallback active (correct but slower at scale)
+- `"ready-js"` — every entry has a vector; semantic search is active (the name is historical: `"ready-vec"`, the sqlite-vec variant, is gone)
 - `"pending"` — not yet initialized (run `akm index` to set up)
 - `"blocked"` — setup failed (see `reason` and `message` fields)
 - `"disabled"` — semantic search is turned off in config
@@ -379,7 +382,7 @@ default agent engine, and summarizes recent `improve_*` events. Unless
 to the `default-llm-engine` and every `configured-engines` LLM connection (and
 an SDK engine's LLM fallback), one probe per distinct endpoint, checks the
 installed akm-cli version against the latest GitHub release (`cli-version`),
-and runs the scheduler's recorded akm binary with `--version` to check it
+runs the scheduler's recorded akm binary with `--version` to check it
 against the running CLI (`scheduler-binary`).
 
 Primary result fields:
@@ -387,23 +390,23 @@ Primary result fields:
 | Field | Description |
 | --- | --- |
 | `status` | Overall health verdict: `pass`, `warn`, or `fail` |
-| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-migrations`, `task-log-backing`, `active-runs`, `default-engine`, `model-map-files`, `default-llm-engine`, `configured-engines`, and `active-improve-strategy` |
+| `hardChecks` | Deterministic checks such as `state-db-schema`, `state-db-round-trip`, `state-db-integrity`, `state-db-migrations`, `active-runs`, `default-engine`, `model-map-files`, `default-llm-engine`, `configured-engines`, and `active-improve-strategy` |
 | `advisories` | Non-fatal warnings including `semantic-search-runtime`, `session-extraction` (akmExtract pipeline health), `cli-version` (installed vs latest release), `thinking-control` (an `enableThinking: false` engine whose recorded usage still shows reasoning tokens), and `engine-last-used` (an engine bound to an enabled improve process with no recorded use in 30 days) |
-| `metrics` | Aggregate task/runtime metrics: `taskFailRate`, `agentFailureRate`, `stuckActiveRuns`, `logBackingRate`, `probeRoundTripMs` |
+| `metrics` | Aggregate task/runtime metrics: `taskFailRate`, `agentFailureRate`, `stuckActiveRuns` |
 | `improve` | Recent improve-loop counts derived from `improve_invoked`, `improve_skipped`, and `improve_completed` events |
 
 The `improve` section includes counts for planned refs, reflect/distill actions,
-memory-prune actions, memory-inference writes, graph-extraction refreshes,
+memory-prune actions, memory-inference writes,
 session-extraction outcomes (`sessionsScanned`, `sessionsExtracted`, `proposalsCreated`),
 dead-URL detections, and skip reasons observed in the selected time window.
 
-`state-db-migrations` reports whether `state.db`'s migration ledger has any
-pending entries (checked read-only, without applying anything). It `fail`s
-when migrations are pending — naming them and pointing at `akm migrate apply`
-— rather than the command crashing, which is what happens when `state.db`
-holds a pending historical-destructive migration and something other than
-`akm upgrade` / `akm migrate apply` opens it directly. Read this check's
-`status` instead of grepping akm's error text for that case.
+`state-db-migrations` reports what `akm health`'s own open of `state.db`
+applied. Every open applies pending migrations (copying the file to
+`state.db.pre-<id>.bak` first when one drops schema), so the check passes and
+names the applied IDs (`evidence.applied`) and the copy (`evidence.backupPath`).
+It `fail`s only when a pending migration could not be applied — naming it and
+pointing at `akm migrate apply` — rather than the command crashing. Read this
+check's `status` instead of grepping akm's error text.
 
 `default-llm-engine` and `configured-engines` probe reachability (not just
 configuration) for a `kind: "llm"` engine — an unreachable endpoint is a hard
@@ -436,14 +439,6 @@ for an infrastructure reason (`llm_unavailable`, `read_failed`, `exception`,
 `locked_concurrent`) — naming the reason and, when recorded, the engine — and
 `pass` otherwise, with per-outcome counts.
 
-The indexed entity graph (entities/relations extracted from bundle assets) has
-no dedicated inspection command; its summary counts surface as an info-level
-metric in `akm health`. Graph data is automatically re-extracted on the first
-`akm improve` cycle after a `DB_VERSION` upgrade, and search ranking can
-optionally use graph-derived confidence-weighted boosts — tune
-`search.graphBoost.confidenceMode` and `search.graphBoost.confidenceWeight` in
-[`docs/reference/configuration.md#search-tuning`](configuration.md#search-tuning).
-
 ### search
 
 Search bundle assets, registries, or both.
@@ -499,6 +494,20 @@ query. The last case also adds one sanitized, endpoint-naming entry to
 preserved by `--shape agent` so machine consumers can lower their confidence
 instead of treating keyword fallback as healthy semantic ranking.
 
+Ranking fuses two candidate lists by reciprocal rank (k = 60, equal weights):
+BM25 over whole documents matching any non-stopword query word, and the
+document vectors nearest to the query embedding, 100 candidates each. A hit's
+`score` is its fused score, and equal scores are ordered by ref. The query is
+embedded with the model's query template (see `embedding.queryTemplate` in
+[`configuration.md`](configuration.md)); when the embedding takes longer than
+`embedding.queryTimeoutMs` (default 3000) or fails, the search is served by
+keyword ranking alone with `fts-fallback` and a warning. Filters (`--type`,
+`--from`, `--filter`, `--belief`, the default session exclusion, proposed
+quality) and one-hit-per-file deduplication narrow the fused list without
+reordering it. Of entries with identical indexed content (the same body
+saved under another name or in another bundle), only the highest-ranked is
+kept.
+
 | Flag | Values | Default | Description |
 | --- | --- | --- | --- |
 | `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter by asset type. Free-form and unvalidated — an unknown type returns no hits. Also accepts any adapter-defined type (e.g. `website`) — see [Bundle Types](bundle-types.md) for the open types each adapter emits. |
@@ -508,8 +517,7 @@ instead of treating keyword fallback as healthy semantic ranking.
 | `--filter` | `<key>=<value>` | _(none)_ | Scope filter — repeatable. Valid keys: `user`, `agent`, `run`, `channel`. Example: `--filter user=alice --filter channel=ops`. Narrows the result set; ranking is unchanged. |
 | `--include-proposed` | flag | `false` | Include entries with `quality: "proposed"` in the result set. Default search excludes them; `generated` and `curated` quality entries are always included. Unknown quality values warn once and remain searchable. |
 | `--belief` | `all`, `current`, `historical` | `all` | Memory belief filter. `current` keeps active memory beliefs; `historical` keeps contradicted/superseded/archived ones. |
-| `--no-project-context` | flag | `false` | Disable the automatic project-context ranking boost for this search only |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage-event and ranking updates for this successful read |
+| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
 | `--include-sessions` | flag | `false` | Include session assets, which are excluded from default results via `config.search.defaultExcludeTypes` |
 | `--format` | `json`, `jsonl`, `yaml`, `text`, `md`, `html` | `json` | Output format |
 | `--detail` | `brief`, `normal`, `full` | `brief` | Output verbosity level |
@@ -529,21 +537,12 @@ availability:
 - **`ref`** -- The asset handle to pass to `akm show` (for example
   `team//scripts/deploy.sh`); present at `brief`, `full`, and `agent` for local
   hits
-- **fragment provenance** -- when `ref` selects an indexed Markdown fragment,
-  `selectedRef` and `parentRef` distinguish the ranked evidence from its parent;
-  one-based `fragmentOrdinal`, `fragmentCount`, source-line bounds, neighbor
-  refs, and separate fragment/parent size estimates are available without
-  changing ranking. `estimatedTokens` describes the fragment for a
-  fragment-qualified hit; `parentEstimatedTokens` describes the whole asset.
 - **`name`** -- The asset's filename or identifier; present at all levels
 - **`origin`** -- The source bundle (e.g. `npm:@scope/pkg`), present only for
   managed source assets; surfaced at `full` only
 - **`id`** -- Registry-level identifier (registry hits only)
-- **`matchStage`** -- Which stage of the progressive AND->OR lexical search
-  ladder produced the hit: `exact` (strict AND), `prefix` (prefix AND), or
-  `relaxed` (OR/prefix-OR recovery). Omitted for hits with no FTS component
-  (e.g. a pure-semantic hybrid match) and for registry hits; surfaced at
-  `normal`, `full`, and `--shape agent`
+- **`whyMatched`** -- The hit's rank in each candidate list that returned
+  it (`lexical rank 3`, `vector rank 12`); surfaced at `full`
 
 The default brief shape is intentionally small. The exact field set per
 detail level (and per `--shape`) is authoritative in
@@ -553,9 +552,9 @@ assembled into the shape registry by the `src/output/shapes.ts` barrel:
 | Level | Local bundle hits | Registry hits |
 | --- | --- | --- |
 | `brief` (default) | `type`, `name`, `ref`, `action`, `estimatedTokens` | `name`, `installRef`, `score` |
-| `normal` | `type`, `name`, `description`, `action`, `score`, `estimatedTokens`, optional `warnings`/`quality`/`keys`/`matchStage` | `name`, `description`, `action`, `installRef`, `score`, optional `warnings` |
-| `full` | full hit object (includes `ref`, `origin`, `tags`, `whyMatched`, optional `warnings`, optional `quality`, optional `matchStage`, timings, bundle metadata) | full hit object |
-| `--shape agent` | `name`, `ref`, `type`, `path`, `editable`, conditional `editHint`, `description`, `action`, `score`, optional `estimatedTokens`/`keys`/`matchStage` | no local access fields |
+| `normal` | `type`, `name`, `description`, `action`, `score`, `estimatedTokens`, optional `warnings`/`quality`/`keys` | `name`, `description`, `action`, `installRef`, `score`, optional `warnings` |
+| `full` | full hit object (includes `ref`, `origin`, `tags`, `whyMatched`, optional `warnings`, optional `quality`, timings, bundle metadata) | full hit object |
+| `--shape agent` | `name`, `ref`, `type`, `path`, `editable`, conditional `editHint`, `description`, `action`, `score`, optional `estimatedTokens`/`keys` | no local access fields |
 
 `--shape summary` is **not valid on `search`** — see
 [`--shape summary`](#--shape-summary) above; it is a usage error (exit 2)
@@ -594,29 +593,37 @@ akm curate "learn the release workflow" --from all --format text
 | `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter curated results by asset type |
 | `--limit` | number | `4` | Maximum curated results |
 | `--from` | `local`, `registry`, `all` | `local` | Where to search before curating |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage-event and ranking updates for this successful read |
-
-`akm curate` selects a small relevance-first shortlist. It preserves the
-strongest search hits first, uses only small type-aware nudges for close-score
-ties, can collapse obvious root/reference families into one top-level result,
-and falls back to token searches when the phrase result set is weak. Curate
-includes direct follow-up commands such as `akm show <ref>` or `akm bundle add <ref>`
-so you can immediately inspect or install what it found.
+| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read |
+
+`akm curate` takes the top `--limit` hits of one search, in search order, and
+enriches each with a preview, run details and up to two support refs: the
+assets the hit's declared links name (`xrefs:`, `supersededBy:` and the other
+kinds `akm show` lists under `links`), what it links to before what links to
+it, skipping assets curate already selected. With
+`search.curateRerank.enabled`, a cross-encoder first reorders the top 30 fused
+candidates (`search.curateRerank.topN`) by name, description and the start of
+each asset's indexed content. Curate includes direct follow-up
+commands such as `akm show <ref>` or `akm bundle add <ref>` so you can
+immediately inspect or install what it found.
 `--detail` and `--shape agent` both work on curate output; `--shape summary`
 does not.
-Curate preserves the underlying `searchMode` and deduplicates semantic fallback
-warnings across its full-query and token-fallback searches.
+Curate preserves the underlying search's `searchMode` and warnings.
 Agent-shaped local items include `ref`, `path`, and `editable`, plus `editHint`
 only for read-only items. Their `followUp` remains `akm show <ref>` rather than
 being replaced by clone guidance.
 Use `--type workflow` when you want curated step-by-step procedures instead of
 individual scripts, skills, or docs.
+Curate returns no items, on purpose, when the input is not a task: a harness
+or tool envelope (input that starts with an XML-style tag and contains a
+closing tag, such as `<task-notification>…</task-notification>`) or the stash
+README boilerplate. The `summary` then starts with `Curate abstained` and
+names the reason, and `tip` says how to curate the task instead. Long input is
+curated like any other.
 `akm curate` is safe to call frequently, including from a hook that fires on
 every prompt: it only ever reads the index as it currently stands (the same
 non-blocking `ensureIndex()` path `search` uses) and never waits on or
 contends with a full `akm index` rebuild in progress.
-Use `--no-track-usage` when this inspection must not update local usage or
-ranking signals.
+Use `--no-track-usage` when this inspection must not record usage events.
 
 ### show
 
@@ -624,8 +631,8 @@ Display an asset by ref. On a markdown document `#fragment` selects one
 section by heading slug (falling back to case-insensitive heading text); an
 unmatched fragment lists the available slugs.
 
-Successful reads record local usage and ranking signals by default; pass
-`--no-track-usage` to suppress those updates.
+Successful reads record local usage events by default; pass
+`--no-track-usage` to suppress them.
 
 ```sh
 akm show scripts/deploy.sh
@@ -655,7 +662,7 @@ akm show memories/retro --filter user=alice --filter agent=claude
 | `--max-chars` | positive integer | `3200` for `lead` | Hard contextual content budget in characters; requires `--context lead` and is mutually exclusive with `--max-tokens`. |
 | `--max-tokens` | positive integer | _(none)_ | Approximate contextual budget using four characters per token; requires `--context lead` and is mutually exclusive with `--max-chars`. |
 | `--filter` | `<key>=<value>` | _(none)_ | Repeatable scope filter (`user`, `agent`, `run`, `channel`). |
-| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage-event and ranking updates for this successful read. |
+| `--track-usage`, `--no-track-usage` | flag | `true` | Record or suppress local usage events for this successful read. |
 
 `meta` is not an asset type — `[<origin>//]meta[:<name>]` direct-reads a
 human-authored orientation doc from a bundle's optional `.meta/` directory
@@ -688,6 +695,16 @@ returns a compact view with `type`, `name`, `ref`, `description`, `tags`,
 `parameters`, `workflowTitle`, `action`, `run`, `origin`, and `keys`, plus the
 optional fragment metadata described below.
 
+`links` lists the asset's declared links, grouped by kind: `outgoing` (the
+assets its own `xrefs:`, `supersededBy:`, `contradictedBy:`,
+`currentBeliefRefs:`, wiki `sources:`, `.derived` parent, page links, or
+workflow and task targets name), `incoming` (the assets that name it), and
+`unresolved` (tokens it names that match no indexed asset, as written). Each
+kind is `{ "total": n, "refs": [...] }` with at most 10 refs; `total` counts
+them all. The field is omitted when nothing links either way. Links are read
+from frontmatter and parsed structure at index time, with no model; they do
+not affect search ranking.
+
 Opaque fragment shows and `--context lead` keep `ref` as the canonical parent
 identity and add
 `selectedRef`, `parentRef`, one-based `fragmentOrdinal`, `fragmentCount`,
@@ -816,7 +833,7 @@ The old `--params <json>` bag is removed.
 | `--max-retries <n>` | When a step fails, reopen the same run and retry the failed step up to this many additional times. Range: 0 through 100; default 0. Gate rejection and interruption are not retried. |
 | `--timeout <duration>` | Abort the whole invocation after `N`, `Nms`, `Ns`, or `Nm`; bare `N` is milliseconds. The active step remains resumable. |
 | `--new` | Start a fresh run even when one is already active for this ref, instead of resuming it. The existing active run is left untouched — it is never abandoned automatically. A workflow ref only: passing a run id with `--new` is a usage error (exit 2). Parameter flags are allowed together with `--new`, since it is starting a new run. |
-| `--skip-if-locked` | If another akm process already holds this run's engine lease (`RUN_LEASE_HELD`), or `state.db` is busy with another writer (`STATE_DB_CONTENDED`), skip gracefully (exit 0) instead of failing (exit 75, `TransientError`). The envelope reports `{ skipped: { reason: "lock-held" \| "state-db-contended", message } }`. Every other failure (a bad flag, an unresolvable target) still fails loudly regardless of this flag. Use for high-frequency scheduled runs so they don't pile up failures while a longer-running invocation is in progress — same family as `improve --skip-if-locked`. |
+| `--skip-if-locked` | If another akm process is already driving this run (it holds the run's lock file: `RUN_LEASE_HELD`), or `state.db` is busy with another writer (`STATE_DB_CONTENDED`), skip gracefully (exit 0) instead of failing (exit 75, `TransientError`). The envelope reports `{ skipped: { reason: "lock-held" \| "state-db-contended", message } }`. Every other failure (a bad flag, an unresolvable target) still fails loudly regardless of this flag. Use for high-frequency scheduled runs so they don't pile up failures while a longer-running invocation is in progress — same family as `improve --skip-if-locked`. |
 
 **Resuming an active run is announced, not silent.** Passing a ref that
 already has an active run in the current scope resumes that run rather than
@@ -941,8 +958,8 @@ Two output modes:
 - **`--format json`**: the full envelope — `ok`, `ref`, `title`,
   `sourceFormat`, `sourcePath`, `irVersion`, `planHash`, `published` (always
   `false`, so a consumer can never mistake this for a run envelope),
-  `execution`, `budget?`, `params?`, `outputs?`, `steps[]`, `sourceReadSet[]`,
-  `notices[]`, `warnings[]`. Each step entry carries an `expansion` field
+  `execution`, `budget?`, `params?`, `outputs?`, `steps[]`, `notices[]`,
+  `warnings[]`. Each step entry carries an `expansion` field
   naming how its target was reached: `{via: "direct"}`, `{via: "task",
   taskRef}`, or — for a step composing a child workflow —
   `{via: "child", childRef, childPlanHash, childOutputs, steps[]}` with the
@@ -1038,7 +1055,7 @@ akm bundle add https://docs.example.com --max-pages 100 --max-depth 5
 
 | Flag | Description |
 | --- | --- |
-| `--name` | Human-friendly name for the source |
+| `--name` | The bundle key. A contract, not a hint: it must be a legal bundle slug (no `:` `.` `#` `/` or whitespace) and not already taken by a different bundle, or the add fails before any write. Re-adding an already-installed source under a different `--name` than it already carries also fails — use `akm bundle rename <old> <new>` instead. Omit it and akm derives a name (falling back to a `-<hash>` suffix on a collision). |
 | `--provider` | Explicit provider for declarative source configuration; normally inferred from the input |
 | `--writable` | Mark a git source as writable so `akm sync` also pushes (default: false) |
 | `--options` | Provider options as JSON (e.g. `'{"ref":"main"}'`) |
@@ -1209,6 +1226,42 @@ in `processed`/`plainSynced`; rejected entries report `status: "blocked"` and a
 security code; provider or transaction errors report `status: "failed"`. The
 command continues with later bundles without half-publishing a blocked one.
 
+### bundle rename
+
+Rename a configured bundle's key everywhere akm itself persists it — the one
+command allowed to change it (renaming by hand-editing `config.json`'s
+`bundles` key strands every durable ref the tool minted under the old id; see
+`akm health` / the startup warning that names this).
+
+```sh
+akm bundle rename old-name new-name
+akm bundle rename old-name new-name --dry-run   # Show the plan; write nothing
+```
+
+| Flag | Description |
+| --- | --- |
+| `--dry-run` | Report what would change (index/state row counts, scheduler refs, content files that still mention the old name) without writing anything |
+
+`<new>` must be a legal, unused bundle slug (the same `--name` contract `akm
+bundle add` enforces) or the rename fails before any write. Rewritten: the
+config `bundles` key; `defaultBundle`/`defaultWriteTarget` when they name the
+old id; every `scheduler.enabled[].ref` with the old `<old>//` prefix; the
+lockfile entry id; every indexed entry's `bundle_id`/ref; and this tool's own
+state rows that name the old bundle (`proposals.ref`, a pending proposal's
+write target, and workflow `task_history.target_ref`). Reported, never
+rewritten: refs inside the bundle's own CONTENT (cross-references, `uses:` in
+a task, `supersededBy`) — the result's `contentRefs` lists the indexed files
+that still spell the old `<old>//` prefix so you can fix them by hand. A real
+run also re-syncs native scheduler bindings under the new name (`taskSync` in
+the result reports the outcome, never thrown, since config/index/state are
+already renamed by then). `taskSync.ok` is `false` both when the sync call
+itself fails and when it comes back reporting one or more
+`taskSync.result.failures` — a binding that failed to prepare has already
+lost its old native row and stays unscheduled until you re-run
+`akm task sync`; `--dry-run` lists the installed native rows that still name
+the old bundle (`nativeSchedulerRows`) so you can see what that sync will
+replace.
+
 ### upgrade
 
 Upgrade `akm` itself to the latest release. Standalone binaries are downloaded,
@@ -1432,7 +1485,7 @@ akm remember "Deployment needs VPN access" --bundle team-bundle
 | `--expires <dur>` | Expiry shorthand (`30d`, `12h`, `6m`). Resolved to an ISO date |
 | `--source <s>` | Free-form source reference — URL, asset ref, file path, or any string |
 | `--xref <ref>` | Cross-reference ref recorded in the memory's `xrefs:` frontmatter list. Repeatable: `--xref knowledge/auth-flow --xref memories/vpn-note`. Each ref must resolve in the write target or a configured source (read-only sources count); an unresolvable ref fails with exit 2 before anything is written. More than 5 refs warns (soft cap) but still writes. Does not trigger the tags-required check. |
-| `--supersedes <ref>` | Ref of an existing asset this memory corrects. Repeatable. Writes the correction with the old ref folded into its `xrefs:` (correction provenance) AND demotes the old asset — `beliefState: superseded` + `supersededBy: [<new ref>]`, a metadata-only frontmatter edit that preserves every other key and the body — then reindexes it so ranking prefers the correction and `--belief current` hides the stale version immediately. An unresolvable ref fails with exit 2 before anything is written or demoted; so does a ref naming the asset being written itself (a correction cannot supersede itself, e.g. `--force` overwriting the same name). A ref that resolves only outside the write target and the working bundle still writes the correction but skips the demotion: stderr warns and the JSON output reports `superseded: [{ref, applied: false, reason}]` — the reason names the `--bundle` remedy when the old asset lives in a configured writable source. An old asset whose existing frontmatter is not parseable YAML is skipped the same way (`applied: false`) instead of being rewritten lossily. Re-running the same correction is idempotent. On a git write target the correction and the demoted old asset land in the same single boundary commit. |
+| `--supersedes <ref>` | Ref of an existing asset this memory corrects. Repeatable. Writes the correction with the old ref folded into its `xrefs:` (correction provenance) AND demotes the old asset — `beliefState: superseded` + `supersededBy: [<new ref>]`, a metadata-only frontmatter edit that preserves every other key and the body — then reindexes it so `--belief current` hides the stale version immediately. An unresolvable ref fails with exit 2 before anything is written or demoted; so does a ref naming the asset being written itself (a correction cannot supersede itself, e.g. `--force` overwriting the same name). A ref that resolves only outside the write target and the working bundle still writes the correction but skips the demotion: stderr warns and the JSON output reports `superseded: [{ref, applied: false, reason}]` — the reason names the `--bundle` remedy when the old asset lives in a configured writable source. An old asset whose existing frontmatter is not parseable YAML is skipped the same way (`applied: false`) instead of being rewritten lossily. Re-running the same correction is idempotent. On a git write target the correction and the demoted old asset land in the same single boundary commit. |
 | `--auto` | Apply heuristic tagging from the body (opt-in, zero-latency, pure TS) |
 | `--enrich` | Call the configured LLM for tag/description proposals (opt-in, 10s timeout, fails soft) |
 | `--user <id>` | Scope this memory to a user id. Persisted as the canonical `scope_user` frontmatter key. |
@@ -1565,9 +1618,9 @@ akm feedback skills/code-review --negative --reason "flaky" --tag slice:train --
 Specify exactly one of `--positive` or `--negative`. The ref must already be
 present in the current local index.
 
-The `--applied-to` flag drives the lesson-strength ranking signal: lessons that
-have demonstrably helped resolve tasks receive a small additive ranking boost
-(capped at +0.3) so they float to the top of search.
+The `--applied-to` flag records the lesson-strength signal: each credit is
+kept in the lesson's `lessonStrength[]` frontmatter. Search ranking does not
+use it.
 
 ### log
 
@@ -1671,18 +1724,25 @@ wrapper over the standalone `akm-migrate` executable (installed alongside
 akm has ever written so the CLI proper reads only current schemas. The steps,
 in order:
 
-1. legacy config `extraParams` keys lifted onto first-class engine fields
-   (`configExtraParams`);
+1. config.json rewritten in its current shape (`configFile`): retired and
+   unknown keys dropped, legacy `extraParams` lifted onto first-class engine
+   fields, the legacy `stashDir`/`sources[]`/`installed` layout converted to
+   `bundles`/`defaultBundle`, `configVersion` bumped — the same pipeline
+   every load already runs in memory, so this only persists it, under a
+   backup;
 2. pending `state.db` migrations, historical-destructive ones included, with
    a verified sibling safety copy (`stateMigrations`) — the only path besides
    `akm upgrade` that admits released migration 018, which an ordinary
    command refuses;
-3. task-v2 files to task v3, then task-v3 files to task source v4
-   (`taskV3Migration`, `taskV4Migration`), each keeping its own lock, backup,
-   prevalidation, and rollback, so a file blocked in the first generation does
-   not stop the second from converting files already at `version: 3`;
-4. superseded pre-0.9.0 `.akm` residue and stale filesystem transactions
-   (`deadResidue`, `staleTxns`).
+3. task files at version 2 or 3, and version 4 files still carrying the
+   retired `schedule[].enabled` key, rewritten as task source v4
+   (`taskFiles`) under one backup directory per run, each emitted document
+   re-parsed by the runtime v4 parser first; a file the planner cannot
+   convert unambiguously is reported `blocked` and left alone;
+4. superseded residue removed (`deadResidue`): pre-0.9.0 `.akm` leftovers in
+   the stash, and the transaction-journal, maintenance-barrier, lock-mutex and
+   version-stamp files older releases kept under `$DATA`, `$STATE` and
+   `$CONFIG`.
 
 ```sh
 akm migrate status
@@ -1701,6 +1761,16 @@ blocked-reason table and worked examples, and
 [Bundling akm](../integration/bundling-akm.md) for the plan JSON shape and
 how to drive this from a container/image boot step.
 
+Each step above runs under its own catch: a step's own anomaly is always
+recorded in the plan's `failedSteps: [{step, error}]` instead of ending the
+whole run — the remaining steps still run in order. Under `apply`, a failed
+step's section falls back to its read-only preview; if that fails too, the
+fallback adds its own `failedSteps` entry, and the section is absent from the
+plan. Any `failedSteps` entry
+forces `status: "blocked"` and adds a matching line to `blockers`, so
+`akm migrate status|apply` reports the plan and exits 1 (not the internal-error
+70) the same way it does for any other blocked plan.
+
 ### config
 
 Read and write configuration. Bare `akm config` (no subcommand) is a usage
@@ -2374,10 +2444,14 @@ akm improve report --since 7d          # ...aggregated over every real run start
 `akm improve` is the public entrypoint for whole-bundle, type-scoped, and
 ref-scoped improvement. It owns the memory-cleanup and lesson-distillation
 flow. A qualified scope such as `team//skills/code-review` selects that bundle;
-a different explicit `--bundle` is a usage error. Inspecting or re-minting the
-collapse-detector canary set is maintainer tooling, not a CLI verb — run
-`bun scripts/refresh-canary-set.ts` (add `--refresh` to mint a new set and
-deactivate the old one; old rows and their cycle history are retained).
+a different explicit `--bundle` is a usage error.
+
+Every stage records what it did with each asset in the improve ledger
+(`improve_ledger` in `state.db`) and reads it before any model call: an asset
+whose proposal was rejected waits 14 days (reflect), 30 days (distill) or 7
+days (other stages) before it is tried again; an expired proposal waits one
+day; an asset a stage looked at and left unchanged is revisited after 7 days,
+or as soon as new feedback (or, for consolidation, an edit) arrives.
 
 Built-in `default` and `frequent` leave the improve-stage extract process off,
 and `default` plus `reflect-distill` leave proactive maintenance off. Use the
@@ -2453,14 +2527,15 @@ clock, or session-log changes.
 
 `plan.processes` (#947) is the resolved process -> engine -> model routing
 table: one row per improve process (`reflect`, `distill`, `consolidate`,
-`memoryInference`, `graphExtraction`, `extract`, `validation`, `triage`,
+`memoryInference`, `extract`, `validation`, `triage`,
 `proactiveMaintenance`), plus a `triage.judgment` row when the strategy
 configures a judgment engine. Each row carries `enabled`, the resolved
 `engine`/`model` (llm-backed processes only) and `engineKind`, this process's
 own lowering `notices`, and — for reflect/distill/consolidate only —
 `eligibleRefs`, the count of this run's `effectiveRefs` the process would act
-on (`shouldSkipRef`'s allowedTypes/process-disabled check; a count, not a
-per-ref matrix, to keep the envelope bounded). A row that could not resolve an
+on (`shouldSkipRef`'s allowedTypes/excludeRefPrefixes (reflect only)/
+process-disabled check; a count, not a per-ref matrix, to keep the envelope
+bounded). A row that could not resolve an
 engine or credential carries `unavailable: {configKey, reason}` — the same
 data behind `skippedProcesses` above, reshaped per process. When the process
 resolved a real engine whose credential just isn't reachable here, the row
@@ -2480,7 +2555,7 @@ default probe-on behavior) to check whether a named engine actually answers.
 builds the exact prompt reflect would send for one asset — the same source
 resolution, runner selection, feedback/schema-hint/related-lesson/rejected-
 proposal gathering `akm improve`'s live reflect step uses — and prints it
-without acquiring a dispatch lease, so it never calls an engine. Add
+without reading a credential, so it never calls an engine. Add
 `--format text` (the default JSON/yaml envelope escapes the prompt into one
 line, which defeats a by-eye read) to confirm by eye that recent feedback is
 framed as an unverified report to investigate (never a fact to insert
@@ -2488,9 +2563,7 @@ verbatim) and that the response contract tells the model never to emit the
 truncation marker or any content from outside the shown asset.
 
 When reinforced facts need promotion, `knowledge` is the higher-authority
-destination than `memory`. The deterministic search ranking also prefers
-`knowledge` over `memory` hits, including inferred `.derived` memories, when
-the evidence is otherwise comparable.
+destination than `memory`.
 
 #### improve report
 
@@ -2509,7 +2582,7 @@ field on the result (`result_json` in `improve_runs`, and in the
 `calls`, `failures`, `promptTokens`, `completionTokens`, `totalTokens`,
 `reasoningTokens`, and `totalDurationMs`. `noCalls` lists every LLM-backed
 process (`reflect`, `distill`, `consolidate`, `memoryInference`,
-`graphExtraction`, `extract`, `validation` — not `triage`/`proactiveMaintenance`,
+`extract`, `validation` — not `triage`/`proactiveMaintenance`,
 which never make an attributable LLM call themselves) the active strategy
 enabled but that ended the run with zero calls, each with a `reason` drawn
 from the existing skip-reason vocabulary: `"engine_unavailable"` (also in
@@ -2647,6 +2720,7 @@ akm proposal list
 akm proposal list --queue team-bundle
 akm proposal list --status pending|accepted|rejected|reverted
 akm proposal list --ref skills/deploy
+akm proposal list --generator consolidate-pair
 ```
 
 | Flag | Description |
@@ -2655,6 +2729,12 @@ akm proposal list --ref skills/deploy
 | `--status` | Filter by `pending`, `accepted`, `rejected`, or `reverted` |
 | `--ref` | Filter by asset ref. A qualified ref preserves bundle identity; a short ref matches that concept in the selected queue |
 | `--type` | Reserved type filter |
+| `--generator <name>` | Filter by generator/source (e.g. `reflect`, `distill`, `consolidate-pair`) — the same value `accept`/`reject --generator` take |
+
+Each retire proposal's `retirement.continuityRisk`, when present, also shows
+in the default listing (`⚠ continuity-risk` inline) and in `proposal show`'s
+text output (the specific failing/unverified queries) — see
+[Retirement continuity](https://github.com/itlackey/akm/blob/main/docs/architecture/improvement.md#retirement-continuity).
 
 Each proposal record carries an optional `confidence` field (0..1) emitted by
 reflect/propose runs. It is recorded for triage and ranking only — there is no
@@ -2776,27 +2856,27 @@ requires `--reason`.
 
 #### proposal drain
 
-Drain the standing pending-proposal backlog using a deterministic triage
-policy, instead of adjudicating proposals one at a time. Default mode stages
-decisions (queue mode); pass `--promote` to actually accept matching
-proposals.
+Drain the standing pending-proposal backlog instead of adjudicating proposals
+one at a time. One rule decides each proposal: a proposal whose quality judge
+passed on its current content is accepted (unless its target changed since it
+was minted — that one is auto-rejected as `stale-target`); an empty diff is
+rejected; everything else goes to the judgment tier when one is enabled, and
+is otherwise left for review. Default mode stages decisions (queue mode); pass
+`--promote` to actually accept.
 
 ```sh
 akm proposal drain --dry-run                        # Preview without writing
-akm proposal drain --policy personal-stash --promote -y
-akm proposal drain --policy conservative --max-accepts 10 --promote -y
-akm proposal drain --max-diff-lines 50 --older-than 7 --promote -y
+akm proposal drain --promote -y
+akm proposal drain --max-accepts 10 --older-than 7 --promote -y
 akm proposal drain --strategy default --promote -y  # Read the triage block from an improve strategy
 ```
 
 | Flag | Description |
 | --- | --- |
-| `--policy` | Built-in preset (`personal-stash`, `conservative`, `manual`) or a path to a policy file |
-| `--strategy` | Read the triage block (policy, apply mode, ceilings, judgment) from this improve strategy instead |
-| `--promote` | Promote (accept) matching proposals. Default is queue mode — stage only, no writes to assets. |
+| `--strategy` | Read the triage block (apply mode, ceilings, judgment) from this improve strategy instead |
+| `--promote` | Promote (accept) judge-passed proposals. Default is queue mode — stage only, no writes to assets. |
 | `--dry-run` | List what would be accepted/rejected/deferred, without writing |
 | `--max-accepts` | Hard per-run accept ceiling; accepts beyond this are reported as `skippedByCap` |
-| `--max-diff-lines` | Defer (never promote) accepts whose proposed content exceeds this many lines |
 | `--older-than` | Only consider proposals created more than this many days ago |
 | `--judgment` | Explicitly enable the judgment tier for this standalone drain, including when the selected strategy says `judgment.enabled: false`; execution overrides still come from that strategy. Without this flag, strategy judgment config does not enable standalone drain judgment. A missing runner remains a no-op with a logged `triage_deferred` summary. |
 | `-y`, `--yes` | Skip the confirmation prompt (required in non-interactive mode for promotion) |
@@ -2845,10 +2925,10 @@ akm task prune --yes                        # Remove every currently-computed or
 akm task prune --id ghost,stale --yes       # Remove only the named orphan ids
 ```
 
-`task add` also accepts `--disabled` (register but leave off in the OS
-scheduler), `--force` (overwrite an existing task with the same id), and
-`--rebind` (explicitly permit scheduler creation from a local invocation that
-would otherwise be considered ineligible).
+`task add` also accepts `--disabled` (write the task but leave its ref out of
+this host's scheduler activation), `--force` (overwrite an existing task with
+the same id), and `--rebind` (also point the bundle's installed scheduler rows
+at this akm invocation, as `akm task sync --rebind` does).
 
 `akm task list [<query>] [--limit <n>] [--from local|registry|all]` is a
 pure alias for `akm search --type task` with the query, `--limit`, and
@@ -2892,22 +2972,39 @@ time. Each run is recorded as a row in the durable `task_history` table
 no `task_invoked`/`task_completed` event type on the `akm log` stream.
 
 Task source cannot enable itself. `akm task enable <fully-qualified-ref>` adds
-an exact source-bound `{kind, ref, sourceId}` grant to this host's
-`scheduler.enabled` config and
-syncs that bundle; `akm task disable` removes it and unschedules the task.
+the ref to this host's `scheduler.enabled` list and syncs that bundle; `akm task disable` removes it and unschedules the task.
 Manual `akm task run` remains available. To remove a task, delete its file
 (`<bundle>/tasks/<id>.yml`) and run `akm task sync` — sync uninstalls the
 orphaned scheduler entry.
 
-`akm task sync --dry-run` prints the planned adds/updates/removes (removals
-carry their owning bundle) without touching the scheduler — zero writes.
-Exits non-zero when removals are pending, so it can gate a CI/health check
-on "sync would change something."
+A config with no `scheduler.enabled` list at all (written before 0.9.17)
+means "keep what is installed": `akm task sync` takes the akm-written rows
+already in the scheduler as this host's choice and writes the list; an
+explicit list is never second-guessed. `akm task sync --dry-run` prints the
+planned adds/updates/removes (removals carry their owning bundle) without
+touching the scheduler — zero writes. Exits non-zero when removals are pending, so it can
+gate a CI/health check on "sync would change something."
+
+`sync`'s (and `sync --dry-run`'s) result always carries `failures: [{path,
+ref?, reason}]` — one entry per item sync could not reconcile: a task/workflow
+source that failed to parse or prepare (its installed row is left as it is),
+two sources claiming the same scheduler id, a desired binding whose id is
+already scheduled from a different bundle or installation, a row whose
+install or removal failed, or — for an unscoped, multi-bundle sync — a whole
+bundle whose sources could not be read. Every one of these is a per-item
+failure: the item is left exactly as it was and reported here, while every
+OTHER item and bundle in the same sync still reconciles; with `--bundle`,
+that one bundle IS the whole sync, so a bundle that cannot be read raises
+instead of being reported here. `failures` is empty on a fully clean sync; a
+non-empty `failures` still exits non-zero, same as a pending removal. A
+crontab whose akm markers are malformed is refused unmodified, and another
+akm process holding the scheduler lock makes sync exit 75 (retry shortly).
 
 `akm task prune` reclaims installed scheduler entries that `sync` can never
-clean up on its own: entries whose own `--scheduler-context` descriptor no
-longer resolves to a live bundle (a corrupt/missing descriptor, or the
-bundle directory it pointed at is gone). It never touches an entry that
+clean up on its own: entries that no longer resolve to a live bundle (a row
+whose `AKM_BUNDLE_DIR` names a directory that is gone, or a row written
+before 0.9.17-alpha.7 whose `--scheduler-context` descriptor cannot be
+read). It never touches an entry that
 still resolves to a live bundle — that's `sync`'s job. Like `sync
 --dry-run`, the default is a dry-run preview (zero scheduler writes) that
 exits non-zero when there are candidates to remove; `--yes` executes the