@llblab/pi-actors 0.44.0 → 0.45.1

package/lib/tools-inspect.ts

@@ -14,6 +14,7 @@ import * as Limits from "./limits.ts";
 import { computeRunControlCapacity } from "./run-evidence-policy.ts";
 import * as Paths from "./paths.ts";
 import * as RecipesDiscovery from "./recipes-discovery.ts";
+import * as RecipesReferences from "./recipes-references.ts";
 import * as ReviewDiagnostics from "./review-diagnostics.ts";
 import * as RunsControls from "./runs-controls.ts";
 import * as RunControlDelivery from "./runs-control-delivery.ts";
@@ -214,8 +215,18 @@ function inspectRecipes(
     { root: recipeRoot, defaultTool: true, mutableUsage: true },
     { root: deps.packagedRecipeRoot ?? Paths.getPackagedRecipeRoot() },
   ]);
+  const skillRecipeNamespaces =
+    RecipesReferences.getActiveSkillRecipeNamespaces();
   const summary = {
     ...RecipesDiscovery.summarizeDiscovery(discovered),
+    skill_recipe_namespaces: skillRecipeNamespaces,
+    skill_recipe_namespace_diagnostics: Object.entries(skillRecipeNamespaces)
+      .filter(([, roots]) => roots.length > 1)
+      .map(([name, roots]) => ({
+        name,
+        roots,
+        error: `Ambiguous active Skill Recipe namespace ${name}`,
+      })),
     drafts: RecipesDiscovery.listDraftRecipes(join(recipeRoot, "drafts")),
   };
   return {

package/lib/tools-local.ts

@@ -67,11 +67,16 @@ function formatRuntimeToolUsageHint(
   includeRunId: boolean,
 ): string {
   const optional = cfg.args.filter((arg) => !required.includes(arg));
+  const exampleDefaults = {
+    ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+    ...cfg.defaults,
+    ...(cfg.recipe?.values ?? {}),
+  };
   const example: Record<string, unknown> = {};
   for (const arg of required)
-    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
   for (const arg of optional)
-    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], cfg.defaults);
+    example[arg] = sampleValueForArg(arg, cfg.argTypes?.[arg], exampleDefaults);
   if (includeRunId) example.run_id = `${cfg.name}-1`;
   const lines = [
     `Expected call shape for ${cfg.name}:`,
@@ -85,6 +90,32 @@ function formatRuntimeToolUsageHint(
   return lines.join("\n");
 }
 
+function resolveRecipeToolValues(
+  cfg: RegisteredTool,
+  callerValues: Record<string, unknown>,
+  ctx: RuntimeToolContext,
+): Record<string, unknown> {
+  const recipeRuntimeValues = {
+    ...(cfg.recipe?.recipe_dir
+      ? { recipe_dir: cfg.recipe.recipe_dir }
+      : {}),
+    ...(cfg.recipe?.skill_dir ? { skill_dir: cfg.recipe.skill_dir } : {}),
+  };
+  return Schema.normalizeRuntimeValues(
+    ModelContext.withCurrentModelValues(
+      {
+        ...Schema.getExplicitToolArgDefaults(cfg.recipe?.args),
+        ...cfg.defaults,
+        ...(cfg.recipe?.values ?? {}),
+        ...callerValues,
+        ...recipeRuntimeValues,
+      },
+      ctx,
+    ),
+    cfg.argTypes,
+  );
+}
+
 function formatRuntimeToolArgumentError(
   cfg: RegisteredTool,
   error: unknown,
@@ -128,9 +159,18 @@ export function createRuntimeToolDefinition(
           defaults: cfg.defaults,
           template: requiredTemplate,
         };
+  const recipeInlineDefaults = Schema.getExplicitToolArgDefaults(
+    cfg.recipe?.args,
+  );
   const requiredArgs =
     isRecipe && cfg.storedArgs !== undefined
-      ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
+      ? new Set(
+          cfg.args.filter(
+            (arg) =>
+              !Object.hasOwn(cfg.defaults, arg) &&
+              !Object.hasOwn(recipeInlineDefaults, arg),
+          ),
+        )
       : RecipesReferences.isRecipeReference(cfg.template) && !recipeTemplate
         ? new Set(cfg.args.filter((arg) => !Object.hasOwn(cfg.defaults, arg)))
         : Schema.getRequiredToolArgNames(requiredTemplateConfig);
@@ -200,13 +240,7 @@ export function createRuntimeToolDefinition(
                 { ...(cfg.recipe?.values ?? {}), ...values },
                 ctx,
               ),
-              values: Schema.normalizeRuntimeValues(
-                ModelContext.withCurrentModelValues(
-                  { ...(cfg.recipe?.values ?? {}), ...cfg.defaults, ...values },
-                  ctx,
-                ),
-                cfg.argTypes,
-              ),
+              values: resolveRecipeToolValues(cfg, values, ctx),
             },
             ctx.cwd,
           );
@@ -221,17 +255,13 @@ export function createRuntimeToolDefinition(
           };
         }
         if (isRecipe && recipeTemplate) {
-          const paramsWithDefaults = ModelContext.withCurrentModelValues(
-            {
-              ...(cfg.recipe?.values ?? {}),
-              ...cfg.defaults,
-              ...(params as Record<string, unknown>),
-            },
-            ctx,
-          );
           return await Execution.executeRegisteredTool(
             { ...cfg, template: recipeTemplate },
-            Schema.normalizeRuntimeValues(paramsWithDefaults, cfg.argTypes),
+            resolveRecipeToolValues(
+              cfg,
+              params as Record<string, unknown>,
+              ctx,
+            ),
             exec,
             ctx.cwd,
             signal,

package/lib/tools-spawn.ts

@@ -138,10 +138,10 @@ export function createSpawnToolDefinition<
           "Optional Run identity in exact run:<id> form.",
         ),
         file: Schema.stringSchema(
-          "Optional template recipe JSON file. Bare names resolve under ~/.pi/agent/recipes.",
+          "Optional template Recipe reference. Supports paths, bare user/adjacent/std names, std:<name>, and skill:<skill>/<recipe>.",
         ),
         recipe: Schema.stringSchema(
-          "Alias for file; template recipe JSON file/name to spawn.",
+          "Alias for file; qualified Skill/std or ordinary Recipe reference to spawn.",
         ),
         template: Schema.unionSchema([
           Schema.stringSchema("Inline command template string"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-actors",
-  "version": "0.44.0",
+  "version": "0.45.1",
   "private": false,
   "description": "Local Actor Kernel for Pi",
   "keywords": [
@@ -65,7 +65,7 @@
     "sourceSkills": [
       "./skills"
     ],
-    "image": "https://github.com/llblab/pi-actors/raw/main/banner.jpg"
+    "image": "https://raw.githubusercontent.com/llblab/pi-actors/main/banner.jpg"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/scripts/async-runner.mjs

@@ -74,7 +74,6 @@ function summarizeCommandDetail(commandDetail) {
 
 export async function runAsyncRunner(stateDir = process.argv[2]) {
   if (!stateDir) throw new Error("missing state dir");
-
   const runPath = join(stateDir, "run.json");
   const progressPath = join(stateDir, "progress.json");
   const resultPath = join(stateDir, "result.json");
@@ -83,11 +82,9 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   const stderrPath = join(stateDir, "stderr.log");
   const executionPath = join(stateDir, "execution.json");
   const meta = JSON.parse(readFileSync(runPath, "utf8"));
-
   function event(kind, data = {}) {
     appendRunTraceEvent(stateDir, { kind, data });
   }
-
   function observation(kind, summary, data = {}, delivery = "log", level = "info") {
     appendRunTraceEvent(stateDir, {
       kind,
@@ -97,7 +94,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...(level === "error" ? { level: "error" } : {}),
     });
   }
-
   function progress(phase, extra = {}) {
     writeJsonAtomic(progressPath, {
       ...(meta.model_policy ? { model_policy: meta.model_policy } : {}),
@@ -106,7 +102,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       ...extra,
     });
   }
-
   let activeSubagents = 0;
   let completedSubagents = 0;
   let promptCounter = 0;
@@ -115,7 +110,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
   const evidenceRecords = [];
   const stageOccurrences = new Map();
   let reportEvidence;
-
   function writeExecutionManifest(status) {
     writeJsonAtomic(executionPath, {
       version: 1,
@@ -129,7 +123,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       updated_at: new Date().toISOString(),
     });
   }
-
   function commandSessionFiles(sessionDir) {
     if (!sessionDir) return [];
     try {
@@ -141,7 +134,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       return [];
     }
   }
-
   function commandEvidenceStartRecord({
     commandDetail,
     commandId,
@@ -181,7 +173,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
           : "not_required",
     };
   }
-
   function commandEvidenceRecord({
     captureDir,
     commandDetail,
@@ -273,7 +264,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
             : "rejected",
     };
   }
-
   function auditReviewReport(text) {
     const required = evidenceRecords
       .filter((record) =>
@@ -294,11 +284,9 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       complete_allowed: missing.length === 0,
     };
   }
-
   function getCommandDoneDelivery(result) {
     return result.code !== 0 || activeSubagents > 0 ? "followup" : "log";
   }
-
   function progressRunning() {
     progress("running", {
       activeSubagents,
@@ -306,14 +294,12 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       failures: subagentFailures,
     });
   }
-
   function promptFilePath() {
     promptCounter += 1;
     const dir = join(stateDir, "prompts");
     mkdirSync(dir, { recursive: true });
     return join(dir, `command-${String(promptCounter).padStart(3, "0")}.md`);
   }
-
   function readPromptText(promptFile) {
     if (!promptFile) return undefined;
     try {
@@ -322,7 +308,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
       return undefined;
     }
   }
-
   async function observedExec(command, args, options) {
     captureCounter += 1;
     const commandId = `command-${String(captureCounter).padStart(3, "0")}`;
@@ -485,7 +470,6 @@ export async function runAsyncRunner(stateDir = process.argv[2]) {
     progressRunning();
     return result;
   }
-
   try {
     event("run.runner.start", { pid: process.pid });
     progressRunning();

package/scripts/executable-block-style.d.mts

@@ -0,0 +1 @@
+export function executableBlockBlankLines(source: string): number[];

package/scripts/executable-block-style.mjs

@@ -0,0 +1,73 @@
+/** Detect blank lines inside executable JavaScript and TypeScript blocks. */
+
+export function executableBlockBlankLines(source) {
+  const lines = source.split(/\r?\n/u);
+  const blanks = [];
+  const stack = [];
+  let blockComment = false;
+  let currentExecutableDepth = 0;
+  let previousCode = "";
+  let quote;
+  for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+    const line = lines[lineIndex];
+    if (
+      /^\s*$/u.test(line) &&
+      currentExecutableDepth > 0 &&
+      quote !== "`"
+    )
+      blanks.push(lineIndex + 1);
+    let code = "";
+    let regularExpression = false;
+    for (let index = 0; index < line.length; index += 1) {
+      const char = line[index];
+      const next = line[index + 1];
+      if (blockComment) {
+        if (char === "*" && next === "/") {
+          blockComment = false;
+          index += 1;
+        }
+        continue;
+      }
+      if (quote) {
+        if (char === "\\") index += 1;
+        else if (char === quote) quote = undefined;
+        continue;
+      }
+      if (regularExpression) {
+        if (char === "\\") index += 1;
+        else if (char === "/") regularExpression = false;
+        continue;
+      }
+      if (char === "/" && next === "*") {
+        blockComment = true;
+        index += 1;
+        continue;
+      }
+      if (char === "/" && next === "/") break;
+      if (
+        char === "/" &&
+        /^(?:|.*(?:[=(,:;!&|?{}]|\b(?:return|case|throw)))\s*$/u.test(code)
+      ) {
+        regularExpression = true;
+        continue;
+      }
+      if (char === '"' || char === "'" || char === "`") {
+        quote = char;
+        continue;
+      }
+      if (char === "{") {
+        const prefix = code.trimEnd() || previousCode;
+        const executable =
+          /\)\s*$|=>\s*$|\b(?:else|try|finally|do)\s*$/u.test(prefix);
+        stack.push(executable);
+        if (executable) currentExecutableDepth += 1;
+      } else if (char === "}") {
+        if (stack.pop()) currentExecutableDepth -= 1;
+      }
+      code += char;
+    }
+    if (quote !== "`") quote = undefined;
+    if (code.trim()) previousCode = code.trim();
+  }
+  return blanks;
+}

package/scripts/locker.mjs

@@ -65,7 +65,6 @@ async function runLocker(argv = process.argv.slice(2)) {
   const controlPath = join(stateDir, "control.fifo");
   let runInstanceId;
   mkdirSync(stateDir, { recursive: true });
-
   function readJson(path, fallback) {
     if (!existsSync(path)) return fallback;
     try {
@@ -74,11 +73,9 @@ async function runLocker(argv = process.argv.slice(2)) {
       return fallback;
     }
   }
-
   function writeJson(path, value) {
     writeJsonAtomic(path, value);
   }
-
   function getControlEndpoint() {
     if (process.platform !== "win32") return { path: controlPath, type: "fifo" };
     const hash = createHash("sha256")
@@ -87,7 +84,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       .slice(0, 20);
     return { path: `\\\\.\\pipe\\pi-actors-locker-${hash}`, type: "named-pipe" };
   }
-
   function writeControlEndpoint(endpoint) {
     if (!runInstanceId) throw new Error("Run generation unavailable for Control endpoint");
     writeJson(join(stateDir, "control-endpoint.json"), {
@@ -96,7 +92,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       run_instance_id: runInstanceId,
     });
   }
-
   function journal(event, data = {}) {
     const release = acquireFileMutationLock(journalPath);
     try {
@@ -111,11 +106,9 @@ async function runLocker(argv = process.argv.slice(2)) {
       writeTextAtomic(journalPath, content);
     } finally { release(); }
   }
-
   function encodeJournal(records) {
     return records.length ? `${records.map((record) => JSON.stringify(record)).join("\n")}\n` : "";
   }
-
   function emitTrace(kind, summary, data = {}, level = "info") {
     appendRunTraceEvent(stateDir, {
       attention: "followup",
@@ -125,11 +118,9 @@ async function runLocker(argv = process.argv.slice(2)) {
       summary,
     });
   }
-
   function now() {
     return Date.now();
   }
-
   function cleanExpiredLocks(locks) {
     const current = now();
     const kept = {};
@@ -139,7 +130,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     }
     return kept;
   }
-
   function normalizeControl(line) {
     const trimmed = line.trim();
     if (!trimmed) return undefined;
@@ -160,8 +150,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       );
     }
   }
-
-
   function tailJournal(count) {
     if (!existsSync(journalPath)) return [];
     return readFileSync(journalPath, "utf8")
@@ -177,7 +165,6 @@ async function runLocker(argv = process.argv.slice(2)) {
         }
       });
   }
-
   function printSnapshot() {
     const locks = cleanExpiredLocks(readJson(locksPath, {}));
     writeJson(locksPath, locks);
@@ -195,7 +182,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       ),
     );
   }
-
   function nextTask(queue, locks) {
     const items = Array.isArray(queue.items) ? queue.items : [];
     const index = items.findIndex((item) => {
@@ -205,7 +191,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     if (index < 0) return undefined;
     return items.splice(index, 1)[0];
   }
-
   function handle(control) {
     const action = control.action;
     const body =
@@ -333,18 +318,15 @@ async function runLocker(argv = process.argv.slice(2)) {
     journal("lock.unknown", { action, input: body });
     emitTrace("lock.unknown", `Unknown Control ${action}`, { action, input: body }, "warning");
   }
-
   if (mode === "snapshot") {
     printSnapshot();
     process.exit(0);
   }
-
   const startupRun = readJson(join(stateDir, "run.json"), undefined);
   if (!startupRun || typeof startupRun.run_instance_id !== "string") {
     throw new Error("Run generation unavailable for Control service");
   }
   runInstanceId = startupRun.run_instance_id;
-
   function handleLine(line) {
     const control = normalizeControl(line);
     if (!control) return false;
@@ -376,7 +358,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       return false;
     }
   }
-
   async function serveFifo(endpoint) {
     if (!existsSync(endpoint.path)) {
       const result = spawnSync("mkfifo", [endpoint.path]);
@@ -403,7 +384,6 @@ async function runLocker(argv = process.argv.slice(2)) {
       fs.closeSync(fd);
     }
   }
-
   async function serveNamedPipe(endpoint) {
     let resolveStopped;
     const stopped = new Promise((resolve) => {
@@ -428,7 +408,6 @@ async function runLocker(argv = process.argv.slice(2)) {
     });
     await stopped;
   }
-
   const endpoint = getControlEndpoint();
   writeJson(queuePath, readJson(queuePath, { items: [] }));
   writeJson(locksPath, cleanExpiredLocks(readJson(locksPath, {})));

package/scripts/recipe-utils.mjs

@@ -369,7 +369,6 @@ if (!command) {
   usage();
   process.exit(1);
 }
-
 if (command === "run-summary")
   runSummary(args[0] ?? "~/.pi/agent/tmp/pi-actors/runs");
 else if (command === "run-ops-snapshot")

package/scripts/release-gates.mjs

@@ -7,6 +7,8 @@ import { dirname, extname, join, normalize, relative, resolve } from "node:path"
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
+import { executableBlockBlankLines } from "./executable-block-style.mjs";
+
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const temp = mkdtempSync(join(tmpdir(), "pi-actors-release-index-"));
 const indexPath = join(temp, "index");
@@ -71,7 +73,6 @@ try {
     .filter(Boolean);
   const fileSet = new Set(files);
   console.log(`[release] exact temporary index: ${files.length} files`);
-
   const secretPatterns = [
     [/-----BEGIN(?: [A-Z0-9]+)? PRIVATE KEY-----[\s\S]{80,}?-----END(?: [A-Z0-9]+)? PRIVATE KEY-----/u, "private-key block"],
     [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/u, "AWS access key"],
@@ -92,7 +93,17 @@ try {
     }
   }
   console.log("[release] bounded secret and public-path hygiene checked");
-
+  const executableSources = files.filter((path) =>
+    /\.(?:[cm]?js|ts)$/u.test(path) && !path.startsWith("dist/"),
+  );
+  for (const path of executableSources) {
+    const blankLines = executableBlockBlankLines(stagedText(path) ?? "");
+    check(
+      blankLines.length === 0,
+      `blank lines inside executable blocks: ${path}:${blankLines.join(",")}`,
+    );
+  }
+  console.log("[release] executable blocks contain no blank lines");
   const removedPaths = [
     "lib/messages.ts",
     "lib/rooms.ts",
@@ -113,7 +124,6 @@ try {
     "lib/run-inspector-overlay.ts",
   ];
   for (const path of removedPaths) check(!fileSet.has(path), `removed surface returned: ${path}`);
-
   const currentSurface = /^(?:lib\/|scripts\/|recipes\/|fixtures\/|skills\/|docs\/|README\.md|AGENTS\.md)/u;
   const forbiddenPatterns = [
     [/room:</u, "room address"],
@@ -144,7 +154,6 @@ try {
     }
   }
   console.log("[release] removed-surface and legacy-fallback allowlists checked");
-
   const directTraceWrite = /(?:appendFileSync|writeFileSync|writeText(?:Atomic)?)\s*\(\s*[A-Za-z0-9_.]*?(?:trace|event)(?:Path|File)/iu;
   for (const path of files.filter((candidate) =>
     (candidate.startsWith("lib/") && candidate.endsWith(".ts")) ||
@@ -172,7 +181,6 @@ try {
     );
   }
   console.log("[release] canonical Trace and Control writer residue checked");
-
   // owner | class | lock | record bound | byte bound | recovery
   const appendOnlyOwners = new Set([
     "lib/runs-trace.ts", // canonical Run evidence | token lock | 2048 | 4 MiB | compact valid suffix
@@ -189,7 +197,6 @@ try {
       check(appendOnlyOwners.has(path), `unregistered shipped append-only writer: ${path}`);
   for (const path of appendOnlyOwners) check(fileSet.has(path), `stale append-only owner inventory: ${path}`);
   console.log(`[release] append-only owner inventory checked: ${appendOnlyOwners.size} source owners`);
-
   check(
     (stagedText("scripts/validate-recipe.mjs") ?? "").includes(
       "qaReport.diagnostics.length === 0 && qaReport.warnings.length === 0",
@@ -197,15 +204,13 @@ try {
     "Recipe QA warnings are not release-blocking",
   );
   console.log("[release] zero-warning Recipe QA gate checked");
-
-  const maximumShippedLines = 29_598;
+  const maximumShippedLines = 32_000;
   const shippedPath = /^(?:lib\/|scripts\/|recipes\/|docs\/|skills\/)/u;
   const shippedLines = files
     .filter((path) => shippedPath.test(path))
     .reduce((total, path) => total + (((stagedText(path) ?? "").match(/\n/gu) ?? []).length + 1), 0);
   check(shippedLines <= maximumShippedLines, `shipped lines ${shippedLines} exceed release maximum ${maximumShippedLines}`);
   console.log(`[release] shipped lines ${shippedLines} <= release maximum ${maximumShippedLines}`);
-
   const sources = files.filter((path) => path === "index.ts" || (path.startsWith("lib/") && path.endsWith(".ts")));
   const sourceSet = new Set(sources);
   const graph = new Map();
@@ -240,7 +245,6 @@ try {
   }
   for (const path of sources) visit(path);
   console.log(`[release] strict Domain DAG: ${sources.length} sources, acyclic`);
-
   for (const path of ["README.md", "AGENTS.md", "BACKLOG.md", "CHANGELOG.md", "docs/README.md"]) {
     check(fileSet.has(path), `missing ABCd root/context file: ${path}`);
   }
@@ -263,7 +267,6 @@ try {
     check(docsIndex.includes(relative("docs", path).replaceAll("\\", "/")), `docs/README.md omits ${path}`);
   }
   console.log("[release] ABCd context roots, routing, and Markdown links checked");
-
   if (failures.length > 0) {
     for (const failure of failures) console.error(`[FAIL] ${failure}`);
     process.exitCode = 1;

package/scripts/validate-recipe.mjs

@@ -187,7 +187,6 @@ export function validateRecipes(argv) {
   if (!targetArg || argv.includes("--help") || argv.includes("-h")) {
     return { help: true, ok: Boolean(targetArg), usage: validateRecipeUsage() };
   }
-
   const files = recipeFiles(expandPath(targetArg), all);
   const results = files.map((file) => validateFile(file, qa));
   const failed = results.filter((result) => !result.ok).length;

package/skills/actors/SKILL.md

@@ -25,11 +25,11 @@ A Run target exposes exactly three inspect views: `recipe`, `trace`, and `contro
 
 ## Recipe
 
-A Recipe defines execution. It may declare args, defaults, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
+A Recipe defines execution. It may declare named typed args, inline fallbacks, configuration `defaults`, composition `values`, imports, artifacts, command-template flags, and `control: ["action"]` when a long-lived service actually consumes actor-local inputs.
 
 Do not declare Control for ordinary one-shot work. Runtime lifecycle actions such as `kill` stay runtime-owned and must not appear in Recipe Control declarations. Imported Recipes act as local definitions inside one Run; they do not create nested Runs unless execution explicitly spawns them.
 
-Prefer maintained packaged Recipes over ad hoc wrappers. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
+Prefer maintained packaged Recipes over ad hoc wrappers. Use `std:<recipe>` for exact packaged lookup and `skill:<skill>/<recipe-path>` for a component bundled with a Pi-active Skill. File-backed Recipes own `{recipe_dir}` and Skill Recipes own `{skill_dir}`; callers never pass or override these origins. Skill Recipes are components, not automatic tools. Keep model, thinking, mission, concurrency, quorum, and timeout choices caller-owned unless a Recipe documents a stable policy.
 
 ## Trace