akm-cli 0.10.261012-beta → 0.10.261014-beta

package/docs/architecture/workflow-engine.md

@@ -15,35 +15,45 @@ commands that drive a run, see [Running Workflows](../guides/run-workflows.md).
 
 ## Frozen plans
 
-The first `akm workflow run <ref>` compiles either peer source format
-(Markdown or GitHub-Actions-style YAML) straight to the one plan type and
-stores it as durable plan **`irVersion` 6** on the run row (`plan_json` +
-`plan_hash`); a new start never emits an older version. `plan_ir_version` and
-`plan_hash` are recorded provenance, not gates: a stored plan is decoded as it
-is — irVersion 4 and 5 plans included — and one frozen by an older or newer
-akm that still decodes simply runs (with one warning). A newer akm's plan that
-does not decode is refused with a message naming "Upgrade akm".
+The first `akm workflow run <ref>` compiles the Markdown source straight to
+the one plan type and stores it as durable plan **`irVersion` 8** on the run row
+(`plan_json` + `plan_hash`); a new start never emits an older version.
+`plan_ir_version` and `plan_hash` are recorded provenance, not gates: a stored
+plan is decoded as it is — irVersion 5, 6 and 7 plans that hold no model step
+included — and one frozen by an older or newer akm that still decodes simply
+runs (with one warning). A plan frozen before 8 with a model step recorded an
+engine where 8 records a connection or harness; it does not decode, and
+`akm workflow run` abandons it and starts afresh. A newer akm's plan that does
+not decode is refused with a message naming "Upgrade akm".
 
 The durable plan records `sourceHash`, the sha256 of the workflow source file
 at freeze. It is used only for the resume warning below, never to refuse a
 run.
 
-Dispatch-significant material is immutable. The resolved request is frozen,
-the resolved target is frozen, and runner selection is frozen.
-Working directory (`cwd`) identity is frozen.
-Git identity and its commit OID are frozen. The executable a unit runs is
-resolved at dispatch, so upgrading a CLI (say, `claude`) never strands a run.
-Exact models, inference, tools and authorization,
+**Freeze records identities, never locations.** The resolved request is frozen,
+the resolved target is frozen, and runner selection is frozen. So are the refs
+the engine itself dereferences, qualified with their bundle: the run's
+`workflow_ref`, each unit's `env:` refs (`{ kind: "env-ref", ref, precedence }`)
+and each child workflow's ref. Exact models, inference, tools and authorization,
 execution limits, parameter snapshots, command/script bytes, and verifier
 selection therefore cannot drift under an in-flight run.
 
-Workflow environment asset values are the narrow live-value exception within
-authored workflow inputs.
-The environment owner key set and secret-token topology are frozen.
-Literal values remain frozen. Pass-through bindings
-materialize at dispatch from the current process, and env/secret references
-materialize their current values only after owner/topology checks. Durable
-plans never store secret values or enable whole-process `inheritEnv`.
+Everything else is live, found again at dispatch through the one ref lookup
+`akm show` uses (no database is opened):
+
+| Frozen | Live at dispatch |
+| --- | --- |
+| argv, `exec.cwd` and `pass_env` names as authored | the owner root of the run's workflow, which every exec unit and agent works in (`exec.cwd` joins it once) |
+| `env:` refs, bundle-qualified | the env file, its keys and every `${ref}` in it, and the secrets they name |
+| `${ref}` tokens in argv and `cwd`, as authored | the secret value or asset path each one names |
+
+The executable a unit runs is resolved at dispatch too, so upgrading a CLI (say,
+`claude`) never strands a run, and a `bundle update` that moves a bundle to a
+new revision directory in the middle of a run is harmless: the next step runs
+from the new directory. Plans
+frozen as irVersion 5 or 6 also carry a `cwdIdentity` and env owner paths; the
+decoder drops them and such a run dispatches by ref. Durable plans never store
+secret values.
 
 **A run executes the plan compiled at creation; edits to source need a new
 run.** Resuming a run re-reads its workflow source only to warn, once, when
@@ -107,9 +117,7 @@ decoding the stored plan, taking that run's own lock, and walking its spine
 through `completeWorkflowStep` are identical to the top-level path. That
 reuse is what makes child run locks arbitrate two-parent contention with no
 new mechanism, and what makes a resumed parent skip a completed child step
-with zero dispatcher calls. The child drive passes a no-op
-`disposeDispatchResources` (the parent's `finally` remains the sole owner of
-the process-lifecycle drain for the whole process) and no `maxSteps` or
+with zero dispatcher calls. The child drive passes no `maxSteps` or
 `maxRetries` (the parent's own budgets count only its own spine steps). The
 lower-level `driveRun` that `runWorkflowSteps` wraps stays module-private —
 reaching for it directly, instead of the public entry point, would be
@@ -120,8 +128,7 @@ version prefix mixed into a unit's input hash is 7
 (`src/workflows/exec/step-work.ts`); 0.9.2 bumped it — a single, durable
 5 → 7 step, since every released tag on the line carries 5 — when
 `taskInputs`, the resolved values of a composed task's reference-kind
-`inputBindings`, joined the preimage (see [ADR
-0002](decisions/0002-unit-reuse-and-input-hash-scope.md)). Child composition
+`inputBindings`, joined the preimage. Child composition
 itself contributed nothing to that bump: the parent unit's input-hash
 preimage already covers everything the child drive depends on — the frozen
 target carries the child's ref, plan hash, content hash, binding mode, and
@@ -183,10 +190,15 @@ the lock.
 
 Native fan-out (`akm workflow run`) uses the minimum of four limits: the
 map's declared `concurrency`, the run's frozen `workflow.maxConcurrency`, the
-selected frozen LLM engine's `concurrency` (including an SDK engine's
-fallback LLM), and the current host's CPU-derived safety limit. Reapplying
+selected frozen connection's `concurrency` (a harness has none), and the current host's CPU-derived safety limit. Reapplying
 host safety keeps a run safe when it resumes on a smaller machine.
 
+`targetConcurrency` (`src/workflows/freeze/step-values.ts`) freezes the
+connection's value as the target's `concurrency` in the plan, and
+`scheduleUnits` (`src/workflows/exec/scheduler.ts`) applies it as
+`llmConcurrency` to cap `map` and `over` fan-out. The scheduler's own default of
+one is a fail-safe for a caller that names no width, not the `map` default.
+
 - **Unset (default):** the CPU-derived value `min(16, max(1, cores − 2))` — a
   conservative default that leaves headroom on the host and matches the
   original Claude-Code cap.
@@ -204,14 +216,19 @@ A workflow that fans out is authorizing **N parallel agents**, not one — see
 [Running Workflows: workflow sources are executed code](../guides/run-workflows.md#security-workflow-sources-are-executed-code)
 for what that means for trust.
 
-## Run scope and persistence
+## Run identity and persistence
 
 Run state (`plan_json`, `plan_hash`, step statuses, and the unit journal)
-persists in the project's `state.db`; the per-run lock file sits beside it. Run state is scoped to
-the current project directory — the nearest `.akm/config.json`, git root,
-bundle root, or current directory — so the same workflow can run
-independently in separate projects, and `akm workflow list`/`status` without
-an explicit run id only ever see runs in that scope.
+persists in the host's `state.db`; the per-run lock file sits beside it. A run
+is identified by its run id and a workflow by its bundle-qualified ref. Run
+state is not scoped to a directory: `akm workflow run <ref>` always starts a
+new run, `akm workflow run <run-id>` drives an existing one,
+`akm workflow resume <run-id>` re-activates a blocked or failed one, and
+`akm workflow list`/`status` show every run on the host from any working
+directory. Starting a ref that already has active runs warns
+and names them; it is never refused. `akm workflow run <ref> --skip-if-locked`
+skips (exit 0) instead of starting when an active run of that ref is held by a
+live process.
 
 ## See also
 

package/docs/guides/README.md

@@ -25,7 +25,6 @@ Task-oriented guides and command tours for using akm.
 
 - [Bundle Author's Guide](author-bundles.md) -- Build and share a bundle on GitHub, npm, or a network directory
 - [Wikis](wikis.md) -- Multi-wiki knowledge bases (Karpathy-style)
-- [Claude Code workflows vs. akm workflows](claude-code-vs-akm-workflows.md) -- Comparing the two things that share a name
 
 ## Recipes
 

package/docs/guides/author-bundles.md

@@ -52,9 +52,7 @@ sync with the code:
   metadata when `akm index` runs.
 
 If you still have a legacy `.stash.json` sidecar, migrate its fields into
-inline metadata before publishing — see the
-[v0.7 → v0.8 migration guide](../migration/v0.7-to-v0.8.md) for the full
-field mapping and a worked example.
+inline metadata before publishing.
 
 **Keep `show` payloads focused.** `akm show` returns the whole asset body by
 default (the whole document for a knowledge asset, the whole `SKILL.md` for a
@@ -110,7 +108,7 @@ renaming the file to match the query.
 
 Run `akm lint` before you publish. It catches structural problems (missing
 `name`/`type` on commands and agents, broken refs, malformed workflow
-structure, invalid task YAML) as well as the dangerous-env-key scan described
+structure, invalid task YAML) as well as the dangerous-env-key findings described
 in [Env Security](#env-security) below.
 
 ```sh
@@ -242,24 +240,21 @@ when a push happens.
 > [0.8 → 0.9 migration guide](../migration/v0.8-to-v0.9.md).
 
 If your bundle includes env files under `env/`, be aware of how `akm` handles
-them during install.
+them.
 
-**Dangerous key detection.** `akm bundle add` and `akm lint` scan env files for
-environment variable names that can be used to hijack process execution when
-the file is loaded via `akm env run`. The flagged names include `LD_PRELOAD`,
+**Dangerous key findings.** `akm lint` reports env files that set environment
+variable names which can be used to hijack process execution when the file is
+loaded via `akm env run`. The flagged names include `LD_PRELOAD`,
 `PATH`, `DYLD_INSERT_LIBRARIES`, `NODE_OPTIONS`, and 37 others (41 literal
 keys total), plus two pattern-based families (`BASH_FUNC_*`, Shellshock-class
-injection; `GIT_CONFIG_*`, git config override injection). When these keys
-are found, `akm bundle add` pauses in interactive mode and asks the user to confirm
-before continuing. In non-interactive (CI) mode the install fails unless the
-user passes `--allow-dangerous-env-keys`. `akm env run` applies the same scan at
-run time: a third-party-sourced bundle is refused unless that reviewed run
-explicitly passes `--allow-dangerous-env-keys`; a first-party bundle warns and
-proceeds.
-
-This is not a ban — it is a speed bump. If your bundle legitimately needs one
-of these keys (for example, a `PATH` override for a hermetic toolchain), do
-the following before publishing:
+injection; `GIT_CONFIG_*`, git config override injection). The finding is
+advice for you as the author, not a gate: installing a bundle is the user's
+trust decision, so `akm bundle add`, `akm bundle update`, `akm env run`,
+`akm secret run` and workflow `env:` bindings never scan, prompt for or block
+these keys, whichever bundle the file comes from.
+
+If your bundle legitimately needs one of these keys (for example, a `PATH`
+override for a hermetic toolchain), do the following before publishing:
 
 1. Document the reason clearly in your `README.md`. Explain which key is set,
    why it is needed, and what the value does.
@@ -273,7 +268,7 @@ the following before publishing:
 
 3. Consider whether the value can be set by the user after install rather than
    shipped in the env file. Env files that ship without values — just key names
-   and comments — do not trigger the audit.
+   and comments — produce no findings.
 
 **Key names are metadata, not secrets.** Env key names appear in `akm env list`
 and search results by design. Only values are protected. The `--sensitive` flag

package/docs/guides/author-workflows.md

@@ -204,15 +204,10 @@ path, a commit id) that the agent can only fill by doing it.
 
 ### What the command can see
 
-The child does **not** inherit your environment. It starts empty and gets a
-small default allowlist — `PATH`, `HOME`, the locale/temp/identity variables,
-and the Windows essentials (`SystemRoot`, `COMSPEC`, `PATHEXT`, …) that
-process creation itself needs — then your `env:` bindings, then the `AKM_*`
-context variables. Ordinary commands (`bun`, `git`, `make`, `cargo`) work
-unchanged; an unrelated `SOME_OTHER_SERVICE_TOKEN` sitting in the shell that
-ran `akm workflow run` does not reach them.
-
-Widen it only by naming what the unit needs:
+The command inherits your environment, as it would typed in your shell: `PATH`,
+`HOME`, the toolchain variables and any credential of the process that ran `akm
+workflow run` reach it. Then come your `env:` bindings, then the `AKM_*` context
+variables. Ordinary commands (`bun`, `git`, `make`, `cargo`) work unchanged.
 
 ```yaml
   - id: build
@@ -220,25 +215,54 @@ Widen it only by naming what the unit needs:
       env: [env/build]
       exec:
         command: ["cargo", "build", "--release"]
-        pass_env: [CARGO_HOME, SCCACHE_DIR]   # a few extra names
 ```
 
-`pass_env:` is for a **per-machine** variable an `env:` binding cannot express
-(an env asset stores a committed value; `CARGO_HOME` differs per build agent).
-Secrets and fixed values belong in exact named `env:` bindings: those values
-are redacted out of everything journaled, and `pass_env:` values are not.
+Fixed values belong in exact named `env:` bindings, and they reach the journal as
+they are. A credential belongs in `secrets/`, bound by a `${secrets/name}` token
+inside the env asset; only values substituted from such a ref are redacted out of
+everything journaled (see [Binding a secret to a
+unit](../reference/workflow-schema.md#binding-a-secret-to-a-unit)). A value the
+command inherited is not redacted.
+
+`exec.pass_env:`, the list of names an earlier release copied into an otherwise
+empty environment, still parses and selects nothing. Workflow starts freeze the
+durable plan v4 family's current executable format (`irVersion: 8`), which
+rejects `inherit_env`; the command inherits the environment without it.
+Pre-`irVersion`-5 stored plans do not execute; start a new run after updating the
+source.
+
+Named bindings are part of the unit's input hash, so changing them re-runs the
+command instead of reusing a row recorded under another scope. What the command
+sees is described under [Workflow Schema: The child's
+environment](../reference/workflow-schema.md#the-childs-environment).
 
-Workflow starts freeze the durable plan v4 family's current executable format
-(`irVersion: 5`), which rejects `inherit_env` instead of persisting an
-unbounded ambient environment. Pre-`irVersion`-5 stored plans do not execute;
-start a new run after updating the source.
+### Using scripts, env and secrets from other bundles
+
+A workflow in one bundle can run a script from a second bundle, with an env
+asset from a third that names a secret in a fourth. Each is addressed by its akm
+ref, `[bundle//]conceptId`, inside a `${...}` token:
+
+```yaml
+  - id: status
+    unit:
+      env: [ci//env/status]                       # env/status.env in bundle ci
+      exec:
+        command: ["bun", "${tools//scripts/lab-status/fetch.ts}"]
+```
 
-Named bindings and `pass_env:` are part of the unit's input hash, so changing
-either re-runs the command instead of reusing a row recorded under another
-scope.
+```sh
+# env/status.env in bundle ci
+REGION=east
+TOKEN=${vault//secrets/status_token}
+```
 
-Full list of allowlisted names:
-[Workflow Schema: The child's environment is an allowlist](../reference/workflow-schema.md#the-childs-environment-is-an-allowlist).
+`${tools//scripts/...}` becomes the script's absolute path when the unit
+dispatches, `${vault//secrets/status_token}` becomes the secret's value, and
+`REGION` reaches the child as it is. Nothing in the plan records where any of
+them lives, so updating a bundle in the middle of a run is harmless. The unit
+runs in the root of the bundle that holds the workflow (`cwd:` is relative to
+it, or absolute). See [Workflow Schema: The exec
+contract](../reference/workflow-schema.md#the-exec-contract).
 
 ### Things to get right
 
@@ -246,20 +270,20 @@ Full list of allowlisted names:
   never `"bun run test"`. Nothing is shell-parsed, which is what makes it safe;
   if you truly need a pipeline, write `["bash", "-lc", "a | b"]` and own that
   choice explicitly.
-- **No interpolation.** The argv is frozen. A `map` step's item reaches the
-  command as `AKM_ITEM` (canonical JSON) and the run params as `AKM_PARAMS` —
+- **No interpolation of run data.** The argv is frozen as authored; the only
+  substitution is a `${ref}` token naming an asset. A `map` step's item reaches
+  the command as `AKM_ITEM` (canonical JSON) and the run params as `AKM_PARAMS` —
   read them from the environment, do not try to splice them into `command:`.
-- **Secrets go in `env:`, never in `command:`.** `command:` is stored verbatim in
-  the frozen plan; `env:` bindings are carried by name and their values are
-  redacted out of everything journaled.
+- **Secrets go in `secrets/`, bound through `env:`, never as literals in
+  `command:`.** `command:` is stored as authored in the frozen plan; `env:` bindings are carried
+  by name, and values substituted from a `${secrets/name}` ref are redacted out
+  of everything journaled.
 - **Long commands need a `timeout:`.** An exec unit defaults to 10 minutes. Use
   `timeout: "30m"` for a slow suite, or `timeout: "none"` only when you really
   mean unbounded.
-- **Don't assume your shell's environment.** The child gets an allowlist, not
-  an inheritance. If a command fails with "not found" or reads a missing
-  toolchain variable, name it in `pass_env:`; use a named `env:` binding for a
-  fixed or secret value. The durable v4 family (`irVersion: 5`) deliberately
-  has no whole-process fallback.
+- **The command has your shell's environment, so a credential in it reaches
+  it.** Use a named `env:` binding for a fixed or secret value you want redacted
+  from the journal; a value the command inherited is not redacted.
 - **A very chatty command still passes; its artifact just says so.** akm retains
   8 MiB of stdout and 8 MiB of stderr. Past that it keeps draining and discards,
   so the command runs to completion and its exit code decides the step. The
@@ -302,10 +326,8 @@ Full reference: [Workflow Schema: Exec (shell) units](../reference/workflow-sche
 - **Writing `exec.command` as a shell string.** `command: "bun run test"` is
   rejected; it must be an argv array (`["bun", "run", "test"]`). Nothing is
   ever shell-parsed, so metacharacters inside an argument stay literal.
-- **Expecting an exec command to inherit your environment.** It gets a default
-  allowlist (`PATH`, `HOME`, locale/temp/identity, the Windows essentials) plus
-  your `env:` bindings and the `AKM_*` context — nothing else. Widen it with
-  `exec.pass_env:` (a few non-secret names). `pass_env` lives inside `exec:`;
+- **Listing names in `exec.pass_env:`.** It parses and selects nothing: the
+  command already inherits your environment. `pass_env` lives inside `exec:`;
   the unit-level `env:` key is a list of exact env asset binding refs. A new v4
   start rejects `inherit_env`.
 - **Asking a model to do deterministic work.** "Run the test suite and tell me
@@ -361,14 +383,20 @@ If lint reports a very broken workflow, note that its errors are sorted by
 line, so fix from the top and re-run — the later ones are usually fallout from
 the first.
 
-## Choosing engines and models
-
-Set `defaults.engine`/`defaults.model` (or per-unit `unit.engine`/`unit.model`)
-rather than hardcoding an exact model id, so the workflow stays
-harness-agnostic. Reference semantic aliases — `fast`, `balanced`, `reasoning`,
-or aliases defined in the installed/user `models.json` files — in `model:` fields; see
+## Choosing where a step runs and which model
+
+A step that dispatches a model runs on your default harness, or on akm's own
+runtime over your default connection when you have no harness. Leave that to
+the machine the workflow runs on. Name one only when a step needs it:
+`harness:` or `connection:` in `defaults` (or per-unit `unit.harness` /
+`unit.connection`), where a name the machine has not configured is an error that
+names it and lists what the machine has, so a workflow shared across machines
+should name a program only when it needs that one. Set `defaults.model`/`unit.model` to an alias rather
+than hardcoding an exact model id, so the workflow stays portable. The aliases
+are `fast`, `balanced`, `reasoning` and any a connection or harness maps in its
+`models`; see
 [Workflow Schema: Model references](../reference/workflow-schema.md#model-references)
-for the exact resolution order and config shape.
+for the exact resolution order.
 
 Point `reasoning` work at a capable model and keep high-volume fan-out units
 on `fast`/`balanced`. The richer example's `review` map step is a good template: `reasoning` on the
@@ -400,13 +428,13 @@ serial behavior wholesale — set
 `akm config set workflow.defaultMapConcurrency 1`.
 
 The declared width is a **ceiling, not a promise**. Three other limits clamp it
-and the smallest wins: `workflow.maxConcurrency`, the selected engine's
-`engines.<name>.concurrency`, and the host's CPU cap. The engine limit is the
-one that surprises people: an LLM engine pointed at **localhost defaults to 1**,
-because local model servers hold a single loaded model and fall over under
-concurrent requests — so a `map` against a local model stays serial no matter
-what the step declares, until you raise that engine's own `concurrency`. Remote
-LLM endpoints default to 4. See
+and the smallest wins: `workflow.maxConcurrency`, the selected connection's
+`concurrency`, and the host's CPU cap. The connection limit is the one that
+surprises people: a connection pointed at **localhost defaults to 1**, because
+local model servers hold a single loaded model and fall over under concurrent
+requests — so a `map` against a local model stays serial no matter what the step
+declares, until you raise that connection's own `concurrency`. Remote endpoints
+default to 4, and a step on a harness has no limit of this kind. See
 [Workflow Schema: Fan-out and concurrency](../reference/workflow-schema.md#fan-out-and-concurrency)
 for the full table.
 
@@ -456,8 +484,8 @@ blast radius before running it.
 
 4. **Deliberately break a gate once.** Run the workflow with params you
    expect to fail validation, and confirm the gate actually rejects rather
-   than silently passing — a missing `workflow.judgeEngine` or a malformed
-   verdict rejects the gate rather than bypassing it (see
+   than silently passing — a missing judge (no connection or harness to run
+   it) or a malformed verdict rejects the gate rather than bypassing it (see
    [Workflow Schema: Gates and verification](../reference/workflow-schema.md#gates-and-verification)),
    so this is worth confirming once per workflow rather than assuming.
 
@@ -504,28 +532,22 @@ for blocked-child recovery and the limits.
 
 ## Troubleshooting
 
-**Every workflow run needs a selected engine.** Freezing resolves an engine
-for each unit. With no `defaults.engine`, akm falls back to a config-free
-`opencode-sdk` engine — provider, model, and auth come from opencode's own
-configuration — and announces it once in the run's `warnings`. The fallback
-needs the **`opencode` binary on PATH**: the bundled `@opencode-ai/sdk`
-package is an HTTP client only and spawns `opencode serve` to have something
-to talk to, so installing the npm package alone is not enough. With no
-binary, freezing fails with `INVALID_CONFIG_FILE` and exit 78.
+**A step that dispatches a model needs a harness or a connection.** Freezing
+resolves where each unit runs: its `unit.harness` or `unit.connection`, else the
+document's `defaults`, else your default harness, else akm's own runtime over
+your default connection. With none of those, freezing fails and the error points
+at `akm setup`. A workflow made only of exec steps needs neither.
 
-A workflow with a non-empty `### gate` additionally requires
-`workflow.judgeEngine` to name a configured LLM or agent engine — the gate
-judge is not covered by the fallback.
+A workflow with a non-empty `### gate` also needs one for the gate judge, which
+runs where model work runs: your default connection, else your default harness.
+An exec-only workflow with a gate still needs it.
 
-`akm setup` normally selects a default execution engine. On a bare container
-or CI image, either install opencode and let the fallback apply, or choose an
-engine explicitly:
+`akm setup` normally configures both. On a bare container or CI image, run it
+with the answers as flags, or add one by hand:
 
 ```sh
-npm i -g opencode-ai           # fallback route: puts `opencode` on PATH
-# ...or pick an engine yourself:
-akm config set engines.claude '{"kind":"agent","platform":"claude"}'
-akm config set defaults.engine claude
+akm setup --yes --endpoint http://localhost:11434/v1   # a model endpoint
+akm setup --yes --harness claude                       # or an agent program you have
 ```
 
 ## See also

package/docs/guides/bundles.md

@@ -59,7 +59,7 @@ akm bundle add github:owner/team-bundle --name team --before community
 | `filesystem` | local path | Indexed in place, writable by default |
 | `git` | `github:`, known git-host URL, or URL ending in `.git` | Cloned into `~/.cache/akm/registry/`, read-only by default |
 | `npm` | `@scope/pkg` | Installed into cache, read-only |
-| `website` | Other HTTP/HTTPS URL | Crawled, converted to markdown, refreshed every 12 hours |
+| `website` | Other HTTP/HTTPS URL | Crawled and converted to markdown when added; re-crawled by `akm bundle update` |
 
 `akm bundle add` materializes and indexes Git install refs before it reports
 success. A declarative `--provider git` add does the same, including writable
@@ -80,8 +80,8 @@ back out of `sourceAdded`/`installed`. Without `--name`, akm derives one
 a `-<hash>` suffix only on a collision — that forgiving fallback applies
 solely to a derived name, never to an explicit `--name`.
 
-Git credentials must be symbolic references: `$VAR`, `${VAR}`, or
-`secret://name`. AKM resolves the reference only at the Git subprocess boundary
+Git credentials must be symbolic references: `$VAR`, `${VAR}`, or an akm ref
+such as `${secrets/gitea_token}`. AKM resolves the reference only at the Git subprocess boundary
 and sends it as an HTTPS bearer header; it does not put the token in the remote
 URL or `config.json`.
 
@@ -136,12 +136,14 @@ Valid `--kind` values are the four bundle providers: `filesystem`, `git`,
 ## akm bundle update / akm bundle remove
 
 `akm bundle update` refreshes git, npm, and website bundles. Each candidate is
-staged outside its active root, audited for dangerous environment keys, and
-only then published and indexed. `akm bundle remove` disconnects a bundle and
+staged outside its active root and only then published and indexed. Installing
+a bundle is the trust decision: neither `add` nor `update` inspects its `env/`
+files, so a bundle that sets `PATH` in an env file installs and refreshes
+unattended with no flag. `akm bundle remove` disconnects a bundle and
 re-indexes without it.
 
-Bundle refresh is deliberately explicit: Git bundles do not poll upstream on
-their own. Consumers that want automatic refresh should schedule
+Bundle refresh is deliberately explicit: git, npm and website bundles do not
+poll upstream on their own, and `akm index` never re-fetches one. Consumers that want automatic refresh should schedule
 `akm bundle update <name>` or `akm bundle update --all`. Scheduled invocations
 should pass `--skip-if-locked` so concurrent index or improve activity becomes
 a successful skip instead of exit 75.
@@ -152,7 +154,6 @@ akm bundle update @scope/bundle          # One managed bundle
 akm bundle update --all                 # All managed bundles
 akm bundle update --all --force         # Force fresh download even if version unchanged
 akm bundle update --all --skip-if-locked # Scheduled refresh: exit 0 on DB contention
-akm bundle update @scope/bundle --allow-dangerous-env-keys  # Approve reviewed dangerous env keys
 
 # Remove
 akm bundle remove @scope/bundle          # By npm id
@@ -161,12 +162,16 @@ akm bundle remove ~/.claude/skills      # By path
 akm bundle remove my-provider           # By name
 ```
 
-Dangerous keys prompt in a terminal (default: No) and block non-interactive
-updates unless `--allow-dangerous-env-keys` is explicit. `--yes` is a deprecated
-no-op on update; it never approves security findings.
-For `--all`, blocked and failed bundles are reported separately and later
-bundles continue. A rejected or failed bundle keeps its prior bytes, lock/config
-state, and search-index generation.
+A read-only git or npm bundle whose upstream revision is unchanged is not
+fetched or replaced again (`--force` fetches it anyway), so a task or workflow
+running from it keeps its directory. When the revision does change, the
+previous revision directory is kept and older ones are removed.
+
+`--allow-dangerous-env-keys` and `--yes` are deprecated no-ops on update,
+accepted through 0.10 so existing scripts keep working.
+For `--all`, failed bundles are reported separately and later bundles continue.
+A failed bundle keeps its prior bytes, lock/config state, and search-index
+generation.
 
 Private bundles that intentionally version every file under `env/` and
 `secrets/` can place this documented marker anywhere in their root
@@ -307,7 +312,6 @@ don't know about yet. The official registry ships pre-configured.
 ```sh
 akm registry list                             # See configured registries
 akm search "deploy" --from registry           # Search registry bundles by topic
-akm search "code review" --from registry --assets  # Include asset-level hits
 akm registry add https://example.com/registry/index.json --name my-team
 akm registry remove my-team
 ```
@@ -326,7 +330,7 @@ get discovered, see [Registry](../reference/registry.md).
 ## See also
 
 - [Discover & Load](discover-and-load.md) — querying the index after bundles are connected
-- [Knowledge Management](knowledge-management.md) — writing your own assets
+- [Capture Knowledge](capture-knowledge.md) — writing your own assets
 - [Use akm With Any Agent](use-with-any-agent.md) — using refs across bundles in prompts
 - [Website Source Recipe](recipes/website-source.md) — walkthrough for adding a crawled website bundle
 - [Website Sources](../reference/website-sources.md) — fetcher reference, X credentials, crawl options

package/docs/guides/discover-and-load.md

@@ -151,7 +151,7 @@ its ranking) and does not trigger a rewrite.
 - [Architecture](../architecture/architecture.md) — ranking and search
   implementation detail (Search Pipeline, Show Resolution, Utility Scoring)
 - [Bundles](bundles.md) — where indexed assets come from
-- [Knowledge Management](knowledge-management.md) — capturing and importing
+- [Capture Knowledge](capture-knowledge.md) — capturing and importing
   assets before they're discoverable
 - [Use akm with any agent](use-with-any-agent.md) — how agents reference
   assets by ref in practice

package/docs/guides/getting-started.md

@@ -34,6 +34,45 @@ Or download a standalone binary directly from the
 Hitting a PowerShell execution-policy error on Windows? See
 [Troubleshooting](#troubleshooting) at the end of this guide.
 
+### Standalone binary and semantic search
+
+Local semantic search (`semanticSearchMode: auto`) runs its embedding model on
+ONNX Runtime. A standalone binary carries the library for its platform. The
+first time it embeds, it copies that library once into akm's cache directory,
+under `onnxruntime/<version>-<platform>-<arch>/` (18 to 34 MB depending on the
+platform; `akm info` prints the cache directory), and loads it from there. Two
+limits follow:
+
+- A standalone binary writes its native addon to the system temp directory and
+  loads it from there, so a temp directory mounted `noexec` blocks semantic
+  search (`akm index` reports it `blocked`; keyword search works). Set `TMPDIR`
+  to a writable, executable directory. The cache directory must be on
+  an executable mount too.
+- Alpine/musl and Intel macOS have no native ONNX Runtime library. Semantic
+  search is unavailable there: `akm index` reports it `blocked` with the reason
+  and search stays keyword-only. A remote `embedding.endpoint` still works.
+
+### akm's own agent runtime
+
+With a connection and no harness, `akm agent` and the other agent work run on
+akm's own runtime, a pinned OpenCode 2 binary that akm runs as a process. This
+is the same for the npm package and the standalone binary: nothing of OpenCode
+is installed with akm, and the first time the runtime runs, akm downloads the
+OpenCode binary for your platform from the npm registry (one package, about
+114 MB, 240 MB on disk), checks it against the registry's integrity hash and
+keeps it in the cache directory under `opencode/<version>/`. It is fetched once.
+Three limits follow:
+
+- That step needs the npm registry. Without network access for it, enable the
+  `opencode` harness with an OpenCode 2 you have installed instead; no setting
+  points akm's runtime at a binary of your own.
+- Alpine/musl runs the musl build of that binary, which needs `libstdc++` and
+  `libgcc`. The Alpine Node image already has them; on a bare Alpine install them
+  with `apk add libstdc++ libgcc`.
+- The binary runs from the cache directory and unpacks its own native pieces
+  into `opencode-runtime/tmp/` in the data directory, so neither may be mounted
+  `noexec`.
+
 **Success check:**
 
 ```sh
@@ -48,17 +87,24 @@ Guided, interactive setup is the default:
 akm setup
 ```
 
-`akm setup` walks through bundle location, embedding/LLM settings, semantic
-search asset preparation, registries, sources, and task definitions. It also
+`akm setup` walks through the bundle location, the agent programs akm may use
+(Claude Code, Codex, OpenCode, ...), a model connection (an OpenAI-compatible
+endpoint, and which of its models answers each of `fast`, `balanced` and
+`reasoning`), embeddings, semantic search asset preparation, registries,
+sources, and task definitions. The model steps are optional: with no connection
+and no agent program, everything that needs no model still works. Setup also
 reviews your scheduled task definitions and asks whether to activate them in
 the OS scheduler — that part of the flow, plus how to migrate or repair
 scheduler bindings later, is covered in [Scheduling](scheduling.md).
 
 For non-interactive use — scripting, CI, or when you just want a working
-bundle fast — use `--yes`:
+bundle fast — use `--yes`. A flag answers one question, so
+`--endpoint` adds a model connection without prompting (see the
+[CLI reference](../reference/cli.md#setup) for the rest):
 
 ```sh
 akm setup --yes
+akm setup --endpoint http://localhost:11434/v1 --yes   # also add a model endpoint
 akm setup --dir ~/custom-bundle   # optional: a non-default bundle location
 ```