@llblab/pi-actors 0.46.0 → 0.47.0

package/dist/skills/actors/SKILL.md

@@ -1,104 +1,115 @@
 ---
 name: actors
-description: Required practical guide for non-trivial pi-actors use and Run-kernel work. Read before using or changing spawn, message, inspect, Runs, tools, Recipes, command templates, Control, Trace, artifacts, or lifecycle mechanics.
+description: Use for any non-trivial pi-actors operation, diagnosis, or development involving Recipes, persistent tools, Runs, spawn, message, inspect, Trace, Control, capability specialization, or activation.
 ---
 
-# Actors (pi-actors)
+# Actors
 
-`pi-actors` treats any runnable local capability—a script, tool, service, pipeline, or subagent—as an actor. A Recipe is its reusable executable definition; a Run is one concrete actor instance:
+## Choose the operation
+
+Start from the intended outcome:
 
 ```text
-Recipe --spawn--> Run
-Run = Recipe + Trace + Control
-```
+Run a maintained capability once
+→ use spawn recipe=<skill>/<recipe>
 
-Use the swarm skill separately for decomposition, quorum design, reviewer lenses, and consensus methodology.
+Make a maintained capability a persistent agent-callable tool
+→ use register_tool from=<skill>/<recipe>
 
-## Public Verbs
+Keep the same capability but narrow caller defaults
+→ use register_tool from=<skill>/<recipe> defaults={...}
 
-- `spawn`: create one Run from a Recipe or inline command template.
-- `message`: send one actor-local Control to `run:<id>`, or the reserved review actions to `runtime`.
-- `inspect`: inspect `run:<id>`, `runtime`, `recipes`, or `tool:<name>`.
-- `register_tool`: persist a trusted capability; it does not address a running actor.
+Register a trusted command directly
+→ use register_tool template="..."
 
-A Run target exposes exactly three inspect views: `recipe`, `trace`, and `control`.
+Build a reusable multi-node execution graph
+→ author a Recipe with named imports
 
-## Recipe
+Run a long-lived controlled process
+→ spawn its async Recipe, then use message and inspect
 
-A Recipe defines execution. It may declare named typed args, inline fallbacks, configuration `defaults`, composition `values`, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
+Coordinate several independent actors or subagents
+→ also read the swarm Skill
 
-Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
+Choose capability-specific behavior
+→ read the owning capability Skill
 
-Prefer maintained Skill-owned Recipes over ad hoc wrappers. Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`; Recipe files have no top-level `name`. `SKILL.md` `name` is Pi host metadata matching its directory, not an additional pi-actors identity field. Use `<skill>/<recipe>` for an exact direct component or an explicit `.json` / `.md` path. Entry paths resolve from invocation `cwd`; relative imports resolve from the importing Recipe directory. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Diagnose resolution, registration, or activation
+→ use Inspect status/doctor flows and stop on contradictory evidence
+```
+
+Use [persistent tools](./references/persistent-tools.md), [Recipes](./references/recipes.md), [Runs](./references/runs.md), or [diagnostics](./references/diagnostics.md) only when the selected operation needs that detail.
 
-## Trace
+## Core distinctions
 
-Trace records bounded structured observations in `trace.jsonl`:
+Keep these boundaries explicit:
 
-```json
-{
-  "id": "…",
-  "ts": "…",
-  "kind": "progress.update",
-  "summary": "…",
-  "data": {},
-  "level": "info",
-  "attention": "notify"
-}
+```text
+Skill Recipe ≠ registered tool
+spawn ≠ registered-tool invocation
+persisted ≠ callable
+direct delegation ≠ named import composition
+Run Control ≠ actor chat
 ```
 
-Trace never carries sender, recipient, route, reply, or message-envelope fields. It is a bounded retained suffix: the canonical lock appends within 2,048 events and 4 MiB or atomically keeps the newest suffix plus one warning-only `runtime.trace_compacted` marker. That marker means older history was discarded; terminal/result/execution/artifact evidence stays independently authoritative. `inspect view=trace` reports completeness. Equal timestamps use same-source physical order, fixed source rank, then stable id without exposing an ordinal or claiming cross-source causality. Attention is a wake hint, not a queue: persist durable state or an artifact first, use `notify` for visible status, and reserve `followup` for needed coordinator context. Compaction may discard old hints.
+A Skill Recipe is a maintained component addressed by `<skill>/<recipe>`. `spawn` creates a Run from a Recipe. `register_tool` creates or updates a persistent user tool. A tool is callable in the current session only when activation evidence says `callable_now: true`.
 
-## Control
+`actors` owns generic Recipe/tool/Run mechanics. The owning capability Skill owns capability-specific selection and constraints. `swarm` owns multi-actor decomposition and integration methodology.
 
-The public Control request is exact:
+## Persistent capability workflow
 
-```json
-{ "target": "run:<id>", "action": "pause", "input": {}, "verbose": false }
+To make `media/player` callable as `music_player` with a default source:
+
+```text
+register_tool
+  name=music_player
+  from=media/player
+  defaults={"source":"~/Music/1MIX"}
 ```
 
-Valid Controls persist in `controls.jsonl` before delivery; invalid envelopes remain outside it. One token-owned lock rejects a 65th pending Control or 1 MiB rewrite before admission, fails closed on malformed or stale-generation evidence, and atomically admits one queued record. Exact-id claims/finalization preserve a 128-terminal tail, expected-state fencing, and 4 KiB errors. Admitted nonterminal Controls never expire automatically. `inspect view=control` reports capacity, saturation, stale work, bytes, and diagnostics. Endpoints carry immutable startup `run_instance_id`; FIFO and named pipe share limits of 64 action characters, 380 serialized input bytes, and 512 newline-terminated wire bytes. Partial writes fail. Put larger data in an artifact and send only its reference. Delivery revalidates owner, generation, state, and process identity.
+Then:
 
-`kill` remains the runtime recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and adds no synthetic Control. Use actor-local `stop` only when declared and implemented. Restart clears generation-local evidence; archive preserves the bounded terminal tree, while prune preserves only requested artifacts.
+1. Require registration to report successful resolution, validation, persistence, registry admission, host registration, activation, and `callable_now: true`.
+2. Call the actual `music_player` tool. Do not call `spawn` and describe that as tool invocation.
+3. Verify agent-facing evidence reports `launch_kind: "tool"`; use `inspect target=tool:music_player view=status` when usage or activation needs confirmation.
+4. If callability is false, stop at the reported activation boundary. Preserve the logical source and diagnose it; do not substitute a Recipe spawn as proof.
 
-## Run State and Safety
+Use direct delegation for the same maintained capability under a persistent name or narrower defaults. Use named imports only when one Recipe graph contains reusable child nodes. See [persistent tools](./references/persistent-tools.md) and [Recipes](./references/recipes.md).
 
-Run state lives under `~/.pi/agent/tmp/pi-actors/runs/<run>/`. Important evidence includes:
+## Run workflow
 
-- `run.json`: captured Run identity, Recipe, owner, generation, process identity, and policy.
-- `trace.jsonl`: structured observations.
-- `controls.jsonl`: durable actor-local inputs and outcomes.
-- `control-endpoint.json`: generation-fenced service readiness.
-- `execution.json`: command/session provenance and bounded complete-capture references.
-- `result.json`, logs, and declared artifacts.
+A Run is one concrete execution of a Recipe:
 
-Trace/Control quotas do not constrain user-declared artifacts, repositories, media sources, complete captures, or actor-owned workload state. No public noun, tool, target, or view is added by bounded retention.
+```text
+Recipe --spawn--> Run
+Run = Recipe + Trace + Control
+```
 
-Never bypass owner filtering, immutable generation fencing, process-identity verification, path containment, redaction, terminal reconciliation, or shutdown kill behavior. Do not edit active Run state to force a result.
+1. Spawn with the exact logical Recipe identity and caller-owned values.
+2. Retain the returned `run:<id>` and normally wait for terminal follow-up instead of polling.
+3. Inspect `view=trace` when retained observations or attention matter.
+4. Inspect `view=control` before diagnosing service readiness, stale work, or saturation.
+5. Send `message` only for an action declared and consumed by that controlled Recipe.
+6. Use terminal state, result, declared artifacts, and execution evidence to prove completion.
 
-## Operating Pattern
+A Run exposes only `recipe`, `trace`, and `control` views. Control is bounded actor-local input, not peer messaging or chat. See [Runs](./references/runs.md).
 
-1. Inspect the Recipe before launch when its contract or policy matters.
-2. Spawn with explicit values and retain the returned `run:<id>`.
-3. Let short Runs finish; avoid polling.
-4. Inspect Trace when evidence or attention requires it; its summary states whether retained history is complete.
-5. Inspect Control capacity before diagnosing stale work or saturation, then send only declared actor-local Controls.
-6. Use runtime kill/cancel behavior for lifecycle termination.
-7. Inspect artifacts and execution evidence for final validation.
+## Diagnosis and stop rules
 
-If work may outlive the current turn, needs steering, produces artifacts, fans out, or must remain inspectable, use a Run rather than shell backgrounding.
+When a pi-actors operation fails:
 
-## Top Recipes
+1. Keep the intended logical Recipe or tool identity.
+2. Inspect the existing `recipes`, `tool:<name>`, `runtime`, or `run:<id>` surface that owns the failure.
+3. Report resolver, registry, activation, Run, Trace, or Control truth exactly.
+4. Retry only after the owning state is healthy.
 
-- [Repository health](../project-work/recipes/repo-health.json)
-- [Quorum review](../swarm/recipes/quorum-review.json)
-- [Artifact bundle](../artifacts/recipes/bundle.json)
-- [Music player service](../media/recipes/player.json)
-- [Resource locker service](./recipes/resource-locker.json)
+Stop if spawn and registry resolve the same Recipe differently. Stop if registration persists but is not callable. Stop if an operation cannot be proven through pi-actors surfaces.
 
-## Deep References
+Never recover by copying maintained Recipe args, defaults, Control, artifacts, or helper commands. Never hard-code a `{skill_dir}` replacement path. Never introduce `bash -lc`, `eval`, direct bundled-helper execution, or shell backgrounding to bypass resolution. Never call `spawn` and claim a tool call. Use [diagnostics](./references/diagnostics.md) for the safe next action.
 
-- [Recipe library](../../docs/recipe-library.md)
-- [Async Runs](../../docs/async-runs.md)
+## When to read another Skill
 
-Read repository source and tests for exact contracts when changing pi-actors itself. Update this skill whenever durable Run mechanics change.
+- Read the owning capability Skill when choosing or operating that capability pack.
+- Read `swarm` in addition to `actors` for multiple actors/subagents, parallel scopes, reviewer lenses, quorum, conflict handling, or integration.
+- For generic mechanics, this Skill outranks capability Skills and `swarm`. Report a stale Skill if it contradicts Recipe identity, registration, activation, spawn, Inspect, Trace, or Control semantics here.
+- When changing the extension implementation itself, apply project implementation instructions after this operating protocol.

package/dist/skills/actors/references/diagnostics.md

@@ -0,0 +1,44 @@
+# Diagnostics
+
+Preserve the intended logical identity and diagnose through public pi-actors surfaces. Do not inspect raw registry files or implementation source as the normal first response.
+
+## Recipe resolution or catalog failure
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=doctor identity=<skill>/<recipe>
+```
+
+Use the focused doctor form for one intended identity. It reports active-Skill ownership, exact resolvability, partial-catalog state, component status, portable source location, resolution generation, any rejection, and bounded next actions. Use the unfiltered doctor only for catalog-wide diagnosis. A partial catalog does not imply every exact component is unavailable. If the owning Skill is inactive, report that blocker rather than locating and running its helper manually.
+
+## Persistent tool failure
+
+```text
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+```
+
+Distinguish persistence, registry admission, host registration, active-tool membership, and `callable_now`. Confirm the source identity, effective caller schema, separate tool/spawn usage, and last launch kind when exposed.
+
+If persistence succeeded but callability is false, do not use `spawn` and claim the tool worked. Follow the reported activation boundary or stop.
+
+## Run failure
+
+```text
+inspect target=run:<id> view=recipe
+inspect target=run:<id> view=trace
+inspect target=run:<id> view=control
+inspect target=runtime view=status
+```
+
+Use Recipe view for captured identity/launch evidence, Trace for bounded observations, Control for readiness/capacity/stale work, and runtime status for kernel-level health. Treat retained-history completeness honestly.
+
+## Safe failure protocol
+
+1. Keep the exact intended Recipe/tool/Run identity.
+2. Identify the owning public surface.
+3. Record exact resolver, registry, activation, or Run truth.
+4. Apply only the bounded next action returned by that owner.
+5. Retry only after the owning state is healthy.
+
+Stop if evidence remains contradictory or the requested operation cannot be proven. Never recover by copying maintained contracts, hard-coding installation paths, directly executing bundled helpers, adding `bash -lc` or `eval`, shell-backgrounding work, editing unrelated Skills, or relabeling a Recipe spawn as a tool call.

package/dist/skills/actors/references/persistent-tools.md

@@ -0,0 +1,74 @@
+# Persistent Tools
+
+Use a persistent tool when the agent should call a trusted capability by name across turns or sessions. Use `spawn` instead for one-off Recipe execution.
+
+## Choose one source mode
+
+```text
+Maintained or explicit-file Recipe
+→ register_tool from=<skill>/<recipe|path.json|path.md>
+
+Trusted command template
+→ register_tool template="..."
+
+Reviewed captured draft
+→ register_tool draft=<draft-path>
+```
+
+Do not mix source modes.
+
+## Specialize a maintained Recipe
+
+```text
+register_tool
+  name=music_player
+  from=media/player
+  defaults={"source":"~/Music/1MIX"}
+```
+
+`from` means logical direct delegation. The source remains authoritative for async behavior, caller args and types, source defaults, artifacts, Control, and runtime-owned origins. The persistent user Recipe stores only the compact specialization; do not copy inherited fields.
+
+Use `description` to narrow agent-facing intent when useful. Every supplied default must name a caller-owned source arg and satisfy its type or enum. Never default runtime-owned origins.
+
+## Prove registration
+
+Read registration as a state transition, not one success word:
+
+```text
+resolved
+→ validated
+→ persisted
+→ registry_active
+→ host_registered
+→ active_tool
+→ callable_now
+```
+
+When `callable_now` is true, call the actual generated tool and verify `launch_kind: "tool"` when provenance matters. When false, stop at the reported activation boundary and use tool/Recipe diagnosis. A Recipe spawn is not an activation test or tool invocation substitute.
+
+Use:
+
+```text
+inspect target=tool:<name> view=status
+inspect target=tool:<name> view=schema
+inspect target=recipes view=doctor
+```
+
+## Command templates
+
+Use `template` only for a trusted command definition, not to make the agent guess whether a string is command text or Recipe delegation. Give raw command tools an agent-facing description and declare or infer only caller-owned args. Use a Recipe file when reusable composition or lifecycle policy is needed.
+
+## Updates and deletion
+
+Use `update=true` only for an intentional replacement. Preserve the existing capability when candidate resolution, validation, persistence, or activation fails. Use the compact deletion form documented by the live `register_tool` schema; do not create a second deletion mechanism.
+
+## Stop rules
+
+Stop rather than:
+
+- copying source Recipe args, defaults, artifacts, Control, or helper command;
+- invoking a Skill helper by installation path;
+- using `spawn` and claiming the tool was called;
+- treating persistence as callability;
+- adding shell evaluation or backgrounding to bypass registration;
+- editing an unrelated rejected Skill component unless that repair is explicitly requested.

package/dist/skills/actors/references/recipes.md

@@ -0,0 +1,51 @@
+# Recipes
+
+A Recipe is a reusable executable definition. Address a maintained component as `<active-skill>/<direct-filename-stem>` or use an explicit `.json` / `.md` path. Recipe files do not declare their own top-level `name`.
+
+## Direct delegation
+
+Use direct delegation when the root remains fundamentally the same capability under a different persistent name, description, or caller default:
+
+```text
+media/player
+→ music_player with a default source
+```
+
+For agent-facing persistent specialization, use:
+
+```text
+register_tool from=media/player defaults={"source":"~/Music/1MIX"}
+```
+
+The delegated root inherits async behavior, args and types, defaults, artifacts, Control, and runtime-owned origins. Do not copy those fields into the wrapper.
+
+## Named import composition
+
+Use imports when authoring a graph with reusable named nodes:
+
+```json
+{
+  "imports": {
+    "review": "swarm/quorum-review",
+    "report": "artifacts/report"
+  },
+  "template": [
+    { "name": "review" },
+    { "name": "report" }
+  ]
+}
+```
+
+Imports are local definitions inside one execution graph. An imported child does not automatically make its Control contract the root Run's Control contract. Do not use imports merely to wrap one Recipe with defaults.
+
+## Caller and runtime ownership
+
+Callers provide only the effective public args. The runtime owns Recipe/Skill location, Run state, Trace, generation, owner/session, and related execution origins. Never declare, default, or override runtime-owned inputs.
+
+Keep selected model, thinking, mission, concurrency, quorum, and timeout caller-owned unless the capability Skill documents stable policy.
+
+## Resolution behavior
+
+Exact resolution uses the current immutable session Skill context. An invalid unrelated component may make catalog inventory partial, but it must not block an unrelated exact valid identity. A disabled, missing, ambiguous, or changed target fails closed without ambient fallback.
+
+If direct spawn and persistent admission disagree for the same identity, stop and diagnose. Do not switch to an absolute helper path, copy the source contract, or execute the helper directly.

package/dist/skills/actors/references/runs.md

@@ -0,0 +1,39 @@
+# Runs
+
+Use a Run when execution may outlive the current turn, needs declared Control, produces retained artifacts/evidence, fans out, or must remain inspectable.
+
+## Launch
+
+```text
+spawn recipe=<skill>/<recipe> values={...} as=run:<id>
+```
+
+Use the owning capability Skill to choose the Recipe and capability-specific values. Retain the returned Run id. A spawn result reports `launch_kind: "spawn"`; it is never evidence of registered-tool invocation.
+
+## Observe
+
+Normally wait for terminal follow-up. Inspect only when requested, when meaningful attention arrives, or when the Run is overdue or blocked:
+
+```text
+inspect target=run:<id> view=recipe
+inspect target=run:<id> view=trace
+inspect target=run:<id> view=control
+```
+
+Trace is bounded retained observation, so read its completeness summary. Prove final outcomes with terminal status, result, declared artifacts, and execution evidence rather than assuming retained Trace is exhaustive.
+
+## Control
+
+Send an actor-local action only when the root Recipe declares and implements it:
+
+```text
+message target=run:<id> action=<declared-action> input={...}
+```
+
+Inspect Control when readiness, capacity, stale work, or saturation matters. Put large data in an artifact and send only a bounded reference or instruction. Use runtime-owned termination for a stuck Run rather than inventing undeclared service actions.
+
+Control is not actor chat, peer routing, or a task inbox. A Recipe import does not create a peer actor. Several actors/subagents require the `swarm` methodology in addition to these Run mechanics.
+
+## Safety
+
+Operate only on owned Runs and their active generation. Never edit Run state to force an outcome, bypass process identity checks, or signal processes directly from UI/instruction code. Restart creates new generation-local evidence; inspect the exact generation before destructive lifecycle action.

package/dist/skills/artifacts/SKILL.md

@@ -1,16 +1,33 @@
 ---
 name: artifacts
-description: Deterministic artifact writing, reporting, manifests, and bundles for reusable actor workflows.
+description: Use when an actor workflow must write reusable files, reports, manifests, or bundles with deterministic paths and declared outputs.
 ---
 
 # Artifacts
 
-Own reusable capabilities that turn bounded input or prior command output into declared files, reports, manifests, and artifact bundles.
+Use this Skill after the desired durable-output outcome is known. For generic Recipe execution, Runs, persistence, or diagnosis, follow `actors`; this Skill only selects artifact behavior.
 
-## Scope
+## Choose the outcome
 
-- Write or assemble caller-declared artifacts with explicit paths and overwrite policy.
-- Produce bounded human-readable reports and machine-readable manifests.
-- Compose validation evidence into artifact outputs without owning the validation policy.
+| Desired outcome | Recipe | Result |
+| --- | --- | --- |
+| Write one generated artifact and a machine-readable manifest, with optional validation first | `artifacts/bundle` | Primary artifact plus manifest |
+| Generate bounded normalized report content without committing a filesystem write | `artifacts/report` | Report content for review or later composition |
+| Generate and write one artifact | `artifacts/write` | Declared artifact path written with explicit mode |
+| Describe one existing or intended artifact | `artifacts/manifest` | Manifest JSON on stdout; no write |
+| Write prior pipeline output exactly | `artifacts/file-write` | Supporting stdin-to-file write; normally use inside composition |
 
-This Skill does not own repository workflow, multi-agent review methodology, Run lifecycle, retention policy, or transport delivery. Its Recipe identity is `artifacts/<filename stem>`; Recipe files have no top-level `name`. Cross-capability composition uses exact `<skill>/<recipe>` references; helper-backed Recipes use only this Skill's `scripts/` through `{skill_dir}`.
+Prefer `bundle` when both durable content and inventory evidence are required. Prefer `write` for one accepted file. Use `report` while content still needs review. Do not use `file-write` as a content generator. If one selected outcome should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its graph.
+
+## Inputs and boundaries
+
+- Keep `input` bounded and evidence-based; choose the current model explicitly where the Recipe requires `model`.
+- Supply caller-owned `artifact_path` and, for `bundle`, a distinct `manifest_path`.
+- `write_mode=create` is the safe default and stops if the target exists. Use `overwrite` or `append` only when the requested mutation is explicit.
+- Parent directories are created by the writer. `~` is resolved for artifact paths.
+- `manifest` reports existence, size, and modification evidence; it does not validate artifact meaning.
+- Validation in `bundle` runs only when `run_validation=true` and uses the caller-supplied trusted command and scope.
+
+## Stop rules
+
+Stop rather than guessing when the target path, overwrite policy, accepted content, model, or validation command is unclear. Do not claim a durable artifact from `report` or `manifest` alone. After a Run starts, use the `actors` evidence and lifecycle protocol; this Skill does not redefine it.

package/dist/skills/media/SKILL.md

@@ -1,16 +1,44 @@
 ---
 name: media
-description: Local media discovery, playlist construction, and controllable playback capabilities.
+description: Use for local media discovery, filtering, library summaries, playlist construction, or controllable playback.
 ---
 
 # Media
 
-Own reusable local media workflows and services.
+Use this Skill for caller-selected local media. For generic Recipe execution, persistent-tool setup, Run lifecycle, or diagnosis, follow `actors`; this Skill only selects media behavior.
 
-## Scope
+## Choose the operation
 
-- Scan caller-selected media sources and build bounded playlists.
-- Run controllable playback when the local player implements declared actions.
-- Emit canonical Trace and consume canonical Control without inventing media-specific runtime nouns.
+| Intent | Recipe | Use when |
+| --- | --- | --- |
+| Start or control playback | `media/player` | A local file, directory, or playlist should become a controlled service |
+| Build a library summary | `media/library` | A filtered playlist should feed bounded report content |
+| Build a filtered playlist | `media/playlist-build` | Extension filtering and `paths`, `m3u`, or `inline` output are required |
+| Scan a directory for raw file paths | `media/playlist-scan` | A shallow unfiltered inventory is intentionally sufficient |
 
-This Skill does not own the Run kernel, user media, transport delivery, or general artifact policy. Its Recipe identity is `media/<filename stem>`; Recipe files have no top-level `name`. Helper-backed Recipes locate only co-located scripts through `{skill_dir}`, and cross-capability composition uses exact `<skill>/<recipe>` references.
+Use `playlist-build` rather than `playlist-scan` for normal media selection. `library` composes playlist output into report content; its `artifact_path` identifies the intended report target but does not by itself prove a durable write.
+
+## Controlled playback
+
+`media/player` is an async controlled service. Start one owned Run, then use only its declared actions: `play`, `pause`, `resume`, `toggle`, `next`, `previous`, `stop`, and `status`.
+
+```text
+spawn recipe=media/player as=run:music values={"source":"~/Music","player":"auto"}
+message target=run:music action=pause
+inspect target=run:music view=control
+```
+
+For recurring playback as a persistent callable tool, use the persistent-capability workflow in `actors` with `from=media/player`; do not copy the player contract.
+
+## Paths and selection
+
+- `source` for playback must name caller-approved local media; do not broaden it to unrelated directories.
+- `source_dir` must be an intended readable directory. `~` is accepted by maintained media helpers.
+- Keep `max_depth` bounded. Use explicit comma-separated extensions for `playlist-build` and `library`.
+- Choose `output_mode=m3u` only when playlist text is wanted; it does not create a playlist file.
+- Choose an explicit `artifact_path` and model for `library` report generation.
+- `player=auto` selects an available supported backend; do not install or substitute a player silently.
+
+## Stop rules
+
+Stop if the source is missing, unreadable, contains no selected media, or no supported player is available. Do not claim playback from process start alone; confirm through Run evidence or `status`. Prefer the declared `stop` action for a responsive player. If the service is unresponsive, return to `actors` for bounded Run recovery rather than shell process control.

package/dist/skills/project-work/SKILL.md

@@ -1,16 +1,37 @@
 ---
 name: project-work
-description: Repository inspection, documentation maintenance, release preparation, and project health workflows.
+description: Use for repository health inspection, project summaries, documentation maintenance, release-readiness evidence, or bounded run-operation reports.
 ---
 
 # Project Work
 
-Own reusable workflows for inspecting and maintaining software projects.
+Use this Skill to produce bounded project evidence and plans. For generic Recipe execution, Run lifecycle, persistence, or multi-actor methodology, follow `actors` and, when applicable, `swarm`; this Skill only selects project workflows.
 
-## Scope
+## Choose the primary workflow
 
-- Summarize Git, package, Skill, changelog, and documentation state.
-- Compose repository health, documentation maintenance, and release-readiness evidence.
-- Keep project-level orchestration separate from lower-level artifact and actor utilities.
+| Intended result | Recipe | Boundary |
+| --- | --- | --- |
+| Repository status, recent history, docs surface, validation, and risks | `project-work/repo-health` | Runs the caller-supplied trusted validation command |
+| Documentation consistency review and maintenance plan | `project-work/docs-maintenance` | Evidence and plan only; does not edit documentation |
+| Multi-lens release verdict with blockers and degraded-confidence evidence | `project-work/release-readiness` | Readiness only; does not publish |
+| Evidence-only release summary and PR-body draft | `project-work/release-summary` | No commit, PR, merge, tag, publish, or external release action |
+| Bounded report over existing actor Run state | `project-work/run-ops` | Read-only report; does not send Control or mutate Runs |
 
-This Skill does not own the Run kernel, publication authority, multi-agent methodology, or artifact-writing mechanics. Its Recipe identity is `project-work/<filename stem>`; Recipe files have no top-level `name`. It composes other capabilities only through exact `<skill>/<recipe>` references and keeps project-specific helper behavior under its own `scripts/` directory.
+Choose `release-readiness` when independent review and a release verdict are needed. Choose `release-summary` when the evidence is already sufficient and only a concise operator-gated summary is wanted. If one primary workflow should become a recurring named tool, use the persistent-capability workflow in `actors`; do not copy its composition.
+
+## Inputs and evidence
+
+- Scope every workflow to the caller-selected repository, docs directory, or Run state.
+- Treat `validation_command` as trusted executable input. Do not invent or broaden it.
+- Select current model policy explicitly for workflows that request a model; release-readiness reviewer roles inherit only the values supplied by the caller.
+- Artifact paths identify intended report targets. Confirm actual declared artifact evidence before claiming a durable file.
+- Preserve degraded or insufficient review status. Never turn partial reviewer output into consensus.
+- Release outputs are evidence, not publication authority.
+
+## Supporting Recipes
+
+`git-status`, `git-log`, `changelog-head`, `changelog-section`, `markdown-index`, `package-summary`, and `skill-summary` support the primary workflows. Use one directly only when its narrow deterministic output is the requested result; otherwise start from a primary workflow and avoid rebuilding its composition manually.
+
+## Stop rules
+
+Stop when repository scope, version, validation command, model policy, or write target is ambiguous. Do not edit docs from a `docs-maintenance` plan, publish from release evidence, or send Run Controls from `run-ops`. Hand those operations to their owning protocol after explicit authorization.

package/dist/skills/recipe-memory/SKILL.md

@@ -1,16 +1,36 @@
 ---
 name: recipe-memory
-description: Package-owned structural review components for safe persistent Recipe capability memory.
+description: Use only for internal automatic Recipe-memory review, diagnosis, or recovery; do not use for normal Recipe creation, registration, or invocation.
 ---
 
 # Recipe Memory
 
-Own the executable reviewer components used by automatic draft and active-tool Recipe evolution.
+Use this Skill only when automatic draft-memory or active-tool review needs diagnosis or bounded recovery. Normal agents must not spawn, register, specialize, or invoke `recipe-memory/draft-review` or `recipe-memory/tool-review`; they are package-owned internal reviewer components.
 
-## Scope
+## Diagnose first
 
-- Review value-free structural projections rather than executable content or machine-local paths.
-- Return bounded decisions for deterministic package-owned executors.
-- Remain package-owned so user Recipes cannot shadow or redirect automatic review.
+```text
+inspect target=recipes view=reviews
+inspect target=runtime view=triage
+```
 
-This Skill does not own registry mutation, CAS, journaling, quarantine, lineage, retry, reset, or safe-boundary activation. Those remain Run-kernel and registry responsibilities. Its direct Recipe identities are `recipe-memory/<filename stem>`; Recipe files have no top-level `name`. They are internal components, never automatic user tools.
+Use the review view to distinguish `draft` and `tool` scope, current phase, failed stage, bounded error, preserved transaction evidence, and the recorded next action. Use runtime triage only when the reviewer Run itself needs Run-level diagnosis. Follow `actors` for generic Inspect, Run, and Control semantics.
+
+## Recovery Controls
+
+Use runtime Controls only when the review evidence names the matching recovery action:
+
+```text
+message target=runtime action=review.retry input={"scope":"draft"}
+message target=runtime action=review.retry input={"scope":"tool"}
+message target=runtime action=review.reset input={"scope":"draft"}
+message target=runtime action=review.reset input={"scope":"tool"}
+```
+
+- `review.retry` resumes the selected failed review scope while preserving authenticated transaction recovery.
+- `review.reset` clears disposable failure state only. It must reject evidence that requires roll-forward recovery.
+- Re-inspect `view=reviews` after one recovery Control; do not loop retries or resets without changed evidence.
+
+## Stop rules
+
+Stop when the phase is healthy or idle, the requested scope does not match the failure, recovery evidence requires deterministic roll-forward, or the reported next action is not retry/reset. Never edit review state, lineage, journals, quarantine, drafts, or persisted Recipes directly. Never bypass automatic review by running its internal Recipes as ordinary capabilities.