@llblab/pi-actors 0.14.3 → 0.16.0

package/AGENTS.md

@@ -17,7 +17,9 @@
 - `/lib/*.ts`: Flat Domain DAG modules for cohesive reusable behavior; `command-templates.ts` mirrors the shared portable command-template standard, `schema.ts` owns tool arg declarations and placeholder-derived tool schemas, `identity.ts` owns names, `config.ts` owns config persistence, `registry.ts` owns registry register/update/delete use-cases, `output.ts` owns result formatting/truncation, `execution.ts` owns registered-tool execution, `recipe-references.ts` owns template recipe reference detection and path resolution, `async-runs.ts` owns async run state, `observability.ts` owns ambient run summaries, `temp.ts` owns pi-agent temp cleanup, `prompts.ts` owns LLM-facing copy, `tools.ts` owns pi-facing tool definitions for both `register_tool`, async run primitives, and generated runtime tools, `runtime.ts` owns load/conflict/registration coordination, and `paths.ts` owns config/tmp path resolution
 - `index.ts` should import local domains as namespaces (`import * as CommandTemplates from "./lib/command-templates.ts"`) so orchestration reads through domain names instead of flat helper imports
 - `/scripts/*.mjs`: Thin helper processes for detached async run execution; keep policy in registered tool config and reusable logic in `/lib`
-- `/recipes/*.json`: Packaged standard recipe library; keep recipes optional, composable, and policy-light; prefer public args/defaults for operator/agent decisions instead of baking project-specific prompts or file names into reusable recipes
+- `/recipes/*.json`: Packaged standard recipe library; keep recipes optional, composable, and policy-light; prefer public args for operator/agent decisions instead of baking project-specific prompts, file names, or concrete model-version defaults into reusable recipes
+- `/skills/actors/SKILL.md`: Dense practical reference for operating pi-actors itself
+- `/skills/swarm/SKILL.md`: Bundled methodology skill for multi-agent standards, strategies, and portable examples; keep it theory/strategy-oriented while pi-actors recipes/scripts provide the local execution engine
 - `/scripts/music-player.mjs`: Standard helper script for the packaged music-player recipe; keep it executable and avoid restoring parallel shell-wrapper variants unless a concrete portability need appears
 - `/tests/*.test.ts`: Focused regression tests for pure domains
 - `/README.md`: Human-facing install, usage, and runtime semantics
@@ -35,6 +37,7 @@
 
 ## Durable Conventions
 
+- `Knowledge surface separation`: pi-actors has distinct knowledge surfaces with different context-entry behavior: injected prompt is always present and should stay a tiny bootstrap/reminder; packaged `actors` skill is auto-matched by name/description and should signal that its body is the highest-density practical guide for operating the extension plus the shortest navigator to bundled recipes; packaged `swarm` skill is auto-matched for multi-agent methodology, strategies, standards, and portable examples; README is the human entrypoint explaining concept, rhythm, benefits, and scenarios but is not automatically in context; `/docs` are detailed transportable standards read on demand; `AGENTS.md` is project context and architectural constraints for agents changing the repo | Trigger: Editing prompt copy, README, docs, skills, or project context | Action: Keep each surface on its own wave, avoid duplicating prompt and skill headers, keep the actors skill recipe navigator compact and concrete, avoid duplicating scenario catalogs or changelog narratives in the actors skill, avoid turning the prompt into docs, keep multi-agent methodology in swarm-oriented guidance rather than the actors skill, keep packaged extension skill metadata versions synchronized with `package.json` version, and avoid extra colons in skill frontmatter scalar lines because skill formatters treat them poorly
 - `Tool registry source`: `~/.pi/agent/actors-tools.json` is the persistent user config | Trigger: Any runtime registration or migration work | Action: Preserve atomic writes and avoid hidden format changes without an explicit migration path
 - `Current runtime contract`: Register trusted command templates with tool names from registry keys, placeholder-derived args, progressive typed arg declarations, inline/default/`??`/ternary config fallback, placeholder-derived numeric node controls, split-first command-arg construction, sequential or `parallel: true` composition, direct no-shell execution, optional per-node `when`, optional per-node positive `timeout` disabled by default, lightweight warnings for obvious trusted-executable risk shapes, per-node `delay`, bounded leaf/node `retry`, `failure: "continue|branch|root"` propagation, `recover` cleanup between retry attempts, template recipes with explicit `async: true` detached mode, actor-oriented `spawn`/`message`/`inspect` tools with run-local JSONL outbox messages, Unix FIFO send, graceful cancel, and force kill, generic detached run primitives with process-group cancellation, injected async `{run_id}` and `{state_dir}` values, coordinator-scoped event-driven observability with at least one triangle per active async run and extra triangles for active parallel branches, runtime-inferred `command.done` bubbling for packaged multi-agent fanout, named recipe `artifacts`, recipe `mailbox` metadata, terminal follow-ups for `done`/`failed`/unhandled `killed`/`exited` states, `template` recipe references, recipe-layer `imports`, co-located recipe entries, `~/.pi/agent/recipes/*.json` template recipe files, run state under `~/.pi/agent/tmp/pi-actors/runs`, and `{file}` as the canonical local file path arg | Trigger: Changing registration or invocation behavior | Action: Keep README, command-template docs, template-recipe docs, async-run docs, actor-message docs, implementation, and migration notes aligned
 - `Typed arg authoring`: Typed args support `string`, `path`, `int`, `number`, `bool`, and `enum(...)` plus two equivalent readability styles: metadata-first (`args` + `defaults` + simple `{name}` placeholders) for long command lines, and inline-first (`{name:type=default}` placeholders) for compact one-property templates | Trigger: Changing arg parsing, docs, schema generation, or registry serialization | Action: Preserve both styles, keep explicit `args` type declarations higher priority than inline placeholder types, and make breaking cleanup explicit when removing old arg shapes
@@ -47,6 +50,7 @@
 - `Communication direction`: The design target is an organic universal message layer across sync tasks, async runs, branches, tools, and coordinators. Breaking changes are allowed to compress concepts, remove accidental duplication, and make duplex communication symmetric where the domain is symmetric. | Trigger: Designing APIs or recipes that communicate | Action: Prefer a concentrated actor/message protocol (`spawn`, `message`, `inspect`, addressed endpoints, typed message envelopes, mailbox accepts/emits) over exposing FIFO/outbox/status mechanics directly; use one envelope for upward, downward, lateral, parent/branch, and branch/parent messages; absorb runtime async primitives into actor API instead of preserving parallel public concepts.
 - `Output discipline`: Tool stdout is returned with bounded context impact | Trigger: Changing execution or formatting | Action: Keep tail truncation, full-output temp files, and failure formatting intact
 - `Extension temp directory`: Temporary runtime files belong under `~/.pi/agent/tmp/pi-actors`; session start prepares the directory and prunes stale entries | Trigger: Adding temp files, run state, logs, or artifacts | Action: Do not use system tmp for extension-owned state unless the operator explicitly overrides a path
+- `Backlog is planning, not history`: `BACKLOG.md` should contain current/future work, blockers, gates, and next leverage points; completed delivery history belongs in `CHANGELOG.md`, and durable behavior belongs in README/docs | Trigger: Editing backlog or reconciling completed slices | Action: Remove historical progress narratives, keep current task/scope/exit criteria, and prefer an 80/20 focus list when many remaining tasks compete for attention
 - `Context sync`: Meaningful implementation or docs changes must reconcile `BACKLOG.md`, `CHANGELOG.md`, README, and docs navigation | Trigger: Closing, narrowing, or discovering work | Action: Run the context validator before final status when practical
 - `Public path hygiene`: Published docs must not include machine-local absolute paths | Trigger: Adding validation commands, examples, or local instructions to README/AGENTS/docs/changelog | Action: Use `~/.pi/...`, `<repo>/...`, `${SKILL_DIR}/...`, or relative paths
 

package/BACKLOG.md

@@ -2,38 +2,60 @@
 
 ## Open Work
 
-Continue progressive component/pipeline expansion in small validated slices; real smoke runs remain gated. Prefer task-first design for new high-level recipe families: start from operator/coordinator work patterns, then derive missing component cells.
-
-- Plan organic universal communication primitives.
-  - Priority: High.
-  - Status: The actor-like model is empirically useful: async runs can emit follow-up messages upward, coordinators can send run-local commands downward, multiple parallel runs can progress independently, and recipes no longer need sleep-poll coordination. The design is captured in `docs/actor-messages.md`: `spawn`, `message`, and `inspect` as concentrated verbs; addressed actors; one symmetric message envelope; mailbox `accepts`/`emits`; and adapter mappings from runtime async actions. Initial implementation landed pure actor address/message normalization plus public `spawn`, `message`, and `inspect` tools for `run:<id>` actors; `spawn` accepts state/artifact metadata, `message` routes `run:<id>` → `coordinator` and `run:<id>` → `session:<id>` envelopes into the runtime attention path, `message` can invoke `tool:<name>` actors, `inspect target=tool:<name>` exposes registered tool actor contracts, `inspect target=coordinator` exposes current-session run inventory, all packaged async recipes declare mailbox metadata, `inspect view=mailbox` exposes recipe mailbox contracts from run metadata, recipe-authored messages now use envelope-aligned `type` fields with deterministic validated wrapping available through `utility-actor-message`, run termination now uses actor-native `control.stop`/`control.cancel`/`control.kill` without runtime-prefixed control aliases, async command events preserve full argv details while keeping coordinator summaries bounded, async-run operations recommendations now emit structured `message`/`inspect` objects instead of shell-like suggestion strings, `inspect view=messages` exposes run actor messages and `inspect view=events` has been removed as a compatibility alias, async-run operations recipes now expose `message_file`/`messages` terminology instead of public event-file args, and operator-facing docs now describe coordination with actor-message terminology before transport details, async-run docs separate public actor behavior from storage/transport mechanics more clearly, public actor-message/template guidance avoids transport-specific wording, and async-run operations recipes now use only `message_file` for actor-message inputs, interactive and high-level pipeline recipe mailboxes now advertise the full actor-native termination controls where the runtime already supports them, task-first/library docs now describe operations snapshots in terms of actor-message tails instead of event tails, and `inspect view=events` has been removed from the public inspect surface in favor of `inspect view=messages`. Remaining work is to absorb remaining runtime async action surfaces into the actor vocabulary instead of preserving a parallel public API.
-  - Scope: Design and implement a small semantic layer around addressed messages and actors while preserving low-level primitives as adapters where useful. Candidate top-level concepts are `spawn` for creating an actor/run from a recipe or template, `message` for sending typed messages to any address, and `inspect` for intentional observation/debugging. Candidate addresses include `run:<id>`, `branch:<run>/<branch>`, `coordinator`, `session:<id>`, `tool:<name>`, and future chat/session endpoints. Candidate message fields include `to`, `from`, `type`, `summary`, `body`, `reply_to`, `correlation_id`, and `metadata`.
-  - Contract direction: Unify “send down” and “messages up” as one message model. `to: run:<id>` routes to a run mailbox, `to: coordinator` routes to the coordinator attention path, and branch/tool/session addresses can be layered over the same semantic envelope. Recipes should declare mailbox capability (`accepts`, `emits`) without exposing FIFO/outbox mechanics or delivery policy as their public interface.
-  - Design gates: Breaking changes are allowed in this phase, so compress concepts instead of preserving accidental surfaces. Consolidate duplicated lifecycle/message/event APIs into a concentrated protocol with the fewest durable nouns and verbs that still explain the system. Duplex communication should be symmetric where the domain is symmetric: the same message envelope should represent run→coordinator, coordinator→run, run→run, branch→parent, and parent→branch traffic, with routing/transport hidden below it. Keep command templates as the portable synchronous execution graph; keep recipe files as semantic definitions; avoid leaking transports into public args; make polling an explicit diagnostic operation, not an example path; replace runtime action names with the actor API rather than preserving parallel concepts.
-  - Exit: The project exposes documented high-level universal communication primitives for starting work, sending messages, and inspecting state; packaged recipes/examples use the organic interface; async send/outbox behavior is intentionally migrated into actor-message coverage; all recipes validate and docs describe the actor/message model clearly.
-
-- Progressively increase component parameterization and higher-level recipe composition.
-  - Priority: High.
-  - Status: `subagent-tools` and `subagents-prompts` now align with the common subagent policy knobs for thinking, tools, model, and output format.
-  - Scope: Iteratively strengthen atom/component recipes with public policy knobs such as model pools, stage-specific models, thinking, tool policy, output format, evidence policy, risk policy, source policy, artifact paths, mailbox contract, handoff format, resume/continuity policy, and validation gates; add higher-level component recipes that compose existing atoms into reusable coordinator patterns.
-  - Exit: Each iteration adds or refines at least one atom-level parameterization surface and at least one composed recipe/pipeline, with packaged recipe import validation passing and docs/changelog updated.
-
-- Add another task-first high-level pipeline candidate from the design map.
-  - Priority: Medium.
-  - Status: `pipeline-release-readiness`, `pipeline-repo-health`, `pipeline-async-run-ops`, `pipeline-docs-maintenance`, `pipeline-media-library`, and `pipeline-artifact-bundle` landed. `pipeline-release-readiness` now includes package-summary evidence before validation/review. `pipeline-media-library` required playlist output-mode parameterization, then reused playlist and artifact-report cells. `pipeline-artifact-bundle` reused artifact-write, artifact-manifest, validation, manifest-write, and actor-message cells.
-  - Scope: Reassess `docs/task-first-recipes.md` for the next high-value task cell, then implement only the minimum missing cells needed for that task.
-  - Exit: Another task-first pipeline lands with docs, package validation, and a note about which missing atoms/utilities it required.
-
-- Grow the standard recipe library with safer structured utility transforms.
-  - Priority: Low.
-  - Status: `utility-artifact-manifest` landed for machine-readable artifact metadata; `utility-artifact-write` landed for deterministic writes of accepted prepared artifacts; `utility-package-summary` landed for bounded package metadata used by release/repo-health flows; `utility-validate-recipe` landed with a dedicated recipe validator script; `utility-run-ops-snapshot` landed for async-run summaries, actor-message tails, and operator-gated cleanup recommendations.
-  - Scope: Continue beyond listing/extraction utilities toward structured transforms for artifact packaging, report normalization, release prep, and machine-readable summaries. Keep helpers generic, parameterized, and justified by repeated recipe needs.
-  - Exit: A future utility slice adds another structured transform only when a repeated recipe need appears; otherwise treat the current helper-backed utility surface as sufficient.
+No release-blocking work remains for `0.16.0`.
+
+## Future Work
+
+### Recipe Registry Curation UX
+
+- Priority: Medium.
+- Status: `inspect target=recipes view=status|summary` exposes active, shadowed, invalid, disabled, and diagnostic recipe state. User-owned recipes track extension-maintained `usage.calls` and `usage.last_called`.
+- Goal: Help operators curate the sticky `~/.pi/agent/recipes` tool surface without automatic deletion or demotion.
+- Direction:
+  - Include usage fields in recipe registry summaries.
+  - Add cleanup recommendations for stale, duplicate, low-use, too-specific, invalid, disabled, and shadowing recipes.
+  - Recommend explicit actions only: keep as tool, set `tool: false`, merge, delete, or archive.
+  - Keep cleanup operator-gated; never silently delete or demote during unrelated work.
+- Exit:
+  - Operators can ask why a recipe/tool exists and what cleanup action is reasonable without reading files manually.
+
+### Host-Level Tool Unregistration
+
+- Priority: Low.
+- Status: Deleted recipe files are removed from the active tool set on reactive reload; host-level registered tool definitions cannot currently be unregistered by this extension.
+- Goal: Remove stale dynamically registered tool definitions completely when the host API supports it.
+- Direction:
+  - Track pi extension API support for custom tool unregistration.
+  - Replace active-tool deactivation fallback with real unregister when available.
+  - Preserve current safe behavior: deleted tools should not remain active after reload.
+- Exit:
+  - Deleting a recipe file removes the corresponding runtime tool definition and active-tool entry without session restart.
+
+### Recipe Discovery Expansion
+
+- Priority: Low.
+- Direction:
+  - Add nested recipe directories only after flat `recipes/*.json` discovery semantics are stable.
+  - Keep same-id priority and invalid-blocking behavior explicit if nested ids are introduced.
+
+### Recipe Usage Telemetry Evolution
+
+- Priority: Low.
+- Direction:
+  - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
+  - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.
+
+### Opportunistic Recipe Library Growth
+
+- Priority: Low.
+- Direction:
+  - Add new utilities or pipelines only when a concrete repeated task pattern justifies them.
 
 ## Blocked Work
 
-- Validate branch-local checkpoint semantics with collaborative-runner experiments.
-  - Priority: Low.
-  - Blocked by: At least one real collaborative branch-runner async-run experiment.
-  - Scope: Use real collaborative branch-runner async runs to validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are sufficient for branch-local validation and bounded reattempts.
-  - Exit: Decision recorded as sufficient, documentation-only refinement needed, or propose a further minimal command-template extension with tests.
+### Branch-Local Checkpoint Semantics
+
+- Priority: Low.
+- Blocked by: At least one real collaborative branch-runner async-run experiment.
+- Scope: Validate whether `failure: "branch"`, node-level `retry`, and `recover` cleanup are enough for branch-local validation and bounded reattempts.
+- Exit: Record one decision: sufficient, documentation-only refinement needed, or propose one minimal command-template extension with tests.

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.16.0: File-Discovered Recipe Registry Migration
+
+- `[Version]` Began the `0.16.0` breaking-change cycle and captured the file-discovered recipe registry migration plan in `BACKLOG.md`. Impact: the next release target is now explicit: replace `actors-tools.json` as live registry with validated recipe files, filename identity, `tool` exposure, override/disable semantics, migration reporting, registry inspection, and usage-informed cleanup.
+- `[Recipe References]` Started filename-identity support for recipes by deriving the recipe id from the JSON filename when `name` is omitted, while preserving optional `tool`, `disabled`, and `description` metadata through recipe resolution. Impact: new recipe files can move toward filename-as-identity without losing human-readable descriptions or tool exposure flags.
+- `[Recipe Discovery]` Added an initial file-discovered recipe registry domain with flat root scanning, filename ids, priority shadowing, invalid high-priority recipe blocking, disabled overrides, and `tool: true` exposure detection. Impact: the 0.16 registry migration now has a tested discovery core before wiring it into runtime loading.
+- `[Recipe Migration]` Added a legacy registry migration domain that converts `actors-tools.json` entries into user recipe files with `tool: true`, preserves descriptions/args/defaults/templates, refuses to overwrite existing recipe files, writes a migration report, and archives the source only when migration has no conflicts or invalid entries. Impact: the breaking registry transition now has a tested compatibility path from the old live registry.
+- `[Recipe Discovery]` Captured the priority model that treats packaged pi-actors recipes as a standard library below ad hoc user-selected recipe files and below `~/.pi/agent/recipes/*.json`, with priority applying only to matching filename ids. Impact: override behavior now has a documented lens and a regression for standard-library versus user recipe precedence.
+- `[Recipe Discovery]` Added source-level default tool exposure so the high-priority user recipe root can behave as the operator-managed tool set by default, while packaged/ad hoc recipes stay component-like unless they opt in with `tool: true` and any recipe can opt out with `tool: false`. Impact: 0.16 keeps the discoverability advantage of the old tool-only registry without forcing a separate live tool config.
+- `[Runtime]` Wired session-start tool loading to migrate the legacy registry, discover recipe-file tools from `~/.pi/agent/recipes` and packaged recipes, and register only active exposed recipes as runtime tools. Impact: the new recipe-discovered registry path is now active in runtime loading instead of only existing as standalone discovery/migration helpers.
+- `[Registry]` Changed `register_tool` persistence to write/update/delete user recipe files under the recipe root instead of mutating the legacy JSON registry, while still activating the tool in the current session. Impact: newly registered tools now enter the 0.16 recipe-discovered registry directly.
+- `[Docs]` Reworked tool-registry documentation, README examples, recipe docs, actor skill guidance, and prompt copy around recipe-file persistence, the user recipe directory as the default tool set, packaged recipes as standard-library components, and `actors-tools.json` as legacy migration input. Impact: public guidance now matches the 0.16 runtime path instead of the old live JSON registry.
+- `[Skill]` Added actors-skill guidance for same-name recipe priority, recipe-root-as-muscle-memory, usage counters, and an explicit cleanup rule for stale/default tools without automatic deletion or demotion. Impact: agents get the override model, sticky-tool tradeoff, and cleanup heuristic directly in the compact operational reference.
+- `[Recipe Usage]` Added extension-maintained recipe launch metadata updates for user-owned runtime tools and direct async recipe starts, tracking `usage.calls` and `usage.last_called` without failure counters while leaving packaged standard-library recipes immutable, then documented the cleanup interpretation in recipe and tool-registry docs. Impact: the operator-managed recipe/tool set now accrues cleanup evidence for muscle-memory review from actual extension launches rather than manual agent bookkeeping.
+- `[Runtime]` Added a best-effort user recipe-root watcher that debounces file changes and reloads recipe-backed tools during the active session, plus runtime-tool fingerprinting so repeated reloads do not re-register unchanged tools while changed definitions refresh, and stale recipe tools are removed from the active tool set on reload when their recipe disappears. Impact: newly created or edited valid recipe files can be connected without a full restart, without duplicate registration churn for unchanged recipes, while deleted recipe tools are deactivated even though host-level unregistration is still not available.
+- `[Recipe Discovery]` Added a discovery summary helper and wired/documented `inspect target=recipes view=status|summary` to report active, shadowed, invalid, disabled, and diagnostic recipe entries. Impact: the registry inspection surface can explain why tools are present, hidden, broken, or disabled from the normal actor inspection tool.
+- `[Backlog]` Reconciled 0.16 planning state after implementation of the core runtime path, usage counters, and reactive recipe reload behavior. Impact: remaining open work is now framed as hardening, inspection UX, and release validation instead of rediscovering already implemented pieces.
+- `[Docs]` Normalized registry examples toward filename/tool ids that match the snake_case tool naming convention, avoiding mixed hyphen/underscore examples around `docs_review`, and aligned package image metadata with the local pi-actors banner. Impact: recipe identity, generated tool naming, and package presentation are less ambiguous in 0.16 guidance.
+- `[Backlog]` Reconciled the recipe registry inspection surface after wiring the initial `inspect target=recipes` summary, then closed the active `0.16.0` release backlog by moving remaining non-blocking ideas to future curation, host-unregistration, discovery expansion, telemetry evolution, and opportunistic recipe-library sections. Impact: the backlog now distinguishes completed release scope from future follow-up work.
+
+## 0.15.0: Packaged Actors Skill And Actor Vocabulary Cleanup
+
+- `[Skill]` Reworked the packaged `actors` skill as a dense self-contained extension reference rather than a scenario catalog or changelog narrative, bundled the `swarm` methodology skill alongside it, synchronized packaged skill metadata versions with the package version, included `skills/` in the npm package contents, registered both skills in package metadata, and linked them from the README start points. Impact: fresh agents get compact practical coverage of pi-actors operation plus complementary multi-agent methodology without duplicating the two roles.
+- `[Prompts]` Tightened the injected onboarding prompt into a shorter runtime bootstrap/reminder that avoids duplicating the skill and notes that README/docs are not automatically in context. Impact: session context stays compact while preserving operational lookup paths.
+- `[Context]` Added a durable knowledge-surface separation convention for prompt, skill header/body, README, docs, and `AGENTS.md`. Impact: future edits have a clear role model for where each kind of pi-actors knowledge belongs and how it reaches the agent context.
+- `[Backlog]` Reconciled task-first pipeline notes with the release-summary/review pipeline candidate in abstract terms. Impact: future pi-actors work can explore evidence preparation without tying the backlog to one completed release pass.
+- `[Actor Tools]` Changed compact `inspect view=messages` and `message` tool output to use actor-message wording instead of public `event`/`delivery`/`outbox` labels. Impact: default tool output now reinforces the actor vocabulary while verbose JSON still exposes implementation details for diagnostics.
+- `[Skill]` Reworded the packaged skill description to avoid extra frontmatter colons and replaced the compact two-branch Core Nouns sketch with an explicit two-path flow. Impact: skill metadata stays formatter-safe and the template→recipe→run versus template/recipe→tool relationship is easier to read.
+- `[Recipe Library]` Added `utility-skill-summary` and routed `pipeline-release-readiness` through packaged skill evidence between package summary and validation. Impact: release readiness reports can verify skill metadata/package-version alignment, formatter-safe frontmatter, body size, and heading shape alongside changelog/package/validation evidence.
+- `[Recipe Library]` Changed async-run operations recipes from public `message_file` inputs to `run_id` inputs, with the helper resolving implementation storage internally. Impact: packaged recipes no longer expose outbox paths as part of their public actor-operations surface.
+- `[Recipe Library]` Added `coordinator-locker`, a long-lived actor recipe backed by `scripts/coordinator-locker.mjs` that manages a FIFO work queue, acquire/renew/release resource lease locks, a journal, and coordinator-directed actor messages, plus `utility-coordinator-lock-snapshot` for state inspection. Impact: future coordinated fanout recipes have a small local coordination cell instead of baking ad hoc queue/lock mechanics into each pipeline.
+- `[Skill]` Clarified the actors skill's relationship to methodology skills and expanded it with a linked Recipe Navigator covering bundled coordination/service recipes, subagent atoms, pipelines, and utilities. Impact: the actors skill is now both the extension operation reference and the shortest agent-facing path to concrete packaged recipe files.
+- `[Recipe Library]` Standardized all packaged async recipes to advertise `control.stop`, `control.cancel`, and `control.kill` in mailbox accepts. Impact: `inspect view=mailbox` now exposes the actor-native termination contract consistently across subagent atoms, coordinator cells, music, and pipelines.
+- `[Recipe Library]` Removed concrete model-version defaults from packaged recipes, removed stale concrete model aliases from operator/docs examples, and added regressions that reject model-like defaults or provider/version aliases in recipe defaults and stale concrete model aliases in public guidance. Impact: reusable components stay policy-light and force the caller/agent to choose current model policy at launch instead of inheriting stale packaged aliases.
+- `[Context]` Recompressed `BACKLOG.md` around current/future work only, added an 80/20 focus section for the remaining actor-vocabulary, recipe-policy, release-evidence pipeline, and utility-growth work, and promoted the backlog-is-planning rule into `AGENTS.md`. Impact: completed history stays in the changelog/docs while the backlog remains an actionable planning surface.
+- `[Recipe Library]` Added `pipeline-release-summary`, an evidence-only release preparation pipeline that composes changelog, package, skill, and validation evidence into a release summary, risk checklist, and PR body draft artifact without commit, PR, merge, tag, publish, or other external release side effects. Impact: release-prep artifacts can be produced under pi-actors while gated release actions remain owned by release workflows.
+- `[Docs]` Reworded remaining public README examples and the async-run operations pipeline prompt toward run-actor vocabulary instead of presenting async-run lifecycle wording as the primary operator concept. Impact: public guidance continues converging on `spawn`, `message`, `inspect`, and actor runs while low-level lifecycle language stays in implementation docs.
+- `[Context]` Closed the active `0.15.0` backlog by moving completed actor-communication, component-policy, and utility-surface work out of open planning, leaving only future opportunistic work and the blocked branch-runner experiment. Impact: the release backlog now reflects no open release-blocking work.
+- `[Skill]` Consolidated the bundled `swarm` methodology skill boundary by removing concrete pi-actors adapter examples and duplicate adapter/component docs from Swarm, keeping detailed MAWP mechanics in the dedicated reference instead of duplicating them in the general skill, and adding regressions that packaged Swarm markdown must not mention pi-actors runtime identifiers, package metadata must register every packaged skill, packaged skill markdown links must resolve, and the actors Recipe Navigator must link every bundled recipe file. Impact: Swarm can live inside this package while remaining portable methodology, and actors remains the shortest concrete path to packaged recipes.
+
 ## 0.14.3: Pipeline Termination Mailbox Consistency
 
 - `[Recipe Library]` Added `control.cancel` and `control.kill` mailbox accepts to packaged async pipeline recipes that previously advertised only `control.stop`. Impact: `inspect view=mailbox` now exposes the full actor-native termination set consistently across high-level pipeline actors.

package/README.md

@@ -1,6 +1,8 @@
 # pi-actors
 
-Actor runtime and orchestrator for agent-managed local processes.
+> Actor runtime and orchestrator for agent-managed local processes.
+
+[<img alt="Actors*" src="banner.jpg" />](https://github.com/llblab/pi-actors "pi-actors")
 
 `pi-actors` turns local programs, scripts, services, recipes, and long-running processes into addressable actors that agents can start, message, inspect, and compose. A music player, a sub-agent fanout, a repo-health pipeline, or any trusted local process can become an actor when it has a template-backed launch path, a mailbox contract, and observable runtime state.
 
@@ -12,6 +14,9 @@ The persistent tool registry is still useful: it lets agents keep durable operat
 - [Open Backlog](./BACKLOG.md)
 - [Changelog](./CHANGELOG.md)
 - [Documentation](./docs/README.md)
+- [Actors skill](./skills/actors/SKILL.md) — dense agent-facing reference for operating the extension
+- [Swarm skill](./skills/swarm/SKILL.md) — multi-agent methodology, strategies, standards, and portable examples for actor-backed swarms
+- [Swarm MAWP notes](./skills/swarm/references/development-swarm.md) — optional small-team development swarm reference
 
 ## What It Is
 
@@ -41,7 +46,7 @@ The key move is not just “register a command.” It is to wrap a process in an
 - **Control**: `message` sends typed envelopes to runs, branches, tools, or the coordinator.
 - **Observation**: `inspect` reads status, logs, messages, mailbox metadata, files, and artifacts intentionally.
 - **Persistence**: `artifacts` and state files make outcomes durable.
-- **Memory**: `actors-tools.json` stores reusable actor-control wrappers across sessions.
+- **Memory**: `~/.pi/agent/recipes/*.json` stores reusable actor-control wrappers across sessions.
 
 ## Key Features
 
@@ -49,7 +54,7 @@ The key move is not just “register a command.” It is to wrap a process in an
 - **Agent-Managed Processes**: Wraps sub-agents, media players, pipelines, diagnostics, and other local programs as controllable entities instead of one-off commands.
 - **Message-Oriented Control**: Uses `spawn`, `message`, and `inspect` as the public coordination vocabulary for start, control, and observation.
 - **Mailbox Contracts**: Lets recipes declare what messages they accept and emit, so agents can discover how to interact with an actor.
-- **Actor Tool Registry**: Stores persistent actor-control tool definitions in `~/.pi/agent/actors-tools.json` and registers them automatically on session start.
+- **Actor Tool Registry**: Stores persistent actor-control tools as recipe files in `~/.pi/agent/recipes/*.json` and registers them automatically on session start.
 - **Command Template Substrate**: Keeps process launch portable with named placeholders, typed args, defaults, sequences, guarded nodes, retries, failure policy, and `parallel: true` fanout.
 - **Composable Actor Recipes**: Stores reusable recipe JSON under `~/.pi/agent/recipes/*.json`; recipes can import other recipes, reuse defaults, declare artifacts, and opt into detached actor lifecycle with `async: true`.
 - **Coordinator-Scoped Observability**: Shows ambient triangles for active actor runs and sends compact completion or request-for-attention follow-ups only to the launching coordinator.
@@ -70,27 +75,17 @@ From git:
 pi install git:github.com/llblab/pi-actors
 ```
 
-## Rename Migration
+## Registry Migration
 
-`pi-actors` reads persistent actor-control tools from:
+`pi-actors` now reads persistent actor-control tools from:
 
 ```text
-~/.pi/agent/actors-tools.json
-```
-
-If you previously used `pi-auto-tools`, copy the old registry intentionally:
-
-```bash
-cp ~/.pi/agent/auto-tools.json ~/.pi/agent/actors-tools.json
+~/.pi/agent/recipes/*.json
 ```
 
-If you installed the brief `0.12.0`/`0.12.1` line and created `tools.json`, copy that file instead:
+That directory is the operator-managed tool set: user recipe files there become tools by default unless they set `tool: false`. Packaged recipes are the lower-priority standard library of declarative actor components and opt into tools with `tool: true`.
 
-```bash
-cp ~/.pi/agent/tools.json ~/.pi/agent/actors-tools.json
-```
-
-The extension does not silently rewrite old registry files; keep or delete the old file after confirming the new registry loads as expected.
+If `~/.pi/agent/actors-tools.json` exists from an older release, pi-actors treats it as legacy compatibility input, migrates entries into recipe files when possible, writes a migration report, and archives the legacy file only when migration is clean.
 
 ## Mental Model
 
@@ -126,12 +121,10 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
 
 ```json
 {
-  "name": "docs-review",
+  "name": "docs_review",
   "async": true,
   "args": ["scope:path", "model:string"],
-  "defaults": {
-    "model": "openai-codex/gpt-5.5"
-  },
+  "defaults": {},
   "mailbox": {
     "accepts": ["control.stop"],
     "emits": ["review.completed", "run.failed"]
@@ -143,14 +136,14 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
 Expose a reusable actor recipe as a normal capability:
 
 ```text
-register_tool name=docs_review description="Start an async docs review actor" template="docs-review.json" args="scope:path,model:string=openai-codex/gpt-5.5"
+register_tool name=docs_review description="Start an async docs review actor" template="docs_review" args="scope:path,model:string"
 ```
 
 `Task` is the user's work item. `Template` is the execution graph. `Actor recipe` is saved JSON. `Run` is one actor instance with status, logs, messages, cancellation, artifacts, and ambient triangles.
 
 ## Compose Recipes With Imports
 
-Recipes can import other recipe files and reuse them as named nodes. This keeps reusable steps small while letting a parent recipe decide whether the combined graph runs foreground or as one async run.
+Recipes can import other recipe files and reuse them as named nodes. This keeps reusable steps small while letting a parent recipe decide whether the combined graph runs foreground or as one detached run actor.
 
 `review-one.json`:
 
@@ -158,7 +151,7 @@ Recipes can import other recipe files and reuse them as named nodes. This keeps
 {
   "name": "review-one",
   "args": ["scope:string", "model:string"],
-  "defaults": { "model": "openai-codex/gpt-5.5" },
+  "defaults": {},
   "template": "pi -p --model {model} --no-tools \"Review {scope}\""
 }
 ```
@@ -189,7 +182,7 @@ register_tool name=review_pair \
   template="review-pair.json"
 ```
 
-Imported recipes are recipe definitions, not nested async runs. The parent recipe's `async: true` creates one run with one state dir; imported recipes contribute command-template graph, args, defaults, and values.
+Imported recipes are recipe definitions, not nested run actors. The parent recipe's `async: true` creates one run actor with one state dir; imported recipes contribute command-template graph, args, defaults, and values.
 
 ## Register Actor-Control Tools
 
@@ -212,33 +205,32 @@ For reusable actor workflows, keep the large template and mailbox contract in a
 ```text
 register_tool name=docs_review \
   description="Start an async docs review actor" \
-  template="docs-review.json" \
-  args="scope:path,model:string=openai-codex/gpt-5.5"
+  template="docs_review" \
+  args="scope:path,model:string"
 ```
 
 If the recipe file contains `async: true`, calling `docs_review` starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
-A recipe can also be co-located in `actors-tools.json` when keeping metadata and the recipe body together is clearer:
+When keeping metadata and the recipe body together is clearer, `register_tool` writes a complete user recipe file:
 
 ```json
 {
-  "review_docs": {
-    "description": "Start an async docs review",
-    "name": "review-docs",
-    "async": true,
-    "template": "pi -p --model openai-codex/gpt-5.5 --tools read,bash \"Review {scope}\""
-  }
+  "description": "Start an async docs review",
+  "tool": true,
+  "async": true,
+  "args": ["scope:path", "model:string"],
+  "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
 }
 ```
 
-A co-located recipe entry still cannot define `tool`; it must own `template` directly.
+The filename is the recipe id/tool name, `async: true` selects detached run mode, and `template` remains the executable body.
 
 ### Sub-agent
 
 ```text
 register_tool name=call_subagent \
   description="Run pi as a non-interactive sub-agent" \
-  template="pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
+  template="pi -p --model {model} --no-tools {prompt}" args="prompt:string,model:string"
 ```
 
 Use `update=true` to overwrite an existing tool. Omit `template` during update to keep the previous template:
@@ -255,29 +247,28 @@ Delete a tool:
 register_tool name=call_subagent template=null
 ```
 
-## Resulting Config
+## Resulting Recipe Files
 
-The commands above persist entries like this in `~/.pi/agent/actors-tools.json`; tool names come from the top-level keys. Stored entries keep `template` last so flags and metadata are read before executable content:
+The commands above persist files under `~/.pi/agent/recipes/`. Tool names come from recipe filenames. Stored recipes keep `template` last so flags and metadata are read before executable content:
 
 ```json
 {
-  "transcribe": {
-    "description": "Transcribe a local audio file",
-    "template": "/path/to/stt --file {file} --lang {lang=ru}"
-  },
-  "call_subagent": {
-    "description": "Run pi as a non-interactive sub-agent",
-    "template": "pi -p --model {model=openai-codex/gpt-5.5} --no-tools {prompt}"
-  },
-  "docs_review": {
-    "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string=openai-codex/gpt-5.5"],
-    "template": "docs-review.json"
-  }
+  "description": "Transcribe a local audio file",
+  "tool": true,
+  "template": "/path/to/stt --file {file} --lang {lang=ru}"
+}
+```
+
+```json
+{
+  "description": "Run pi as a non-interactive sub-agent",
+  "tool": true,
+  "args": ["prompt:string", "model:string"],
+  "template": "pi -p --model {model} --no-tools {prompt}"
 }
 ```
 
-This file is the durable actor-tool registry. `register_tool` is the interactive API; `actors-tools.json` is the persisted state that is loaded on future sessions.
+The recipe directory is the durable actor-tool registry. `register_tool` is the interactive API; recipe files are the persisted state loaded on future sessions.
 
 ## Manage Actors
 
@@ -288,9 +279,10 @@ Start from an inline template as an addressable run actor:
 ```json
 {
   "as": "run:docs-review",
-  "template": "pi -p --model openai-codex/gpt-5.5 --no-tools {prompt}",
+  "template": "pi -p --model {model} --no-tools {prompt}",
   "values": {
-    "prompt": "Review docs/spec.md for contradictions."
+    "prompt": "Review docs/spec.md for contradictions.",
+    "model": "current-review-model"
   }
 }
 ```
@@ -313,7 +305,7 @@ Reusable local recipes live in `~/.pi/agent/recipes/*.json`; recipe tools honor
 
 Packaged standard recipes live under root `recipes/` with helper scripts under root `scripts/`. They are reusable library definitions, not automatically installed operator policy.
 
-The subagent component recipes start non-interactive pi subagents as async runs or compose component recipes into higher-level coordinator pipelines. Use the no-tools recipe for the safest default, the explicit-tool variant when a bounded tool allowlist is needed, or the prompts fanout parent recipe to see imported subagent recipe nodes composed into one async run:
+The subagent component recipes start non-interactive pi subagents as detached run actors or compose component recipes into higher-level coordinator pipelines. Use the no-tools recipe for the safest default, the explicit-tool variant when a bounded tool allowlist is needed, or the prompts fanout parent recipe to see imported subagent recipe nodes composed into one run actor:
 
 ```text
 register_tool name=subagent_prompt \
@@ -325,7 +317,7 @@ register_tool name=subagent_tools \
   template="subagent-tools.json"
 
 register_tool name=subagents_prompts \
-  description="Start parallel no-tools subagents from a prompt array as one async run" \
+  description="Start parallel no-tools subagents from a prompt array as one run actor" \
   template="subagents-prompts.json"
 
 subagent_prompt prompt="Review docs/async-runs.md for unclear wording." run_id=docs-review
@@ -336,7 +328,7 @@ subagents_prompts \
 inspect target=run:review-prompts view=tail
 ```
 
-The music player recipe starts a local file, URL, directory, or playlist as an async run, keeps the agent unblocked, shows the ambient triangle indicator in the launching coordinator, and can be controlled with addressed `message` calls. The standard library ships one Node.js wrapper recipe:
+The music player recipe starts a local file, URL, directory, or playlist as a run actor, keeps the agent unblocked, shows the ambient triangle indicator in the launching coordinator, and can be controlled with addressed `message` calls. The standard library ships one Node.js wrapper recipe:
 
 ```text
 register_tool name=music_player \
@@ -374,8 +366,8 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - `recover` runs a cleanup command template between failed retry attempts and stops retries if cleanup fails.
 - Commands execute directly without shell evaluation, but trusted executables still run with the same permissions as pi.
 - Obvious high-risk templates such as shells, interpreter eval modes, and broad filesystem mutation surface lightweight warnings without blocking existing tools.
-- `async: true` on a recipe selects detached run lifecycle; omitted or false async runs the recipe foreground through registered tools.
-- Layer boundaries stay explicit: command templates define synchronous execution graphs; template recipes add saved JSON metadata/import resolution and named `artifacts`; async runs add detached lifecycle, state, IPC, and observability.
+- `async: true` on a recipe selects detached run-actor lifecycle; omitted or false runs the recipe foreground through registered tools.
+- Layer boundaries stay explicit: command templates define synchronous execution graphs; template recipes add saved JSON metadata/import resolution and named `artifacts`; run actors add detached lifecycle, state, IPC, and observability.
 - `spawn`, `message`, and `inspect` are high-level actor adapters. `spawn` creates `run:<id>` actors from recipes or inline templates with optional state/artifact metadata, `message` sends one typed envelope to `run:<id>` mailboxes, `branch:<run>/<branch>` mailboxes, `tool:<name>` calls, or coordinator/session attention paths, and `inspect` intentionally reads `run:<id>` status/tail/messages/mailbox metadata, coordinator/session run status, or registered `tool:<name>` contracts while the broader actor/message protocol is refined.
 - `spawn`, `message`, and `inspect` are the public async coordination vocabulary. Low-level async actions map to this actor API: start belongs to `spawn`; send/control/stop/kill belongs to `message`; status/tail/messages/list belongs to `inspect`. Use `inspect view=messages` for actor-envelope streams. Use `control.stop`, `control.cancel`, and `control.kill` for run termination; runtime-prefixed control aliases are no longer part of the public surface.
 - Actor management returns compact text by default; pass `verbose: true` to `inspect` when full JSON state is needed.
@@ -384,7 +376,7 @@ See [`docs/recipe-library.md`](./docs/recipe-library.md) for install notes and r
 - Native Windows should use WSL or a recipe-specific transport for run-local message-controlled recipes; Linux uses stricter `/proc` runner ownership checks for stale PID protection.
 - Registered tools may set `template` to a recipe JSON path/name; calling them follows that recipe's `async` mode.
 - File-backed recipes may declare `imports` and embed imported recipes with `{ "name": "alias" }` nodes, or read `{alias.defaults.key}`, `{alias.defaults.key=fallback}`, and `{alias.values.key?yes:no}` references before command-template execution.
-- Interactive sessions show ambient async activity as stable `▷` triangles aggregated across runs started by the current agent session. Each running async run contributes at least one triangle; parallel active branches can contribute more. One `▶` wave moves over the active set; terminal `done`/`failed`/unhandled `killed`/`exited` messages are delivered as compact follow-up context only to the launching coordinator agent, while intentional `cancel`, `kill`, and `stop` actions stay silent because the action already reports synchronously. Failed commands and in-flight parallel branch completions can bubble through `command.done`; successful final leaf completions remain diagnostic to avoid sequential pipeline noise.
+- Interactive sessions show ambient actor activity as stable `▷` triangles aggregated across runs started by the current agent session. Each running run actor contributes at least one triangle; parallel active branches can contribute more. One `▶` wave moves over the active set; terminal `done`/`failed`/unhandled `killed`/`exited` messages are delivered as compact follow-up context only to the launching coordinator agent, while intentional `cancel`, `kill`, and `stop` actions stay silent because the action already reports synchronously. Failed commands and in-flight parallel branch completions can bubble through `command.done`; successful final leaf completions remain diagnostic to avoid sequential pipeline noise.
 - Use `{file}` as the canonical local file path arg.
 - Stored `script` entries are rejected with migration guidance.
 

package/docs/actor-messages.md

@@ -58,7 +58,7 @@ Field rules:
 - `type`: required semantic message type.
 - `summary`: short human-facing line for notifications/follow-ups.
 - `body`: string or JSON payload.
-- routing/delivery is inferred from `to`, actor ownership, and coordinator runtime policy; recipes should not expose delivery knobs. When a coordinator session is known, addressed run/branch/control messages fail closed before controlling or emitting from runs owned by another session.
+- Routing/delivery is inferred from `to`, actor ownership, and coordinator runtime policy; recipes should not expose delivery knobs. When a coordinator session is known, addressed run/branch/control messages fail closed before controlling or emitting from runs owned by another session.
 - `reply_to`: optional message id for conversational checkpoints.
 - `correlation_id`: optional task/run/workflow id.
 - `metadata`: optional structured routing or domain hints.

package/docs/async-runs.md

@@ -139,10 +139,10 @@ The actor-level surface is:
 
 Low-level async actions map into the actor surface instead of forming a second public model:
 
-- start → `spawn`
-- send/control → `message`
-- status/tail/messages/list → `inspect`
-- stop/kill → `message` with `control.stop` or `control.kill`, with synchronous results
+- Start → `spawn`
+- Send/control → `message`
+- Status/tail/messages/list → `inspect`
+- Stop/kill → `message` with `control.stop` or `control.kill`, with synchronous results
 
 Compact text is returned by default so async management does not flood agent context; use verbose inspection when the full state object is needed. List output intentionally shares one state root across music, subagents, timers, and other async work; source fields such as `tool` and `recipe` distinguish run purpose when the launcher recorded them. Registered tools are the preferred user-facing surface for reusable recipes.
 

package/docs/command-templates.md

@@ -79,13 +79,13 @@ Implementations may expand `~` in command position and may resolve relative comm
 
 Supported forms:
 
-| Form                | Meaning                                          |
-| ------------------- | ------------------------------------------------ |
-| `{name}`            | Required value from runtime values or `defaults` |
-| `{name=default}`    | Inline default when no value is provided         |
-| `{name??fallback}`  | Fallback when value is missing, null, or empty   |
-| `{name?yes:no}`     | Ternary string selected by truthiness of `name`  |
-| `{items[index]}`    | Array item selected by literal or repeat index   |
+| Form               | Meaning                                          |
+| ------------------ | ------------------------------------------------ |
+| `{name}`           | Required value from runtime values or `defaults` |
+| `{name=default}`   | Inline default when no value is provided         |
+| `{name??fallback}` | Fallback when value is missing, null, or empty   |
+| `{name?yes:no}`    | Ternary string selected by truthiness of `name`  |
+| `{items[index]}`   | Array item selected by literal or repeat index   |
 
 Resolution order is runtime values → `defaults` → inline default → error. Nullish coalescing and ternary conditions treat missing, empty, `false`, `0`, and `no` as false. Use `??` for value fallback and ternaries for small string selection such as optional CLI flags; larger policy branches should stay in recipes, scripts, or separate template nodes. Default values that are themselves a single placeholder, such as `{prompt}` resolving to `{prompts[index]}`, are resolved recursively with a small depth guard. A repeat node may set `repeat` to `{items.length}` when an array arg should determine fanout width.
 
@@ -248,12 +248,12 @@ Parallel nodes use the same object shape. Flags come first and `template` stays
       "parallel": true,
       "template": [
         {
-          "label": "gpt-5.5",
+          "label": "reviewer-a",
           "timeout": 300000,
           "template": "review-gpt {scope}"
         },
         {
-          "label": "deepseek-pro",
+          "label": "reviewer-b",
           "timeout": 300000,
           "template": "review-deepseek {scope}"
         },
@@ -272,9 +272,9 @@ Parallel nodes use the same object shape. Flags come first and `template` stays
 A degraded parallel join is still usable when at least one branch succeeds:
 
 ```text
---- branch: gpt-5.5 status: done ---
+--- branch: reviewer-a status: done ---
 review text
---- branch: deepseek-pro status: failed ---
+--- branch: reviewer-b status: failed ---
 exit: 1
 stderr: provider balance exhausted
 ```

package/docs/recipe-library.md

@@ -46,7 +46,7 @@ Core subagent recipes:
 - `recipes/subagent-followup.json`: Same-context or degraded continuation.
 - `recipes/subagent-judge.json`: Post-merge/report quality judge.
 
-Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. The generic prompt launchers, including `subagent-tools` and `subagents-prompts`, expose the same core model/thinking/tool/output knobs so callers do not need separate recipe families for policy tuning. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
+Most atoms expose policy knobs such as `model`, `thinking`, `tools`, `output_format`, `evidence_policy`, `risk_policy`, source policy, continuity policy, handoff format, or model pools. Packaged recipes intentionally do not ship concrete model-version defaults: callers must pass current model policy at launch, which keeps reusable recipe components from aging around old provider aliases. The generic prompt launchers, including `subagent-tools` and `subagents-prompts`, expose the same core model/thinking/tool/output knobs so callers do not need separate recipe families for policy tuning. Interactive async atoms also declare mailbox metadata for their basic control, completion, and domain-result message surface. Higher-level recipes pass these knobs through instead of hard-coding local policy.
 
 Register one atom:
 
@@ -68,8 +68,10 @@ inspect target=run:docs-review view=tail
 
 Pipeline recipes demonstrate second-order composition:
 
+- `recipes/coordinator-locker.json`: Long-lived coordinator cell with queue, acquire/renew/release lease locks, journal, and actor messages for worker coordination.
 - `recipes/subagent-review-coordinator.json`: Lens reviewers → verifier → merger → judge → normalizer.
-- `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → package summary → validation → release review → artifact report.
+- `recipes/pipeline-release-readiness.json`: Task-first release cell: changelog section → package summary → packaged skill summary → validation → release review → artifact report.
+- `recipes/pipeline-release-summary.json`: Evidence-only release summary cell: changelog section → package summary → packaged skill summary → validation → release summary / risks / PR body draft artifact. It does not commit, open a PR, merge, tag, publish, or perform external release side effects.
 - `recipes/pipeline-repo-health.json`: Task-first repository-health cell: git status/log → docs index → validation → normalized artifact report.
 - `recipes/pipeline-async-run-ops.json`: Task-first async-run operations cell: run summary → actor-message tail → normalized operations report → artifact report.
 - `recipes/pipeline-review-readiness.json`: Release/readiness gate over selected lenses.
@@ -96,16 +98,18 @@ Utility recipes cover local operator workflows that do not need subagents:
 - `recipes/utility-git-status.json`: Read concise branch/worktree state for a repo.
 - `recipes/utility-git-log.json`: Read recent decorated commit history for a repo.
 - `recipes/utility-run-state-files.json`: List run-state files such as `run.json` under an async run state root.
+- `recipes/utility-coordinator-lock-snapshot.json`: Summarize a coordinator-locker actor state directory with queue depth, locks, and recent journal entries.
 - `recipes/utility-changelog-head.json`: Read the top slice of a changelog for release summary prep.
 - `recipes/utility-playlist-scan.json`: List local media files as playlist-building input.
 - `recipes/utility-run-summary.json`: Use `scripts/recipe-utils.mjs` to summarize async run state files as JSON.
-- `recipes/utility-run-ops-snapshot.json`: Combine async run summaries, actor-message JSONL tails, and stale/terminal recommendations into one structured operations snapshot.
+- `recipes/utility-run-ops-snapshot.json`: Combine async run summaries, recent actor messages for a selected `run_id`, and stale/terminal recommendations into one structured operations snapshot.
 - `recipes/utility-playlist-build.json`: Use `scripts/recipe-utils.mjs` to build a filtered playlist listing as newline paths, M3U, or inline `|`-separated source.
 - `recipes/utility-changelog-section.json`: Use `scripts/recipe-utils.mjs` to extract one changelog release section.
 - `recipes/utility-artifact-manifest.json`: Use `scripts/recipe-utils.mjs` to emit a machine-readable JSON manifest for an artifact path.
 - `recipes/utility-artifact-write.json`: Deterministically write prepared artifact content from stdin to `artifact_path` with explicit `create`, `overwrite`, or `append` mode.
 - `recipes/utility-actor-message.json`: Deterministically wrap stdin as a validated addressed actor-message envelope with the same public names as the envelope: `to`, `from`, `type`, `summary`, `body`, optional `correlation_id`/`reply_to`, and `metadata`.
 - `recipes/utility-package-summary.json`: Use `scripts/recipe-utils.mjs` to emit bounded package metadata such as name, version, files, scripts, and dependency counts.
+- `recipes/utility-skill-summary.json`: Use `scripts/recipe-utils.mjs` to summarize packaged skill frontmatter, body shape, formatter-safe scalar lines, and package-version alignment.
 - `recipes/utility-validate-recipe.json`: Use `scripts/validate-recipe.mjs` to validate one template recipe file, or all packaged recipes in a directory with `all: true`.
 
 These recipes are intentionally small. Register them only for trusted local commands and prefer narrow scopes. The helper-backed utilities share `scripts/recipe-utils.mjs` so repeated parsing/listing logic stays out of recipe strings.