@llblab/pi-actors 0.15.0 → 0.16.1

package/BACKLOG.md

@@ -2,18 +2,54 @@
 
 ## Open Work
 
-No open release-blocking work remains for `0.15.0`.
+No release-blocking work remains for `0.16.0`.
 
-The former active tracks are now release-ready:
+## Future Work
 
-- Universal actor communication: public guidance centers `spawn`, `message`, `inspect`, actor messages, mailbox contracts, and artifacts; low-level lifecycle/storage wording is confined to implementation/diagnostic docs.
-- Component parameterization and composition: packaged recipes are policy-light, require caller-provided model/model-pool policy, expose reusable knobs, validate imports/mailboxes, and are covered by the actors Recipe Navigator.
-- Structured utility transforms: current utility surface is sufficient for shipped pipelines; add future utilities only when a repeated packaged-pipeline need appears.
+### Recipe Registry Curation UX
 
-## Future Work
+- Priority: Medium.
+- Status: `inspect target=recipes view=status|summary` exposes active, shadowed, invalid, disabled, and diagnostic recipe state. User-owned recipes track extension-maintained `usage.calls` and `usage.last_called`.
+- Goal: Help operators curate the sticky `~/.pi/agent/recipes` tool surface without automatic deletion or demotion.
+- Direction:
+  - Include usage fields in recipe registry summaries.
+  - Add cleanup recommendations for stale, duplicate, low-use, too-specific, invalid, disabled, and shadowing recipes.
+  - Recommend explicit actions only: keep as tool, set `tool: false`, merge, delete, or archive.
+  - Keep cleanup operator-gated; never silently delete or demote during unrelated work.
+- Exit:
+  - Operators can ask why a recipe/tool exists and what cleanup action is reasonable without reading files manually.
 
-- Add new utilities or pipelines only when a concrete repeated task pattern justifies them.
-- Continue opportunistic actor-vocabulary cleanup when touching implementation docs or diagnostics.
+### Host-Level Tool Unregistration
+
+- Priority: Low.
+- Status: Deleted recipe files are removed from the active tool set on reactive reload; host-level registered tool definitions cannot currently be unregistered by this extension.
+- Goal: Remove stale dynamically registered tool definitions completely when the host API supports it.
+- Direction:
+  - Track pi extension API support for custom tool unregistration.
+  - Replace active-tool deactivation fallback with real unregister when available.
+  - Preserve current safe behavior: deleted tools should not remain active after reload.
+- Exit:
+  - Deleting a recipe file removes the corresponding runtime tool definition and active-tool entry without session restart.
+
+### Recipe Discovery Expansion
+
+- Priority: Low.
+- Direction:
+  - Add nested recipe directories only after flat `recipes/*.json` discovery semantics are stable.
+  - Keep same-id priority and invalid-blocking behavior explicit if nested ids are introduced.
+
+### Recipe Usage Telemetry Evolution
+
+- Priority: Low.
+- Direction:
+  - Consider sidecar stats sync/backup policy after inline user-owned `usage.calls` / `usage.last_called` proves useful.
+  - Do not add failure counters as primary usefulness evidence unless there is a strong operator-facing need.
+
+### Opportunistic Recipe Library Growth
+
+- Priority: Low.
+- Direction:
+  - Add new utilities or pipelines only when a concrete repeated task pattern justifies them.
 
 ## Blocked Work
 

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.16.1: Recipe Registry Hotfix
+
+- `[Runtime]` Prevented invalid user recipe files from aborting extension startup when tool-schema generation fails, surfacing a warning and skipping the offending tool instead. Impact: one bad recipe in `~/.pi/agent/recipes` no longer takes down the pi-actors extension.
+- `[Recipe Discovery]` Excluded the legacy migration report file from recipe discovery. Impact: `actors-tools-migration-report.json` no longer appears as a broken recipe/tool candidate after migration.
+- `[Package]` Bumped package and packaged skill metadata to `0.16.1` for the hotfix release.
+
+## 0.16.0: File-Discovered Recipe Registry Migration
+
+- `[Version]` Began the `0.16.0` breaking-change cycle and captured the file-discovered recipe registry migration plan in `BACKLOG.md`. Impact: the next release target is now explicit: replace `actors-tools.json` as live registry with validated recipe files, filename identity, `tool` exposure, override/disable semantics, migration reporting, registry inspection, and usage-informed cleanup.
+- `[Recipe References]` Started filename-identity support for recipes by deriving the recipe id from the JSON filename when `name` is omitted, while preserving optional `tool`, `disabled`, and `description` metadata through recipe resolution. Impact: new recipe files can move toward filename-as-identity without losing human-readable descriptions or tool exposure flags.
+- `[Recipe Discovery]` Added an initial file-discovered recipe registry domain with flat root scanning, filename ids, priority shadowing, invalid high-priority recipe blocking, disabled overrides, and `tool: true` exposure detection. Impact: the 0.16 registry migration now has a tested discovery core before wiring it into runtime loading.
+- `[Recipe Migration]` Added a legacy registry migration domain that converts `actors-tools.json` entries into user recipe files with `tool: true`, preserves descriptions/args/defaults/templates, refuses to overwrite existing recipe files, writes a migration report, and archives the source only when migration has no conflicts or invalid entries. Impact: the breaking registry transition now has a tested compatibility path from the old live registry.
+- `[Recipe Discovery]` Captured the priority model that treats packaged pi-actors recipes as a standard library below ad hoc user-selected recipe files and below `~/.pi/agent/recipes/*.json`, with priority applying only to matching filename ids. Impact: override behavior now has a documented lens and a regression for standard-library versus user recipe precedence.
+- `[Recipe Discovery]` Added source-level default tool exposure so the high-priority user recipe root can behave as the operator-managed tool set by default, while packaged/ad hoc recipes stay component-like unless they opt in with `tool: true` and any recipe can opt out with `tool: false`. Impact: 0.16 keeps the discoverability advantage of the old tool-only registry without forcing a separate live tool config.
+- `[Runtime]` Wired session-start tool loading to migrate the legacy registry, discover recipe-file tools from `~/.pi/agent/recipes` and packaged recipes, and register only active exposed recipes as runtime tools. Impact: the new recipe-discovered registry path is now active in runtime loading instead of only existing as standalone discovery/migration helpers.
+- `[Registry]` Changed `register_tool` persistence to write/update/delete user recipe files under the recipe root instead of mutating the legacy JSON registry, while still activating the tool in the current session. Impact: newly registered tools now enter the 0.16 recipe-discovered registry directly.
+- `[Docs]` Reworked tool-registry documentation, README examples, recipe docs, actor skill guidance, and prompt copy around recipe-file persistence, the user recipe directory as the default tool set, packaged recipes as standard-library components, and `actors-tools.json` as legacy migration input. Impact: public guidance now matches the 0.16 runtime path instead of the old live JSON registry.
+- `[Skill]` Added actors-skill guidance for same-name recipe priority, recipe-root-as-muscle-memory, usage counters, and an explicit cleanup rule for stale/default tools without automatic deletion or demotion. Impact: agents get the override model, sticky-tool tradeoff, and cleanup heuristic directly in the compact operational reference.
+- `[Recipe Usage]` Added extension-maintained recipe launch metadata updates for user-owned runtime tools and direct async recipe starts, tracking `usage.calls` and `usage.last_called` without failure counters while leaving packaged standard-library recipes immutable, then documented the cleanup interpretation in recipe and tool-registry docs. Impact: the operator-managed recipe/tool set now accrues cleanup evidence for muscle-memory review from actual extension launches rather than manual agent bookkeeping.
+- `[Runtime]` Added a best-effort user recipe-root watcher that debounces file changes and reloads recipe-backed tools during the active session, plus runtime-tool fingerprinting so repeated reloads do not re-register unchanged tools while changed definitions refresh, and stale recipe tools are removed from the active tool set on reload when their recipe disappears. Impact: newly created or edited valid recipe files can be connected without a full restart, without duplicate registration churn for unchanged recipes, while deleted recipe tools are deactivated even though host-level unregistration is still not available.
+- `[Recipe Discovery]` Added a discovery summary helper and wired/documented `inspect target=recipes view=status|summary` to report active, shadowed, invalid, disabled, and diagnostic recipe entries. Impact: the registry inspection surface can explain why tools are present, hidden, broken, or disabled from the normal actor inspection tool.
+- `[Backlog]` Reconciled 0.16 planning state after implementation of the core runtime path, usage counters, and reactive recipe reload behavior. Impact: remaining open work is now framed as hardening, inspection UX, and release validation instead of rediscovering already implemented pieces.
+- `[Docs]` Normalized registry examples toward filename/tool ids that match the snake_case tool naming convention, avoiding mixed hyphen/underscore examples around `docs_review`, and aligned package image metadata with the local pi-actors banner. Impact: recipe identity, generated tool naming, and package presentation are less ambiguous in 0.16 guidance.
+- `[Backlog]` Reconciled the recipe registry inspection surface after wiring the initial `inspect target=recipes` summary, then closed the active `0.16.0` release backlog by moving remaining non-blocking ideas to future curation, host-unregistration, discovery expansion, telemetry evolution, and opportunistic recipe-library sections. Impact: the backlog now distinguishes completed release scope from future follow-up work.
+
 ## 0.15.0: Packaged Actors Skill And Actor Vocabulary Cleanup
 
 - `[Skill]` Reworked the packaged `actors` skill as a dense self-contained extension reference rather than a scenario catalog or changelog narrative, bundled the `swarm` methodology skill alongside it, synchronized packaged skill metadata versions with the package version, included `skills/` in the npm package contents, registered both skills in package metadata, and linked them from the README start points. Impact: fresh agents get compact practical coverage of pi-actors operation plus complementary multi-agent methodology without duplicating the two roles.

package/README.md

@@ -1,6 +1,8 @@
 # pi-actors
 
-Actor runtime and orchestrator for agent-managed local processes.
+> Actor runtime and orchestrator for agent-managed local processes.
+
+[<img alt="Actors*" src="banner.jpg" />](https://github.com/llblab/pi-actors "pi-actors")
 
 `pi-actors` turns local programs, scripts, services, recipes, and long-running processes into addressable actors that agents can start, message, inspect, and compose. A music player, a sub-agent fanout, a repo-health pipeline, or any trusted local process can become an actor when it has a template-backed launch path, a mailbox contract, and observable runtime state.
 
@@ -44,7 +46,7 @@ The key move is not just “register a command.” It is to wrap a process in an
 - **Control**: `message` sends typed envelopes to runs, branches, tools, or the coordinator.
 - **Observation**: `inspect` reads status, logs, messages, mailbox metadata, files, and artifacts intentionally.
 - **Persistence**: `artifacts` and state files make outcomes durable.
-- **Memory**: `actors-tools.json` stores reusable actor-control wrappers across sessions.
+- **Memory**: `~/.pi/agent/recipes/*.json` stores reusable actor-control wrappers across sessions.
 
 ## Key Features
 
@@ -52,7 +54,7 @@ The key move is not just “register a command.” It is to wrap a process in an
 - **Agent-Managed Processes**: Wraps sub-agents, media players, pipelines, diagnostics, and other local programs as controllable entities instead of one-off commands.
 - **Message-Oriented Control**: Uses `spawn`, `message`, and `inspect` as the public coordination vocabulary for start, control, and observation.
 - **Mailbox Contracts**: Lets recipes declare what messages they accept and emit, so agents can discover how to interact with an actor.
-- **Actor Tool Registry**: Stores persistent actor-control tool definitions in `~/.pi/agent/actors-tools.json` and registers them automatically on session start.
+- **Actor Tool Registry**: Stores persistent actor-control tools as recipe files in `~/.pi/agent/recipes/*.json` and registers them automatically on session start.
 - **Command Template Substrate**: Keeps process launch portable with named placeholders, typed args, defaults, sequences, guarded nodes, retries, failure policy, and `parallel: true` fanout.
 - **Composable Actor Recipes**: Stores reusable recipe JSON under `~/.pi/agent/recipes/*.json`; recipes can import other recipes, reuse defaults, declare artifacts, and opt into detached actor lifecycle with `async: true`.
 - **Coordinator-Scoped Observability**: Shows ambient triangles for active actor runs and sends compact completion or request-for-attention follow-ups only to the launching coordinator.
@@ -73,27 +75,17 @@ From git:
 pi install git:github.com/llblab/pi-actors
 ```
 
-## Rename Migration
+## Registry Migration
 
-`pi-actors` reads persistent actor-control tools from:
+`pi-actors` now reads persistent actor-control tools from:
 
 ```text
-~/.pi/agent/actors-tools.json
-```
-
-If you previously used `pi-auto-tools`, copy the old registry intentionally:
-
-```bash
-cp ~/.pi/agent/auto-tools.json ~/.pi/agent/actors-tools.json
+~/.pi/agent/recipes/*.json
 ```
 
-If you installed the brief `0.12.0`/`0.12.1` line and created `tools.json`, copy that file instead:
+That directory is the operator-managed tool set: user recipe files there become tools by default unless they set `tool: false`. Packaged recipes are the lower-priority standard library of declarative actor components and opt into tools with `tool: true`.
 
-```bash
-cp ~/.pi/agent/tools.json ~/.pi/agent/actors-tools.json
-```
-
-The extension does not silently rewrite old registry files; keep or delete the old file after confirming the new registry loads as expected.
+If `~/.pi/agent/actors-tools.json` exists from an older release, pi-actors treats it as legacy compatibility input, migrates entries into recipe files when possible, writes a migration report, and archives the legacy file only when migration is clean.
 
 ## Mental Model
 
@@ -129,7 +121,7 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
 
 ```json
 {
-  "name": "docs-review",
+  "name": "docs_review",
   "async": true,
   "args": ["scope:path", "model:string"],
   "defaults": {},
@@ -144,7 +136,7 @@ Move to actor recipes when work is long-running, parallel, service-like, or agen
 Expose a reusable actor recipe as a normal capability:
 
 ```text
-register_tool name=docs_review description="Start an async docs review actor" template="docs-review.json" args="scope:path,model:string"
+register_tool name=docs_review description="Start an async docs review actor" template="docs_review" args="scope:path,model:string"
 ```
 
 `Task` is the user's work item. `Template` is the execution graph. `Actor recipe` is saved JSON. `Run` is one actor instance with status, logs, messages, cancellation, artifacts, and ambient triangles.
@@ -213,27 +205,25 @@ For reusable actor workflows, keep the large template and mailbox contract in a
 ```text
 register_tool name=docs_review \
   description="Start an async docs review actor" \
-  template="docs-review.json" \
+  template="docs_review" \
   args="scope:path,model:string"
 ```
 
 If the recipe file contains `async: true`, calling `docs_review` starts a detached run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
-A recipe can also be co-located in `actors-tools.json` when keeping metadata and the recipe body together is clearer:
+When keeping metadata and the recipe body together is clearer, `register_tool` writes a complete user recipe file:
 
 ```json
 {
-  "review_docs": {
-    "description": "Start an async docs review",
-    "name": "review-docs",
-    "async": true,
-    "args": ["scope:path", "model:string"],
-    "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
-  }
+  "description": "Start an async docs review",
+  "tool": true,
+  "async": true,
+  "args": ["scope:path", "model:string"],
+  "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
 }
 ```
 
-A co-located recipe entry still cannot define `tool`; it must own `template` directly.
+The filename is the recipe id/tool name, `async: true` selects detached run mode, and `template` remains the executable body.
 
 ### Sub-agent
 
@@ -257,30 +247,28 @@ Delete a tool:
 register_tool name=call_subagent template=null
 ```
 
-## Resulting Config
+## Resulting Recipe Files
 
-The commands above persist entries like this in `~/.pi/agent/actors-tools.json`; tool names come from the top-level keys. Stored entries keep `template` last so flags and metadata are read before executable content:
+The commands above persist files under `~/.pi/agent/recipes/`. Tool names come from recipe filenames. Stored recipes keep `template` last so flags and metadata are read before executable content:
 
 ```json
 {
-  "transcribe": {
-    "description": "Transcribe a local audio file",
-    "template": "/path/to/stt --file {file} --lang {lang=ru}"
-  },
-  "call_subagent": {
-    "description": "Run pi as a non-interactive sub-agent",
-    "args": ["prompt:string", "model:string"],
-    "template": "pi -p --model {model} --no-tools {prompt}"
-  },
-  "docs_review": {
-    "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string"],
-    "template": "docs-review.json"
-  }
+  "description": "Transcribe a local audio file",
+  "tool": true,
+  "template": "/path/to/stt --file {file} --lang {lang=ru}"
+}
+```
+
+```json
+{
+  "description": "Run pi as a non-interactive sub-agent",
+  "tool": true,
+  "args": ["prompt:string", "model:string"],
+  "template": "pi -p --model {model} --no-tools {prompt}"
 }
 ```
 
-This file is the durable actor-tool registry. `register_tool` is the interactive API; `actors-tools.json` is the persisted state that is loaded on future sessions.
+The recipe directory is the durable actor-tool registry. `register_tool` is the interactive API; recipe files are the persisted state loaded on future sessions.
 
 ## Manage Actors
 

package/docs/template-recipes.md

@@ -21,6 +21,8 @@ A recipe wraps one command-template tree. The wrapped `template` keeps the norma
 
 Layer boundary: `imports`, `{ "name": "alias" }` imported-recipe nodes, `{alias.defaults.key}` references, fallback expressions, and recipe-local ternaries are recipe-loading features. They resolve before the command-template graph runs and do not extend the portable Command Template Standard. Typed imports are recipe definitions: they expose the imported recipe's command-template-shaped metadata (`template`, `args`, `defaults`, flags, and `values`), while async-run launch fields such as `async` and `state_dir` remain lifecycle configuration for starting a run, not part of the imported execution graph.
 
+Packaged recipes are the pi-actors recipe standard library: declarative actor config components that can be imported, launched, inspected, overridden, or composed by user recipes. Treat them as stable building blocks rather than user-local policy.
+
 ## Layer Ownership
 
 Template-recipe standard owns:
@@ -67,6 +69,36 @@ Async recipe:
 
 `name` names the saved definition when an explicit name is needed. File-backed recipes usually omit it because the filename is the canonical recipe id. `template` is the command-template tree. `async: true` selects detached run mode when the recipe is invoked through a registered tool.
 
+## Discovery Priority
+
+Recipe priority only matters when two discovered recipes have the same filename id. The conceptual ladder from lowest to highest priority is:
+
+1. No recipe for that id.
+2. Packaged pi-actors recipe components, acting as the standard library.
+3. Explicitly referenced ad hoc user recipe files located outside `~/.pi/agent/recipes`.
+4. User recipe files under `~/.pi/agent/recipes/*.json`.
+
+The high-priority user recipe directory is also the default tool set: recipes placed there are agent tools unless they explicitly set `tool: false`. This preserves the old advantage of a tool-only registry because listing `~/.pi/agent/recipes` shows the operator-managed tool surface. Packaged and ad hoc recipes are recipe components by default; they opt into agent-tool exposure with `tool: true`.
+
+Higher-priority files shadow lower-priority files with the same basename. A highest-priority invalid recipe is still visible and blocks fallback so operators do not accidentally run packaged behavior when a user override is broken. A highest-priority recipe with `disabled: true` also blocks fallback and intentionally disables that id.
+
+## Usage Metadata
+
+User-owned recipes may accumulate extension-maintained usage metadata:
+
+```json
+{
+  "usage": {
+    "calls": 12,
+    "last_called": "2026-05-22T10:30:00.000Z"
+  }
+}
+```
+
+The extension increments `usage.calls` and updates `usage.last_called` when it starts that concrete recipe, either through a recipe-backed tool call or a direct async recipe-file run. Agents should treat these fields as cleanup evidence, not as authored recipe contract. Packaged standard-library recipes are not mutated for usage metadata.
+
+There is intentionally no failure counter in the recipe contract. A failed launch can reflect caller misuse, missing runtime values, or an environmental problem rather than recipe uselessness. Cleanup decisions should be explicit operator work: keep as a tool, set `tool: false`, merge, delete, or archive.
+
 For object form, keep `template` last. Recipe metadata comes first; executable content stays last.
 
 ## Named Artifacts
@@ -171,34 +203,19 @@ Call-time params override file params. `values` are merged with file values; cal
 
 ## Registered Recipe Tools
 
-A registered tool can point at an actor recipe by storing the recipe path or name in `template`:
+A registered tool is a recipe file exposed as an agent tool. User recipes under `~/.pi/agent/recipes/*.json` are tools by default; packaged/ad hoc recipes opt in with `tool: true`:
 
 ```json
 {
-  "docs_review": {
-    "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string"],
-    "template": "docs-review.json"
-  }
-}
-```
-
-If `docs-review.json` contains `async: true`, calling `docs_review` starts a detached actor run and returns metadata. If `async` is omitted or false, calling `docs_review` executes the recipe foreground and returns normal tool output.
-
-A registered tool may also co-locate an actor recipe directly in `actors-tools.json`:
-
-```json
-{
-  "review_docs": {
-    "description": "Start an async docs review",
-    "name": "review-docs",
-    "async": true,
-    "template": "review {scope}"
-  }
+  "description": "Start an async docs review actor",
+  "tool": true,
+  "async": true,
+  "args": ["scope:path", "model:string"],
+  "template": "review {scope} --model {model}"
 }
 ```
 
-The co-located entry must still own `template` directly and must not define `tool`.
+If a tool recipe contains `async: true`, calling the tool starts a detached actor run and returns metadata. If `async` is omitted or false, calling the tool executes the recipe foreground and returns normal tool output.
 
 ## Values And Public Args
 

package/docs/tool-registry.md

@@ -1,33 +1,43 @@
 # Tool Registry
 
-`pi-actors` stores registered actor-control command-template tools and template-recipe launchers in `~/.pi/agent/actors-tools.json` and registers them automatically on session start.
+`pi-actors` stores persistent agent tools as recipe files under `~/.pi/agent/recipes/*.json` and registers the active tool set automatically on session start.
 
-This document is the local adaptation of the portable [Command Template Standard](./command-templates.md).
+This document is the local adaptation of the portable [Command Template Standard](./command-templates.md) and the recipe-file runtime described in [Template Recipe Standard](./template-recipes.md).
 
-## Rename Migration
+## Registry Model
 
-`pi-actors` reads only `~/.pi/agent/actors-tools.json` as its registry source. When moving from `pi-auto-tools`, copy the previous registry explicitly:
+The 0.16 registry source is file-discovered recipes, not a live tool-only JSON file:
 
-```bash
-cp ~/.pi/agent/auto-tools.json ~/.pi/agent/actors-tools.json
-```
+- `~/.pi/agent/recipes/*.json` is the highest-priority user recipe root and the operator-managed tool set.
+- Recipes in that root are tools by default.
+- `tool: false` keeps a user recipe file recipe-only.
+- Packaged pi-actors recipes are the lower-priority standard library of declarative actor config components.
+- Packaged or ad hoc recipes opt into tool exposure with `tool: true`.
+- Recipe identity is the filename basename; `~/.pi/agent/recipes/docs_review.json` has id/tool name `docs_review`.
+
+`~/.pi/agent/actors-tools.json` is legacy compatibility input. On startup, pi-actors migrates it into recipe files when possible, writes a migration report, and archives the source only when migration has no conflicts or invalid generated recipes.
+
+Because the user recipe directory is sticky agent muscle memory, runtime launches update `usage.calls` and `usage.last_called` on user-owned recipe files. Use that evidence during focused cleanup passes: keep valuable tools, set `tool: false` for useful components that should leave the active tool surface, merge duplicates, or delete/archive low-value files. The extension does not maintain a failure counter and agents should not silently clean tools during unrelated work.
 
-If a short-lived `~/.pi/agent/tools.json` file exists from the early `pi-actors` rename window, copy that file instead:
+`register_tool` is the preferred agent-facing mutation API. It creates, updates, and deletes recipe files in `~/.pi/agent/recipes`; agents do not need to edit the files directly for normal registration. Direct file edits are still valid for operators and advanced agents. Runtime behavior is reactive: file creation, deletion, or edits in the user recipe root trigger validation and tool-set refresh, with invalid recipes surfaced as diagnostics rather than silently ignored.
 
-```bash
-cp ~/.pi/agent/tools.json ~/.pi/agent/actors-tools.json
+Inspect the discovered registry with:
+
+```text
+inspect target=recipes view=status
+inspect target=recipes view=summary verbose=true
 ```
 
-No automatic rewrite is performed so operators can decide when to retire old config files.
+The summary reports active, shadowed, invalid, disabled, and diagnostic entries so operators can answer why a tool is present, hidden, broken, or disabled.
 
 ## Registering Tools
 
 `register_tool` is the interactive API for listing, creating, updating, or deleting persistent tools. Call it without arguments to list registered tools.
 
 ```text
-register_tool name=transcribe_groq \
-  description="Transcribe audio files using Groq Whisper API" \
-  template="~/.pi/agent/skills/groq-stt/scripts/transcribe.mjs {file} {lang=ru} {model=whisper-large-v3-turbo}"
+register_tool name=transcribe_audio \
+  description="Transcribe an audio file" \
+  template="~/bin/transcribe {file:path} {lang=ru} {model:string}"
 ```
 
 ```text
@@ -47,32 +57,30 @@ Use `update=true` to overwrite an existing tool. Omit `template` and co-located
 ]
 ```
 
-For reusable actor workflows, register a small tool whose `template` points to an actor recipe instead of embedding the launch graph in the tool itself:
+For reusable actor workflows, register a small tool whose `template` points to an existing actor recipe instead of embedding the launch graph in the tool itself:
 
 ```text
 register_tool name=docs_review \
   description="Start an async docs review actor" \
-  template="docs-review.json" \
+  template="docs-review" \
   args="scope:path,model:string"
 ```
 
-This stores the recipe path in the registry as `template`. If `~/.pi/agent/recipes/docs-review.json` contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
+This writes or updates `~/.pi/agent/recipes/docs_review.json` with `tool: true` and a recipe-reference template. If the referenced recipe contains `async: true`, calling the tool starts a detached actor run and returns metadata immediately. If `async` is omitted or false, the same recipe runs foreground and returns normal tool output.
 
-When co-location is clearer than a separate file, the registry entry may include recipe fields directly beside tool metadata:
+When co-location is clearer than a separate file, `register_tool` writes the recipe fields directly into the user recipe file:
 
 ```json
 {
-  "review_docs": {
-    "description": "Start an async docs review",
-    "name": "review-docs",
-    "async": true,
-    "args": ["scope:path", "model:string"],
-    "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
-  }
+  "description": "Start an async docs review",
+  "tool": true,
+  "async": true,
+  "args": ["scope:path", "model:string"],
+  "template": "pi -p --model {model} --tools read,bash \"Review {scope}\""
 }
 ```
 
-This is still not a cycle: `name` names the saved definition when it differs from the tool key, `async: true` selects detached run mode, and `template` remains the executable body. Co-located recipe entries must not define `tool`.
+This is still not a cycle: the filename is the saved definition id, `async: true` selects detached run mode, and `template` remains the executable body.
 
 Delete a tool with `template=null`:
 
@@ -82,24 +90,22 @@ register_tool name=call_subagent template=null
 
 ## Stored Shape
 
-Tool names come from the top-level registry keys. Tool entries define `template`; it may be an inline command template, a template recipe JSON path/name, or the body of a co-located template recipe when `async` or entry-local `name` is present. Template entries keep `template` last, matching the command-template readability rule. The commands above persist entries like this:
+Tool names come from recipe filenames in `~/.pi/agent/recipes`. Recipe files define `template`; it may be an inline command template, a command-template sequence, or an async recipe body. Template entries keep `template` last, matching the command-template readability rule. The commands above persist recipe files like this:
 
 ```json
 {
-  "transcribe_groq": {
-    "description": "Transcribe audio files using Groq Whisper API",
-    "template": "~/.pi/agent/skills/groq-stt/scripts/transcribe.mjs {file} {lang=ru} {model=whisper-large-v3-turbo}"
-  },
-  "call_subagent": {
-    "description": "Run pi as a non-interactive sub-agent",
-    "args": ["prompt:string", "model:string"],
-    "template": "pi -p --model {model} --no-tools {prompt}"
-  },
-  "docs_review": {
-    "description": "Start an async docs review actor",
-    "args": ["scope:path", "model:string"],
-    "template": "docs-review.json"
-  }
+  "description": "Transcribe an audio file",
+  "tool": true,
+  "template": "~/bin/transcribe {file:path} {lang=ru} {model:string}"
+}
+```
+
+```json
+{
+  "description": "Run pi as a non-interactive sub-agent",
+  "tool": true,
+  "args": ["prompt:string", "model:string"],
+  "template": "pi -p --model {model} --no-tools {prompt}"
 }
 ```
 
@@ -108,7 +114,7 @@ Tool names come from the top-level registry keys. Tool entries define `template`
 When `args` is omitted, `pi-actors` derives tool parameters from placeholders in `template`:
 
 ```text
-template="~/bin/transcribe {file} {lang=ru} {model=whisper-large-v3-turbo}"
+template="~/bin/transcribe {file:path} {lang=ru} {model:string}"
 ```
 
 The optional `args` field is an explicit placeholder declaration, matching the command-template standard. Untyped declarations remain valid:

package/index.ts

@@ -40,6 +40,8 @@ const RESERVED_TOOL_NAMES = new Set([
 export default function toolRegistryExtension(pi: ExtensionAPI) {
   let runsAnimationInterval: NodeJS.Timeout | undefined;
   let runsNotifyTimeout: NodeJS.Timeout | undefined;
+  let recipeReloadTimeout: NodeJS.Timeout | undefined;
+  let recipeRootWatcher: FSWatcher | undefined;
   let stateRootWatcher: FSWatcher | undefined;
   const runDirWatchers = new Map<string, FSWatcher>();
   const observedRuns = new Map<string, Observability.RunObservedStatus>();
@@ -147,23 +149,54 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
       watchRunDir(ctx, `${RUN_STATE_ROOT}/${entry.name}`);
     }
   }
+  const closeRecipeWatcher = (): void => {
+    recipeRootWatcher?.close();
+    recipeRootWatcher = undefined;
+    if (recipeReloadTimeout) clearTimeout(recipeReloadTimeout);
+    recipeReloadTimeout = undefined;
+  };
+  const scheduleRecipeReload = (ctx: ExtensionContext): void => {
+    if (recipeReloadTimeout) clearTimeout(recipeReloadTimeout);
+    recipeReloadTimeout = setTimeout(() => {
+      runtime.loadTools(ctx);
+      ctx.ui.notify("Recipe tools refreshed from ~/.pi/agent/recipes", "info");
+    }, 150);
+    recipeReloadTimeout.unref?.();
+  };
+  const watchRecipeRoot = (ctx: ExtensionContext): void => {
+    const recipeRoot = Paths.getRecipeRoot();
+    if (recipeRootWatcher || !existsSync(recipeRoot)) return;
+    try {
+      recipeRootWatcher = watch(recipeRoot, () => scheduleRecipeReload(ctx));
+      recipeRootWatcher.on("error", () => {
+        recipeRootWatcher?.close();
+        recipeRootWatcher = undefined;
+      });
+    } catch {
+      // Watching is best-effort; restarting the session reloads recipe tools.
+    }
+  };
   const actorToolDefinitions = new Map<string, any>();
   const runtime = Runtime.createAutoToolsRuntime({
     configPath: CONFIG_PATH,
     exec: CommandTemplates.execCommandTemplate,
+    getActiveTools: () => pi.getActiveTools(),
     getAllTools: () => pi.getAllTools(),
     registerTool: (definition) => {
       actorToolDefinitions.set(definition.name, definition);
       pi.registerTool(definition);
     },
     reservedToolNames: RESERVED_TOOL_NAMES,
+    setActiveTools: (toolNames) => pi.setActiveTools(toolNames),
   });
   pi.on("session_start", async (_event, ctx) => {
     await Temp.prepareExtensionTempDir(TEMP_DIR);
     runtime.loadTools(ctx);
     updateRunUi(ctx);
     closeRunWatchers();
+    closeRecipeWatcher();
     refreshRunWatchers(ctx);
+    watchRecipeRoot(ctx);
     if (runsAnimationInterval) clearInterval(runsAnimationInterval);
     runsAnimationInterval = setInterval(() => updateRunUi(ctx, false), 1000);
     runsAnimationInterval.unref?.();
@@ -172,6 +205,7 @@ export default function toolRegistryExtension(pi: ExtensionAPI) {
     if (runsAnimationInterval) clearInterval(runsAnimationInterval);
     runsAnimationInterval = undefined;
     closeRunWatchers();
+    closeRecipeWatcher();
   });
   pi.on("before_agent_start", async (event) => ({
     systemPrompt: `${event.systemPrompt}\n\n${Prompts.ONBOARDING_SYSTEM_PROMPT}`,

package/lib/async-runs.ts

@@ -30,6 +30,7 @@ import { substituteCommandTemplateToken } from "./command-templates.ts";
 import { writeJsonAtomic } from "./file-state.ts";
 import * as Paths from "./paths.ts";
 import * as RecipeReferences from "./recipe-references.ts";
+import * as RecipeUsage from "./recipe-usage.ts";
 
 export interface AsyncRunStartParams {
   async?: boolean;
@@ -172,6 +173,12 @@ function resolveRecipeFile(file: string): string {
   return RecipeReferences.resolveRecipePath(file, DEFAULT_RECIPE_ROOT);
 }
 
+function isMutableUsageRecipeFile(file: string): boolean {
+  const userRoot = resolve(DEFAULT_RECIPE_ROOT);
+  const resolved = resolve(file);
+  return resolved.startsWith(`${userRoot}/`);
+}
+
 function readRecipeFile(file: string): AsyncRunStartParams {
   const path = resolveRecipeFile(file);
   const raw = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
@@ -316,6 +323,9 @@ export function startRun(
     ? resolveRecipeFile(startParams.file)
     : undefined;
   const recipe = startParams.name || getRunIdFromFile(recipeFile);
+  if (recipeFile && isMutableUsageRecipeFile(recipeFile)) {
+    RecipeUsage.recordRecipeLaunch(recipeFile);
+  }
   const outFd = openSync(stdout, "a");
   const errFd = openSync(stderr, "a");
   const argv = ["--experimental-strip-types", RUNNER_PATH, stateDir];

package/lib/config.ts

@@ -23,6 +23,7 @@ export interface RegisteredTool {
   template?: CommandTemplateValue;
   storedArgs?: string[];
   storedDefaults?: Record<string, string>;
+  sourcePath?: string;
 }
 
 export interface LoadConfigResult {

package/lib/paths.ts

@@ -5,7 +5,8 @@
  */
 
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 
 export function getAgentDir(
   env: Record<string, string | undefined> = process.env,
@@ -33,3 +34,7 @@ export function getRunStateRoot(agentDir = getAgentDir()): string {
 export function getRecipeRoot(agentDir = getAgentDir()): string {
   return join(agentDir, "recipes");
 }
+
+export function getPackagedRecipeRoot(): string {
+  return resolve(dirname(fileURLToPath(import.meta.url)), "..", "recipes");
+}