akm-cli 0.9.16-alpha.1 → 0.9.16

package/docs/reference/configuration.md

@@ -16,14 +16,13 @@ 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 and are not migrated by `akm upgrade`. Configure the current schema
-directly. The standalone migrator exists only for explicit task migration:
-task v2 to task v3, then task v3 to task source v4, in one pass.
+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
 
-Like the task-source v2/v3 auto-shim (`akm migrate apply`'s in-memory
-counterpart, documented under Migration below), a known older `configVersion`
+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
@@ -64,6 +63,9 @@ the first bump that will need it, per #863.
     "maxConcurrency": 8,
     "judgeEngine": "reviewer"
   },
+  "execution": {
+    "allowedTools": ["read_file", "search"]
+  },
   "improve": {
     "strategies": {
       "nightly": {
@@ -78,6 +80,25 @@ 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.
+
+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
+can activate schedules. Prefer `akm task enable <ref>` and `akm task disable
+<ref>` over editing the JSON by hand; both update the allow-list and sync the
+affected bundle. An unscoped `akm task sync` reconciles enabled refs across all
+enabled configured bundles.
+
 ## Engines
 
 `engines` is the only public execution map. An engine name is lowercase
@@ -112,6 +133,12 @@ An agent engine may set `bin`, `args`, `workspace`, `model`, and `timeoutMs`.
 Only `platform: "opencode-sdk"` may set `llmEngine`; it names
 the LLM engine used as that SDK engine's fallback connection.
 
+Executable assets may request tools, but the request is not authority. Configure
+the host-local `execution.allowedTools` list to define the ceiling; `"*"` is an
+explicit allow-all. The default is an empty list. Asset frontmatter cannot set
+`workspace`, `environment`, or opaque `runtime` values; those belong to local
+engine configuration or workflow environment bindings.
+
 `platform: "opencode-sdk"` needs the **`opencode` binary** on PATH (or a `bin`
 pointing at it). akm bundles `@opencode-ai/sdk`, but that package is an HTTP
 client with no dependencies — it spawns `opencode serve` and talks to it — so
@@ -357,17 +384,11 @@ bundled.
 ## Indexing
 
 AKM-native Markdown contributes a normalized body projection to the
-lowest-weight `content` search field. The projection removes frontmatter,
-comments, fenced code, and link destinations, and is never produced for
-secret, env, session, or session-checkpoint assets.
-
-Embedding input is not capped or truncated at all (index redesign): each
-entry's structured fields (name/description/tags/hints) become one "card"
-unit and each Markdown fragment becomes one "fragment" unit
-(`src/indexer/units/unit.ts`), and a unit whose text would still exceed the
-embedding provider's own probed window is split into ordinal sub-units that
-share its fragment id — never truncated. See [Semantic
-search](#semantic-search) for how that window is probed.
+lowest-weight `content` search field. The projection is capped at 16,384
+characters, removes frontmatter, comments, fenced code, and link destinations,
+and is never produced for secret, env, session, or session-checkpoint assets.
+Embedding input is separately capped at 8,192 characters with structured
+metadata placed before body content.
 
 ## Semantic search
 
@@ -402,80 +423,76 @@ unless a remote `embedding` config is provided.
 `akm improve`'s memory-inference/consolidate passes when they call an
 embedding model: `provider`, `endpoint`, `model`, `apiKey` (symbolic
 reference, same rules as engine `apiKey`), `dimension`, `localModel`,
-`timeoutMs`, `concurrency`, and `ollamaOptions.num_ctx`.
-
-Request PACKING — how many documents land in one HTTP request, and the
-token budget that bounds it — is no longer config at all. `akm index`
-probes the embedding endpoint itself (llama.cpp's `GET /props`, Ollama's
-`POST /api/show`) for its real context window and in-flight slot count
-before packing any request, calibrating its chars-per-token estimate
-against the provider's own tokenizer (llama.cpp's `/tokenize`) where it
-offers one; an endpoint that answers neither probe (an OpenAI-compatible server, a gateway) gets a
-conservative built-in default. This replaced four retired keys —
-`maxInputTokens`, `maxTokens`, `batchSize`, `contextLength` — see
-[Retired Configuration](#retired-configuration).
-
-The knobs that remain, both optional (defaults apply when unset), for a
-remote endpoint (`src/llm/embedders/remote.ts`):
+`maxInputTokens`, `maxTokens`, `batchSize`, `contextLength`, `timeoutMs`,
+`concurrency`, and `ollamaOptions.num_ctx`.
+
+The knobs that bound request/document size and rate, all optional (defaults
+apply when unset), for a remote endpoint (`src/llm/embedders/remote.ts`):
 
 | Key | Default | Bounds |
 | --- | --- | --- |
+| `embedding.maxInputTokens` | `512` | Per-DOCUMENT cap, applied before batching (#956). A document's embedded text is truncated to its head (unicode-safe) at this many estimated tokens instead of ever being skipped for size alone — a document is skipped only when its truncated head is empty. |
+| `embedding.maxTokens` | `6000` (`DEFAULT_TOKEN_BUDGET`) | Per-REQUEST token budget: how many (already-capped) documents' estimated tokens fit in one HTTP request. With the 512-token default document cap, a request carries about 11 documents by default. Lowered from 8000 to 6000 (#954): the 4-chars-per-token estimator undercounts dense technical text by 7-55%, so 8000 regularly overshot an 8192-token endpoint's real context window. |
+| `embedding.batchSize` | `100` | Per-REQUEST document-COUNT safety cap, independent of the token budget — guards against many tiny documents packing an oversized request. |
+| `embedding.contextLength` | unset | Ollama's `num_ctx` ONLY, forwarded verbatim as `options.num_ctx` on the native `/api/embed` request. Does **not** feed the request token budget above (#956) — the two used to share this one field, so setting it for the server's context window silently changed request batching too. |
 | `embedding.timeoutMs` | `120000` (120s) | Per-request wall timeout — see below. |
-| `embedding.concurrency` | `1` loopback / `2` remote, or the provider's own probed slot count | In-flight request window — see below. |
-
-**What used to fix the field's 8k-context overflow.** A 0.9.15-beta field
-report described documents estimated under the request budget that still
-tokenized to 8.5k-12.4k real tokens against an 8192-token endpoint, because
-the 4-chars-per-token estimator undercounts dense technical text.
-0.9.15-beta answered it with three of the four now-retired keys; none of
-them does anything in this release (see [Retired
-Configuration](#retired-configuration)), but the shape of the old fix is
-worth knowing because the probed-window replacement above closes the same
-gap structurally instead of by convention:
-
-- `embedding.maxInputTokens: 512` used to be a per-DOCUMENT cap, applied
-  before batching. This was the actual fix for the original overflow: no
-  single document could contribute more than 512 estimated tokens to a
-  request, no matter how `maxTokens` or `contextLength` were set.
-- `embedding.maxTokens: 6000` used to be the per-REQUEST budget: how many
-  already-capped documents' estimated tokens fit in one HTTP request. A
-  request-level budget alone could not stop one oversized document from
-  overflowing a request — only the per-document cap above did that.
-- `embedding.contextLength: 8192` fed only Ollama's `num_ctx`, forwarded
-  verbatim on a native `/api/embed` request. It never bounded request or
-  document sizing, and had no effect at all against a non-Ollama endpoint.
-
-None of the three is read any more. A field config still carrying
-`contextLength: 8192` + `maxTokens: 8000` (the exact 0.9.15-beta values
-from the original report) loads on this release without error and without
-effect — the same "ignored, unvalidated, no warning" handling every retired
-key gets (see below) — because `akm index` now probes the endpoint's real
-context window itself and packs every request against that instead of
-against a configured estimate, so the original overflow is unreachable
-regardless of what either retired key is set to.
+| `embedding.concurrency` | `1` loopback / `2` remote | In-flight request window — see below. |
+
+**Which knob fixed the field's 8k-context overflow, worked examples.** A
+0.9.15-beta field report described documents estimated under the request
+budget that still tokenized to 8.5k-12.4k real tokens against an
+8192-token endpoint, because the 4-chars-per-token estimator undercounts
+dense technical text. Three knobs changed shape between beta and this
+release; only one of them makes that overflow structurally unreachable:
+
+- `embedding.maxInputTokens: 512` — per-DOCUMENT cap, applied before
+  batching. Example: a 6,000-character API reference page is truncated to
+  its first ~2,000 characters (512 estimated tokens) before it is ever
+  counted toward a request. This is the fix for the original overflow: no
+  single document can contribute more than 512 estimated tokens to a
+  request, no matter how `maxTokens` or `contextLength` are set.
+- `embedding.maxTokens: 6000` — per-REQUEST budget: how many already-capped
+  documents' estimated tokens fit in one HTTP request. Example: with the
+  default 512-token document cap, a request packs about 11 documents before
+  this budget is reached and the request is sent; if the run's first
+  request is still rejected for exceeding the endpoint's real context
+  window, akm shrinks this budget to three quarters of its value (floored
+  at twice `maxInputTokens`) for every later request in the same run. A
+  request-level budget alone cannot stop one oversized document from
+  overflowing a request — only the per-document cap above does that.
+- `embedding.contextLength: 8192` — Ollama's `num_ctx` only, forwarded
+  verbatim on a native `/api/embed` request. It has no effect on request or
+  document sizing, and no effect at all against a non-Ollama endpoint — see
+  below for why that used not to be true.
+
+A field config of `contextLength: 8192` + `maxTokens: 8000` (the exact
+0.9.15-beta values from the original report) produces no 400s on 0.9.15:
+`maxInputTokens` (512, new this release) caps every document before it is
+counted, so the original 8.5k-12.4k-token documents that overflowed the
+8192-token endpoint can never reach the request budget in the first place —
+independent of whatever `maxTokens` or `contextLength` are set to.
 
 `embedding.timeoutMs` (positive integer, default `120000` — 120s) is the
-budget for a request at the FULL (probed) token budget; a local model
-server on a large, token-budget-bounded batch legitimately takes longer
-than the prior fixed 30s cut off. A smaller request gets a proportionally
-smaller timeout —
+budget for a request at the FULL token budget (`embedding.maxTokens`); a
+local model server on a large, token-budget-bounded batch legitimately takes
+longer than the prior fixed 30s cut off. A smaller request gets a
+proportionally smaller timeout —
 `clamp(timeoutMs × requestTokens / tokenBudget, 30000, timeoutMs)` — so a
 dead endpoint is still detected in seconds on the common case of small
 documents. Set `embedding.timeoutMs` lower to fail fast against a
 known-fast endpoint, or higher for a slow local server on large batches.
 
-The probed token budget is also a run-scoped adaptive starting point, not a
-hard ceiling, but ONLY when the endpoint did not report a real window of
-its own (an OpenAI-compatible server or gateway, the conservative built-in
-default): on the FIRST rejection of an `akm index` run for exceeding the
-endpoint's context window, akm shrinks the request budget to three quarters
-of its current value for every request not yet sent, and prints one line
-naming the new value. A window akm actually probed from the endpoint
-(llama.cpp, Ollama) is treated as authoritative and is never second-guessed
-this way — a rejection against it still recovers via the same
-split-and-retry every rejection gets (below), just without lowering the
-budget for the rest of the run. This never fires a second time in the same
-run either way.
+`embedding.maxTokens` (or its default) is also a run-scoped adaptive
+starting point, not a hard ceiling (#954): on the FIRST rejection of an
+`akm index` run for exceeding the endpoint's context window, akm shrinks
+the request budget to three quarters of its current value — floored at
+twice `embedding.maxInputTokens` — for every request not yet sent, and
+prints one line naming the new value. This never changes the rejected
+request's own split-and-retry (below), never shrinks a second time in the
+same run, and never grows the budget back up. Users who set
+`embedding.maxTokens` explicitly are unaffected by the LOWERED DEFAULT
+above but still benefit from this same-run recovery if their own value
+turns out to be too high for the endpoint.
 
 A request TIMEOUT (not a rejection for exceeding the context window) never
 drops its batch immediately: field confirmation showed that once akm
@@ -495,17 +512,19 @@ requests and reports failure — batches already committed are kept; rerun
 once (a remote endpoint only; the local transformer path is unaffected):
 `1` for a loopback endpoint (`localhost`, `127.0.0.0/8`, etc. — a local
 model server serves one inference at a time, and parallel requests thrash
-it) and `2` for a remote one, unless the provider's own probed slot count
-(llama.cpp's `total_slots`) or `embedding.concurrency` (positive integer,
-1-16, checked first) overrides it. This default holds for the overwhelming
-majority of setups; set an explicit override only for an endpoint that
-genuinely serves parallel requests — a local server started with a
-multi-slot flag (llama.cpp's `--parallel N`, vLLM) — not to "speed up" an
-ordinary single-slot model server, which the default already protects from
+it) and `2` for a remote one, unless `embedding.concurrency` (positive
+integer, 1-16) overrides it. This default holds for the overwhelming
+majority of setups; set the override only for an endpoint that genuinely
+serves parallel requests — a local server started with a multi-slot flag
+(llama.cpp's `--parallel N`, vLLM) — not to "speed up" an ordinary
+single-slot model server, which the default already protects from
 reload-thrash. Request SIZE remains the first throughput lever regardless:
-the probed token budget and document-count cap described above control how
-many documents land in one request, taking about the same wall time as a
-single one against a healthy endpoint.
+`embedding.batchSize` (a document-count cap, default 100) together with
+`embedding.maxTokens` (an estimated token budget per request, default 6000
+— NOT `embedding.contextLength`, see the table above) control how many
+documents land in one request — with the default 512-token
+`embedding.maxInputTokens` document cap, that is about 11 documents,
+taking about the same wall time as a single one against a healthy endpoint.
 
 ## Search tuning
 
@@ -513,6 +532,7 @@ single one against a healthy endpoint.
 
 | Key | Purpose |
 | --- | --- |
+| `search.minScore` | Drop results below this score |
 | `search.defaultExcludeTypes` | Asset types excluded from results by default |
 
 ### Graph boost search tuning
@@ -521,35 +541,22 @@ single one against a healthy endpoint.
 | --- | --- |
 | `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`) |
 
-### Search rerank (#951)
-
-An optional cross-encoder rerank pass over `akm search`'s already-ranked
-LOCAL stash hits, 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 search's own ranking unchanged. Applied once to local hits
-before `--from local`/`--from all` diverge, so both see the reranked order
-and neither double-applies it; registry hits (`--from registry`, and the
-registry half of `--from all`) are never reranked and never trigger the
-endpoint — registry results staying separate from stash hits is a locked
-contract (AGENTS.md).
+### Curate rerank (#951)
 
-Reranking changes hit ORDER only. Each hit's `score` is left as the
-retrieval score `akm search` already computed — see the score-vs-order note
-in `docs/reference/cli.md`'s search section for why.
-
-Moved here from `akm curate` in 0.9.16 (`search.curateRerank` →
-`search.rerank`) — the pass was always meant for search, not curate; see
-`docs/migration/release-notes/0.9.16.md`.
+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.
 
 | Key | Purpose |
 | --- | --- |
-| `search.rerank.enabled` | Turn the rerank pass on (default `false`) |
-| `search.rerank.endpoint` | Full URL of the reranker's rerank endpoint |
-| `search.rerank.model` | Model name sent to the endpoint (optional) |
-| `search.rerank.apiKey` | `$VAR`/`secret://<name>` credential reference (optional) |
-| `search.rerank.timeoutMs` | Request timeout (default `10000`) |
-| `search.rerank.topN` | How many of search's ranked LOCAL hits to send (default `8`, max `50`) |
+| `search.curateRerank.enabled` | Turn the rerank pass on (default `false`) |
+| `search.curateRerank.endpoint` | Full URL of the reranker's rerank endpoint |
+| `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`) |
 
 ## Feedback
 
@@ -571,6 +578,12 @@ bundle's `components.<id>.adapter` key pins it to a specific format adapter
 instead of relying on auto-detection — see [Bundle Types](bundle-types.md)
 for the full adapter list and what each one reads/writes.
 
+Each physical content root has one bundle id. Duplicate paths and symbolic-link
+aliases are rejected because source ownership, scheduler authority, and default
+selection must not depend on which spelling a caller used. If an older config
+contains aliases, choose the id whose durable refs should survive and remove
+the other entry before running ordinary commands.
+
 ### defaultWriteTarget
 
 `defaultWriteTarget` names the bundle that write commands (`akm remember`,
@@ -720,6 +733,16 @@ one file, and have each host's local config extend it.
   add`/`akm sync` first so the file is materialized locally, then point
   `extends` at it.
 
+Shared layers carry portable policy, not host authority. `bundles`, source and
+write defaults, registries, embedding connections, scheduler grants,
+`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
+the local file. Improve publication (`strategies.*.sync`) and reranker network
+configuration are local as well. Bundle-relative chains stay physically inside
+the bundle root for every hop; lexical `..` paths and symlink escapes are both
+rejected before a referenced file is read.
+
 There is no `extends: <url>` form: config load is synchronous and runs on
 every invocation, and akm deliberately does not fetch network resources at
 load time (the same reason `registries` is never fetched until a
@@ -824,22 +847,3 @@ profile identities.
 `embedding.chunkSize` was never read by anything under `src/` (#954), so a
 config that still sets it is simply ignored — it still loads, unvalidated
 and without warning.
-
-`search.minScore` was never read by anything under `src/` as of 0.9
-(index-redesign B5c), so a config that still sets it is simply ignored — it
-still loads, unvalidated and without warning. It used to tune a
-semantic-only floor over the old entries_fts + entries_vec search path,
-calibrated for that path's 0-1 cosine/BM25 scores. The single search path is
-`units_fts` + `units_vec`, scoring lexical evidence by BM25 magnitude and
-semantic evidence by cosine similarity on the same 0.7/0.3 split as before,
-on the scale the ranking contributors expect — no separate floor is applied.
-
-`embedding.maxInputTokens`, `embedding.maxTokens`, `embedding.batchSize`,
-and `embedding.contextLength` are retired (index redesign): `akm index`
-packs requests against the embedding provider's own probed context window
-and slot count instead (see [Semantic search](#semantic-search)). A config
-that still sets any of them is simply ignored — it still loads, unvalidated
-and without warning, the same as `embedding.chunkSize` above.
-`embedding.contextLength` specifically fed Ollama's `num_ctx`; that request
-field is now sent automatically from the same probe, or set explicitly via
-`embedding.ollamaOptions.num_ctx`.

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

@@ -208,8 +208,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `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` |
-| `task_logs_purged` | Old task-log rows (log lines in `logs.db`) deleted by improve maintenance | `purgedCount`, `retentionDays` |
-| `task_log_files_purged` | Old per-run flat task log files (the transitional `<taskId>/<timestamp>.log` tail files under the task log dir) deleted by improve maintenance | `purgedCount`, `retentionDays` |
+| `task_logs_purged` | Old scheduled-task log files purged by improve maintenance | |
 
 *Workflows*
 

package/docs/reference/tasks.md

@@ -148,12 +148,10 @@ name: Nightly review
 run: akm improve --strategy default
 schedule:
   - cron: "@daily"
-    enabled: false
 ```
 
-A bare string (`schedule: "0 8 * * 1"`) is shorthand for one enabled
-binding with no inputs. A list entry may set its own `enabled` (default
-`true`) and literal `inputs`; those literals are validated against the
+A bare string (`schedule: "0 8 * * 1"`) is shorthand for one trigger with
+no inputs. A list entry may set literal `inputs`; those literals are validated against the
 task's `inputs:` declarations both at parse time and again at
 `akm task sync` (once with declared defaults applied), and are
 **delivered** to the scheduled run: `akm task sync` compiles each entry's
@@ -163,18 +161,26 @@ fired run receives them exactly as `akm task run <id> --<name> <value>`
 would. Multiple schedule entries create deterministic scheduler bindings
 for the one source task.
 
-Task source v4 has **no document-level `enabled` flag** — enablement is
-per schedule binding. Disable one binding by setting its own
-`enabled: false`. `--schedule` is a required flag on every `akm task add`
-invocation, `--disabled` included — not a check specific to `--disabled` —
-so `akm task add --disabled` always has a schedule to write `enabled: false`
-onto and never needs to reject a schedule-less task with "nothing to
-disable."
+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.
 
 `akm task run <id>` executes a task immediately, including a disabled task.
-`akm task sync` validates the complete desired set before atomically
-reconciling scheduler state. Scheduled invocations re-read the guarded current
-task bytes; workflow targets then create a fresh durable workflow freeze.
+`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
+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.
 
 ## Typed inputs and output
 
@@ -200,7 +206,6 @@ output:
 uses: commands/review
 schedule:
   - cron: "0 8 * * 1"
-    enabled: true
     inputs: { scope: all, ticket: OPS-1234 }
 timeout: 45000
 engine: reviewer
@@ -229,9 +234,7 @@ redact: [TOKEN]
   field path (`schedule`, or `schedule[<i>]`), naming the unsatisfied
   input. The rule covers every entry: the `schedule: "<cron>"` string
   shorthand, a list entry with no `inputs:` key, and an entry whose
-  `inputs:` mapping is present but incomplete — including one written
-  `enabled: false`, so enabling it later can never turn a parsed document
-  unrunnable. `akm task sync` keeps its own equivalent check over the
+  `inputs:` mapping is present but incomplete. `akm task sync` keeps its own equivalent check over the
   defaulted values and still rejects the whole desired set before touching
   any scheduler state. Give every schedule entry an explicit value for the
   input, or declare a `default` instead; manual runs are unaffected — a
@@ -343,7 +346,8 @@ Common v2 → v3 blocked reasons and what to do about each — these need a
 hand-authored replacement, not a re-run; see [the 0.9.1 to 0.9.2 migration
 guide](../migration/v0.9.1-to-v0.9.2.md#v2--v3-blocked-cases) for the full v2
 to v4 field mapping (`command:` array → `run:` + `shell:`, `timeoutMs:` →
-`timeout:`, document-level `enabled:` → per-`schedule:`-entry `enabled`):
+`timeout:`). Source-owned `enabled` fields are removed; native bindings that
+are provably enabled seed the host-local activation list:
 
 | Reason | Meaning | Fix |
 |---|---|---|
@@ -357,7 +361,6 @@ Common v3 → v4 blocked reasons and what to do about each:
 | `github-action-target-removed` | The task's `uses:` is a GitHub Action locator (`owner/repo[/path]@ref`); that spelling has no task source v4 equivalent. | Rewrite the target as `commands/`, `scripts/`, `workflows/`, or `akm/command` by hand. |
 | `with-on-non-command-target` | A `with:` block is authored on a target other than `uses: akm/command`. | Task-call inputs are declared and bound separately in v4 — author `inputs:` on the task and, if it is a workflow step's own composition, bind them with the step's `with:` instead. |
 | `ambiguous-scheduling-source` | The document declares both `akm.schedule` and `on:`. | Pick one; the migrator will not guess which one wins. |
-| `enabled-false-has-no-schedule-entry` | `akm.enabled: false` with no cron trigger to attach it to (the only trigger is `on.workflow_dispatch`). | Task source v4 has no document-level `enabled` flag — decide whether the task should be scheduled (add a cron) or left manual-only (drop `akm.enabled`), then re-run. |
 | `read-only-source` | The owning source or file is not writable. | Move or re-source the file somewhere writable, or edit it by hand. |
 | `invalid-v3-task` | The v3 document itself is structurally invalid (unknown fields, missing selector, malformed trigger, etc). | Fix the underlying v3 document first — the migrator translates structure, it does not repair it. |
 | `generated-v4-validation-failed` | The converted bytes fail the real task source v4 parser; the detail carries the parse error. | Read the detail — it names the offending field and why v4 refuses it — then fix that field in the v3 file and preview again. |
@@ -402,20 +405,20 @@ 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`/`converts`/`blocked`/`invalid`/`not-a-task` diagnostic
+  `valid`/`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 originally declared schema version (2, 3, or 4).
+  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, and
-  `--disabled` writes `schedule: [{cron: …, enabled: false}]` instead of a
-  document-level flag.
+  `with:` bag; `--schedule` is required on every invocation. `--disabled`
+  leaves the new ref absent from local scheduler activation.
 - `akm task history` reads durable run history from `state.db`.
-- Disable a binding by editing the source and syncing: set that schedule
-  entry's own `enabled: false`.
+- `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 --dry-run` previews the reconcile (adds/updates/removes,
   removals annotated with their owning bundle) without writing to the
@@ -469,8 +472,10 @@ on:
 refs consumed it as run params; command/script refs rejected it outright).
 A GitHub Action locator (`owner/repo[/path]@ref`) was a recognized `uses:`
 shape that was always rejected before dispatch — remote action acquisition
-was never implemented in any akm release. `akm.enabled: false` disabled the
-whole document, not a specific schedule binding.
+was never implemented in any akm release. `akm.enabled` was source-owned
+scheduling state. `akm migrate apply` removes it; migration preserves actual
+host activation only when the native scheduler proves that the corresponding
+binding is enabled.
 
 See [Migrating to task source v4](#migrating-to-task-source-v4) above to
 convert a file out of this grammar.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akm-cli",
-  "version": "0.9.16-alpha.1",
+  "version": "0.9.16",
   "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": [