akm-cli 0.9.1 → 0.9.2-alpha.2

package/docs/reference/configuration.md

@@ -9,22 +9,10 @@ directory. Project `.akm/config.json` files are not merged.
 
 A present configuration file must set `configVersion` to exactly `"0.9.0"`.
 Missing, older, newer, numeric, and malformed versions are rejected by ordinary
-commands without rewriting the file. `akm migrate status` reports config and
-database state independently; it exits nonzero when migration is blocked.
-`akm migrate apply` installs an operator-prepared 0.9 config and applies pending
-database migrations, but it never guesses profile-to-engine mappings. See [the
-migration guide](../migration/v0.8-to-v0.9.md) before editing an existing
-installation.
-
-Canonical config and durable database access fail closed while a restore or
-migration-apply operation is incomplete. Use `akm migrate status` to inspect it
-and `akm migrate apply` to retry; do not delete migration control files manually.
-
-AKM 0.8 does not provide these migration commands. To cross from 0.8 to 0.9,
-prepare the target and an independent filesystem backup first, install or stage
-the 0.9 binary manually, then invoke that new binary with `migrate apply
---config`. Do not use `upgrade --migration-config` from 0.8; that installed 0.8
-code cannot enforce safeguards introduced by 0.9.
+commands without rewriting the file. 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 v2 to
+task v3 conversion.
 
 ```jsonc
 {
@@ -80,8 +68,17 @@ LLM endpoints must be complete `http://` or `https://` chat-completions URLs
 ending in `/chat/completions`, without userinfo, query, or fragment. API keys
 are symbolic only: `$VAR` or `${VAR}`. AKM resolves them only at dispatch.
 
-An agent engine may set `bin`, `args`, `workspace`, `model`, `timeoutMs`, and
-`modelAliases`. Only `platform: "opencode-sdk"` may set `llmEngine`; it names
+An LLM engine may set `reasoningEffort` to a non-empty provider-supported
+value such as `"none"`, `"low"`, or `"high"`. AKM sends it as the top-level
+OpenAI-compatible `reasoning_effort` parameter alongside the existing
+`enableThinking` control, because providers do not all honor the same thinking
+switch. `reasoning_effort` is AKM-owned and cannot be set through
+`extraParams`. If a response reports reasoning tokens despite
+`enableThinking: false`, AKM emits a runtime warning so an ineffective provider
+control is visible.
+
+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.
 
 `platform: "opencode-sdk"` needs the **`opencode` binary** on PATH (or a `bin`
@@ -90,10 +87,102 @@ client with no dependencies — it spawns `opencode serve` and talks to it — s
 the npm dependency alone does not make the platform usable. Install the binary
 with `npm i -g opencode-ai` or opencode's own installer.
 
-Config-root `modelAliases` resolve by exact engine/platform column first, then
-the shared `llm` column for direct and fallback LLM engines, then `"*"`. The
-resolved exact model is used consistently by direct dispatch, SDK fallback,
-health evidence, and frozen workflow plans.
+### Model-map files
+
+AKM ships an immutable `models.json` package asset with three intent aliases:
+`fast`, `balanced`, and `reasoning`. The installed starter has separate
+columns for Claude Code, OpenCode, and OpenCode SDK only. A provider-specific
+identifier is not pretended to work on unrelated engines. Add mappings for
+Gemini, Codex, named direct LLM engines, or other harnesses in your user file.
+Config-root and per-engine `modelAliases` are rejected; this file is the only
+alias definition surface.
+
+An optional operator-owned file lives beside `config.json` at
+`$XDG_CONFIG_HOME/akm/models.json` (or `<AKM_CONFIG_DIR>/models.json`). It uses
+the same version-1 schema as the installed file:
+
+```json
+{
+  "version": 1,
+  "aliases": {
+    "fast": {
+      "gemini": "gemini-2.5-flash"
+    },
+    "reasoning": {
+      "claude": {
+        "inference": {
+          "effort": "medium"
+        }
+      },
+      "local-reasoner": {
+        "model": "qwen3:30b",
+        "inference": {
+          "effort": "high"
+        }
+      }
+    }
+  }
+}
+```
+
+Each engine mapping is either a non-empty exact model string or a structured
+profile with the documented fields `model` and `inference`. A user profile may
+omit `model` when the installed layer already supplies it, as the partial
+Claude override above does. After overlay, every alias/engine entry must have a
+usable model. Unknown profile fields are rejected; JSON-safe fields inside
+`inference` are preserved for engine adapters to lower optimistically.
+
+The user file overlays the installed file by alias, engine, and nested object
+field. Objects merge recursively. Arrays, scalars, and explicit `null` replace
+the lower value; omitted fields preserve it. Alias and engine keys are
+case-normalized, and case-colliding definitions are rejected. Unknown model
+inputs still pass through byte-for-byte as exact identifiers. Once a name is a
+known merged alias, selecting an engine with no mapping is an actionable
+configuration error rather than silently sending the alias as a model ID.
+
+The common execution cascade reads these files for current direct command and
+non-interactive agent calls, task-v3 runs, and improve/proposal/index
+model work routed through that resolver. A structured alias expands as
+defaults at the layer that selected it; explicit sibling fields and nearer
+layers still win. The resulting request carries the exact model ID and merged
+inference object. Engine lowerers consume that exact selection and never run
+alias resolution again. New workflow starts persist the exact request and
+symbolic runner selection in durable plan v4; resume consumes that frozen
+material without resolving aliases again.
+
+Copy the complete installed starter into the user configuration directory when
+you want to customize all fields:
+
+```sh
+akm models copy-defaults
+akm models copy-defaults --overwrite  # explicit replacement confirmation
+```
+
+The command validates the installed asset, creates the config directory, and
+writes a fully synced sibling before publication. Without `--overwrite`, a
+hard-link/no-replace operation makes publication atomic: a racing creator wins
+without losing its bytes. A filesystem that cannot provide that operation
+fails safely instead of falling back to a clobbering rename.
+
+With `--overwrite`, the portable guarantee is an atomic pathname replacement
+that never follows the target when it is a symlink. AKM verifies the observed
+regular-file identity again immediately before rename, but the portable
+filesystem APIs do not provide a conditional compare-and-swap rename. Another
+process can still change the directory entry after that check; AKM replaces
+the entry at the pathname without dereferencing it. Consequently,
+`overwritten: true` means overwrite was requested for an entry AKM observed,
+not that an inode identity was transactionally locked. Symlinks and other
+non-regular targets observed at either check are refused.
+
+AKM does not auto-create or sync this file, and authoritative defaults never
+live in the cache. npm/Node and normal Bun installs read the packaged
+`dist/assets/models.json` lazily, so `akm health` can report a missing or
+malformed package asset as a `model-map-files` failure. A standalone binary has
+the same authoritative bytes embedded at compile time and therefore has no
+external model-map asset that can later disappear; its health check validates
+the embedded copy, and release tests pin copied bytes to `src/assets/models.json`.
+The health check passes when the optional user file is absent and warns with
+its path and JSON location when the user file is unreadable or invalid.
 
 `defaults.engine` names an LLM or agent engine. `defaults.llmEngine` must name
 an LLM engine. There is no first-engine fallback: an unset `defaults.engine`
@@ -157,6 +246,32 @@ incompatible engine never falls back to another engine. Built-in strategies
 are complete presets. User-defined strategies inherit omitted fields from the
 built-in `default` strategy before applying their own overrides.
 
+`processes.triage.judgment` explicitly controls the optional judgment tier.
+Use `true` to enable it, `false` to disable it, or an object with `enabled`,
+`engine`, `model`, `timeoutMs`, and/or `llm` overrides. Existing object values
+such as `{}` and `{ "engine": "reviewer" }` remain enabled by default. Unknown
+object keys are rejected so misspellings cannot silently change execution;
+the retired `mode` and `profile` keys continue to report their engine migration
+guidance. When enabled, engine selection is judgment → triage → strategy →
+`defaults.llmEngine`, and resolution fails closed if none is available.
+
+```jsonc
+{
+  "improve": {
+    "strategies": {
+      "nightly": {
+        "processes": {
+          "triage": {
+            "enabled": true,
+            "judgment": { "enabled": true, "engine": "reviewer" }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
 The shipped `default` and `frequent` strategies keep improve-stage session
 extraction off. `proactiveMaintenance` is off in `default` and
 `reflect-distill`; run `akm improve --strategy proactive-maintenance` to use the
@@ -173,15 +288,12 @@ bundled.
 
 ## Indexing
 
-`index.indexBodyOpening` defaults to `false`. When enabled, AKM captures the
-first prose paragraph of each Markdown asset body, capped at 280 characters,
-into the lowest-weight search content and embedding text. Secret and env files
-are never read for this field, and session-kind memories are excluded.
-
-Changing this option changes indexed text. Run `akm index --full` after
-toggling it so all entries and embeddings are rebuilt consistently. If the
-setting differs from the state used to build the current index, AKM warns until
-that full rebuild completes.
+AKM-native Markdown contributes a normalized body projection to the
+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
 
@@ -190,6 +302,17 @@ embedding-based search. `"auto"` lets AKM set up embeddings (which downloads
 a local model unless you point `embedding` at a remote provider) and falls
 back to keyword-only FTS if the embedding runtime is unavailable; `"off"`
 disables semantic search outright and search is always keyword-only FTS.
+If a backend marked ready cannot serve a query, search still returns the FTS
+results but reports `searchMode: "fts-fallback"` and one sanitized warning.
+This is distinct from `searchMode: "keyword"`, which is the normal result when
+semantic search is disabled or has not been built. A read-only sandbox that
+cannot record best-effort usage telemetry does not by itself mark search as
+degraded.
+The npm/Bun package declares `@huggingface/transformers` as a normal dependency.
+AKM imports that external package directly; it does not carry a copied runtime
+under `src/` or `dist/`. If the dependency is unavailable, reinstall `akm-cli`
+or configure a remote `embedding.endpoint`. Setup does not mutate a global
+installation to add runtime packages.
 The default is `"off"` so a bare or headless install (`akm bundle create`, `--yes`,
 `--config`) never silently downloads the local embedding model on first
 index.
@@ -284,6 +407,10 @@ Each entry is `{ url, name?, enabled?, provider?, options? }`; `provider`
 defaults to `"static-index"`. See [Registries](https://github.com/itlackey/akm/blob/main/docs/reference/registry.md) for the full
 field reference and provider list.
 
+Registry `url` values must not contain username/password userinfo. The built-in
+providers do not currently support authenticated registry requests; `options`
+does not add an authentication mechanism. Use a credential-free HTTPS endpoint.
+
 ## Output defaults
 
 `output.format` (one of `json`\|`yaml`\|`text`\|`jsonl`\|`md`\|`html`,
@@ -327,10 +454,6 @@ akm config get engines.fast
 akm config set engines.fast '{"kind":"llm","endpoint":"http://localhost:11434/v1/chat/completions","model":"qwen3"}'
 akm config set engines.fast.apiKey '$LOCAL_LLM_API_KEY'
 akm config unset engines.old
-akm migrate status
-akm migrate status --config ./prepared-0.9.json
-akm migrate apply --config ./prepared-0.9.json --dry-run
-akm migrate apply --config ./prepared-0.9.json
 ```
 
 Object values passed to `config set` deep-merge with their current value.
@@ -347,7 +470,7 @@ generic walker.
 | `AKM_LLM_API_KEY` | Fallback only for the selected `defaults.llmEngine` |
 | `AKM_EMBED_API_KEY` | Embedding credential |
 | `AKM_BUNDLE_DIR` | Override the bundle directory |
-| `AKM_DATA_DIR` | Override the data directory — durable `index.db`/`workflow.db`/`state.db`, `akm.lock`, config backups (or set `XDG_DATA_HOME`) |
+| `AKM_DATA_DIR` | Override the data directory — `index.db`, durable `state.db`, and `akm.lock` (or set `XDG_DATA_HOME`) |
 | `AKM_CACHE_DIR` | Override the cache directory — regenerable caches (or set `XDG_CACHE_HOME`) |
 | `AKM_STATE_DIR` | Override the state directory — task-scheduler invocation state (or set `XDG_STATE_HOME`) |
 | `AKM_SQLITE_JOURNAL_MODE` | SQLite journal mode: `WAL` (default), `DELETE`, or `TRUNCATE` |

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

@@ -22,6 +22,24 @@ In every case the receiving endpoint is one you configured or invoked; the data
 
 ---
 
+## Dry runs and diagnostic output
+
+Command dry-run is an intentionally zero-write diagnostic.
+A command dry-run does not mutate or write authored source.
+A command dry-run does not mutate or write durable state.
+A command dry-run records no usage.
+A command dry-run emits no events.
+A command dry-run performs no accounting.
+
+`akm command run --dry-run` still reads the selected source and configuration,
+performs authorization, and lowers a request. It does not dispatch or
+materialize credentials. Its output contains only safe field provenance and
+fixed lowering notices; resolved prompt, command, environment, endpoint,
+model, and credential values are excluded. Live `--verbose` writes the same
+safe diagnostic metadata to stderr while preserving normal stdout.
+
+---
+
 ## Local On-Disk Surface
 
 AKM writes to these locations on your machine. All paths follow [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/latest/) conventions on Linux/macOS and Windows conventions on Windows.
@@ -141,7 +159,7 @@ the set of types the code actually emits at HEAD (verified against every
 | `show` | `akm show <ref>` | `ref`, `type`, `name` |
 | `select` | `akm show` after a search returning the same ref | `ref`, `entryId` |
 | `feedback` | `akm feedback <ref>` | `signal` (positive/negative) |
-| `sync` | `akm sync` (renamed from `save` in 0.9.0; historical rows keep `save`, and `akm log --type save`/`--type sync` are synonyms on read) | `ref` |
+| `sync` | `akm sync` | `ref` |
 | `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` |

package/docs/reference/supported-formats.md

@@ -18,10 +18,10 @@ one explicitly. 0.9.0 recognizes 11 formats.
 | `website-snapshot` | Crawled pages tagged `website` (name, description, full body, original crawl URL) | Root `manifest.json` with `url` + `fetchedAt` | Read-only | A website materialized locally via `akm bundle add <url>` |
 | `agent-skills` | Standalone Agent Skills packages as type `skill` (name, description, tags, body) | A direct child directory containing `SKILL.md` | Read-only | The [github.com/anthropics/skills](https://github.com/anthropics/skills) layout — one `<name>/SKILL.md` per package at the bundle root |
 | `claude` | `CLAUDE.md` as `instruction`; `commands/`, `agents/`, `skills/<name>/SKILL.md` as their matching types | Root `CLAUDE.md` plus at least one of `commands/`, `agents/`, `skills/` | Read-only | Point AKM at an existing Claude Code `.claude` tool directory |
-| `opencode` | Same shape as `claude`, rooted on `AGENTS.md` | `opencode.json`/`opencode.jsonc`, or root `AGENTS.md` plus a tool directory (plural or singular alias) | Read-only | Point AKM at an existing OpenCode `.opencode` tool directory |
+| `opencode` | Same shape as `claude`, rooted on `AGENTS.md` | `opencode.json`/`opencode.jsonc`, or root `AGENTS.md` plus a canonical plural tool directory | Read-only | Point AKM at an existing OpenCode `.opencode` tool directory |
 | `dotenv` | `env` entries as key names only (never values); `secret` entries as file names only (never content) | Every top-level directory is `env/` and/or `secrets/`, with at least one present | Writable, narrowly — `akm env create`/`env remove`/`secret set` only | A standalone env/secrets-only bundle |
-| `akm-workflow` | Workflow steps, name, description, tags | A top-level `.md` file with explicit `type: workflow` frontmatter | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
-| `akm-task` | Tasks as type `task`, name, full raw YAML | A top-level `.yml` file that parses with a non-empty `schedule` key | Read-only | A standalone scheduled-task bundle |
+| `akm-workflow` | Workflow steps, name, description, tags | Either a top-level `.md` file with explicit `type: workflow` frontmatter or a peer top-level GitHub-shaped `.yml` workflow | Writable — `akm workflow create` only | A standalone workflow bundle, one workflow per file |
+| `akm-task` | Strict task-v3 `.yml` sources (`version: 3`) as type `task`, including local schedules/manual triggers and the exact authored YAML | A top-level `.yml` file accepted by the task-v3 source probe (`akm.schedule` or supported `on`) | Read-only | A standalone scheduled-task bundle; `.yaml` is rejected |
 | `llm-wiki` | `raw/` sources as `wiki-source`; `pages/` as their `pageKind` (default `note`), with resolved cross-reference links | Root `schema.md` plus a `pages/` directory | Read-only (author by writing directly into `pages/`; AKM indexes and serves the result) | [Karpathy's LLM-wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — agent-authored reference wikis |
 | `akm` (native) | AKM's own 14 native asset types — see [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) | A `.stash` marker directory, or two-plus native subdirectories, or the fallback when nothing else matches | Fully writable — every AKM-native write command | Your working bundle, and any bundle authored as AKM's own format |
 | `okf` | Frontmatter `type` (defaults to `knowledge`); name, description, tags, links, body | A root `index.md`, or any `.md` file anywhere carrying a non-empty frontmatter `type` | Read-only | The [Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) — the portable baseline every markdown-based format here is a superset of |
@@ -32,6 +32,25 @@ import`, `proposal accept`, and similar) won't create or edit files in a
 bundle of that format. Reading, searching, and `akm lint` validation work
 against every format in the table above regardless of write support.
 
+For native tool formats such as `claude` and `opencode`, the adapter translates
+recognized native agents and commands into AKM's indexed/runtime representation
+when the bundle is read. AKM does not create a canonical copy, synchronize tool
+directories, or write translated assets back into those native bundles. The
+native files remain authoritative.
+
+## Task format
+
+The `akm-task` adapter and native AKM task directory use the same strict
+`version: 3` task-v3 contract. An `akm-task` source is `.yml` only; `.yaml` is
+diagnosed but never indexed, scheduled, or executed. See [Tasks](tasks.md).
+
+## Workflow formats
+
+Workflow sources are the one intentional peer-format case inside the native
+AKM workspace: workflows may be `.md` or `.yml`, and both compile to the same
+source IR. Task sources remain `.yml` only and require task v3. See
+[Tasks](tasks.md) and [Workflow Schema](workflow-schema.md).
+
 ## Why this matters
 
 This table is the proof of the first pillar: **one library for every agent**.
@@ -46,5 +65,6 @@ formats are writable today and why.
 
 - [Asset Types](https://github.com/itlackey/akm/blob/main/docs/reference/asset-types.md) — the 14 native asset types AKM's own format recognizes
 - [Adapters](https://github.com/itlackey/akm/blob/main/docs/architecture/adapters.md) — how AKM picks a format, the write-path internals, and current caveats
+- [Agent, Command, Engine, and Model Resolution](https://github.com/itlackey/akm/blob/main/docs/architecture/specs/agent-command-engine-model-design.md) — approved runtime semantics for translated native agents and commands
 - [Concepts](https://github.com/itlackey/akm/blob/main/docs/guides/concepts.md) — the retrieval loop these formats feed
 - [Wikis](https://github.com/itlackey/akm/blob/main/docs/guides/wikis.md) — the `llm-wiki` authoring workflow

package/docs/reference/tasks.md

@@ -0,0 +1,182 @@
+# Tasks
+
+Task assets are strict, local automation sources. They live at
+`<bundle>/tasks/<id>.yml`, use task schema `version: 3`, and can be run directly
+or reconciled to cron, launchd, or Windows Task Scheduler with `akm task sync`.
+The task file is authored source; scheduler entries are derived OS state.
+
+## 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: 3`; unknown keys
+and older versions fail closed. The published [task schema](../../schemas/akm-task.json)
+describes the hand-authored contract, while `src/tasks/source-v3.ts` remains the
+authoritative bounded parser.
+
+At the top level a task can use `name`, exactly one executable selector, common
+step fields, and exactly one trigger source:
+
+```yaml
+version: 3
+name: Nightly review
+uses: workflows/nightly-review
+with:
+  strict: true
+akm:
+  schedule: "0 4 * * *"
+  enabled: true
+  timeout: 30m
+```
+
+Task YAML is bounded before expansion: source size, YAML depth, aggregate node
+count, mapping width, string size, and collection sizes all have finite limits.
+Aliases, merge keys, custom tags, duplicate keys, accessors, and non-plain data
+are rejected rather than normalized.
+
+## Executable targets: `uses` or `run`
+
+A task selects exactly one of `uses` or `run`; the two fields are mutually
+exclusive.
+
+`uses` accepts these 0.9.2 target shapes:
+
+- `akm/command`, the built-in inline/referenced command action. Its `with`
+  object requires exactly one of `with.ref` or `with.content`; they are
+  mutually exclusive. `with.arguments` is one optional portable string, used
+  for the single, one-pass `$ARGUMENTS` substitution.
+- Asset refs rooted at `commands/`, `workflows/`, or `scripts/`, optionally
+  qualified with a bundle such as `team//commands/review`.
+- A revision-qualified GitHub action spelling such as `owner/repo@ref` or
+  `owner/repo/path@revision`. That syntax is recognized so it cannot be
+  mistaken for an AKM ref, but remote action acquisition and execution are
+  unsupported in 0.9.2 and fail before dispatch.
+
+Agent refs such as `agents/reviewer` are personas and are not executable.
+Task refs such as `tasks/nightly` are also not executable. Local actions
+(`./action`) are rejected and Docker actions (`docker://image`) are unsupported.
+GitHub expressions are unsupported and rejected before dispatch. Unqualified
+remote actions are rejected too.
+
+The runtime applies this target-by-target field matrix. Validation is strict;
+fields are not silently discarded.
+For `scripts/` asset refs, `with` is rejected before dispatch.
+
+| Target | `with` | task `env` | Interpreter / execution |
+|---|---|---|---|
+| `run` | Rejected; `with` is legal only with `uses` | Allowed | One authored string through the selected closed host `shell` |
+| `akm/command` | Required action object: exactly one of `ref` or `content`, plus optional portable `arguments` | Allowed and passed through the command resolver | Shared command authorization and lowering |
+| `commands/<name>` | Direct command refs: `with` is rejected; use `akm/command` for portable arguments | Allowed and passed through the command resolver | Shared command authorization and lowering |
+| `workflows/<name>` | Of asset refs, workflow refs alone consume `with` as workflow params | A nonempty task `env` is rejected because the durable workflow runtime cannot consume it in 0.9.2 | Fresh durable workflow start |
+| `scripts/<name>.<ext>` | Script refs: `with` is rejected | Allowed for the child process | Closed extension-to-interpreter table below |
+| `owner/repo[/path]@ref` | Not consumed | Not consumed | Recognized spelling, but remote acquisition is rejected in 0.9.2 |
+
+Script refs use this closed table; any other extension fails before dispatch:
+
+| Extensions | Interpreter |
+|---|---|
+| `.sh` | `sh` |
+| `.ts`, `.js` | Bun; JavaScript and TypeScript script targets require Bun (the standalone binary uses its embedded Bun runtime) |
+| `.ps1` | `powershell -NoProfile -NonInteractive -File` |
+| `.cmd`, `.bat` | `cmd /d /s /c` |
+| `.py` | `python` |
+| `.rb` | `ruby` |
+| `.go` | `go run` |
+| `.pl` | `perl` |
+| `.php` | `php` |
+| `.lua` | `lua` |
+| `.r` | `rscript` |
+| `.swift` | `swift` |
+| `.kt`, `.kts` | Kotlin (`kotlin` for `.kt`, `kotlinc -script` for `.kts`) |
+
+`run` is one non-empty shell string. It may specify `shell` from the closed host
+shell table `bash`, `sh`, `zsh`, `pwsh`, `powershell`, or `cmd`. Shell expansion
+is runtime behavior for an explicitly authored task `run`; AKM does not infer a
+shell from `uses`. `working-directory` must be a relative, contained path under
+the task's workspace root. Absolute paths, traversal, dangling links, and
+symlink escapes fail before execution.
+
+Common resolver fields live under `akm`: `agent`, `engine`, `model`,
+`inference`, `outputSchema`, `tools`, `timeout`, `redact`, `maxSteps`, and
+`maxRetries`. Environment entries are literal string, number, or boolean
+values. Keep credentials out of task source; `redact` contains environment
+variable names, never secret values.
+
+## Scheduling and triggers
+
+A task has exactly one scheduling source: either `akm.schedule` or top-level
+`on`. The two sources are mutually exclusive.
+
+The compact AKM spelling is:
+
+```yaml
+version: 3
+run: akm improve --strategy default
+akm:
+  schedule: "@daily"
+  enabled: false
+```
+
+The GitHub-shaped local trigger subset accepts schedule entries and an empty
+manual trigger:
+
+```yaml
+version: 3
+uses: commands/review
+on:
+  schedule:
+    - cron: "0 6 * * *"
+  workflow_dispatch: {}
+```
+
+`workflow_dispatch` accepts no inputs. Service events such as `push` are
+rejected and create no watcher or polling daemon. A source with only
+`workflow_dispatch` is manual-only and is not installed as a time schedule.
+Multiple schedule entries create deterministic scheduler bindings for the one
+source task.
+
+`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.
+
+## Migrating task v2 to v3
+
+Normal execution rejects task v2 and prints the migration hint. Preview the
+same fail-closed migration plan that apply consumes:
+
+```sh
+akm migrate apply --dry-run
+akm migrate apply
+```
+
+The planner reports every input file as `changed`, `skipped`, or `blocked`.
+Deterministic prompt, command-ref, workflow-ref, and safe command-string cases
+become v3. An argv array or any command whose shell meaning cannot be preserved
+is blocked for manual review and remains untouched. Apply validates a complete
+v3 replacement before writing and backs up each original immediately before
+replacement.
+
+See the [0.9.1 to 0.9.2 migration guide](../migration/v0.9.1-to-v0.9.2.md)
+for before/after examples, preserved fields, and recovery guidance.
+
+## Operations
+
+- `akm search --type task` and `akm show tasks/<id>` inspect task assets.
+- `akm task add` writes a task-v3 source and installs it after validation.
+- `akm task history` reads durable run history from `state.db`.
+- Set `akm.enabled: false` and sync to disable a binding.
+- Delete the `.yml` source and sync to remove its derived binding.
+- Use `akm task sync --rebind` only when deliberately changing the captured
+  AKM runtime, then verify with `akm task doctor`.
+
+Scheduler execution is at least once. Backends provide a stable invocation
+identity and AKM fences stale attempts, but an ambiguous process crash can be
+observed only after the external work has started. Make scheduled side effects
+idempotent where possible.
+
+## See also
+
+- [CLI Reference: task](cli.md#task)
+- [Scheduling guide](https://github.com/itlackey/akm/blob/main/docs/guides/scheduling.md)
+- [Workflow source formats](workflow-schema.md)
+- [Data and telemetry](data-and-telemetry.md)