@llblab/pi-actors 0.46.1 → 0.47.0

package/AGENTS.md

@@ -2,13 +2,14 @@
 
 ## Meta-Protocol Principles
 
-- `README.md`: human product entrypoint.
-- `AGENTS.md`: durable implementation protocol.
+- `README.md` and `docs/`: human-facing product entrypoint, concepts, and reference.
+- `skills/`: agent-facing operating protocols and Skill-local operational references.
+- injected system prompt: routing-only meta-protocol that selects the owning Skill.
+- `AGENTS.md`, source, and tests: implementation protocol and executable evidence.
 - `BACKLOG.md`: canonical future-only work.
 - `CHANGELOG.md`: completed delivery history.
-- `docs/README.md`: documentation index.
 
-Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
+Do not make normal-use Skills depend on README/docs, do not copy Skill operating manuals into the system prompt, and do not present implementation evidence as the agent operating path. Keep these surfaces distinct and reconcile them after meaningful changes. Every release section, historical or new, keeps at most 8 outcome records of at most 512 characters.
 
 ## Concept
 
@@ -37,7 +38,8 @@ Pi host
      -> lib/inspector*.ts             owner-filtered actor-instance inspection
      -> scripts/*.mjs                 process/service entrypoints
      -> skills/*/recipes/*            Skill-owned Recipe components
-     -> skills/* + docs/*             agent and human guidance
+     -> skills/*                      agent operating protocols
+     -> README.md / docs/*            human product guidance
 ```
 
 `index.ts` wires Pi ports and must not own domain behavior. Keep the local TypeScript import graph acyclic. For architecture-affecting work, load and follow `.agents/skills/domain-dag/SKILL.md`; its validator is local agent tooling, not an npm, CI, or release gate.

package/BACKLOG.md

@@ -1,585 +1,3 @@
 # Project Backlog
 
-## 0.46.1 — Registration Truth
-
-**Base:** `0.46.0` at `4abe9b26525a57883446b1d897e9e1ddf6cacde5`  
-**Release type:** patch / contract repair  
-**Primary evidence:** `tests/registration-truth.test.ts`, distilled from `PI_ACTORS_RECIPE_UX_SESSION_REPORT.md`  
-**Release sentence:** every live pi-actors surface resolves user Recipes against the same session Skill context, registration validates the effective delegated contract before persistence, activation is truthfully observable, and unrelated invalid Skill components can no longer poison valid capability discovery.
-
-## Mission
-
-Repair the runtime seams exposed by the first real `0.46.0` Skill-Recipe authoring session before redesigning agent guidance.
-
-The intended operation was:
-
-```text
-maintained Skill Recipe
-    media/player
-        ↓ specialize
-persistent user tool
-    music_player
-        ↓ activate
-call in the same session
-```
-
-The session instead observed:
-
-```text
-spawn resolves media/player
-standalone QA resolves media/player
-register_tool cannot resolve media/player
-live registry rejects the wrapper
-one unrelated invalid Skill Recipe empties the catalog
-runtime-owned placeholders leak into the tool schema
-registry persistence is reported as registration success
-spawn is mistakenly used as proof of tool invocation
-```
-
-`0.46.1` owns the mechanical truth required for `0.47.0` agent-native UX.
-
-Do **not** solve these failures with more prose, compatibility aliases, copied Recipe contracts, helper paths, shell wrappers, or new orchestration concepts.
-
-The target transaction is:
-
-```text
-current session
-    ↓
-one RecipeResolutionContext
-    ↓
-resolve candidate
-    ↓
-derive effective Recipe/tool contract
-    ↓
-validate candidate
-    ↓
-persist
-    ↓
-registry admission
-    ↓
-host registration + active-tool reconciliation
-    ↓
-verify activation
-    ↓
-return truthful state
-```
-
----
-
-# 1. Retained Canon
-
-The `0.46.0` capability model remains authoritative:
-
-```text
-Recipe --spawn--> Run
-Run = Recipe + Trace + Control
-```
-
-Public Run verbs remain:
-
-```text
-spawn
-message
-inspect
-```
-
-Persistent capability mutation remains:
-
-```text
-register_tool
-```
-
-Run views remain:
-
-```text
-recipe
-trace
-control
-```
-
-Recipe references remain exactly:
-
-```text
-<skill>/<recipe>
-explicit/path.json
-explicit/path.md
-```
-
-Skill Recipe identity remains:
-
-```text
-<active Skill identity>/<direct Recipe filename stem>
-```
-
-Retain:
-
-- six bundled Skill-owned capability packs;
-- flat Skill `recipes/` directories;
-- no root packaged Recipe library;
-- no `std:` or `skill:` prefixes;
-- no top-level file-backed Recipe `name`;
-- session-scoped active Skill identity;
-- runtime-owned `{recipe_dir}` and `{skill_dir}`;
-- bounded Trace and Control;
-- owner/generation/process fencing;
-- automatic review transactions;
-- secure npm publication;
-- project-local Domain DAG Skill outside CI/release.
-
----
-
-# 2. Contract
-
-## 2.1 One live resolution environment
-
-Every operation that decides whether a Recipe can be used in the live session must consume the same immutable session resolution environment.
-
-Conceptually:
-
-```ts
-interface RecipeResolutionContext {
-  session_id: string;
-  cwd: string;
-  active_skills: ActiveSkillRecipeContext;
-  generation: string;
-}
-```
-
-The exact internal type may be smaller, but there must be one explicit owner and one semantic contract.
-
-The following must not invent independent active-Skill contexts:
-
-```text
-spawn
-register_tool candidate validation
-user Recipe registry admission
-user Recipe registry reload
-tool schema derivation
-inspect recipes
-inspect tool
-automatic review when resolving user wrappers
-live Recipe validation used by registration
-```
-
-Standalone package QA may still construct an offline package context, but it must be labeled as offline/package QA and may not be represented as proof of live registry admission.
-
-## 2.2 One user Recipe admission path
-
-A user Recipe under:
-
-```text
-~/.pi/agent/recipes/<name>.json
-```
-
-is an active agent tool only if one authoritative admission function can:
-
-1. parse the authored Recipe;
-2. resolve its delegation/import graph with the live `RecipeResolutionContext`;
-3. derive runtime-owned origins;
-4. derive the effective argument/type/default contract;
-5. classify async behavior;
-6. validate Control/artifacts;
-7. produce one `RegisteredTool` projection;
-8. produce bounded diagnostics on failure.
-
-`register_tool`, startup/reload discovery, and live revalidation must use this same admission contract.
-
-Do not maintain one path that creates a `RegisteredTool` directly from `register_tool` input and another path that later interprets the persisted Recipe differently.
-
-## 2.3 Registration is a state transition
-
-A successful registration response must distinguish at least:
-
-```text
-resolved
-validated
-persisted
-registry_active
-host_registered
-active_tool
-callable_now
-```
-
-These states may all become `true` in the healthy path, but they are not synonyms.
-
-Never return text that implies current-session invocation if the system cannot prove it.
-
-## 2.4 Effective contract before mutation
-
-A Recipe-backed tool must be validated from the **resolved effective contract**, not the shallow wrapper shape.
-
-For:
-
-```json
-{
-  "description": "Play local music.",
-  "defaults": {
-    "source": "~/Music/1MIX"
-  },
-  "template": "media/player"
-}
-```
-
-the effective tool contract inherits from `media/player`:
-
-```text
-async
-args
-arg types
-defaults
-artifacts
-Control
-runtime-owned origins
-```
-
-without copying those fields into the authored wrapper.
-
-The tool schema must contain only caller-owned inputs.
-
-## 2.5 Partial catalog, exact resolver
-
-The active Skill component catalog is diagnostic/discovery state.
-
-It must never be required for exact resolution of an unrelated valid component.
-
-An invalid:
-
-```text
-some-skill/bad-recipe
-```
-
-must not make:
-
-```text
-media/player
-```
-
-unresolvable merely because a catalog listing failed.
-
----
-
-# 3. Runtime-Owned Inputs
-
-The following are runtime-owned and must never leak into caller-facing tool schemas merely because they occur in an effective Recipe template:
-
-```text
-recipe_dir
-skill_dir
-state_dir
-trace_file
-run_instance_id
-owner/session identity
-runtime state root
-```
-
-`run_id` remains an intentional caller-visible optional override for async tool invocation if the existing public contract retains it.
-
-The executor must inventory every runtime-injected placeholder and centralize ownership rather than maintaining ad hoc exclusion lists in unrelated schema code.
-
-Declared user args retain their actual types:
-
-```text
-string
-path
-bool
-int
-number
-enum
-array
-```
-
-A delegated Recipe may not degrade them all to strings.
-
----
-
-# 4. Activation Truth
-
-`pi-actors` must determine what the Pi host can actually guarantee after dynamic `registerTool`.
-
-Preferred contract:
-
-```text
-register_tool returns callable_now=true
-→ host definition exists
-→ tool is in the current active tool set
-→ the next model step in the same session can call it
-```
-
-If the Pi host cannot guarantee that:
-
-```text
-register_tool returns callable_now=false
-activation=<exact boundary>
-```
-
-and all prompts/docs must say so.
-
-Do not infer model visibility from persistence or an extension-local map.
-
-The implementation must test the real Pi integration path, not only mocked registration callbacks.
-
----
-
-# 5. Registration Atomicity
-
-For a new registration:
-
-```text
-candidate
-→ resolve/validate without mutation
-→ durable write
-→ authoritative registry admission
-→ host registration/activation
-→ verification
-```
-
-If failure occurs before persistence, no user Recipe file appears.
-
-If persistence succeeds but authoritative admission fails unexpectedly:
-
-- restore/delete the just-written candidate under the canonical mutation lock;
-- restore prior in-memory registry state;
-- report the exact failed phase;
-- do not leave an invalid file while returning generic success.
-
-For updates:
-
-- preserve the prior file bytes until replacement is known valid;
-- do not destroy a working tool because the replacement cannot resolve;
-- retain existing CAS/path/symlink/mutation safety.
-
-Host APIs that cannot unregister stale dynamic definitions must be explicitly accounted for. Validate as much as possible before host mutation.
-
----
-
-# 6. Registry and Component Observability
-
-Existing:
-
-```text
-inspect target=recipes view=status
-inspect target=recipes view=summary
-inspect target=recipes view=doctor
-inspect target=tool:<name> view=status
-inspect target=tool:<name> view=schema
-```
-
-remain the public surfaces.
-
-Do not add a new `recipe:` target in this patch.
-
-Recipe registry inspection must expose bounded current state such as:
-
-```text
-registry_generation
-scanned_at
-resolution_generation
-watch_status
-user_recipe_count
-active_tool_count
-skill_component_count
-rejected_skill_component_count
-catalog_partial
-```
-
-Rejected Skill components must be reported individually with:
-
-```text
-skill
-stem if derivable
-portable file location
-reason
-```
-
-Use portable paths such as:
-
-```text
-~/.pi/agent/skills/...
-<pi-actors>/skills/...
-```
-
-rather than raw home-directory leakage.
-
-`inspect tool:<name> view=status` must expose activation state where it can be proven.
-
----
-
-# 7. Fail-Soft Skill Component Discovery
-
-Refactor active Skill component listing so it returns valid entries and failures together.
-
-Conceptually:
-
-```ts
-interface SkillComponentInventory {
-  components: ActiveSkillRecipeComponent[];
-  rejected: SkillComponentDiagnostic[];
-  partial: boolean;
-}
-```
-
-Rules:
-
-- invalid top-level `Recipe.name` rejects that component;
-- nested Recipe files reject those files/that namespace as appropriate;
-- JSON/Markdown same-stem collision rejects that stem;
-- one duplicate active Skill identity may invalidate that Skill namespace;
-- unrelated Skill namespaces continue;
-- every rejection is bounded and diagnosable;
-- exact resolver remains independent and may resolve a valid exact component while catalog inventory is partial.
-
-Do not silently omit bad components.
-
----
-
-# 8. Launch-Kind Truth
-
-Keep existing usage distinctions:
-
-```text
-tool
-spawn
-direct Recipe/foreground execution where applicable
-```
-
-At minimum:
-
-- `spawn` result/details expose `launch_kind: "spawn"`;
-- registered tool invocation evidence exposes `launch_kind: "tool"`;
-- `inspect tool` usage summary distinguishes tool calls from Recipe spawn calls;
-- no product copy describes `spawn recipe=<user-wrapper>` as invoking the registered tool.
-
-Do not add a second generic invocation mechanism just for testing.
-
----
-
-# 9. Work Items
-
-## RGT-12 — Publish `0.46.1`
-
-**Goal:** ship the prepared registration-truth release before agent UX redesign.
-
-**State:** gated on explicit release intent and repository `ADMIN` authority.
-
-**Remaining:**
-
-- Run the existing guarded GitHub release flow for prepared version `0.46.1`.
-- Verify npm package identity/provenance and GitHub Release convergence.
-- After successful publication, reset this backlog to:
-
-```text
-# Project Backlog
-
 No open items.
-```
-
-**Unblocker:** the operator explicitly authorizes the `0.46.1` release and confirms `ADMIN` permission for this repository.
-
-**Dependencies:** none.
-
----
-
-# 10. Dependency Graph
-
-```text
-RGT-12
-```
-
-Integration hotspots:
-
-```text
-lib/extension-runtime.ts
-lib/recipes-references.ts
-lib/recipes-discovery.ts
-lib/runtime.ts
-lib/registry.ts
-lib/tools-register.ts
-lib/tools-local.ts
-lib/tools-inspect.ts
-lib/schema.ts
-lib/recipes-usage.ts
-```
-
-Use one integration owner for resolution/admission semantics.
-
----
-
-# 11. Required Test Matrix
-
-| Boundary               | Required evidence                                                 |
-| ---------------------- | ----------------------------------------------------------------- |
-| Live context           | spawn/register/registry/inspect share exact session Skill context |
-| Session isolation      | no context bleed across sessions/replacements                     |
-| Startup                | Skill-dependent user tools reconcile after active Skills known    |
-| Watcher                | reload uses current context/generation, stale callback fenced     |
-| Delegation             | compact wrapper inherits effective Recipe contract                |
-| Invalid wrapper        | rejected before persistence with precise diagnostic               |
-| Schema ownership       | runtime-owned values absent                                       |
-| Schema types           | enum/bool/int/path/array retained                                 |
-| Defaults               | wrapper overrides validated against effective types               |
-| Catalog                | unrelated bad component yields partial inventory                  |
-| Exact resolution       | valid component resolves despite unrelated rejection              |
-| Registry observability | generation/time/watch/current counts available                    |
-| Registration           | persisted/active/host/callable states separated                   |
-| Rollback               | failed update preserves previous working tool                     |
-| Pi host                | same-session injection proven or truthful limitation returned     |
-| Launch kind            | tool vs spawn explicit in result/usage                            |
-| Source/dist            | same behavior in repository and packed install                    |
-| Security               | path/CAS/redaction/generation/review safety retained              |
-
----
-
-# 12. Explicitly Deferred to `0.47.0`
-
-Only the **agent interface/guidance layer** is deferred:
-
-```text
-register_tool from=<skill>/<recipe>
-register_tool defaults={...}
-system prompt redesign as Skill-loading meta-protocol
-actors Skill redesign as root agent operating protocol
-capability Skill description/entrypoint redesign
-agent-facing delegation-vs-import decision guidance
-focused resolution explanation UX
-fresh-agent journey dogfood
-human-doc vs agent-Skill separation cleanup
-```
-
-Do not defer any known runtime inconsistency from the report.
-
----
-
-# 13. Negative Scope
-
-Do not add:
-
-```text
-new Run nouns
-new Run views
-new generic invocation tool
-new recipe target namespace
-task graph runtime
-actor chat
-rooms/peers/mailboxes
-remote Recipe registry
-compatibility std:/skill: aliases
-copied packaged Recipe wrappers
-shell fallbacks
-new capability-authoring Skill
-large system-prompt rewrite
-```
-
----
-
-# 14. Stop Conditions
-
-Stop and preserve evidence if:
-
-- Pi cannot dynamically expose a newly registered tool in the same session and the product cannot observe the activation boundary;
-- one authoritative user Recipe admission path cannot serve registry and `register_tool`;
-- session-scoped Skill-dependent tools require global mutable state;
-- rollback would overwrite concurrent user edits;
-- schema ownership cannot distinguish runtime and caller values without changing Recipe semantics;
-- fixing a failure appears to require copying a Skill Recipe contract into the user wrapper.
-
-Resolve blockers at the owning boundary rather than hiding them with agent guidance.

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.47.0: Agent-Native Actor UX
+
+- `Skill-First Operation`: Replaced the injected product manual with a compact Skill-routing meta-protocol. `actors` is now the decision-first authority for generic Recipe/tool/Run mechanics, capability Skills own capability choice, and `swarm` owns only multi-actor methodology.
+- `Persistent Capability Authoring`: Added explicit, mutually exclusive `register_tool from`, `template`, and `draft` modes; public caller `defaults`; canonical Skill/file resolution; compact direct delegation; inherited descriptions, async contracts, typed args, artifacts, Control, and runtime origins; and removal of public `values`.
+- `Registration Truth UX`: Registration now reports logical source, effective required/optional args, persistence, registry/host/active-tool state, callability, activation boundary, and bounded next actions without raw config or executable template payloads. Failed activation retains rollback guarantees.
+- `Focused Diagnosis`: Added `inspect target=recipes view=doctor identity=<skill>/<recipe>` with active ownership, exact resolvability, partial-catalog state, portable source, generation, rejection, and next actions. Tool status now includes source, effective args, activation boundary, and separate spawn/tool usage.
+- `Capability Protocols`: Rewrote all six Skill descriptions as routing triggers and made Media, Artifacts, Project Work, and Recipe Memory compact agent operating guides. Human installation, product, catalog, development, and release guidance remains independently owned by README/docs.
+- `Swarm Methodology`: Reduced Swarm to overhead admission, decomposition, disjoint ownership, lenses, quorum, conflict evidence, integration, and stop rules; moved deep review/development methods to Skill-local references and delegated all generic Run/Recipe mechanics to `actors`.
+- `Safe Recovery`: Inactive, missing, duplicate, removed, malformed, rejected, partial-catalog, and inactive-tool failures now preserve logical identity, redact physical Skill paths, and teach bounded public diagnosis/retry actions without copied contracts, helper paths, shell evaluation, backgrounding, or spawn substitution.
+- `Journey and Package Evidence`: Added deterministic Journeys A-G, reviewed fresh-agent Journey B evidence, and packed first-session parity for final Skills/prompt/references, `from` registration, source-equivalent schema, same-session activation, focused doctor, actual tool invocation, and unshipped `.agents/` evidence.
+
 ## 0.46.1: Registration Truth
 
 - `Live Resolution`: Spawn, registration, registry admission/reload, schema derivation, and Inspect now consume one immutable session Recipe context. Skill-dependent user wrappers reconcile only after Pi supplies active Skills, watcher reloads retain the current generation, and stale session consumers fail closed.

package/README.md

@@ -74,6 +74,7 @@ inspect target=run:test view=trace source=lifecycle lines=40
 inspect target=run:test view=control
 inspect target=runtime view=status
 inspect target=recipes view=status
+inspect target=recipes view=doctor identity=media/player
 inspect target=tool:my_tool view=status
 ```
 
@@ -81,7 +82,7 @@ A Run exposes exactly `recipe`, `trace`, and `control` views.
 
 ### `register_tool`
 
-Persist a trusted command template or Recipe-backed capability under `~/.pi/agent/recipes`. Registration remains separate from running Control. Treat it as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
+Persist a maintained Recipe with `register_tool name=<tool> from=<skill>/<recipe> defaults={...}`, or register a trusted command through the separate `template` mode. Definitions live under `~/.pi/agent/recipes`. Treat a tool as callable in the current session only when the result reports `callable_now: true`; persistence, Recipe spawning, and registered-tool invocation are distinct states.
 
 ## Recipe
 

package/dist/lib/prompts.d.ts

@@ -4,20 +4,21 @@
  * Owns LLM-facing descriptions, prompt snippets, guidelines, and parameter descriptions
  */
 export declare const REGISTER_TOOL_DESCRIPTION: string;
-export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent command templates as agent-callable tools";
+export declare const REGISTER_TOOL_PROMPT_SNIPPET = "Register persistent Recipes or command templates as agent-callable tools";
 export declare const REGISTER_TOOL_GUIDELINES: string[];
-export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors quick model:\n- Local-first actor memory: persist trusted local capabilities instead of rebuilding shell recipes.\n- Layers: task -> command template -> recipe/tool -> spawn -> run:<id>; tool:<name> wraps registered capabilities.\n- Command templates stay sync and shell-free: string leaves split into executable + argv, infer .js/.mjs through node\u2192bun\u2192deno run and .sh through bash, and treat operators such as && as literal arguments; use template arrays for sequencing or an explicit trusted shell/script when shell semantics are required. Flags include args/defaults, parallel, concurrency, min_successful, when, timeout, delay, retry, failure, recover, repeat, accept_output, output.\n- Placeholders support typed/default args plus {value??fallback} and {flag?yes:no}.\n- ~/.pi/agent/recipes/*.json is actor muscle memory: valid admitted recipes are reconciled as tools across sessions; register_tool writes there and reports current activation truth.\n- Recipes own template directly and may declare metadata/defaults/imports/control/artifacts; files >1 MiB or import depth >32 fail closed.\n- Recipe imports are local variables; imported recipes are definitions, not nested async runs; parent async:true creates one run.\n- Actor-mode trigger: if work may outlive this turn, need steering/follow-up/artifacts, run as a service, fan out, or be resumed/inspected later, use spawn -> message -> inspect instead of ad hoc shell backgrounding.\n- Use spawn/message/inspect for actor-level start/send/observe; short foreground checks can stay ordinary tools/templates; avoid internal transport vocabulary in public guidance.\n- Run state lives under ~/.pi/agent/tmp/pi-actors/runs. Inspect intentionally and avoid busy-polling. Terminal and coordinator-bound notifications queue as Pi follow-ups so concurrently completed actors can reach the coordinator after current work instead of steering between tool calls. Terminal follow-up content stays minimal: run, status, one base path, and relative artifact names only; semantic output stays in non-LLM details and run state. When a deferred actor result gates the next step, wait for its terminal follow-up; do not schedule continuation loops, repeatedly inspect, or mutate its reviewed scope while it runs. Inspect early only for an operator request, a meaningful actor event, or diagnosis of an overdue/stuck run.\n- Maintain ~/.pi/agent/recipes like MEMORY.md for capabilities: keep useful tools, curate stale ones, and fix/remove/disable invalid recipes flagged by registry warnings; active-Skill and explicit file Recipes remain components outside user tool discovery; offer to save successful recurring patterns only after confirmation.\n- Prefer maintained active-Skill Recipes with spawn recipe=<skill>/<recipe> before ad hoc scripts/wrappers; explicit file Recipes use exact .json/.md paths; review swarms inherit current model/thinking, preflight before fanout, and expose quorum/concurrency/TTL knobs unless explicit args are passed.\n- For any non-trivial actor use or pi-actors change, read the bundled actors skill first. Before launching multiple actors/subagents for parallel implementation, independent artifact generation, delegated audit, or review, also read the bundled swarm skill; the coordinator owns decomposition, disjoint scopes, launch correctness, integration, and final validation. For deeper guidance, inspect installed extension sources/docs/recipes because README/docs are not automatically in context.";
+export declare const ONBOARDING_SYSTEM_PROMPT = "pi-actors Skill routing:\n- Treat active bundled Skills as the operating authority.\n- For non-trivial pi-actors operation, diagnosis, or development, load and read the actors Skill before acting.\n- For work requiring multiple actors or subagents, additionally load and read the swarm Skill.\n- For capability-specific selection or constraints, load the owning capability Skill; actors owns generic mechanics and swarm owns multi-actor methodology.\n- Keep a Skill Recipe distinct from a registered tool and a Recipe spawn distinct from registered-tool invocation; actors owns the proof rules.\n- Treat persistence or registration as distinct from current callability; actors owns activation proof.\n- On failure or disagreement, preserve the logical Recipe identity, stop, and follow actors diagnosis; never bypass the owning Skills with copied contracts, helper paths, shell evaluation, or background-process workarounds.\n- If a capability Skill conflicts with actors about generic mechanics, follow actors and report the stale capability guidance.\n- README and docs are human-facing references, not the normal agent operating path.\n- AGENTS, source, and tests are implementation protocol and evidence; use them when changing or debugging the extension, not as substitutes for operating Skills.";
 export declare const REGISTER_TOOL_PARAM_DESCRIPTIONS: {
     readonly name: "Tool name in snake_case (e.g., 'transcribe')";
     readonly description: "Describe what the tool does for the LLM. Required unless deleting; omitted updates keep the old description.";
-    readonly draft: "Promote a draft recipe path from ~/.pi/agent/recipes/drafts into an active named recipe under ~/.pi/agent/recipes. Requires name; use update=true to overwrite.";
+    readonly from: "Recipe to specialize by canonical <skill>/<recipe> identity or explicit .json/.md path. Inherits async, args/types, source defaults, artifacts, Control, and runtime origins.";
+    readonly defaults: "Optional caller-owned defaults. Keys and values must satisfy the effective source or command-template argument contract.";
+    readonly draft: "Promote a captured draft Recipe path from ~/.pi/agent/recipes/drafts. This is a source mode; do not combine it with from or template.";
     readonly async: "Set true for a co-located async template recipe. Omit for ordinary command templates or file-backed recipe references.";
-    readonly template: "Command template with {arg} or {arg=default} placeholders, or a template recipe JSON path/name. With async, this is the co-located recipe body. Bare recipe names resolve under ~/.pi/agent/recipes. Omitted updates keep the old template. Empty string deletes the tool.";
+    readonly template: "Trusted command template with {arg} or {arg=default} placeholders. To specialize a Recipe, use from instead. Omitted updates keep the old template; empty string deletes the tool.";
     readonly templateArray: "Sequential command-template composition array. Leaves may be strings or objects with template/defaults/timeout/retry/failure/recover.";
     readonly templateNull: "Delete the tool when template is null.";
     readonly args: "Optional comma-separated placeholder declarations. Usually omit because args are derived from template placeholders. Interactive shorthand defaults are accepted and normalized. Example: file,lang,mode=fast";
     readonly update: "Set to true to overwrite an existing tool registration.";
-    readonly values: "Optional default runtime placeholder values for a co-located template recipe.";
 };
 export declare function formatRegisteredToolPromptSnippet(template: unknown): string;
 export declare function formatRecipeToolPromptSnippet(recipe: string, asyncRecipe: boolean): string;