akm-cli 0.9.30 → 0.10.26101001-alpha

package/docs/guides/recipes/headless-install.md

@@ -0,0 +1,97 @@
+# Recipe: Headless Install
+
+A precise, no-prompts sequence for automated or agent-driven setup of `akm` —
+no interactive wizard, no assumed defaults.
+
+```sh
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 1. Install (standalone binary, runtime-free)
+curl -fsSL https://github.com/itlackey/akm/releases/latest/download/install.sh | bash
+
+# 2. Initialize the bundle directory and accept all defaults (no prompts)
+akm setup --yes
+
+# 3. Don't rely on the implicit semantic-search default in an unattended
+#    script — the default can vary by release and by install path. Set it
+#    explicitly so this script's behavior is deterministic. `auto` uses local
+#    embeddings (downloaded on first index run); `off` skips them entirely.
+akm config set semanticSearchMode auto
+
+# 4. Add sources (adjust paths as needed)
+akm bundle add /path/to/skills
+
+# 5. Build the search index (downloads the embedding model on first run if
+#    semantic search is enabled)
+akm index
+
+# 6. Verify
+akm info
+akm search "test"
+
+# 7. Install agent guidance
+akm hints --detail brief >> AGENTS.md
+
+echo "akm setup complete"
+```
+
+## Notes on each step
+
+**Install.** The standalone binary (step 1) is runtime-free. The npm package
+(`npm install -g akm-cli`, or one-shot via `npx akm-cli <command>`) requires
+Node.js >= 22; a working Bun >= 1.0 is optional and preferred for execution
+after Node starts the package launcher.
+
+**Setup.** `akm setup --yes` accepts every default with no prompts. To
+pre-configure an LLM or agent engine at the same time instead of accepting
+defaults, pass `--config` with a JSON object, optionally followed by
+`--probe` to verify connectivity:
+
+```sh
+akm setup --config '{
+  "engines": {
+    "default": {
+      "kind": "llm",
+      "endpoint": "http://localhost:11434/v1/chat/completions",
+      "model": "llama3.2"
+    }
+  },
+  "defaults": { "llmEngine": "default" }
+}' --probe
+```
+
+For the full set of accepted top-level `--config` keys and their meaning,
+see [configuration.md](../../reference/configuration.md).
+
+**Semantic search.** Headless setups (`--yes` or `--config`, no wizard
+prompts) defer the embedding-model download to the first `akm index` run,
+unlike the interactive wizard which downloads immediately during `akm
+setup`. Set the mode explicitly rather than relying on the implicit default:
+
+```sh
+akm config set semanticSearchMode auto   # local embeddings, downloaded on first index
+akm config set semanticSearchMode off    # skip embeddings entirely
+```
+
+For resource requirements and remote-embedding alternatives, see
+[configuration.md](../../reference/configuration.md).
+
+**Add source.** `akm bundle add <path|github:owner/repo|@scope/package>`
+registers a directory or package as a source. Add every source before
+indexing.
+
+**Index and verify.** `akm index` builds the search index; `akm info` reports
+`indexStats.entryCount` and `semanticSearch.status`; `akm search "<query>"`
+confirms retrieval actually returns results.
+
+**Install agent guidance.** `akm hints --detail brief >> AGENTS.md` appends the
+canonical usage block agents need to discover and use the library. Run this
+after indexing so the guidance matches the installed version.
+
+## See also
+
+- [configuration.md](../../reference/configuration.md) — full configuration
+  key reference
+- [docs/agents/agent-install.md](../../agents/agent-install.md) — agent-facing
+  entry point that links here

package/docs/guides/recipes/website-source.md

@@ -0,0 +1,28 @@
+# Recipe: Turn a Website into a Searchable Bundle
+
+Crawl a documentation site into markdown knowledge assets you can search and
+show like any other source.
+
+```sh
+akm bundle add https://docs.example.com --name docs
+```
+
+Website sources are crawled and converted to markdown knowledge assets, then
+indexed locally — no different from a local directory or a git bundle once
+they're in.
+
+Control the crawl scope with `--max-pages` and `--max-depth`:
+
+```sh
+akm bundle add https://www.agentic-patterns.com/ --name agent-patterns --max-pages 100
+```
+
+Reindex and search once the crawl finishes:
+
+```sh
+akm index
+akm search "agent" --type knowledge
+```
+
+See [Registry](../../reference/registry.md) for the full install flow and
+supported ref formats.

package/docs/guides/run-workflows.md

@@ -0,0 +1,279 @@
+# Running Workflows
+
+This guide walks through operating a workflow run day to day: starting or
+continuing one, checking on it, resuming it after it blocks, and abandoning
+one you no longer want. It assumes you already know what a workflow is; see
+[Workflow Schema](../reference/workflow-schema.md) for the exact frontmatter
+and body syntax, and
+[Architecture: The Workflow Engine](../architecture/workflow-engine.md) for
+what happens under the hood (frozen plans, dispatch, resume-without-replay).
+For task/schedule-driven workflow runs — akm tasks and the OS scheduler —
+see [Scheduling](scheduling.md).
+
+## Start or continue a run
+
+`akm workflow run <run-id|workflows/ref>` starts or continues a persisted run
+and executes it until completion, failure, verification rejection,
+interruption, or an explicit invocation limit. Run state is scoped to the
+current project directory (nearest `.akm/config.json`, git root, bundle root,
+or current directory), so the same workflow can run independently in separate
+projects.
+
+Every new run/start compiles source IR v1 and freezes the durable plan v4
+family's current executable format (`irVersion: 5`) before publishing the run.
+A workflow ref is a Markdown `.md` source.
+
+```sh
+akm workflow run workflows/ship-release --version 1.2.3
+akm workflow run workflows/review --changed_files a.ts --changed_files b.ts
+akm workflow run <run-id> --max-retries 2 --timeout 10m
+```
+
+Parameter flags must come after the target and exactly match declared
+`params` keys. Values are coerced through each parameter's JSON Schema:
+repeat an array flag, pass an object or whole array as JSON, and use a bare
+boolean flag for `true`. There are no hyphen/underscore aliases. Parameters
+are accepted only while creating a new run — a later invocation against an
+active run rejects parameter flags.
+
+`--max-steps <n>` leaves a partial run active after at most `n` steps.
+`--max-retries <n>` retries a failed step on the same run up to `n` additional
+times (0 through 100). `--timeout <duration>` bounds the whole invocation and
+accepts `N`, `Nms`, `Ns`, or `Nm`; bare `N` is milliseconds. A timeout or
+signal abort releases the run's lock without advancing the active step, so the
+run remains resumable. Failed, gate-rejected, timed-out, and interrupted runs
+exit nonzero.
+
+The run freezes its plan, exact models, execution limits, parameter snapshot,
+and verifier selection at creation — edits to source or config do not alter
+an in-flight run. See
+[Architecture: Frozen plans](../architecture/workflow-engine.md#frozen-plans)
+for why.
+
+## Check status
+
+`akm workflow status` shows the full run state — all step statuses, notes,
+and evidence — for a given run ID or workflow ref.
+
+```sh
+akm workflow status <run-id>
+akm workflow status workflows/ship-release
+# When given a ref, resolves to the most-recently-updated run in the current scope
+```
+
+Use this to inspect where a run is after a context window break, or to verify
+all steps completed cleanly before closing a PR.
+
+**`--units` — per-unit diagnostics.** For an orchestrated run, add `--units`
+to also list the run's journaled unit rows — each unit's id, status,
+`failure_reason`, and any result/error diagnostic text the row carries:
+
+```sh
+akm workflow status <run-id> --units
+```
+
+This is a **diagnostic** surface, deliberately kept out of the deterministic
+artifact graph. A step's promoted artifact (what `steps.x.output` resolves to,
+and what a gate judges) keeps only a failed unit's structured `failure_reason`
+— never the raw error text — so step evidence stays reproducible across
+resumes. When you need the human-facing *why* behind a failure, `--units`
+reads the unit journal directly and shows it without ever feeding that text
+back into an artifact or input hash.
+
+## Child runs
+
+A step that composes another workflow (see [Workflow Schema: Child
+workflows](../reference/workflow-schema.md#child-workflows)) drives that
+child inline when the composing step runs. `akm workflow status` on a run
+that composes children renders a `children:` tree after its `steps:` block:
+
+```sh
+akm workflow status <run-id>
+```
+
+```
+steps:
+  - build [work] (completed)
+  - dispatch [dispatch] (completed)
+children:
+  - ✓ 4f2b1a9c workflows/leaf [completed] (step "dispatch")
+```
+
+Each row shows the child's run id, its workflow ref, its status, and which
+of the parent's steps spawned it; a blocked child also shows its resume
+command. Nesting reflects composition depth — a child that itself composes
+a grandchild shows its own indented `children:` rows.
+
+**Recovering a blocked child.** A blocked child blocks the composing step
+(and the parent run) too — `akm` will not resume a child for you. Resume the
+**child** first, then resume and re-run the **parent**; re-driving the
+parent is what advances it, because that re-enters the composing step and
+drives the now-resumed child:
+
+```sh
+akm workflow resume <childRunId>
+akm workflow resume <parentRunId>
+akm workflow run <parentRunId>
+```
+
+**Nested blocks (composition depth 2+).** The three-command sequence above
+clears a block exactly one level deep. When a grandchild blocks — a root
+workflow composes a child, and that child composes the grandchild that
+actually blocks — re-driving the root does **not** cascade down into
+re-driving the still-blocked grandchild: a composing step never re-drives a
+child whose own status is already `blocked`, so re-running the root just
+re-observes the child's block and re-blocks the root the same way, without
+ever reaching the grandchild. Resume **every** blocked run in the chain,
+deepest first, then re-run only the root:
+
+```sh
+akm workflow resume <grandchildRunId>
+akm workflow resume <childRunId>
+akm workflow resume <rootRunId>
+akm workflow run <rootRunId>
+```
+
+The status tree prints `resume`/`then` commands on each blocked node, but
+those two commands alone only ever name that node and the root — they do not
+enumerate an intermediate chain. Read the tree top to bottom and resume every
+`blocked` row you see (deepest first) before re-running the root.
+
+**Child runs are hidden by default.** `akm workflow list` excludes child
+runs so the list stays a view of the runs you started; pass `--children` to
+include them:
+
+```sh
+akm workflow list              # child runs excluded
+akm workflow list --children   # child runs included
+```
+
+A child run id always works directly, listed or not — `akm workflow status
+<childRunId>`, `resume`, `abandon`, and `run` all operate on it exactly like
+any other run.
+
+## List runs in scope
+
+`akm workflow list` shows workflow runs in the current scope.
+
+```sh
+akm workflow list              # All runs in this scope (any status)
+akm workflow list --active     # Only status=active (executable) runs
+akm workflow list --ref workflows/ship-release  # Runs for a specific workflow
+```
+
+`--active` filters to runs whose status is exactly `active` — currently
+executable work. A `blocked` run (parked awaiting a human `akm workflow
+resume`) or a `failed`/`completed` run is **not** active and is excluded, so a
+script that treats `--active` output as runnable never picks one up. Blocked
+runs remain listed by the unfiltered `akm workflow list` with their `blocked`
+status.
+
+**Example: see what is in flight**
+
+```sh
+akm workflow list --active
+# → lists runs by workflow ref, status, currentStepId, and updatedAt
+```
+
+## Resume a blocked or failed run
+
+```sh
+akm workflow resume <run-id>
+```
+
+Flips a `blocked` or `failed` run back to `active`. Completed runs cannot be
+resumed. Use `akm workflow list` to find runs by status. Once resumed,
+`akm workflow run <run-id>` continues it — units already journaled as
+completed are skipped, not re-run (see
+[Architecture: Resume skips completed units](../architecture/workflow-engine.md#resume-skips-completed-units)).
+
+A resume consumes the frozen plan and journaled attempts; it does not re-read
+configuration or the index, and reads the authored workflow only to warn once
+when it changed since the run was frozen (the run continues on the frozen
+plan; `akm workflow run <ref> --new` picks up the edit). A stored plan this akm
+cannot decode is abandoned with a message naming how to start a new run.
+
+## Abandon a run
+
+```sh
+akm workflow abandon <run-id>
+```
+
+Marks a run failed so it stops counting as active. This only changes the
+run's status — `resume` can still reopen it later if you change your mind.
+
+## Follow a run's events
+
+There is no `akm workflow watch` (0.9.0: dropped — a foreground polling
+daemon in a one-shot CLI). `akm log --run <run-id>` reads the same
+`workflow_*` / `workflow_unit_*` events from the general append-only events
+stream: `--since '@offset:<id>'` gives a durable row-id cursor a cooperating
+process can poll from, in place of `watch --stream`'s in-process loop.
+
+```sh
+akm workflow run <run-id> &                                  # engine in one shell
+akm log --run <run-id> --since '@offset:0'                   # backlog so far
+akm log --run <run-id> --since '@offset:<nextOffset>'        # poll for more, from the prior call's nextOffset
+```
+
+Event metadata is ids/status/enums only — never workflow-authored content —
+so following a run's events is safe to pipe into logs or dashboards.
+
+## Security: workflow sources are executed code
+
+Workflow steps that include shell commands run with **the full filesystem and
+network access of the user invoking `akm workflow run`** — same as if the user
+had typed those commands in their shell. There is no sandbox and no separation
+between trusted and untrusted workflows. An `exec` unit's *environment* is
+narrowed to an allowlist by default
+([Workflow Schema](../reference/workflow-schema.md#the-childs-environment-is-an-allowlist)),
+which bounds accidental exposure of unrelated credentials — but a command that
+runs at all can still read those credentials off disk, so it is a hygiene
+boundary, not a containment one. AKM
+directly orchestrates workflows as a defined execution surface — it does not
+blindly execute arbitrary indexed content — but that orchestration still runs
+the workflow's own declared shell commands with your full access once you
+choose to run it.
+
+This is by design: a workflow is a runbook authored by you or by a bundle
+maintainer you trust. The flexibility of "run any shell command, read any
+file, hit any network" is what makes workflows useful as automation.
+
+The consequence is that **you should treat workflow sources the same way you
+treat package dependencies**:
+
+- **Only add workflow sources you trust.** `akm bundle add github:<some-user>/<bundle-repo>`
+  followed by `akm workflow run workflows/<their-thing>` is functionally
+  equivalent to piping a stranger's bash script into your shell. Read the
+  workflow file first (`akm show workflows/<name>`) before running it.
+- **Audit before run** for any workflow that touches secrets, deploys to
+  production, or writes outside the project tree. Read the `env:` bindings a
+  workflow declares, and read its `exec.pass_env` lines.
+  The durable v4 family (`irVersion: 5`) rejects `inherit_env`. Authors must
+  use exact named bindings and `pass_env` names.
+- **Pin known-good versions** when adding workflow sources from a registry
+  or git remote (`akm bundle add github:owner/repo#v1.2.3`), and update
+  deliberately rather than via `akm bundle update --all`. A trusted workflow
+  source can become hostile if its upstream is compromised.
+- **Workflow steps cannot escape this trust model** by being labeled
+  `dryRun` or `interactive` — those flags affect bookkeeping, not execution.
+  `akm workflow status` is read-only; `akm workflow run` executes configured
+  units with your process's access.
+
+If you operate a CI runner or shared host where untrusted workflows might be
+executed, scope the process: a dedicated user account with no secrets in its
+environment, ephemeral working directory, and a network/filesystem allowlist
+enforced outside akm.
+
+## See also
+
+- [Workflow Schema](../reference/workflow-schema.md) — exact frontmatter,
+  refs, gates, and outputs syntax
+- [Author's Guide: Writing Workflows](../guides/author-workflows.md) —
+  writing and testing a workflow definition
+- [Architecture: The Workflow Engine](../architecture/workflow-engine.md) —
+  persistence, dispatch, and resume internals
+- [Scheduling](scheduling.md) — running akm tasks (including workflow runs)
+  through the OS scheduler
+- [CLI Reference](../reference/cli.md) — full flag documentation for all
+  `workflow` subcommands

package/docs/guides/scheduling.md

@@ -0,0 +1,123 @@
+# Scheduling
+
+This guide covers running akm tasks — `akm improve` and other background
+work — through the OS scheduler (cron / launchd / schtasks) safely: how
+`akm setup` reviews task definitions before touching the scheduler, how to
+verify the result, and how to migrate or repair scheduler bindings after
+moving or reinstalling akm.
+
+## Review tasks during setup
+
+Interactive setup reviews every embedded task definition — both the
+general-purpose core task-template set and the maintainer-oriented
+multi-cadence improve task set — in one pass. See the
+[task CLI reference](../reference/cli.md#task) for the full template list.
+
+```sh
+akm setup
+```
+
+Before any OS scheduler change, setup shows every reviewed task's schedule
+and enabled state and asks one explicit activation question. Confirming runs
+the scheduler sync; declining leaves both task files and scheduler state
+unchanged.
+
+**Safety note:** schedule activation always requires an explicit confirmation
+after reviewing the complete task summary. Nothing is written to the OS
+scheduler without that review step.
+
+## Verify
+
+```sh
+akm task doctor
+```
+
+`akm task doctor` reports the scheduler backend, paths, task state, and
+warnings — run it after any setup pass, and again after a `--rebind` (below),
+to confirm the scheduler state matches what you expect.
+
+## Non-interactive setup never activates schedules
+
+`akm setup --yes`, config-file setup, and CI runs skip the task step
+entirely: neither task definitions nor OS scheduler entries are created or
+changed. Run interactive `akm setup` to review, prepare, and activate tasks.
+
+## Task definitions vs. scheduler state
+
+Task definitions live under `<bundle>/tasks/` as task source v4 `.yml` sources;
+the [task source reference](../reference/tasks.md) defines their executable and
+scheduling grammar. A definition cannot enable itself: the refs this host schedules live
+separately in `config.json` under `scheduler.enabled`, a list of
+fully-qualified refs. Use `akm task enable <bundle>//tasks/<id>` or `akm task
+disable <ref>` to change it without editing bundle content. An unscoped `akm
+task sync` installs exactly the listed refs from every enabled configured
+bundle and removes akm-written bindings for refs that are gone or no longer
+listed. Removing a bundle drops its refs from the list; disabling a bundle
+leaves them inert.
+
+Native scheduler entries are separate OS state. Activation captures the
+installed akm runtime so scheduled execution does not silently switch to a
+different checkout or package. Editing definitions and running ordinary `akm
+task sync` preserves that captured runtime.
+
+A scheduled fire re-reads the guarded current source and creates a fresh
+durable-v4-family freeze at executable `irVersion: 5`.
+Scheduler sync/validation evidence is not an executable snapshot and is never reused as the later run plan.
+
+## A scheduled `akm improve` covers one bundle
+
+An `akm improve` run improves one bundle, the one it writes to: `--bundle`,
+else `defaultWriteTarget`, else the working bundle. A scheduled row sets
+`AKM_BUNDLE_DIR` to the working bundle of the shell that synced it, so a
+scheduled `akm improve` covers that bundle (or `defaultWriteTarget`, when set)
+and leaves your other bundles alone, even the writable ones. To improve
+another bundle on a schedule, give it a task of its own; the `--bundle` inside
+the command is `akm improve`'s own:
+
+```sh
+akm task add improve-team --schedule "15 3 * * *" \
+  --command "akm improve --bundle team --skip-if-locked --require-engines"
+```
+
+## Rerunning setup preserves scheduler bindings
+
+Rerunning `akm setup` preserves existing scheduler bindings by design — it
+will not silently rebind entries that are already activated.
+
+## Upgrades
+
+A config written before 0.9.17 has no `scheduler.enabled` list. The first
+`akm task sync` (or `setup`, `task enable`, `task disable`, `task add`) after
+the upgrade takes the akm-written rows already installed in the native
+scheduler as this host's choice, writes the list, and says so — a scheduled
+task survives an upgrade by any install method with no manual step. An
+explicit empty list is a choice: sync then removes every akm-written row.
+`akm migrate status` reports anything else that remains pending, and why.
+
+## Migrating or repairing scheduler bindings (`--rebind`)
+
+If akm was moved, reinstalled under a different package prefix, or repaired
+after an installation problem, migrate scheduler entries deliberately:
+
+```sh
+akm task sync --rebind
+akm task doctor
+```
+
+Use `--rebind` only for that explicit runtime migration or repair — it
+captures the current installed runtime, replacing whatever runtime a prior
+activation had captured.
+
+If you change the AKM storage path during reconfiguration, or move or install
+akm at a new runtime path, follow setup with `akm task sync --rebind`; setup
+never silently rebinds existing entries on your behalf.
+
+## See also
+
+- [Getting Started](getting-started.md) — the first-run path this guide was
+  split out of
+- [CLI Reference: task](../reference/cli.md#task) — the full `task` command
+  group, including `add`, `enable`, `disable`, `run`, `sync`, `doctor`, and
+  `history`
+- [Task source reference](../reference/tasks.md) — exact file grammar,
+  targets, triggers, and migration