akm-cli 0.9.17-alpha.3 → 0.9.17-alpha.4

package/docs/reference/configuration.md

@@ -10,32 +10,17 @@ automatic project-config discovery.
 
 ## Version 0.9
 
-A present configuration file must set `configVersion` to a version this
-binary knows: the current `"0.9.0"`, or a known older version it can
-auto-upgrade in memory (see "Version read shim" below). Missing, newer,
-numeric, and any other unrecognized version are rejected by ordinary
-commands without rewriting the file — an older binary never guesses at a
-newer, unknown shape. Pre-0.9 config and database layouts are not runtime
-inputs. Historical task sources and scheduler activation are handled by the
-standalone `akm-migrate` executable, also invoked by `akm migrate` / `akm
-upgrade`; ordinary runtime code reads only the current shape.
-
-### Version read shim
-
-For config only, a known older `configVersion`
-is converted to the current shape in memory on load — with a one-line stderr
-deprecation warning — rather than hard-failing every command. Nothing is
-written back to disk by the shim itself; the very next config-mutating
-command (`akm config set`, etc.) persists the upgrade for free, since every
-config write already forces `configVersion` to the current value, which
-silences the warning. A `configVersion` this binary does not recognize at
-all — including anything newer than current — still fails closed with
-`UNSUPPORTED_CONFIG_VERSION`.
-
-As of this writing `"0.9.0"` is the only `configVersion` akm has ever
-shipped, so there is no real older shape for the shim to convert yet; the
-mechanism (`src/core/config/config-version-shim.ts`) is established ahead of
-the first bump that will need it, per #863.
+`configVersion` is `"0.9.0"`, the only value akm has ever shipped. It is
+read, never gated on: a file without the field loads silently, and a file
+declaring any other value is named once on stderr (`config.json declares
+configVersion "X"; this release reads it as 0.9.0.`) and read as the
+current shape anyway — nothing is rewritten on disk. The next config write
+(`akm config set`, etc.) and `akm migrate apply`'s config step both persist
+`"0.9.0"`, which silences the note. When a newer akm wrote the shared
+config, `akm health`'s `binary-config-skew` advisory is what says so. Pre-0.9
+config and database layouts are not runtime inputs. Historical task sources
+are handled by the standalone `akm-migrate` executable, also invoked by `akm
+migrate` / `akm upgrade`; ordinary runtime code reads only the current shape.
 
 ```jsonc
 {
@@ -82,15 +67,16 @@ the first bump that will need it, per #863.
 
 ## Scheduler activation
 
-`scheduler.enabled` is this host's explicit scheduling allow-list. Each entry
-has a `kind` (`task` or `workflow`), a canonical fully qualified `ref`, and a
-`sourceId` binding the grant to the configured source installation that was
-approved. Absence means disabled. Replacing a bundle's path or locator under
-the same name invalidates the old grant; ordinary updates from the same origin
-do not. Authored task/workflow files may describe schedules but cannot grant
-themselves authority to create native scheduler entries. Do not edit
-`sourceId` manually: `akm task enable` writes it, and `akm migrate apply`
-upgrades grants written by older releases.
+`scheduler.enabled` is this host's list of scheduled refs, such as
+`stash//tasks/nightly`. A ref that is not listed is disabled. On disk each
+entry is still written as the `{kind, ref, sourceId}` object 0.9.16 reads,
+so that release keeps working against a config this one wrote; in memory it
+is the ref.
+A config without the list (written before 0.9.17) means "keep what is
+installed": the first `akm task sync` fills it from the akm-written native
+scheduler rows. The 0.9.17-alpha `{kind, ref, sourceId}` entries are read as
+their `ref`. Authored task/workflow files may describe schedules but cannot
+put themselves on the list.
 
 This key is deliberately local: if a config uses `extends`, any `scheduler`
 section in the base is ignored with a warning. Only the top-level local config
@@ -424,7 +410,22 @@ unless a remote `embedding` config is provided.
 embedding model: `provider`, `endpoint`, `model`, `apiKey` (symbolic
 reference, same rules as engine `apiKey`), `dimension`, `localModel`,
 `maxInputTokens`, `maxTokens`, `batchSize`, `contextLength`, `timeoutMs`,
-`concurrency`, and `ollamaOptions.num_ctx`.
+`queryTimeoutMs`, `queryTemplate`, `documentTemplate`, `concurrency`, and
+`ollamaOptions.num_ctx`.
+
+Retrieval models expect a prompt around queries and documents. akm picks it by
+model name (`src/llm/embedders/profile.ts`): Qwen3-Embedding gets
+`Instruct: Given a question or task, retrieve the knowledge asset that helps with it\nQuery:{text}`
+on queries; nomic-embed `search_query: ` / `search_document: `; the BGE
+English, mxbai and arctic models `Represent this sentence for searching
+relevant passages: ` on queries; E5 `query: ` / `passage: `; any other model
+none. `embedding.queryTemplate` and `embedding.documentTemplate` override the
+preset (`{text}` marks where the text goes, a template without it is a prefix,
+and `""` means none). The document template is part of the embedding
+fingerprint, so changing it re-embeds the index; the query template applies
+at search time only. `embedding.queryTimeoutMs` (default `3000`) bounds how
+long a search waits for its query embedding before falling back to keyword
+ranking with a warning.
 
 The knobs that bound request/document size and rate, all optional (defaults
 apply when unset), for a remote endpoint (`src/llm/embedders/remote.ts`):
@@ -528,26 +529,20 @@ taking about the same wall time as a single one against a healthy endpoint.
 
 ## Search tuning
 
-`search` tunes ranking, not behavior an ordinary user needs to touch:
+`search` sets which types search leaves out by default, and the optional curate reranker:
 
 | Key | Purpose |
 | --- | --- |
-| `search.minScore` | Drop results below this score |
 | `search.defaultExcludeTypes` | Asset types excluded from results by default |
 
-### Graph boost search tuning
-
-| Key | Purpose |
-| --- | --- |
-| `search.graphBoost.*` | Entity-graph relevance boost: `directBoostPerEntity`/`directBoostCap` (directly related entities), `hopBoostPerEntity`/`hopBoostCap` (multi-hop, capped at `maxHops` ≤ 3), `confidenceMode` (`blend`, the only supported value), `confidenceWeight` (0–1, default `0.2`) |
-
 ### Curate rerank (#951)
 
-An optional cross-encoder rerank pass over `akm curate`'s already-selected
-candidates, via a standalone `/rerank`-style HTTP endpoint (NOT one of the
-`engines.*` `"llm"`/`"agent"` kinds). Disabled by default; a misconfigured
-endpoint, network failure, timeout, or malformed response falls back to
-curate's own ranking unchanged.
+An optional cross-encoder rerank pass over the top fused search candidates
+`akm curate` fetches, via a standalone `/rerank`-style HTTP endpoint (NOT one
+of the `engines.*` `"llm"`/`"agent"` kinds). Each candidate is sent as its
+name, description and the start of its indexed content (2,000 characters in
+all). Disabled by default; a misconfigured endpoint, network failure, timeout,
+or malformed response keeps the fused order.
 
 | Key | Purpose |
 | --- | --- |
@@ -556,7 +551,7 @@ curate's own ranking unchanged.
 | `search.curateRerank.model` | Model name sent to the endpoint (optional) |
 | `search.curateRerank.apiKey` | `$VAR`/`secret://<name>` credential reference (optional) |
 | `search.curateRerank.timeoutMs` | Request timeout (default `10000`) |
-| `search.curateRerank.topN` | How many of curate's ranked candidates to send (default `8`, max `50`) |
+| `search.curateRerank.topN` | How many of the top fused candidates to rerank (default `30`, max `50`) |
 
 ## Feedback
 
@@ -734,7 +729,7 @@ one file, and have each host's local config extend it.
   `extends` at it.
 
 Shared layers carry portable policy, not host authority. `bundles`, source and
-write defaults, registries, embedding connections, scheduler grants,
+write defaults, registries, embedding connections, scheduler activation,
 `execution`, `experimental`, and setup state are ignored when inherited.
 Engine definitions may be shared, but credentials and executable authority
 (`apiKey`, `apiKeyFile`, `bin`, `args`, and `workspace`) must be supplied by
@@ -823,11 +818,9 @@ one of the three per engine.
 
 `embedding.apiKey` accepts the same three forms and resolves `secret://` the
 same way, on every path that sends an embedding request: `akm index`
-(including its `bundle update` post-commit embedding pass and the targeted
-re-embed a write command like `akm remember` triggers), `akm improve`'s
-consolidate pass (memory dedup and similarity clustering), and the
-fingerprint-rename canary `akm index` runs when the embedding config
-changes. All of them build the
+(including the reindex `akm bundle update` runs and the targeted re-embed a
+write command like `akm remember` triggers), `akm improve`'s
+consolidate pass (memory dedup and similarity clustering). All of them build the
 provider request through the same `RemoteEmbedder`/`resolveSecret` boundary,
 so a `secret://` reference resolves identically regardless of which command
 triggered the request (#953).

package/docs/reference/data-and-telemetry.md

@@ -60,7 +60,7 @@ Override: set `AKM_CONFIG_DIR` or `XDG_CONFIG_HOME`.
 | `state.db` | Events, local usage telemetry, proposals, task history, improve run results, and workflow run state/history (the former `workflow.db` was folded in during the 0.9.0 cutover) | **No** — deletes event/usage logs, proposal queue, improve history, and workflow run history |
 | `logs.db` | Structured, high-volume task/run log lines (`{ts, task_id, run_id, stream, level, line}`), joined to `state.db`'s `task_history` rows by `task_id@started_at`. Kept separate from `state.db` because log lines are append-only and freely purgeable, unlike durable state | Yes — log lines are regenerable per run; deleting loses historical run output only |
 | `akm.lock` | Inter-process write lock | Yes — recreated automatically |
-| `backups/task-v3/`, `backups/task-v4/` | Copies of task files taken by `akm migrate apply` before it rewrites them, one timestamped directory per run; the five most recent per generation are kept (#897) | Yes — once the migrated tasks are verified |
+| `backups/tasks/` | Copies of task files taken by `akm migrate apply` before it rewrites them, one timestamped directory per run that rewrote a file | Yes — once the migrated tasks are verified |
 | `akm.lock.lck` | Lock write sentinel | Yes — recreated automatically |
 
 Override: set `AKM_DATA_DIR` or `XDG_DATA_HOME`.
@@ -161,6 +161,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
 | `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
 | `sync` | `akm sync` | `ref` |
+| `index_db_vacuumed` | `akm index` VACUUMed index.db, after an index layout migration or because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `stash_synced` | `akm improve`'s internal auto-sync pass (the `sync.push` feature), **distinct from** the `akm sync` command above | `committed`, `pushed`, `skipped`, `reason`, `attributed` (paths the run wrote and staged), `unattributed` (in-scope paths that went dirty during the run without the run writing them — left for their author) |
 | `env_access` | `akm env run <name> -- <command>` (audit trail: key **names** only, values never recorded) | `ref`, `keys` |
 | `secret_access` | `akm secret run <ref> <VAR> -- <command>` (audit trail: var **name** only, value never recorded) | `ref`, `var` |
@@ -176,7 +177,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `proposal_expiration_pass` | Summary emitted once per `akm improve` maintenance run after per-proposal `proposal_expired` events | expiry counts |
 | `proposal_orphan_purge` | Stale proposals whose target asset no longer exists on disk, pruned by improve maintenance | `checked`, `rejected` |
 | `proposal_creation_rejected` | `createProposal()` validation failed before write | `ref`, `reason`, `source` |
-| `triage_drained` | `akm proposal drain` run summary | `promoted`, `rejected`, `deferredByReason`, `skippedByCap`, `policy`, `applyMode` |
+| `triage_drained` | `akm proposal drain` run summary | `promoted`, `rejected`, `deferredByReason`, `skippedByCap`, `applyMode` |
 | `triage_deferred` | `akm proposal drain` left items unresolved after the (optional) judgment tier | `deferred`, `deferredByReason`, `reason` |
 
 *`akm improve` pipeline*
@@ -194,20 +195,13 @@ the set of types the code actually emits at HEAD (verified against every
 | `improve_reflect_outcome` | Per-asset reflect result | `ref`, `ok`, `durationMs`, `reason` |
 | `propose_invoked` | `akm proposal new` | `ref` |
 | `distill_invoked` | Distill phase inside the `akm improve`/`akm proposal new` pipeline. **`akm distill` is not a CLI command** — there is no standalone verb by that name | `ref`, outcome |
-| `consolidate_completed` | `akm improve`'s consolidate pass processed at least one memory | `ref` (`memories/_consolidation`) |
 | `extract_invoked` | `akm proposal extract --type <harness>` / `--auto`, or improve-stage session extraction | `outcome`, `sessionId`, `harness` |
 | `extract_triaged` | The pre-LLM extract triage gate evaluated at least one session | `evaluated`, `passed`, `triagedOut`, `sourceRun` (aggregated) |
 | `schema_repair_invoked` | The schema-repair pass inside `akm improve` (`runSchemaRepairPass`) attempts to patch missing frontmatter on an asset that failed schema validation. **There is no `akm lint --repair` flag** — `lint` has `--fix`/`--auto-fix`, unrelated to this event | `ref`, outcome |
 | `proactive_selected` | The proactive-maintenance selector runs (once per `akm improve` run) | `count`, `dueTotal`, `neverReflected` (aggregated) |
-| `improve_replay_selected` | Bounded replay-budget selection ran | `count`, `budget`, `convergedSkipped`, `candidatePool` (aggregated) |
-| `improve_salience_first_run` | First improve run with no pre-existing salience baseline to compare against | `candidateCount`, `note` |
 | `improve_salience_rank_change` | Bundle-wide rank-change report, from the second improve run onward | `stashSize`, `totalChanged`, `forgettingCandidates`, `topDrops` |
-| `outcome_proxy_inverted` | Proxy-adequacy tripwire: `outcome_score` correlates *negatively* with accepted-change rate (corr < −0.3) | `correlation`, `n` |
-| `outcome_proxy_dead` | Proxy-adequacy tripwire: `outcome_score` is statistically unrelated to accepted-change rate (\|corr\| < 0.1, n ≥ 500) | `correlation`, `n` |
-| `collapse_detector_alert` | The collapse/churn detector trips an alert rule during an improve cycle | `kind` (collapse-recall\|collapse-entropy\|collapse-shrink\|churn\|merge-floor), `detail`, `metrics`, `canarySetId`, `runId` |
 | `events_purged` | Old events deleted by improve maintenance (90-day default retention) | `purgedCount`, `retentionDays` |
 | `improve_runs_purged` | Old `improve_runs` rows deleted by improve maintenance (same retention window as events) | `purgedCount`, `retentionDays` |
-| `improve_cycle_metrics_purged` | Old `improve_cycle_metrics` rows (365-day retention) deleted by improve maintenance | `purgedCount`, `retentionDays` |
 | `state_db_vacuumed` | state.db was VACUUMed after the retention purge because more than half its pages were free | `pagesBefore`, `pagesAfter`, `freelistRatioBefore` |
 | `task_logs_purged` | Old scheduled-task log files purged by improve maintenance | |
 
@@ -241,7 +235,7 @@ queryable per-run or aggregated with `akm improve report`; see
 
 ### 2. Usage Events Table
 
-`usage_events` is the local analytical record behind utility ranking,
+`usage_events` is the local analytical record behind utility scores,
 retrieval-demand counts, GRR, and real-query eval generation (0.9.0: its CLI
 read surface, `akm history`, was removed — the table itself and everything
 below still applies). It stores
@@ -252,7 +246,7 @@ configured endpoint.
 
 Successful `search`, `curate`, and `show` commands record usage by default.
 Pass `--no-track-usage` to any of those commands to leave local usage events
-and ranking signals unchanged.
+unchanged.
 
 Every runtime writer stamps provenance as `user`, `improve`, `task`, `audit`, or
 `unknown`. Direct interactive CLI traffic defaults to `user`; internal improve,
@@ -264,20 +258,18 @@ real-query labels.
 
 Per-entry `search`, `curate`, and `show` rows carry a local-only
 `metadata.downstreamAttribution` object. Version 1 uses `control: true` for
-current traffic where neither memory inference nor graph extraction applies;
-rows without the version marker are historical/unattributed. Attributed rows
-use `control: false` and may contain:
+current traffic where memory inference does not apply; rows without the
+version marker are historical/unattributed. Attributed rows use
+`control: false` and may contain:
 
 - `memoryInference`: `direct` when the emitted ref is an inferred child, or
   `surface` when derived description/tags were actually present in the emitted
   search or selected curate output. Brief output and internally replaced
   descriptions are controls, not surface attribution.
-- `graphExtraction`: the positive graph-ranking contribution that was actually
-  applied after the shared contributor cap, plus `bodyHash` and
-  `extractionRunId` when available. It is absent when `graph-ranking` is
-  ablated. The number is a ranking-input contribution, not proof that graph
-  changed final rank, selection, or outcome; score saturation and competing
-  contributors can leave ordering unchanged.
+- `graphExtraction`: written only by releases that boosted search with the
+  graph — the graph contribution applied to the hit, plus `bodyHash` and
+  `extractionRunId` when available. Current releases do not rank by the graph
+  and never write it.
 
 Attribution metadata contains fully-qualified refs and graph identifiers, never
 asset bodies or provenance content. It is not added to `search`, `curate`, or
@@ -299,6 +291,13 @@ Contents:
 - Full proposal content (Markdown text)
 - Created/updated timestamps
 
+Beside it, the `improve_ledger` table records what each improve stage last did
+with each asset — one row per bundle, asset ref and stage: the outcome
+(`proposed`, `accepted`, `rejected`, `quality_rejected`, `review_needed`,
+`expired`, `unchanged`, `failed`, `judged_no_action`), when it was attempted,
+and the earliest time the stage may try that asset again. It holds refs,
+timestamps, a proposal id and a short reason — never asset content.
+
 ### 4. Task History Table
 
 A record of scheduled task runs (from `akm task`):

package/docs/reference/tasks.md

@@ -5,31 +5,43 @@ Task assets are strict, local automation sources. They live at
 launchd, or Windows Task Scheduler with `akm task sync`. The task file is
 authored source; scheduler entries are derived OS state.
 
-**Task source v4 (`version: 4`) is the only task source grammar this
-release accepts.** A document with `version: 3` or `version: 2` (or any
-other value) fails to load with `UsageError` code
-`TASK_SCHEMA_VERSION_UNSUPPORTED`, naming the migrator. Task source v4 adds
-typed `inputs:` and a single bounded `output:` schema (command targets
-only), and makes scheduling OPTIONAL rather than mandatory. `akm task add`
-authors task source v4 directly.
+**Task source v4 (`version: 4`) is the current task source grammar.** A
+document with `version: 3` or `version: 2` still reads and runs: an
+in-memory shim converts it to v4 on the same bytes `akm migrate apply`
+would produce, prints a one-line stderr deprecation warning (once per file
+per process), and never writes anything to disk. Only a v2/v3 document the
+deterministic conversion itself cannot resolve (an ambiguous shell command,
+say) fails to load, with `UsageError` code `TASK_SCHEMA_VERSION_UNSUPPORTED`
+naming the specific blocked reason and the human decision it needs. A
+declared `version: 4` document whose `schedule[]` still carries a
+per-entry `enabled` key — 0.9.15's v4 grammar accepted it, this release's
+does not — reads through the same kind of in-memory shim: the key is
+stripped without ever being read (activation is host-local, below) and the
+same one-line deprecation warning is printed. Task source v4 adds typed
+`inputs:` and a single bounded `output:` schema (command targets only), and
+makes scheduling OPTIONAL rather than mandatory. `akm task add` authors
+task source v4 directly.
 
 If you have `version: 3` or `version: 2` files on disk (from an earlier
 akm release), see [Migrating to task source v4](#migrating-to-task-source-v4)
-below — `akm migrate apply` converts both generations in one pass. The
+below — `akm migrate apply` converts both generations in one pass and
+rewrites the file on disk, silencing the read-time deprecation warning. The
 retired v3 grammar itself is documented at the bottom of this page
 ([Task v3 (retired): grammar reference for migration](#task-v3-retired-grammar-reference-for-migration))
-purely so you can read an old file while migrating it; it is not accepted
-by any command in this release.
+purely so you can read an old file while migrating it; it is no longer
+accepted as a standing grammar by any command in this release.
 
 ## Files and schema
 
 The only recognized task extension is `.yml`. A `.yaml` near miss is never
-indexed, scheduled, or run. Every task must declare `version: 4`; a
+indexed, scheduled, or run. Every task should declare `version: 4`; a
 document with no `version:` key, or a `version:` that is not a number,
 fails with `TASK_SOURCE_INVALID` (`must be exactly 4.` / `is required and
 must be exactly 4.`) — a genuinely malformed v4 document, not a legacy one.
-`version: 3` and `version: 2` fail with `TASK_SCHEMA_VERSION_UNSUPPORTED`
-instead (see [Migrating to task source v4](#migrating-to-task-source-v4)).
+`version: 3` and `version: 2` read via the in-memory deprecation shim
+described above and, only when the deterministic conversion itself cannot
+resolve the document, fail with `TASK_SCHEMA_VERSION_UNSUPPORTED` instead
+(see [Migrating to task source v4](#migrating-to-task-source-v4)).
 The published [task schema](../../schemas/akm-task.json) describes the
 hand-authored contract; `src/tasks/source/task-source-v4.ts` is the
 authoritative bounded parser.
@@ -162,25 +174,22 @@ would. Multiple schedule entries create deterministic scheduler bindings
 for the one source task.
 
 Task source v4 has **no enablement flag**. A source describes what may run;
-it cannot authorize its own host scheduling. Activation is an exact,
-host-local allow-list in `config.json` under `scheduler.enabled`, keyed by
-asset kind, fully qualified ref, and the approved source installation identity.
-Absence means disabled. A removed, disabled, or replaced bundle cannot reuse a
-grant written for an earlier source under the same name. Use `akm task
-enable <bundle>//tasks/<id>` and `akm task disable <bundle>//tasks/<id>` to
-change that list and immediately sync the affected bundle. `akm task add`
-enables its new task by default; `--disabled` writes the same task source but
-does not add the local activation.
+it cannot authorize its own host scheduling. Activation is this host's list of
+fully-qualified refs in `config.json` under `scheduler.enabled`. A ref that
+is not listed is disabled. A config with no list at all (written before
+0.9.17) means "keep what is installed": the first sync fills the list from
+the akm-written native bindings. Use `akm task enable <bundle>//tasks/<id>`
+and `akm task disable <bundle>//tasks/<id>` to change the list and
+immediately sync the affected bundle. `akm task add` enables its new task by
+default; `--disabled` writes the same task source but does not list it.
 
 `akm task run <id>` executes a task immediately, including a disabled task.
-`akm task sync` scans every enabled configured bundle, selects only locally
-activated task/workflow refs, validates the complete desired set, and then
-atomically reconciles scheduler state. `--bundle <name>` narrows that pass to
+`akm task sync` scans every enabled configured bundle, reads only locally
+activated task/workflow refs, and reconciles the native scheduler one row at a
+time (see [Operations](#operations)). `--bundle <name>` narrows that pass to
 one active bundle. If every configured bundle is disabled, sync removes the
-attributable native entries without reading task content. Scheduled task
-invocations check both the local activation and current source identity again at
-fire time before re-reading the guarded current task bytes; workflow targets
-then create a fresh durable workflow freeze.
+attributable native entries without reading task content. Workflow targets
+create a fresh durable workflow freeze at fire time.
 
 ## Typed inputs and output
 
@@ -405,21 +414,45 @@ for full before/after examples and recovery guidance.
   anything — see [`akm task explain`](#akm-task-explain) above.
 - `akm task validate <path>` parses one task file by filesystem path (the
   file need not live in a configured bundle) and reports the same
-  `valid`/`blocked`/`invalid`/`not-a-task` diagnostic
+  `valid`/`converts`/`blocked`/`invalid`/`not-a-task` diagnostic
   `akm task sync` would produce for it — including sync's own cron-dialect
   check and its per-schedule-entry input-contract check — without touching
   the scheduler and without requiring a configured engine, even for a
   command-kind task. The envelope's own `sourceVersion` field names the
-  file's declared schema version. Version 2/3 files are `blocked` with an
-  `akm migrate apply` instruction; validation never migrates them in memory.
-- `akm task add` writes a task source v4 document and installs it after
-  validation. `--params` renders typed `inputs:` declarations instead of a
-  `with:` bag; `--schedule` is required on every invocation. `--disabled`
-  leaves the new ref absent from local scheduler activation.
+  file's declared schema version. A version 2/3 file the in-memory shim
+  converts reports `converts` (exit 0); one the shim's deterministic
+  planner cannot resolve reports `blocked` (exit 1) naming the human
+  decision it needs. A `version: 4` file whose only defect is a retired
+  `schedule[].enabled` also reports `converts` (`sourceVersion` still `4`)
+  — it read through the shim too, not the direct v4 path.
+- `akm task add` validates a task source v4 document, writes it, adds its ref
+  to local scheduler activation, and syncs its bundle. `--params` renders
+  typed `inputs:` declarations instead of a `with:` bag; `--schedule` is
+  required on every invocation. `--disabled` writes the same source but
+  leaves the ref out of activation. `--force` overwrites an existing task of
+  the same id; without it add refuses. Add also refuses, before writing
+  anything, when the id is already scheduled from another bundle or
+  installation. If the row itself cannot be installed, add fails and says so;
+  the task stays written and enabled, and the next `akm task sync` retries it.
 - `akm task history` reads durable run history from `state.db`.
 - `akm task enable <ref>` / `akm task disable <ref>` change only local
   scheduler config, then reconcile that bundle.
 - Delete the `.yml` source and sync to remove its derived binding(s).
+- `akm task sync` reads the installed rows once, compares each against what
+  its source renders, and installs, rewrites, or removes rows one at a time.
+  A row that fails to install or remove is reported in `failures` and every
+  other row still applies. A source that fails to parse is reported the same
+  way, and its installed row is left exactly as it is. Rows akm cannot attribute to a bundle this sync covers —
+  another bundle's, another installation's (the row's own descriptor names a
+  different bundle path), or anything outside akm's `# akm:task` markers,
+  `com.akm.task.` labels, or `\akm\` task folder — are never touched. A
+  Task Scheduler row is compared by the fingerprint akm writes into its
+  `<Source>` plus its enabled state, so an edit made in Task Scheduler that
+  keeps that fingerprint is left alone.
+- `akm task sync`, `add`, `enable`, `disable`, and `prune --yes` hold one lock
+  file, `$STATE/locks/scheduler.lock`, while they read and write the native
+  scheduler. A second one started meanwhile exits 75 (retry shortly); a lock
+  left by a process that is no longer running is reclaimed.
 - `akm task sync --dry-run` previews the reconcile (adds/updates/removes,
   removals annotated with their owning bundle) without writing to the
   scheduler; exits non-zero when removals are pending.
@@ -430,8 +463,23 @@ for full before/after examples and recovery guidance.
   Defaults to a dry-run preview (zero writes); `--yes` executes it; `--id
   <id1,id2,...>` scopes to specific ids and refuses any id that isn't a
   current orphan candidate.
-- Use `akm task sync --rebind` only when deliberately changing the captured
-  AKM runtime, then verify with `akm task doctor`.
+- A plain sync keeps each installed row's launcher. Use
+  `akm task sync --rebind` only when deliberately changing the captured AKM
+  runtime, then verify with `akm task doctor`. When the launcher sync writes
+  runs akm from a source checkout (`src/cli.ts`, a local build, or a package
+  inside a git work tree), sync says so once: scheduled runs then run
+  whatever the checkout holds.
+- `akm task sync` writes one `PATH=` line inside a `# akm:env BEGIN`/`END`
+  section directly above the first akm task block in the crontab (on macOS,
+  an `EnvironmentVariables` entry in each plist). It is the PATH of the shell
+  that ran the sync, rewritten on every crontab write and removed with the
+  last akm block; cron applies it to every row below it. The
+  `--scheduler-context` descriptor a row references holds directories only:
+  the bundle path, plus any `AKM_CONFIG_DIR`, `AKM_DATA_DIR`, `AKM_CACHE_DIR`
+  or `AKM_STATE_DIR` that shell had set explicitly. Defaults resolve at fire
+  time, so a scheduled run uses the same state, data and cache directories an
+  interactive command does. Run the sync from a shell whose environment you
+  would want scheduled.
 
 Scheduler execution is at least once. Backends provide a stable invocation
 identity and AKM fences stale attempts, but an ambiguous process crash can be

package/docs/reference/workflow-schema.md

@@ -188,8 +188,8 @@ child is re-read at dispatch time. Concretely:
   workflow depends on.
 
 See [Architecture: The Workflow Engine](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md#child-workflows)
-for the embedded-plan integrity chain (`irVersion`, `planHash`,
-`contentHash`) and why a tampered embedded child plan fails to decode.
+for how an embedded child plan is decoded (`irVersion`, `planHash`, and
+`contentHash` are recorded provenance, not re-verified).
 
 ### Composition limits
 
@@ -217,9 +217,9 @@ run and drives it to completion, or as far as it gets, before the parent
 step is finalized. The drive happens **inline, in the parent's own
 process**: it is the same engine `akm workflow run` uses on the child's
 frozen plan, not a separately scheduled job. Consequently, whatever aborts
-the parent's own dispatch — `Ctrl-C`, a `--timeout`, a budget ceiling, or
-the parent losing its run lease — also aborts the child drive; both runs
-are left resumable, never partially torn down.
+the parent's own dispatch — `Ctrl-C`, a `--timeout`, or a budget ceiling —
+also aborts the child drive; both runs are left resumable, never partially
+torn down.
 
 The child's final status maps onto the composing step and the parent run:
 
@@ -228,9 +228,9 @@ The child's final status maps onto the composing step and the parent run:
 | `completed` | completes; its output is the child's exported result — its declared `outputs:` (see [What a step's output is](#what-a-steps-output-is)), or `{runId, status}` when the child declares none | continues |
 | `failed` | `failed` | `failed` |
 | `blocked` | `blocked` | `blocked` |
-| aborted mid-drive (parent cancelled/timed out/lost its lease) | left unfinished, not finalized | active and resumable |
-| the child could not be published or its plan failed an integrity re-check | `failed` | `failed` |
-| another process already holds the child's run lease | `failed` | `failed` |
+| aborted mid-drive (parent cancelled/timed out) | left unfinished, not finalized | active and resumable |
+| the child could not be published (its params do not satisfy the child's declared `params:`) | `failed` | `failed` |
+| another process already holds the child's run lock | `failed` | `failed` |
 
 **Blocked-child recovery.** A blocked child blocks its composing step —
 `akm` does not resume a child for you, because a gate is a gate for a
@@ -531,12 +531,8 @@ unknown step, unknown param, bad path — at lint time.
 ### Params are not secret
 
 Run params are copied verbatim into every unit's dispatched instructions and
-are part of the unit's content-derived input hash — the same hash that makes
-resume-without-replay possible (see
-[Resume is journaled replay](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md#resume-is-journaled-replay)).
-Redacting a param would change what gets hashed and make a resumed run
-diverge from the original, so params are **declared non-secret and
-un-redactable** by design: secrets belong in `env:` refs instead, which carry
+are stored on the run row and shown by `akm workflow status`, so params are
+**declared non-secret**: secrets belong in `env:` refs instead, which carry
 by name only through the plan and are resolved from akm's env/secret store
 at dispatch (see [Reference: Env & Secrets](https://github.com/itlackey/akm/blob/main/docs/reference/env-and-secrets.md)).
 
@@ -545,7 +541,9 @@ values that *look* like credentials — secret-suggesting key names (`token`,
 `password`, `apikey`, `credential`, …) or long, high-entropy strings matching
 known token prefixes — and surfaces a warning naming the param path and
 recommending an `env:` ref instead. This is advisory only: it never blocks a
-run and never mutates params, and false positives/negatives are expected.
+run and never mutates params, and false positives/negatives are expected. The
+same heuristic feeds the dispatch redaction set, so a unit result or
+diagnostic that echoes such a value is scrubbed before it is journaled.
 
 ## What a step's output is
 
@@ -1053,9 +1051,7 @@ request for whole-process inheritance; use exact named environment bindings
 and `pass_env:` instead. Both mechanisms are dispatch-significant, keep the
 visible environment surface bounded, and form part of the unit's input hash.
 
-The historical `inherit_env` spelling is unsupported. Pre-`irVersion`-5 stored
-plans are rejected; they are never upgraded or replayed through a second
-runtime.
+The historical `inherit_env` spelling is unsupported.
 
 ### What `akm show` reports for an exec step
 

package/docs/reference/workflows.md

@@ -46,14 +46,11 @@ artifacts, and exec vocabulary. The YAML adapter accepts the documented local
 `name`/`on`/`jobs` subset. `.yaml` is not a workflow source.
 
 Both adapters produce strict source IR version 1. New starts resolve source
-owners and executable targets, then freeze durable plan `irVersion` 5. Only
-the current `irVersion` executes: a run frozen at an older version keeps
-`status`, `list`, and `abandon` working, but `resume`/`next`/`complete`/`run`
-fail closed — abandon it and start a new run from current source. See
-[Architecture: The Workflow Engine](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md#resume-is-journaled-replay)
-for the exact policy and
-[Migrating from akm 0.9.1 to 0.9.2](https://github.com/itlackey/akm/blob/main/docs/migration/v0.9.1-to-v0.9.2.md#workflow-cutover)
-if you are upgrading with runs in flight.
+owners and executable targets, then freeze durable plan `irVersion` 5. A
+stored plan is read back as it is: one frozen at another `irVersion` that
+still decodes runs, and one this akm cannot decode is abandoned by
+`akm workflow run` with a message naming how to start a new run. See
+[Architecture: The Workflow Engine](https://github.com/itlackey/akm/blob/main/docs/architecture/workflow-engine.md#resume-skips-completed-units).
 
 A step can compose another workflow as a child — directly
 (`uses: workflows/<ref>`) or through a task whose own target is a workflow
@@ -121,7 +118,7 @@ service events, and runners; none of those capabilities is implied by 0.9.2.
 - [Capture Knowledge](https://github.com/itlackey/akm/blob/main/docs/guides/capture-knowledge.md) — turn a workflow run's
   outputs into searchable memories
 - [Improve the Library](https://github.com/itlackey/akm/blob/main/docs/guides/improve-the-library.md) — feed run outcomes
-  back into a workflow asset's ranking and proposed edits
+  back into a workflow asset's utility score and proposed edits
 - [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) — the workflow asset type and run-state
   storage in the broader AKM model
 - [CLI Reference](cli.md) — full flag documentation for all `workflow`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.17-alpha.3",
+  "version": "0.9.17-alpha.4",
   "type": "module",
   "description": "akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cursor.",
   "keywords": [