@llblab/pi-kit 0.1.5 → 0.1.7

package/node_modules/@llblab/pi-actors/docs/async-runs.md

@@ -25,7 +25,7 @@ Each Run persists:
 - captured Recipe/template/values;
 - model and thinking policy provenance.
 
-Inspection, Control, cancellation, kill, retirement, and teardown filter by owner. Lifecycle mutations revalidate generation, state, and process identity under the canonical lock.
+Inspection, Control, cancellation, kill, retirement, and teardown filter by owner. Public Run-specific `inspect` and `message` also require a current coordinator session whose id exactly matches the persisted non-empty owner; possession of `run:<id>` alone grants no access. Missing coordinator identity, ownerless state, and cross-owner state fail closed. `inspect target=runtime view=runs` returns only the current session's exact-owner inventory and is the supported diagnostic when a remembered Run is inaccessible. Lifecycle mutations additionally revalidate generation, state, and process identity under the canonical lock.
 
 ## State Files
 
@@ -86,11 +86,19 @@ Unix services may publish a FIFO; native Windows services publish a Windows name
 
 A service exact-id claims queued or transport-delivered Controls and records handled/failed outcomes through the canonical Control journal authority. Admission performs one locked read, integrity/generation check, terminal-tail compaction, capacity decision, and atomic write. The 65th pending Control and a rewrite exceeding 1 MiB fail as bounded `control_backpressure` before admission; malformed, unreadable, oversized, or stale-generation journals fail with an integrity reason and no rejected record. `inspect view=control` reports pending capacity, saturation, stale work, journal bytes, and diagnostics. Every transition uses the same lock, expected-state fence, 128-terminal compaction, and atomic bounded rewrite; persisted errors truncate inside the string at 4 KiB. Admitted nonterminal Controls never expire automatically. Delivery failure evidence cannot regress a Control already claimed or completed by a fast consumer. Services capture their startup generation, so stale-generation Controls never execute.
 
-Runtime lifecycle `kill`, retention actions, and review retry/reset remain runtime-owned rather than Recipe-declared. Kill is the recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and creates no synthetic Control. Same-directory restart clears all generation-local evidence before the new `run_instance_id`; archive moves the exact bounded terminal tree, while prune removes kernel state and preserves only explicitly requested artifacts.
+Runtime lifecycle `kill`, retention actions, and review retry/reset remain runtime-owned rather than Recipe-declared. Invoke Run actions through the public tool exactly as follows:
+
+```text
+message target=run:<id> action=kill
+message target=run:<id> action=archive
+message target=run:<id> action=prune input={"preserve_artifacts":true}
+```
+
+Kill accepts only a running owned generation and is the recovery path for a stuck saturated Run: it bypasses actor-local Control capacity and creates no synthetic Control. Archive and prune accept only terminal owned Runs. Archive moves the entire Run state directory and leaves a tombstone at the original path. Prune removes kernel state and preserves declared existing artifacts only when `preserve_artifacts` is explicitly true, copying them to retained artifact storage first. Same-directory restart clears all generation-local evidence before the new `run_instance_id`.
 
 ## Execution Evidence
 
-`execution.json` stores general command/session provenance. The async runner keeps bounded stdout/stderr logs plus complete capture artifacts when semantic validation requires untruncated evidence. Pi command execution also records owned session provenance for later Trace projection and review checks. Trace and Control quotas do not constrain declared user artifacts, repositories or media sources, complete execution captures, or actor-owned queue/workload state; each remains governed by its own lifecycle and policy.
+`execution.json` stores general command/session provenance. The async runner keeps bounded stdout/stderr logs plus complete capture artifacts when semantic validation requires untruncated evidence. Pi command execution also records owned session provenance for later Trace projection and review checks. Session evidence files larger than 4 MiB are rejected before JSONL materialization and surface explicit truncation diagnostics instead of being loaded unboundedly. Artifact manifests compute size and SHA-256 incrementally in 64 KiB chunks. Trace and Control quotas do not constrain declared user artifacts, repositories or media sources, complete execution captures, or actor-owned queue/workload state; each remains governed by its own lifecycle and policy.
 
 Review acceptance remains a command-stage concern. General execution evidence does not imply review approval.
 
@@ -126,7 +134,7 @@ Packaged controlled services demonstrate the endpoint protocol:
 - `music-player/playback` consumes playback Controls and emits playback Trace;
 - `actors/resource-locker` consumes queue/lease actions, emits lock Trace, and atomically retains at most 512 valid journal records within 1 MiB.
 
-Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. The obsolete advisory `wake.jsonl` notifier was removed; filesystem watchers and bounded reconciliation observe authoritative state directly.
+Shared archive/prune evidence similarly retains at most 256 valid records within 1 MiB under its canonical lock. Filesystem watchers and bounded reconciliation observe authoritative state directly.
 
 One-shot pipelines omit Control and terminate through their command graph.
 
@@ -136,6 +144,10 @@ One-shot pipelines omit Control and terminate through their command graph.
 inspect target=run:<id> view=recipe
 inspect target=run:<id> view=trace source=lifecycle lines=40
 inspect target=run:<id> view=control
+inspect target=runtime view=runs
+inspect target=runtime view=triage
 ```
 
+Runtime `runs` is the exact-owner inventory; `triage` aggregates failed Runs, Control pressure, incomplete Trace evidence, and attention for that inventory. See [Management Inspection](./inspection.md) for every target/view combination and applicable inputs.
+
 Use `/actor-inspector` to inspect Runs as concrete actor instances in the live TUI. Runtime, Recipe registry, and tool definitions remain separate management targets. No public noun, tool, target, or view is added by bounded retention.

package/node_modules/@llblab/pi-actors/docs/command-templates.md

@@ -30,7 +30,7 @@ Command-template standard does not own:
 
 ## Shape
 
-A command template is either a command-line string or an ordered array of command-template leaves:
+A command template is a command-line string, an ordered array of command-template nodes, or an object that applies execution fields to a nested `template`:
 
 ```json
 {
@@ -62,7 +62,8 @@ Common object fields:
 - `retry`: Optional max attempts including the first. Default is `1`.
 - `failure`: Optional failure propagation scope: `continue`, `branch`, or `root`. Default is `continue`.
 - `recover`: Optional command template run between failed retry attempts. Recovery output is ignored; recovery failure stops retries.
-- `template`: Required command string or ordered composition array.
+- `repeat`: Optional non-negative expansion count or supported length expression. Repeated nodes receive generated zero-based index placeholders.
+- `template`: Required nested command string, ordered composition array, or command-template object.
 
 For object form, write `template` last. Read the node flags first, then the executable content. Storage paths, labels, selectors, descriptions, and registry-specific metadata belong to each extension's local schema.
 
@@ -83,7 +84,7 @@ 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   |
@@ -206,7 +207,7 @@ Repeat expressions support only integers, `index`, `prev`, `next`, `repeat`, par
 
 Repeat placeholders are local generated values. Call-time args should not use these reserved names to override the repeat index.
 
-Parallel children use the same object shape: flags come first and `template` stays last. A join remains usable when at least one branch succeeds and reports each branch label/status. Some local schemas may accept `pipe`, but the portable standard is `template: [...]`.
+Parallel children use the same object shape: flags come first and `template` stays last. A join remains usable when at least one branch succeeds and reports each branch label/status. The portable composition field is always `template`.
 
 ## Failure Propagation
 

package/node_modules/@llblab/pi-actors/docs/inspection.md

@@ -0,0 +1,83 @@
+# Management Inspection
+
+The public `inspect` tool exposes four exact target families. Targets are management projections, not interchangeable aliases.
+
+## Target and View Matrix
+
+| Target | Views | Purpose |
+| --- | --- | --- |
+| `run:<id>` | `recipe`, `trace`, `control` | Inspect one accessible Run generation |
+| `runtime` | `status`, `runs`, `triage` | Inspect package policy, owned Run inventory, or aggregate operational pressure |
+| `recipes` | `status`, `summary`, `doctor`, `imports`, `reviews` | Inspect user Recipe discovery, active Skill components, exact resolution, imports, and automatic-review recovery |
+| `tool:<name>` | `status`, `schema` | Inspect persistent-tool activation/usage or its current callable schema |
+
+`verbose=false` normally returns compact text and `verbose=true` returns structured details. `tool:<name> view=schema` is always structured because its callable parameter schema has no useful compact equivalent.
+
+## Run Targets
+
+```text
+inspect target=run:demo view=recipe
+inspect target=run:demo view=trace source=lifecycle lines=40
+inspect target=run:demo view=control lines=20
+```
+
+Run views require a current coordinator session and an exact, non-empty match between that session id and the Run's persisted owner. Possessing a `run:<id>` is not authorization. Missing coordinator identity, ownerless state, and cross-owner state fail closed.
+
+- `recipe` returns captured generation-local Recipe, launch, policy, and artifact declarations.
+- `trace` returns the bounded unified projection plus retained-history completeness. `source` accepts `all`, `lifecycle`, `control`, `process`, `agent`, `artifact`, or `runtime`; `lines` bounds returned rows.
+- `control` returns endpoint readiness, declared and runtime-owned actions, pending capacity, saturation, stale work, diagnostics, and recent redacted records; `lines` bounds recent records.
+
+Use the runtime inventory when a remembered Run id is inaccessible from the current session:
+
+```text
+inspect target=runtime view=runs
+```
+
+## Runtime Targets
+
+```text
+inspect target=runtime view=status
+inspect target=runtime view=runs
+inspect target=runtime view=runs status=failed
+inspect target=runtime view=triage
+```
+
+- `status` reports immutable package/runtime identity, state schema, and current automatic-review policy.
+- `runs` returns the complete inventory owned by the current coordinator session; it is not paginated or capped by `lines`. Optional `status` filters that exact-owner inventory.
+- `triage` aggregates the same exact-owner inventory into failed Runs, pending/stale Controls, backpressure, incomplete Trace diagnostics, and retained attention evidence.
+
+Runtime inventory never broadens authorization and never returns ownerless or foreign Run state.
+
+## Recipe Targets
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=summary
+inspect target=recipes view=doctor identity=music-player/playback
+inspect target=recipes view=imports verbose=true
+inspect target=recipes view=reviews verbose=true
+```
+
+- `status` reports registry/watch state, active/shadowed/invalid/disabled user Recipes, active Skill components, drafts, usage, and diagnostics.
+- `summary` returns the compact discovery-oriented projection of the same current context.
+- `doctor` diagnoses one canonical `<skill>/<recipe>` identity when `identity` is provided; without an identity it reports registry remediation evidence.
+- `imports` exposes active Skill namespaces and component import inventory for resolution diagnosis.
+- `reviews` exposes bounded automatic draft/tool review state and recovery guidance.
+
+`identity` is accepted only with `view=doctor`. Skill inventory is fail-soft diagnostic evidence; exact launch and registration still resolve against the immutable active-session context.
+
+## Tool Targets
+
+```text
+inspect target=tool:music_player view=status
+inspect target=tool:music_player view=schema
+```
+
+- `status` separates persistence, registry admission, host registration, `callable_now`, activation boundary, source identity, and `tool_calls` versus `spawn_calls`.
+- `schema` returns the currently callable description, parameter schema, and prompt snippet. It fails clearly when a definition is persisted but its live callable schema is unavailable.
+
+A registered tool is a capability definition, not a Run. Tool status cannot substitute for Run inspection, and Recipe spawning cannot prove registered-tool invocation.
+
+## Boundaries
+
+Inspection is read-only, owner-filtered where Run state is involved, and redacted. Evidence-heavy Run, review, diagnostic, and text projections apply their documented bounds; `runtime view=runs` deliberately returns the complete matching exact-owner inventory. Inspection does not mutate journals, infer authority from displayed data, expose private active-Skill installation paths, or turn retained Trace into an audit archive. Use `message` for admitted runtime or actor-local actions.

package/node_modules/@llblab/pi-actors/docs/recipe-library.md

@@ -80,7 +80,7 @@ Do not bulk-copy bundled Recipes into the user Recipe root. Internal `recipe-mem
 npm run recipes:qa
 ```
 
-Recipe QA recursively inventories direct Skill components and validates filesystem identity, syntax, imports, Control declarations, origin ownership, portable artifact paths, and `{skill_dir}` helper references. Nested files and JSON/Markdown stem collisions fail precisely. Recipe descriptions remain optional; QA requires zero capability diagnostics and zero warnings without enforcing style, documentation quotas, or architecture policy. Removed mailbox declarations fail with the migration diagnostic rather than receiving automatic conversion.
+Recipe QA recursively inventories direct Skill components and validates filesystem identity, syntax, imports, Control declarations, origin ownership, portable artifact paths, and `{skill_dir}` helper references. Nested files and JSON/Markdown stem collisions fail precisely. Recipe descriptions remain optional; QA requires zero capability diagnostics and zero warnings without enforcing style, documentation quotas, or architecture policy. `mailbox` is not part of the current Recipe contract and fails validation.
 
 ## Related
 

package/node_modules/@llblab/pi-actors/docs/template-recipes.md

@@ -1,27 +1,45 @@
-# Template Recipes
+# Template Recipe Standard
 
-A Recipe stores a reusable command-template definition as JSON or Markdown.
+A Template Recipe is a file-backed, reusable command-template graph. It adds stable identity, typed inputs, composition, optional detached execution, artifacts, Control, and provenance around the portable [Command Template Standard](./command-templates.md).
 
-## JSON
+## Mental Model
+
+A Recipe has three layers:
+
+1. **Recipe contract**: identity, description, arguments, defaults, imports, lifecycle, artifacts, and Control.
+2. **Command-template graph**: the executable string, sequence, parallel fanout, conditions, retry, and output behavior stored in `template`.
+3. **Run projection**: detached process state, Trace, Control delivery, artifacts, and inspection when `async: true`.
+
+Use a Recipe when a command graph should be named, validated, reused, imported, registered as a tool, or launched as a Run. Use an inline command template when file identity and Recipe metadata add no value.
+
+## File Formats
+
+Recipes may be authored as JSON or Markdown. Both formats compile to the same Recipe contract.
+
+### JSON
+
+JSON is the most direct form for structured composition:
 
 ```json
 {
-  "async": true,
-  "description": "Create a repository health artifact",
+  "description": "Create a repository health report",
   "args": ["repo:path", "artifact_path:path", "model:string"],
-  "defaults": { "artifact_path": "{state_dir}/health.md" },
-  "imports": { "review": "swarm/quorum-review" },
-  "artifacts": { "report": "{artifact_path}" },
+  "defaults": {
+    "artifact_path": "{state_dir}/health.md"
+  },
+  "async": true,
+  "artifacts": {
+    "report": "{artifact_path}"
+  },
   "template": {
-    "name": "review",
-    "values": { "input": "Inspect {repo}", "model": "{model}" }
+    "template": "pi -p {repo} --model {model}"
   }
 }
 ```
 
-## Markdown
+### Markdown
 
-Markdown Recipes use YAML frontmatter and one executable fence:
+Markdown uses YAML frontmatter for the Recipe contract and one executable fence for `template`:
 
 ````markdown
 ---
@@ -30,142 +48,283 @@ args:
   - file:path
 ---
 
-Human notes remain advisory.
+Human-facing notes may explain intent and usage.
 
 ```template
 summarize {file}
 ```
 ````
 
-Fences marked `template`, `command-template`, `json`, or `recipe` can define execution. Frontmatter supports Recipe metadata and command-template flags.
+Executable fences may be marked `template`, `command-template`, `json`, or `recipe`. Narrative Markdown outside the executable fence is advisory and is not executed.
+
+Choose JSON for dense machine-oriented graphs. Choose Markdown when a short executable definition benefits from nearby human guidance.
+
+## Identity and Placement
+
+Recipe identity comes from its location and filename, never from a top-level `name` field.
+
+| Placement | Identity | Typical use |
+| --- | --- | --- |
+| Direct file under an active Skill's `recipes/` directory | `<skill>/<filename-stem>` | Maintained Skill capability |
+| Explicit `.json` or `.md` path | Resolved file path with filename-stem evidence | Local or project-specific composition |
+| File under `~/.pi/agent/recipes` | Registered user tool identity | User-maintained reusable tool |
 
-Skill Recipe identity is `<active Skill name>/<Recipe filename stem>`. Recipe files have no top-level `name`; both JSON and Markdown fail with migration guidance when that removed field is present. `SKILL.md` `name` remains Pi host metadata and matches the Skill directory; pi-actors introduces no additional Skill identity field. The `name` field on a command-template node still selects an imported alias and is not Recipe self-identity.
+A Skill Recipe is one direct file under `<skill>/recipes/`. Nested files are not Skill components. The Skill name comes from its active `SKILL.md`; the Recipe stem comes from the direct filename.
 
-## Fields
+A Recipe file must not declare top-level `name`. Within a command-template graph, a node-level `name` has a different purpose: it invokes an alias declared in `imports`.
 
-Common Recipe fields:
+## Recipe Field Reference
 
-- `description`, `disabled`;
-- `args`, typed arg declarations, inline defaults, `defaults`, and composition `values`;
-- `imports` with optional binding defaults/values;
-- `template`;
-- `async`;
-- `singleton: true` for one explicit Skill-owned async service slot;
-- `artifacts`;
-- `control` for actual controlled services;
-- command-template flags such as `parallel`, `concurrency`, `min_successful`, `when`, `timeout`, `delay`, `retry`, `failure`, `recover`, `repeat`, `accept_output`, and `output`;
-- `retire_when: "children_terminal"` for opt-in supervisor retirement.
+The following fields belong to the file-level Recipe contract. Unless noted otherwise, each field is optional.
 
-## Imports
+| Field | Type | Default | Contract |
+| --- | --- | --- | --- |
+| `description` | string | none | Human-facing purpose used by discovery and tool surfaces. Describe the outcome, not implementation history. |
+| `disabled` | boolean | `false` | Prevents launch and import when `true`. Use it to make an authored Recipe intentionally unavailable without deleting the file. |
+| `args` | string[] | inferred/untyped placeholders | Declares public inputs. Entries may be untyped (`input`), typed (`file:path`), enum-constrained (`mode:enum(check,fix)`), or include an inline default (`limit:int=10`). Names must be unique and agree with placeholder types. |
+| `defaults` | object | `{}` | Supplies fallback values for declared inputs. A default may reference another placeholder and is resolved recursively with a depth bound. Every authored default must correspond to a declared argument. |
+| `values` | object | `{}` | Binds composition values before executing the Recipe graph. Use for authored wiring between wrapper/import context and template nodes, not for caller-owned configuration. |
+| `imports` | object | `{}` | Maps local aliases to other Recipes. Each value is a canonical Skill reference, explicit file path, or binding object with `from`, `defaults`, and/or `values`. Imports are resolved and validated before launch. |
+| `template` | string, array, or command-template object | required | Defines the executable command-template graph. It may directly execute commands, compose nodes, invoke import aliases, or delegate to another Recipe. |
+| `async` | boolean | `false` | Launches the Recipe as a detached Run when `true`. Detached execution owns durable state, Trace, terminal reconciliation, and optional Control/artifacts. |
+| `singleton` | boolean | `false` | Gives one async Skill Recipe a stable `run:<skill>` service slot. Valid only with `async: true`; at most one singleton Recipe may belong to a Skill. |
+| `artifacts` | object of string paths | `{}` | Declares named files produced by the Run. Paths support placeholders, resolve under containment policy, and appear in Run inspection. |
+| `control` | string[] | `[]` | Declares actions consumed by an actual controlled service. Actions must be unique lowercase ASCII names, non-reserved, and at most 64 characters. |
+| `retire_when` | `"children_terminal"` | none | Opts an async supervisor into retirement after all owned child Runs become terminal. Omit it for ordinary Run lifecycle. |
+| `actor_context` | boolean or `"off"` | enabled | Controls injection of Recipe composition context into compatible child-agent prompts. Use `false` or `"off"` only when a deliberately minimal child prompt is required. |
+
+### Value Resolution
+
+For a declared name, effective values resolve in this order:
+
+```text
+caller values
+→ node/import/Recipe values
+→ defaults
+→ inline argument default
+→ missing-value error
+```
+
+The selected value is then validated against its declared type or enum. Runtime-provided origin values such as `{recipe_dir}` and `{skill_dir}` are immutable and cannot be declared or overridden through `args`, `defaults`, or `values`.
+
+## Command-Template Fields
+
+A Recipe may place command-template execution fields beside `template`, and any object node inside the graph may use the same fields. Their execution semantics are defined by the [Command Template Standard](./command-templates.md).
+
+| Field | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `label` | string | none | Human-readable node label for diagnostics and branch reports. |
+| `parallel` | boolean | `false` | Runs an array node concurrently instead of sequentially. |
+| `concurrency` | positive integer or placeholder | unlimited | Caps simultaneous children of a parallel node. |
+| `min_successful` | non-negative integer or placeholder | none | Requires a minimum count of successful branches with non-empty stdout. |
+| `when` | boolean or expression | `true` | Skips the node when its guard resolves false. |
+| `timeout` | milliseconds or placeholder | `0` / unbounded | Terminates an execution attempt after a positive duration. |
+| `delay` | milliseconds or placeholder | `0` | Waits before starting the node. |
+| `retry` | positive integer or placeholder | `1` | Sets total attempts, including the first attempt. |
+| `failure` | `continue`, `branch`, or `root` | `continue` | Selects how a node failure propagates through composition. |
+| `recover` | command template | none | Runs cleanup between failed attempts; a recovery failure ends retry. |
+| `repeat` | non-negative integer or expression | none | Repeats a node, exposing the current index to placeholders. |
+| `accept_output` | supported semantic contract | none | Applies fail-closed semantic validation to otherwise successful stdout. |
+| `output` | string selector | `stdout` | Selects the result channel returned by the graph. |
+
+Keep Recipe metadata at the file level and execution behavior near the node it controls. For object form, place `template` last so readers encounter contract and execution flags before executable content.
+
+## Imports and Composition
+
+Imports are local aliases within one resolved execution graph:
 
 ```json
 {
+  "description": "Review and format one report",
+  "args": ["input:string", "thinking:string=medium"],
   "imports": {
     "review": "swarm/quorum-review",
-    "report": {
+    "format": {
       "from": "../shared/report.md",
-      "defaults": { "thinking": "medium" }
+      "defaults": {
+        "thinking": "{thinking}"
+      }
     }
   },
   "template": [
-    { "name": "review", "values": { "input": "{input}" } },
-    { "name": "report", "values": { "input": "Use prior output" } }
+    {
+      "name": "review",
+      "values": {
+        "input": "{input}"
+      }
+    },
+    {
+      "name": "format",
+      "values": {
+        "input": "Use prior output"
+      }
+    }
   ]
 }
 ```
 
-Imports are local definitions. Named nodes call imported templates inside the same execution graph and Run. Effective values follow `caller > node/import/Recipe values > defaults > inline arg default > missing-value error`, then the selected value is checked against its declared type or enum.
+### Accepted References
 
-Imports accept exactly `<skill>/<recipe>` or an explicit `.json` / `.md` file path. A Skill reference selects one direct filename stem under the exact Skill currently active through Pi resource discovery; duplicate active Skill identities and JSON/Markdown stem collisions fail closed. Explicit paths may be relative (`./local-review.json`, `../shared/report.md`) or absolute (`/absolute/path/to/recipe.json`). An entry file path resolves from invocation `cwd`; a relative import resolves from the importing Recipe's directory. No bare or ambient lookup remains.
+An import `from` value accepts exactly one of these forms:
 
-Direct delegation can use another Recipe as the entire template. The delegated Recipe remains the source of truth while the wrapper may narrow args/defaults or override selected lifecycle metadata.
+| Form | Resolution |
+| --- | --- |
+| `<skill>/<recipe>` | One direct filename stem under the exact active Skill |
+| `./file.json` or `../file.md` | Relative to the importing Recipe's directory |
+| `/absolute/path/to/file.json` | Exact absolute file |
 
-A launched Run captures each entry/import role, filename-derived stem, logical reference, Skill identity when owned, and import alias ancestry. Private physical source paths remain execution provenance; Inspector and child-agent context expose logical identities rather than machine-local Skill locations.
+An entry Recipe path resolves from invocation `cwd`. A relative import resolves from the importing Recipe, not from invocation `cwd`. Bare ambient names and implicit fallback search are not part of the contract.
 
-## Migration from pre-0.46 references
+Duplicate active Skill names, duplicate JSON/Markdown stems, missing references, disabled targets, import cycles, and excessive import depth fail closed. A launched Run captures the resolved graph; later catalog changes affect future launches only.
 
-```text
-std:foo              -> owning-skill/foo
-skill:foo/bar        -> foo/bar
-root packaged foo    -> owning-skill/new-file-stem
-Recipe name field    -> delete; filename is identity
-nested skill path    -> flatten filename or use explicit file path
+### Import Bindings
+
+A string import uses the target as authored:
+
+```json
+{ "review": "swarm/quorum-review" }
 ```
 
-Removed `std:` and `skill:` forms fail with migration guidance; they are not aliases. Root packaged Recipes no longer exist. Flatten a maintained Skill component to a direct filename, or reference a nested/local file explicitly when it is intentionally outside the Skill component namespace.
+An object binding can supply alias-local defaults or values:
 
-## Singleton Services
+```json
+{
+  "review": {
+    "from": "swarm/quorum-review",
+    "defaults": { "thinking": "medium" },
+    "values": { "mode": "strict" }
+  }
+}
+```
+
+Use `defaults` when callers may override the value. Use `values` for authored composition wiring subject to the normal resolution order.
+
+### Direct Delegation
+
+A Recipe may use another Recipe as its entire template. The delegated Recipe remains authoritative while the wrapper may narrow public arguments, defaults, or selected lifecycle metadata. Singleton Run and Recipe identities remain owned by the delegated singleton; wrappers cannot create alternate service identities.
+
+## Async Runs and Singleton Services
 
-`singleton: true` is valid only for an async Skill Recipe, and one Skill may declare at most one singleton Recipe. The runtime derives `run:<skill>` and the canonical `<skill>/<recipe>` identity, then rejects a conflicting caller-supplied Run id. A compatible repeated launch returns the healthy active generation; contradictory Recipe identity, ownership, startup values, or Control fails closed. A terminal result is never reused even during runner exit; retry after that process exits starts a fresh `run_instance_id` under the same logical Run id. Actor-owned workload continuity requires a validated state artifact that restart cleanup deliberately preserves; singleton identity alone never proves restored state.
+`async: true` changes execution from an inline result to a detached Run. The Run receives durable state, stdout/stderr evidence, Trace, generation identity, and terminal reconciliation.
 
-Direct Recipe delegation inherits the original singleton Run and Recipe identities, so registered tools and explicit wrappers cannot retarget the service or create parallel aliases.
+A singleton Recipe additionally follows these rules:
+
+- it must be a direct Recipe owned by one active Skill;
+- it must declare `async: true`;
+- one Skill may declare at most one singleton Recipe;
+- its logical address is `run:<skill>`;
+- a compatible repeated launch reuses the healthy active generation;
+- conflicting Recipe identity, owner, startup values, or Control contract fails closed;
+- terminal generations are never reused;
+- singleton identity alone does not restore workload state after restart.
+
+Use singleton only for a genuine long-lived Skill service. Ordinary jobs should remain non-singleton Runs.
 
 ## Control
 
-Only a process that consumes actor-local input declares actions:
+Declare Control only when the launched process consumes actor-local input:
 
 ```json
 {
+  "description": "Run a controllable service",
   "async": true,
   "control": ["pause", "resume", "stop"],
   "template": "{skill_dir}/scripts/service.mjs --state-dir {state_dir}"
 }
 ```
 
-Actions must be lowercase ASCII, unique, non-reserved, and at most 64 characters. Serialized Control input is at most 380 bytes so every admitted wire record remains within 512 bytes on FIFO and named pipe. One-shot Recipes omit Control. Larger data belongs in a declared artifact/path; outputs belong in Trace, artifacts, execution evidence, or the command result.
+Control action names are lowercase ASCII, unique, non-reserved, and at most 64 characters. Serialized Control input is limited to 380 bytes so admitted wire records remain within 512 bytes on FIFO and named pipe transports.
+
+Do not use Control as a general data channel. Large inputs belong in declared files or artifacts; outputs belong in Trace, artifacts, execution evidence, or the command result.
 
 ## Artifacts
 
+Declare deterministic outputs by stable name:
+
 ```json
 {
   "artifacts": {
     "report": "{state_dir}/report.md",
     "manifest": "{state_dir}/manifest.json"
-  }
+  },
+  "template": "generate-report --output {state_dir}/report.md"
 }
 ```
 
-Artifact paths resolve under containment policy and appear in Run inspection. Recipes should write declared artifacts deterministically and fail when the requested write policy cannot be honored.
-
-## File Origins
-
-Every file-backed Recipe receives immutable `{recipe_dir}`. A Recipe under an active Skill also receives `{skill_dir}`, resolved to the directory containing that Skill's `SKILL.md`; using `{skill_dir}` elsewhere fails clearly. These runtime values cannot be declared in `args`, `defaults`, or `values`, and caller input cannot override them. They expand in templates, recursive defaults/values, imports, and artifacts while existing `./` executable behavior remains relative to invocation `cwd`.
+Artifact declarations do not create files. The Recipe must write them and fail when its write policy cannot be honored. Inspection reports declaration, availability, size, and digest evidence without treating undeclared arbitrary paths as public artifacts.
 
-## Context and Provenance
+## Runtime Origins
 
-File-backed Runs capture Recipe context records for the entry and imports. File identity is the filename stem; a direct Recipe under an active Skill has the logical identity `<skill>/<stem>`. The captured bundle explains composition identity and remains generation-local evidence. Runtime origin paths remain in local Run provenance but are omitted from model-facing launch values. It does not override the authored task prompt.
+Every file-backed Recipe receives immutable `{recipe_dir}`, the directory containing the Recipe file. A Recipe directly owned by an active Skill also receives `{skill_dir}`, the directory containing that Skill's `SKILL.md`.
 
-Recipes that need a minimal child prompt may opt out of injected Recipe context through the documented `actor_context` launch option.
+| Placeholder | Availability | Meaning |
+| --- | --- | --- |
+| `{recipe_dir}` | every file-backed Recipe | Stable origin for Recipe-relative helpers and assets |
+| `{skill_dir}` | active Skill-owned Recipe only | Stable origin for Skill-owned helpers and assets |
+| `{state_dir}` | async Run context | Generation-local durable Run state directory |
+| `{current_model}` | when current Pi policy is available | Current model inherited as an explicit resolved value |
+| `{current_thinking}` | when current Pi policy is available | Current thinking policy inherited as an explicit resolved value |
 
-## Current Policy
+Origin and policy placeholders expand through templates, recursive defaults/values, imports, and artifacts where applicable. Resolution fails before launch when a required runtime value is unavailable.
 
-Defaults can inherit current Pi policy:
+Example policy inheritance:
 
 ```json
 {
+  "args": ["model:string", "thinking:string"],
   "defaults": {
     "model": "{current_model}",
     "thinking": "{current_thinking}"
-  }
+  },
+  "template": "pi -p inspect --model {model} --thinking {thinking}"
 }
 ```
 
-Resolution fails before launch when required current policy is unavailable. The Run persists whether values were inherited or explicit.
+## Context and Provenance
+
+A file-backed launch captures generation-local records for the entry Recipe and every resolved import. Records include role, filename stem, logical reference, Skill identity when applicable, and import alias ancestry.
 
-## Resolution Context
+Logical identities are exposed to Inspector and child-agent context. Machine-local physical paths remain local execution provenance and are not promoted into model-facing launch values.
 
-User Recipes under `~/.pi/agent/recipes` remain intentionally registered tools, not an ambient import namespace. Each session receives one immutable resolution context from Pi's loaded Skill metadata; spawn, user-Recipe admission, registration, schema derivation, live inspection, and watcher reconciliation consume that same context rather than scanning ambient Skill roots or keeping a process-global mutable namespace. A launch captures its resolved graph, so later Skill changes affect only future launches. An invalid or missing exact target fails without fallback. Disabled Recipes cannot launch. Registry watchers converge after atomic changes without executing partial definitions.
+`actor_context` controls only compatible child-prompt injection:
 
-Active-Skill catalog inventory is fail-soft diagnostic state, not exact-resolution authority. Invalid components are reported individually and make the catalog partial while unrelated valid `<skill>/<recipe>` references remain exactly resolvable.
+```json
+{
+  "actor_context": false,
+  "template": "pi -p minimal-task"
+}
+```
+
+Disabling injected context does not remove Run provenance or change the authored task prompt.
+
+## Authoring Checklist
+
+1. Choose a direct Skill identity or explicit file location.
+2. When useful, add one outcome-oriented `description`; descriptions are optional.
+3. Declare every public input in `args`, including types where useful.
+4. Put overridable fallback configuration in `defaults`.
+5. Add imports only when composition earns a stable local alias.
+6. Keep execution flags on the node they govern.
+7. Use `async` only when detached lifecycle or durable evidence is required.
+8. Declare `control` only for actions the process actually consumes.
+9. Declare deterministic artifact paths before writing them.
+10. Validate exact references, portable paths, and platform assumptions.
 
 ## Validation
 
+Validate one Recipe:
+
 ```bash
 node skills/actors/scripts/validate-recipe.mjs path/to/recipe.json --qa
+```
+
+Validate all maintained Skill Recipes:
+
+```bash
 node skills/actors/scripts/validate-recipe.mjs skills --skills --qa --summary
 ```
 
-Skill validation recursively inventories every direct `<skill>/recipes/*.json|*.md` component, rejects nested files and duplicate stems, and checks filename identity, JSON/Markdown compilation, origins, imports, Control, artifacts, portable paths, helper targets, and platform notes. Files exceeding 1 MiB or import depth 32 fail closed.
+Validation checks file size, filename identity, JSON/Markdown compilation, argument contracts, imports, cycles and depth, runtime origins, Control, artifacts, portable paths, helper targets, and platform notes. Recipe files larger than 1 MiB and import graphs deeper than 32 levels fail closed.
 
 ## Related