akm-cli 0.9.16-alpha.1 → 0.9.16

package/docs/reference/cli.md

@@ -218,87 +218,97 @@ and builds the search index.
 Build or refresh the search index.
 
 ```sh
-akm index            # Reconcile: diff every configured root against the index, drain the embedding queue
-akm index --full     # Force every file to be re-derived, ignoring the unchanged-file shortcut, reconciling in place
+akm index            # Incremental (only changed directories)
+akm index --full     # Full rebuild (reuses unchanged embeddings — see below)
 akm index --verbose  # Print phase progress to stderr
-akm index --reembed  # Drop the active embedding identity's vectors, then re-embed every unit from scratch
-akm index status     # Report file/entry/unit counts, active identity, and last-reconcile time — no writes
+akm index --clean    # Normal index + remove stale entries from the DB
+akm index --clean --dry-run # Report stale entries without deleting
+akm index --reembed  # Force re-embedding of every entry
+akm index --skip-if-locked  # for scheduled/opportunistic runs: skip (exit 0) if a run is already in progress
 ```
 
-Returns stats: `totalEntries`, `entriesUpserted`, `sourcesScanned`,
-`verification`, optional `warnings`, and `timing` breakdown in milliseconds.
-Use `--verbose` to print the indexing mode,
+Returns stats: `totalEntries`, `generatedMetadata`, `directoriesScanned`,
+`directoriesSkipped`, `verification`, optional `warnings`, and `timing`
+breakdown in milliseconds. Use `--verbose` to print the indexing mode,
 semantic-search settings, and phase-by-phase progress to stderr while the
 index is being built. Malformed workflow assets are skipped with file-path
 warnings instead of aborting the full run.
 
-**Progress in non-verbose JSON/yaml/jsonl mode:** phase-start messages and
-each phase's summary line — including `[embed] endpoint ...` and `[drain]
-done: ...` — reach stderr regardless of `--verbose`: a long-running index
-build against a slow or unresponsive provider is no longer silent until the
-whole run finishes. Two high-frequency, one-line-per-unit-of-work lines are
-the exception and stay suppressed without `--verbose`: drain's per-batch
-commit line (`[drain] batch N: ...`) and reconcile's per-root line
-(`Reconciled "<path>": N files scanned.`) — printing one of those per batch
-or per root would be spam, not a heartbeat. Pass `--verbose` to print those
-two as well, alongside the same summary lines. Text mode is where
-`--verbose` also matters for everything else: without it, progress updates a
-single spinner line in place; with it, every line is printed as it arrives
-instead. JSON stdout output is unaffected either way.
-
-**Reconcile, not a walk-and-rebuild pipeline:** `akm index` diffs every
-configured root's files against the index (stat cache: unchanged files are
-skipped without a re-parse), upserts what changed, removes what is genuinely
-gone, then drains the content-addressed embedding queue. Every write is a
-short, idempotent transaction — there is no rebuild lock, no writer lock on
-the index path, and no per-command background reindex spawn: two concurrent
-`akm index` runs simply converge on the same end state instead of
-contending. `akm index status` (no writes) reports file/entry/unit counts,
-the active embedding identity, and the last-reconcile time.
-
-**`--full`:** does NOT drop or wipe anything first. It reconciles with every
-walked file treated as needing re-derivation — the stat-hint "unchanged"
-shortcut is skipped, so every file is re-parsed — but each file's existing
-row (keyed by its stable `item_ref`) is updated in place, not deleted and
-reinserted: the row keeps its id, its embeddings, and its learned utility
-scores. Content-addressed units (`units`/`units_vec`, keyed by content hash,
-never by entry id) are never at risk from a reindex at all, `--full`
-included — there is nothing to re-embed for unchanged content. Gone-path
-detection (files genuinely removed) is unaffected by `--full`; a root whose
-walk could not be trusted this run (an unreachable path, a mid-walk stat
-failure) has its entire existing snapshot preserved rather than partially
-wiped over a transient scan failure.
-
-**`--reembed`:** drops the active embedding identity's vectors, then the
-drain re-embeds every unit from scratch under that identity. Ordinary
-indexing does not need a separate rename-compatibility check: the identity a
-unit's vector is keyed under is exactly what the provider's response
-reported (model id and vector width), so a config-only rename of
-`embedding.model` that still resolves to the same server-reported model
-keeps the same identity — and its stored vectors — automatically, while a
-genuine model or dimension change lands under a different identity and its
-units are simply "missing" until the next drain.
-
-**`--skip-if-locked`:** deprecated, no effect — index runs no longer take a
-rebuild lock, so there is nothing left to skip around. Passing it prints one
-deprecation warning; the run proceeds exactly as an ordinary `akm index`
-would. Kept only so an existing script or scheduled task does not fail on an
-unknown flag. If index.db is genuinely busy (a second connection holds a
-write transaction) long enough to exhaust the driver's own SQLite
-`busy_timeout`, the run fails with exit 75 (`TransientError`, code
-`INDEX_DB_CONTENDED`) instead of the raw driver error at exit 70 — the same
-retry-shortly contract as `STATE_DB_CONTENDED`, so a scheduler can branch on
-it instead of alerting.
-Locks that do still exist (`akm improve`, `akm workflow run`) are registered through a brief
-internal barrier shared by every akm lock and lease; two runs launched close enough together to
-collide on that registration step retry briefly and then, if it is still busy, exit 75 (code
-`MAINTENANCE_BARRIER_BUSY`) rather than the config-error exit 78 a 2026-09-10 field report
-found — a busy registration barrier is ordinary contention between two legitimate runs, never a
-broken config file.
-
-In text mode, the default CLI UI shows a spinner with processed-versus-total
-source counts; structured output modes (`json`, `yaml`, `jsonl`) stay clean
-and machine-readable.
+**Progress in non-verbose JSON mode (default output format, #954):** even
+without `--verbose`, phase-start messages and the embedding heartbeat
+(`Still generating embeddings: X/N stored, F failed; waiting on embedding
+provider.`) are now written to stderr, and a failed embedding batch logs at
+the default level instead of `--verbose`-only — a long-running index build
+against a slow or unresponsive provider is no longer silent until the whole
+run finishes. Text-mode output keeps its spinner instead (no stderr line
+growth); JSON stdout output is unaffected either way. The high-frequency
+per-batch `Embedded N/M entries.` line stays out of non-verbose stderr (it
+fires after every committed batch) — pass `--verbose` for that level of
+detail.
+
+**`--clean` flag:** After indexing completes, verifies every indexed entry's source
+file still exists on disk. Removes any entries whose file is missing (for local
+bundle sources only; remote entries are skipped). Returns a `clean` block in the
+JSON result with `checked`, `removed`, `removedRefs` arrays, and `dryRun` flag.
+Use `--clean` to resolve the edge case where a deleted file in an unchanged
+directory lingers in the index across incremental runs. With `--dry-run`, reports
+which entries would be removed without modifying the database.
+
+**`--full` no longer re-embeds unchanged content (#955):** a full rebuild
+(and an index-generation bump on first open under a new binary) used to
+delete every embedding unconditionally, forcing a full re-embed of the
+whole corpus even when nothing changed. Vectors about to be discarded are
+now salvaged (keyed by a hash of their content plus the fingerprint they
+were generated under) and handed straight back to unchanged entries at the
+start of the next embedding pass, with zero provider calls for them — a
+progress line reports the split (`Reused N embeddings from the previous
+generation; embedding M new.`). Content that changed even by one byte, or
+a fingerprint that no longer matches, still goes through the provider
+normally. `--reembed` is the way to force a full re-embed regardless.
+
+**`--reembed` flag:** Forces a full purge and re-embed of every entry,
+independent of the embedding-model-rename compatibility check described
+below. Ordinary indexing already tells a config-only rename of
+`embedding.model` (e.g. a gateway that changes how it names the same model)
+apart from a genuine model change, and keeps the stored vectors when they
+are still compatible; `--reembed` skips that check and forces a rebuild
+regardless of what it would have decided.
+
+**`--skip-if-locked` flag:** Every explicit `akm index` run acquires an
+opt-in, PID-liveness-only rebuild lock and releases it on exit — this is
+advisory, never the blocking lock #872 removed (see
+[Locks](https://github.com/itlackey/akm/blob/main/docs/architecture/internals/indexing.md#locks)). A human-typed
+`akm index` with no flag is never gated by it: if another run already holds
+the lock, it warns and proceeds anyway, contending with the existing run. If
+that contention makes index.db genuinely busy (SQLite `database is locked`)
+long enough to exhaust the driver's retry window, the run now fails with
+exit 75 (`TransientError`, code `INDEX_DB_CONTENDED`) instead of the raw
+driver error at exit 70 — the same retry-shortly contract as
+`STATE_DB_CONTENDED`, so a scheduler can branch on it instead of alerting.
+The rebuild lock itself is registered through a brief internal barrier
+(`getMaintenanceBarrierPath()`) shared with every other akm lock/lease; two
+`akm index` runs launched close enough together to collide on that
+registration step retry briefly and then, if it is still busy, also exit 75
+(code `MAINTENANCE_BARRIER_BUSY`) rather than the config-error exit 78 a
+2026-09-10 field report found — a busy registration barrier is ordinary
+contention between two legitimate runs, never a broken config file.
+`--skip-if-locked` changes that only for the invocation that passes it: if
+the lock is already held by a live process, it skips gracefully (exit 0,
+`{ ok: true, skipped: { reason: "lock-held", pid, launcherPid, startedAt } }`
+— `launcherPid` is the holder's launcher pid when known, `null` otherwise,
+#956) instead of contending. `akm index` and `akm curate` are both safe to call frequently —
+`curate` never blocks on a rebuild in progress ([read-path indexing stays
+non-blocking](#curate)) — but a hook, cron job, or scheduled task that
+invokes `akm index` directly should pass `--skip-if-locked` so it steps
+aside instead of piling up behind a longer rebuild (the shipped
+`index-refresh` task does this).
+
+`akm index` always rebuilds the search index and keeps metadata in the index.
+When a selected named LLM engine (`defaults.llmEngine` or an indexing-pass
+override) is configured and the per-pass gate allows it, metadata
+enhancement runs during indexing. In text mode, the default CLI UI shows a
+spinner with processed-versus-total source counts; structured output modes
+(`json`, `yaml`, `jsonl`) stay clean and machine-readable.
 
 ### info
 
@@ -327,16 +337,12 @@ Returns a JSON object with:
 | `indexStats` | Index stats: `entryCount`, `byType` (per-asset-type breakdown), `lastBuiltAt`, `hasEmbeddings`, `vecAvailable` |
 
 `semanticSearch.status` values:
-- `"ready-vec"` — embeddings present, `sqlite-vec` active
+- `"ready-vec"` — native sqlite-vec extension active (fastest)
+- `"ready-js"` — pure JS fallback active (correct but slower at scale)
 - `"pending"` — not yet initialized (run `akm index` to set up)
+- `"blocked"` — setup failed (see `reason` and `message` fields)
 - `"disabled"` — semantic search is turned off in config
 
-(`"ready-js"`, a pure-JS cosine fallback for when the extension was
-unavailable, is retired — the unit vector store has no BLOB fallback to fall
-back to. A degraded/failed embedding run is reflected here as `"pending"`,
-not a separate `"blocked"` value; see `akm index`'s own `verification.semanticStatus`,
-which does distinguish `"blocked"`, for that detail.)
-
 Use `akm info` to verify that semantic search is working after setup.
 
 Scripts that need akm's resolved paths (for example a health check that
@@ -493,18 +499,6 @@ query. The last case also adds one sanitized, endpoint-naming entry to
 preserved by `--shape agent` so machine consumers can lower their confidence
 instead of treating keyword fallback as healthy semantic ranking.
 
-An optional cross-encoder rerank pass (#951, `search.rerank.*` —
-`docs/reference/configuration.md`) can run over local hits before `--from
-local`/`--from all` diverge; disabled by default, and registry hits (`--from
-registry`, and the registry half of `--from all`) are never reranked. When it
-runs, it changes hit **ORDER** only — each hit's `score` stays the retrieval
-score `akm search` computed, not the reranker's own relevance value. A
-consumer that wants the reranked ranking must read hits in ARRAY ORDER, not
-by re-sorting on `score`: `score` is a fixed `[0,1]` contract (see the
-callout below) that a reranker's own scale — provider-defined, not
-calibrated to `[0,1]` — would break if it overwrote it, and a re-sort would
-silently undo the rerank for exactly the consumers it exists to serve.
-
 | Flag | Values | Default | Description |
 | --- | --- | --- | --- |
 | `--type` | `skill`, `command`, `agent`, `knowledge`, `instruction`, `workflow`, `script`, `memory`, `env`, `secret`, `lesson`, `task`, `session`, `fact`, `any` | `any` | Filter by asset type. Free-form and unvalidated — an unknown type returns no hits. Also accepts any adapter-defined type (e.g. `website`) — see [Bundle Types](bundle-types.md) for the open types each adapter emits. |
@@ -1048,7 +1042,8 @@ akm bundle add https://docs.example.com --max-pages 100 --max-depth 5
 | `--provider` | Explicit provider for declarative source configuration; normally inferred from the input |
 | `--writable` | Mark a git source as writable so `akm sync` also pushes (default: false) |
 | `--options` | Provider options as JSON (e.g. `'{"ref":"main"}'`) |
-| `--allow-insecure` | Bypass plain-HTTP source rejection **and** dangerous env key blocking. Accepts two risks: (1) plain-HTTP download without TLS, (2) env keys that can hijack process execution. Use only after reviewing the bundle manually |
+| `--allow-insecure-transport` | Allow a plain-HTTP source URL after explicitly accepting transport substitution risk |
+| `--allow-dangerous-env-keys` | Allow reviewed process-hijacking env keys in the installed bundle; does not permit plain HTTP |
 | `--max-pages` | Maximum pages to crawl for website sources (default: 50) |
 | `--max-depth` | Maximum crawl depth for website sources (default: 3) |
 
@@ -1076,7 +1071,7 @@ config override injection).
 
 When dangerous keys are found, `akm bundle add` pauses and prompts for
 confirmation (default: No). In non-interactive mode (CI, scripts) the
-install fails with **exit 1** unless `--allow-insecure` is passed, and the
+install fails with **exit 1** unless `--allow-dangerous-env-keys` is passed, and the
 freshly-installed bundle is rolled back before the process exits.
 
 ```sh
@@ -1084,7 +1079,7 @@ freshly-installed bundle is rolled back before the process exits.
 akm bundle add github:owner/repo-with-sensitive-env
 
 # Non-interactive: fails unless bypassed
-akm bundle add github:owner/repo-with-sensitive-env --allow-insecure
+akm bundle add github:owner/repo-with-sensitive-env --allow-dangerous-env-keys
 ```
 
 Bundle publishers: see the [Author Bundles guide](https://github.com/itlackey/akm/blob/main/docs/guides/author-bundles.md#env-security)
@@ -1161,14 +1156,14 @@ akm bundle update npm:@scope/pkg
 akm bundle update --all
 akm bundle update --all --force   # Force fresh download even if version is unchanged
 akm bundle update --all --yes     # Skip confirmation when an update needs to delete a moved install dir
-akm bundle update npm:@scope/pkg --allow-insecure  # Explicitly approve reviewed dangerous env keys
+akm bundle update npm:@scope/pkg --allow-dangerous-env-keys  # Explicitly approve reviewed dangerous env keys
 ```
 
 | Flag | Description |
 | --- | --- |
 | `--all` | Update all managed sources |
 | `--force` | Delete cached extraction before re-downloading |
-| `--allow-insecure` | Permit a staged update containing dangerous environment keys after warning. Without it, an interactive terminal prompts with a default of No; non-interactive use fails closed. This is independent of `--yes`. |
+| `--allow-dangerous-env-keys` | Permit a staged update containing dangerous environment keys after warning. Without it, an interactive terminal prompts with a default of No; non-interactive use fails closed. This is independent of `--yes`. |
 | `-y`, `--yes` | Skip the confirmation prompt for the rare branch where the resolved content location moved and the previous install directory must be deleted. No effect on a normal refresh, which deletes nothing. |
 
 The audit examines key names in `.env`-suffixed files under the staged
@@ -1650,7 +1645,7 @@ akm registry add https://skills.sh --name skills.sh --provider skills-sh
 | `--name` | Human-friendly label for the registry |
 | `--provider` | Provider type (e.g. `static-index`, `skills-sh`). Default: `static-index` |
 | `--options` | Provider-specific options as JSON (e.g. `'{"apiKey":"key"}'`) |
-| `--allow-insecure` | Allow a plain HTTP registry URL (rejected by default) |
+| `--allow-insecure-transport` | Allow a plain HTTP registry URL (rejected by default) |
 
 Duplicate URLs are rejected.
 
@@ -1913,6 +1908,7 @@ akm env run env/prod --only A,B -- cmd  # inject only A and B
 akm env run env/prod --except DEBUG -- cmd
 akm env run env/prod --clean -- cmd
 akm env run env/prod --clean --inherit SSH_AUTH_SOCK -- cmd
+akm env run third-party//env/prod --allow-dangerous-env-keys -- cmd
 ```
 
 Runs the command with the env file's values injected **directly into the child
@@ -1925,7 +1921,8 @@ environment (PATH/HOME/locale/terminal basics) instead of inheriting the full
 parent environment; use `--inherit KEY1,KEY2` to pass specific parent vars
 through in clean mode. Before spawning, the injected key names are scanned for
 known process-hijacking variables (`LD_PRELOAD`, `PATH`, `GIT_CONFIG_*`, ...):
-a first-party bundle warns and proceeds; a third-party-sourced bundle is refused.
+a first-party bundle warns and proceeds; a third-party-sourced bundle is refused
+unless the reviewed run explicitly passes `--allow-dangerous-env-keys`.
 
 > The single-key `run <ref>/KEY` form was removed. To inject one value, store it
 > as a [secret](#secret) and use `akm secret run secrets/<name> <VAR> -- …`, or
@@ -2818,9 +2815,10 @@ shell commands. It manages on-disk task definitions under
 (cron / launchd / schtasks). Task source v4 YAML (`version: 4`) is the only
 executable source contract this release accepts; `akm task add` writes v4 —
 see the canonical [Tasks reference](tasks.md). The
-group is `add | run | explain | validate | list | sync | doctor | history | prune`
+group is `add | enable | disable | run | explain | validate | list | sync | doctor | history | prune`
 — there is no `show` or `remove`; use `akm show tasks/<id>` to inspect one
-task, and edit the file + `akm task sync` to change or remove a schedule.
+task. Use `task enable` / `task disable` for host-local activation; edit the
+file only to change the authored schedule or remove the task.
 `task list` is a delegating alias for `akm search --type task` — both
 spellings return the identical envelope.
 
@@ -2832,11 +2830,13 @@ akm task add <id> --schedule "@daily" \     # Register a new task and install it
 akm task add review --schedule "@daily" --prompt "Review recent changes" --engine reviewer
 akm task add nightly --schedule "@daily" --command "akm improve" --disabled  # register but leave off
 akm task add nightly --schedule "@daily" --command "akm improve" --force    # overwrite an existing task id
+akm task enable team//tasks/nightly       # Add local activation and sync its bundle
+akm task disable team//tasks/nightly      # Remove local activation and unschedule it
 akm task run <id>                           # Execute now (what the scheduler calls)
 akm task explain <ref>                      # Read-only: declared inputs, target, schedule — spawns nothing
 akm task validate <path>                    # Read-only: parse one task file by path, report sync's diagnostic
 akm task history [<id>] [--id <id>] [--limit <n>]  # Recent runs from state.db (positional id == --id)
-akm task sync                               # Reconcile on-disk YAML with scheduler
+akm task sync                               # Reconcile activated refs from all enabled configured bundles
 akm task sync --dry-run                     # Preview the reconcile — zero scheduler writes
 akm task sync --rebind                      # Also capture the current installed runtime
 akm task doctor                             # Report scheduler backend + paths
@@ -2869,21 +2869,19 @@ concept ref or id, and the file need not live in any configured bundle —
 and reports the same diagnostic `akm task sync` would produce for it,
 INCLUDING sync's own cron-dialect check and its per-schedule-entry
 input-contract check (so a file `sync` would reject can never be reported
-`valid`/`converts` here): `{ok, path, sourceVersion, outcome, reason?,
+`valid` here): `{ok, path, sourceVersion, outcome, reason?,
 resolved?}` where `outcome` is `valid` (parses as task source v4 directly
-and passes both sync checks), `converts` (task v2/v3 that the deterministic
-migrator converts in memory and which then also passes both sync checks),
-`blocked` (task v2/v3 the migrator itself cannot convert — needs a human
-decision), `invalid` (the YAML doesn't parse, or the document fails schema
+and passes both sync checks), `blocked` (task v2/v3 that must first be
+rewritten by `akm migrate apply`), `invalid` (the YAML doesn't parse, or the document fails schema
 validation, or it parsed but fails one of the two sync checks), or
 `not-a-task` (the YAML parses but never declares a `version:` field — not
 shaped like a task source). `resolved` is the compiled task shape
 `akm task sync` itself would build a scheduler binding from — id, the
 compiled schema version, resolved `uses`/`run` target, declared `inputs`
-contract, and `schedule` bindings — present only on `valid`/`converts`.
+contract, and `schedule` bindings — present only on `valid`.
 Unlike `akm task explain`, it never runs execution lowering: a command-kind
 task validates the same whether or not the local config has an engine
-configured. Exits 0 for `valid`/`converts`, 1 for
+configured. Exits 0 for `valid`, 1 for
 `blocked`/`invalid`/`not-a-task`, 2 for a missing or unreadable path.
 **Read-only**: it never touches the scheduler and never requires the file to
 be indexed or wired into a bundle.
@@ -2893,9 +2891,11 @@ time. Each run is recorded as a row in the durable `task_history` table
 (`state.db`), surfaced by `akm task history` — **not** by `akm log`; there is
 no `task_invoked`/`task_completed` event type on the `akm log` stream.
 
-To disable a scheduled task, set `enabled: false` on its `schedule:` entry
-(task source v4 has no document-level `enabled` flag — it lives per
-schedule-binding) and run `akm task sync`. To remove one, delete its file
+Task source cannot enable itself. `akm task enable <fully-qualified-ref>` adds
+an exact source-bound `{kind, ref, sourceId}` grant to this host's
+`scheduler.enabled` config and
+syncs that bundle; `akm task disable` removes it and unschedules the task.
+Manual `akm task run` remains available. To remove a task, delete its file
 (`<bundle>/tasks/<id>.yml`) and run `akm task sync` — sync uninstalls the
 orphaned scheduler entry.
 
@@ -2916,9 +2916,10 @@ to specific binding ids — naming an id that isn't a current orphan
 candidate (not installed, or it still resolves to a live bundle) is
 refused with a usage error and removes nothing.
 
-Scheduler activation captures the installed akm runtime. Ordinary `task sync`
-reconciles definitions, schedules, and enabled state while preserving that
-runtime binding. Use `task sync --rebind` only after intentionally moving or
+Scheduler activation is host-local config and captures the installed akm
+runtime. Ordinary `task sync` reconciles activated refs from all enabled
+configured bundles while preserving that runtime binding. Use `task sync
+--rebind` only after intentionally moving or
 replacing the installation, or to repair a stale runtime path, then verify the
 result with `akm task doctor`. Interactive `akm setup` reviews every embedded
 task template (both the core set and the improve-schedule set) and asks once
@@ -2936,9 +2937,10 @@ Setup reconfiguration preserves existing scheduler runtime bindings. Changing
 the AKM storage path or installed runtime path therefore requires an explicit
 `akm task sync --rebind`; setup does not silently migrate those entries.
 
-**Bundle targeting (`--bundle <bundle>`).** By default every subcommand
-operates on the primary/default bundle. `add`, `history`, `sync`, `run`, and
-`explain` all accept `--bundle <bundle>` to schedule, reconcile, or inspect
+**Bundle targeting (`--bundle <bundle>`).** By default read/write commands
+operate on the primary/default bundle, while an unscoped `sync` reconciles all
+enabled configured bundles. `add`, `enable`, `disable`, `history`, `sync`,
+`run`, and `explain` accept `--bundle <bundle>` to schedule, reconcile, or inspect
 tasks that live in another configured bundle (`doctor` reports scheduler-wide
 state and takes no `--bundle`; `validate` takes a bare filesystem path
 instead of a ref, so it has no bundle to target either):
@@ -2950,9 +2952,9 @@ akm task sync --bundle team-bundle             # reconcile only that bundle
 
 A non-default bundle is recorded in the installed scheduler entry as a
 `--bundle <bundle>` token, so the scheduled `akm task run` resolves the task
-(and its relative asset refs) from that bundle. `sync` reconciles one bundle at a
-time and only touches entries attributed to it, so a plain (primary) sync never
-disturbs another bundle's scheduled tasks. Scheduler ids are the bare task id and
+(and its relative asset refs) from that bundle. `sync --bundle` limits a run to
+one bundle; unscoped `sync` reconciles every configured bundle as one
+transaction. Scheduler ids are the bare task id and
 are never namespaced: registering a task whose id is already scheduled from a
 different bundle is a hard error.