@wairon/cli 5.1.1-dev.2 → 5.1.1-dev.4

package/dist/index.js

@@ -47,7 +47,7 @@ function createAgentRecord(partial) {
     ...partial
   });
 }
-var import_zod, BuiltinTargetSchema, CustomTargetSchema, OutputTargetSchema, AgentStatusSchema, AgentRecordSchema;
+var import_zod, BuiltinTargetSchema, CustomTargetSchema, OutputTargetSchema, AgentStatusSchema, AgentRecordSchema, AgentTemplateSchema, AgentBriefSchema;
 var init_agent = __esm({
   "src/models/agent.ts"() {
     "use strict";
@@ -101,6 +101,30 @@ var init_agent = __esm({
       createdAt: import_zod.z.string().datetime(),
       updatedAt: import_zod.z.string().datetime()
     });
+    AgentTemplateSchema = import_zod.z.object({
+      /** Template identifier (architect, domain-owner, implementer, …) */
+      templateName: import_zod.z.string(),
+      /** The raw instruction body with {{variable}} placeholders, before rendering */
+      instructions: import_zod.z.string()
+    });
+    AgentBriefSchema = import_zod.z.object({
+      /** The resolved agent's stable id (e.g. sdd_core-owner, system-architect) */
+      agentId: import_zod.z.string(),
+      /** Human-readable display name of the agent */
+      name: import_zod.z.string(),
+      /** The instruction template the brief was rendered from */
+      template: import_zod.z.string(),
+      /** Domain the agent belongs to (absent = global root) */
+      domainRoot: import_zod.z.string().optional(),
+      /** Glob patterns of the files this agent owns — the write-scope fence */
+      ownedPaths: import_zod.z.array(import_zod.z.string()),
+      /** Spec paths the subagent should read first */
+      readPaths: import_zod.z.array(import_zod.z.string()).optional(),
+      /** The fully rendered instruction body — paste-ready as a subagent prompt */
+      instructions: import_zod.z.string(),
+      /** Rendered variant guidance, also folded into instructions */
+      variantGuidance: import_zod.z.string().optional()
+    });
   }
 });
 
@@ -254,6 +278,14 @@ var init_project = __esm({
        * per-component isolation.
        */
       generateComponentImplementers: import_zod3.z.boolean().default(false),
+      /**
+       * Whether `wairon generate` writes per-subsystem owner/architect agent FILES.
+       * Off by default: agents are served as LIVE briefs (sdd_get_agent_brief /
+       * wairon-agent://), and files are merely the opt-in materialized view of the
+       * same briefs. When off, generate reconciles to zero agent files — leftover
+       * wairon-managed files are removed (hand-authored files never are).
+       */
+      materializeAgentFiles: import_zod3.z.boolean().default(false),
       /**
        * Severity overrides for SDD validation rules.
        * Key: rule code (e.g. CIRCULAR_DEPENDENCY), Value: error | warning | off
@@ -773,6 +805,20 @@ var init_specs = __esm({
        * writes with hydration read-backs (MISSING_HYDRATION); optional elsewhere.
        */
       effect: import_zod6.z.enum(["read", "write"]).optional(),
+      /**
+       * Typed acknowledgment of a real caller OUTSIDE the modeled narrative graph
+       * (runtime timer/hook, external system, sibling subsystem). Unused-detection
+       * seeds the method as an entrypoint, so reachability PROPAGATES through its
+       * narrative — unlike a lint.allow, which only silences the finding. `caller`
+       * states WHO invokes it (placeholder-thin prose is INVOKED_BY_UNDESCRIBED;
+       * a method the internal walk already reaches is INVOKED_BY_REDUNDANT).
+       * Prefer a `register` narrative step when the wiring is internal — the
+       * registration itself is then a modeled, checkable edge.
+       */
+      invokedBy: import_zod6.z.object({
+        kind: import_zod6.z.enum(["runtime", "external", "sibling-subsystem"]),
+        caller: import_zod6.z.string().optional()
+      }).optional(),
       /** Opaque pack/tool extension data (see ExtDataSchema) — preserved verbatim. */
       ext: ExtDataSchema.optional()
     });
@@ -798,6 +844,8 @@ var init_specs = __esm({
       // cross-component call (targetComponent/targetMethod)
       "dispatch",
       // capability routed through a generic Portal's dispatch table (targetComponent + capability)
+      "register",
+      // runtime-callback handoff (targetComponent/targetMethod): reachability edge, never an invocation
       "branch",
       // if/else: condition + onTrueStep (default next) / onFalseStep
       "switch",
@@ -847,9 +895,9 @@ var init_specs = __esm({
       description: import_zod6.z.string(),
       type: NarrativeStepTypeSchema,
       targetComponent: import_zod6.z.string().optional(),
-      // Required if type is 'call' or 'dispatch', references L2 Component id
+      // Required if type is 'call', 'register' or 'dispatch', references L2 Component id
       targetMethod: import_zod6.z.string().optional(),
-      // Required if type is 'call', references Method name on target interface
+      // Required if type is 'call' or 'register', references Method name on target interface
       capability: import_zod6.z.string().optional(),
       // Required if type is 'dispatch': the capability routed through the target Portal's dispatch table
       /**
@@ -1163,7 +1211,7 @@ var init_defaults = __esm({
       copilot: ".github/prompts",
       codex: ".codex/agents"
     };
-    WAIRON_VERSION = "5.1.1-dev.2";
+    WAIRON_VERSION = "5.1.1-dev.4";
     GITHUB_REPO = "SYW-Apps/Waffle-AIron";
     ARCHITECT_AGENT_ID = "agent-architect";
     ARCHITECT_TEMPLATE_ID = "architect";
@@ -1388,6 +1436,66 @@ var init_errors = __esm({
   }
 });
 
+// src/core/templates.ts
+function builtinTemplatesDir() {
+  return path3.resolve(__dirname, "..", "templates");
+}
+function loadTemplate(id, globalOverride) {
+  const dirs = templateSearchDirs(globalOverride);
+  for (const dir of dirs) {
+    const filePath = path3.join(dir, `${id}.yaml`);
+    if (pathExists(filePath)) {
+      const raw = readYamlFile(filePath);
+      return { ...TemplateSchema.parse(raw), templateName: id };
+    }
+  }
+  throw new TemplateNotFoundError(id);
+}
+function loadAgentOverride(agentId) {
+  const filePath = path3.join(AI_PATHS.root(), "agents", `${agentId}.md`);
+  return readFileOrNull(filePath);
+}
+function listTemplateIds(globalOverride) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const dir of templateSearchDirs(globalOverride)) {
+    for (const file of listFiles(dir, ".yaml")) {
+      seen.add(path3.basename(file, ".yaml"));
+    }
+  }
+  return Array.from(seen).sort();
+}
+function templateSearchDirs(globalOverride) {
+  return [
+    AI_PATHS.templatesDir(),
+    // 1. project-local
+    globalTemplatesDir(globalOverride),
+    // 2. global user/org
+    builtinTemplatesDir()
+    // 3. built-in fallback
+  ];
+}
+function renderTemplateInstructions(template, vars) {
+  return template.instructions.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
+    return key in vars ? vars[key] : `{{${key}}}`;
+  });
+}
+function parseTemplate(yamlContent) {
+  return TemplateSchema.parse(parseYaml(yamlContent));
+}
+var path3;
+var init_templates = __esm({
+  "src/core/templates.ts"() {
+    "use strict";
+    path3 = __toESM(require("path"));
+    init_fs();
+    init_yaml();
+    init_errors();
+    init_template();
+    init_loader();
+    init_defaults();
+  }
+});
+
 // src/utils/version.ts
 function isNewerVersion(current2, candidate) {
   const baseVersion = (v) => v.replace(/-.*$/, "");
@@ -1430,20 +1538,20 @@ function packFiles(dir, prefix = "") {
   for (const e of entries) {
     if (DIGEST_EXCLUDED.has(e.name)) continue;
     const rel2 = prefix ? `${prefix}/${e.name}` : e.name;
-    if (e.isDirectory()) out.push(...packFiles(path3.join(dir, e.name), rel2));
+    if (e.isDirectory()) out.push(...packFiles(path4.join(dir, e.name), rel2));
     else if (e.isFile()) out.push(rel2);
   }
   return out.sort();
 }
 function computePackDigest(packDir) {
   const hash = crypto.createHash("sha256");
-  const abs = path3.resolve(packDir);
+  const abs = path4.resolve(packDir);
   let isFile = false;
   try {
     isFile = fs2.statSync(abs).isFile();
   } catch {
   }
-  const entries = isFile ? [[path3.basename(abs), abs]] : packFiles(abs).map((rel2) => [rel2, path3.join(abs, rel2)]);
+  const entries = isFile ? [[path4.basename(abs), abs]] : packFiles(abs).map((rel2) => [rel2, path4.join(abs, rel2)]);
   for (const [rel2, full] of entries) {
     hash.update(rel2);
     hash.update("\0");
@@ -1457,7 +1565,7 @@ function computePackDigest(packDir) {
 }
 function readInstallRecord(packPath) {
   try {
-    const raw = readYamlFile(path3.join(packPath, INSTALL_RECORD));
+    const raw = readYamlFile(path4.join(packPath, INSTALL_RECORD));
     return raw && typeof raw === "object" ? raw : {};
   } catch {
     return {};
@@ -1494,7 +1602,7 @@ function versionedEntries(nameDir, fallbackName) {
   const out = [];
   for (const v of versions) {
     if (!v.isDirectory()) continue;
-    const versionDir = path3.join(nameDir, v.name);
+    const versionDir = path4.join(nameDir, v.name);
     const entryFile = packDirEntry(versionDir);
     if (!entryFile) continue;
     out.push(installedFrom(versionDir, declaredName(entryFile) ?? fallbackName, v.name));
@@ -1502,7 +1610,7 @@ function versionedEntries(nameDir, fallbackName) {
   return out;
 }
 function storeEntryPacks(store, entry) {
-  const full = path3.join(store, entry.name);
+  const full = path4.join(store, entry.name);
   if (entry.isFile()) {
     if (!PACK_FILE_RE.test(entry.name)) return [];
     const name = declaredName(full) ?? entry.name.replace(PACK_FILE_RE, "");
@@ -1534,16 +1642,16 @@ function resolveInstalledPack(name, version) {
   return candidates[0];
 }
 function installPackFromDirectory(sourceDir, origin) {
-  const abs = path3.resolve(sourceDir);
+  const abs = path4.resolve(sourceDir);
   const entryFile = packDirEntry(abs);
   if (!entryFile) {
     throw new Error(`"${sourceDir}" is not a pack directory (no pack.yaml | pack.cjs | index.cjs | \u2026).`);
   }
-  const manifest = readManifest(entryFile, path3.dirname(entryFile));
+  const manifest = readManifest(entryFile, path4.dirname(entryFile));
   const version = manifest.version && manifest.version.length > 0 ? manifest.version : UNVERSIONED;
-  const dest = path3.join(packStoreDir(), manifest.name, version);
+  const dest = path4.join(packStoreDir(), manifest.name, version);
   fs2.rmSync(dest, { recursive: true, force: true });
-  fs2.mkdirSync(path3.dirname(dest), { recursive: true });
+  fs2.mkdirSync(path4.dirname(dest), { recursive: true });
   fs2.cpSync(abs, dest, { recursive: true });
   const digest = computePackDigest(dest);
   const record = {
@@ -1552,7 +1660,7 @@ function installPackFromDirectory(sourceDir, origin) {
     waironVersion: WAIRON_VERSION,
     installedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
-  writeYamlFile(path3.join(dest, INSTALL_RECORD), record);
+  writeYamlFile(path4.join(dest, INSTALL_RECORD), record);
   return {
     name: manifest.name,
     version,
@@ -1568,8 +1676,8 @@ function uninstallPack(name, version) {
   if (targets.length === 0) return false;
   for (const target of targets) {
     fs2.rmSync(target.path, { recursive: true, force: true });
-    const parent = path3.dirname(target.path);
-    if (path3.resolve(parent) === path3.resolve(packStoreDir())) continue;
+    const parent = path4.dirname(target.path);
+    if (path4.resolve(parent) === path4.resolve(packStoreDir())) continue;
     try {
       if (fs2.readdirSync(parent).length === 0) fs2.rmdirSync(parent);
     } catch {
@@ -1577,13 +1685,13 @@ function uninstallPack(name, version) {
   }
   return true;
 }
-var crypto, fs2, path3, UNVERSIONED, INSTALL_RECORD, DIGEST_EXCLUDED, PACK_FILE_RE;
+var crypto, fs2, path4, UNVERSIONED, INSTALL_RECORD, DIGEST_EXCLUDED, PACK_FILE_RE;
 var init_packstore = __esm({
   "src/core/packstore.ts"() {
     "use strict";
     crypto = __toESM(require("crypto"));
     fs2 = __toESM(require("fs"));
-    path3 = __toESM(require("path"));
+    path4 = __toESM(require("path"));
     init_yaml();
     init_defaults();
     init_version();
@@ -1610,11 +1718,11 @@ function emptyExtensions() {
   return { packNames: [], packs: [], rules: [], profiles: {}, languages: {}, skills: [], patterns: [], guarantees: [], assertions: [], instructions: [], errors: [], selectionFailures: [] };
 }
 function globalPacksDir() {
-  return process.env.WAIRON_PACKS_DIR ?? path4.join(os2.homedir(), ".wairon", "packs");
+  return process.env.WAIRON_PACKS_DIR ?? path5.join(os2.homedir(), ".wairon", "packs");
 }
 function packDirEntry(dir) {
   for (const name of PACK_DIR_ENTRIES) {
-    const p = path4.join(dir, name);
+    const p = path5.join(dir, name);
     if (fs3.existsSync(p)) return p;
   }
   return null;
@@ -1629,7 +1737,7 @@ function latestVersionDir(nameDir) {
   let best = null;
   for (const v of versions) {
     if (!v.isDirectory()) continue;
-    const dir = path4.join(nameDir, v.name);
+    const dir = path5.join(nameDir, v.name);
     if (!packDirEntry(dir)) continue;
     if (!best || isNewerVersion(best.version, v.name)) best = { version: v.name, dir };
   }
@@ -1644,7 +1752,7 @@ function discoverPacks(dir) {
   }
   const refs = [];
   for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-    const full = path4.join(dir, e.name);
+    const full = path5.join(dir, e.name);
     if (e.isDirectory()) {
       if (packDirEntry(full)) refs.push(full);
       else {
@@ -1674,16 +1782,16 @@ function mergePack(out, pack, ref, scope, packDir) {
       foreignBuiltins: [.../* @__PURE__ */ new Set([...existing.foreignBuiltins, ...def.foreignBuiltins])]
     } : def;
   }
-  for (const s of pack.skills) out.skills.push({ ...s, pack: pack.name, packVersion: pack.version, sourcePath: path4.resolve(packDir, s.source) });
+  for (const s of pack.skills) out.skills.push({ ...s, pack: pack.name, packVersion: pack.version, sourcePath: path5.resolve(packDir, s.source) });
   for (const p of pack.patterns) out.patterns.push({ ...p, pack: pack.name });
   out.guarantees = [.../* @__PURE__ */ new Set([...out.guarantees, ...pack.guarantees])];
   for (const a of pack.assertions) out.assertions.push({ ...a, pack: pack.name, fullCode: assertionFullCode(pack.name, a.code) });
   for (const b of pack.instructions) out.instructions.push({ ...b, pack: pack.name });
 }
 function resolvePackRef(ref, projectRoot) {
-  const pathLike = ref.startsWith(".") || path4.isAbsolute(ref) || isYamlPath(ref);
+  const pathLike = ref.startsWith(".") || path5.isAbsolute(ref) || isYamlPath(ref);
   if (!pathLike) return ref;
-  const resolved = path4.resolve(projectRoot, ref);
+  const resolved = path5.resolve(projectRoot, ref);
   if (fs3.existsSync(resolved) && fs3.statSync(resolved).isDirectory()) {
     const entry = packDirEntry(resolved);
     if (!entry) throw new Error(`directory pack has no entry file (${PACK_DIR_ENTRIES.join(" | ")})`);
@@ -1697,7 +1805,7 @@ function readManifest(target, projectRoot) {
     if (raw == null) throw new Error("file not found or empty");
     return { ...DeclarativePackSchema.parse(raw), rules: [] };
   }
-  const req = (0, import_module.createRequire)(path4.join(projectRoot, "package.json"));
+  const req = (0, import_module.createRequire)(path5.join(projectRoot, "package.json"));
   const modRaw = req(target);
   const mod = modRaw?.default ?? modRaw;
   const parsed = DeclarativePackSchema.parse({
@@ -1725,7 +1833,7 @@ function loadExtensionPacks(refs, projectRoot) {
     try {
       const target = resolvePackRef(ref, projectRoot);
       const manifest = readManifest(target, projectRoot);
-      mergePack(out, manifest, ref, scope, path4.dirname(target));
+      mergePack(out, manifest, ref, scope, path5.dirname(target));
       for (const r of manifest.rules) out.rules.push(r);
     } catch (e) {
       out.errors.push(`Extension pack "${ref}" failed to load: ${e instanceof Error ? e.message : String(e)}`);
@@ -1778,7 +1886,7 @@ function defaultPackSelections() {
       const entry = packDirEntry(pack.path) ?? pack.path;
       let manifest;
       try {
-        manifest = readManifest(entry, path4.dirname(entry));
+        manifest = readManifest(entry, path5.dirname(entry));
       } catch {
         continue;
       }
@@ -1816,7 +1924,7 @@ function diagnoseProjectPacks() {
     const globalsApplied = [];
     if (globalsOn) {
       for (const ref of discoverPacks(globalPacksDir())) {
-        const match = installed.find((p) => path4.resolve(p.path) === path4.resolve(ref));
+        const match = installed.find((p) => path5.resolve(p.path) === path5.resolve(ref));
         if (match) globalsApplied.push({ name: match.name, version: match.version });
       }
     }
@@ -1897,7 +2005,7 @@ function verifyIntegrity(selection, packDir, where) {
   };
 }
 function detectBundleStoreDrift(selection, bundleDir) {
-  const bundledVersion = path4.basename(bundleDir);
+  const bundledVersion = path5.basename(bundleDir);
   const installed = resolveInstalledPack(selection.name, bundledVersion);
   if (!installed) return void 0;
   const bundleDigest = computePackDigest(bundleDir);
@@ -1911,9 +2019,9 @@ function detectBundleStoreDrift(selection, bundleDir) {
   };
 }
 function findBundledPack(projectRoot, selection) {
-  const base = path4.join(projectRoot, ".wai", "packs", selection.name);
+  const base = path5.join(projectRoot, ".wai", "packs", selection.name);
   if (selection.version) {
-    const pinned = path4.join(base, selection.version);
+    const pinned = path5.join(base, selection.version);
     return packDirEntry(pinned) ? pinned : null;
   }
   if (packDirEntry(base)) return base;
@@ -1926,19 +2034,19 @@ function findBundledPack(projectRoot, selection) {
   let best = null;
   for (const v of versions) {
     if (!v.isDirectory()) continue;
-    const dir = path4.join(base, v.name);
+    const dir = path5.join(base, v.name);
     if (!packDirEntry(dir)) continue;
     if (!best || isNewerVersion(best.version, v.name)) best = { version: v.name, dir };
   }
   return best?.dir ?? null;
 }
-var fs3, os2, path4, import_module, import_zod7, ProfileDefSchema, LanguagePackDefSchema, PackSkillSchema, PackInstructionBlockSchema, PackInstructionsSchema, PatternDefSchema, AssertionSelectorSchema, assertionBase, PackAssertionSchema, DeclarativePackSchema, EXTENDABLE_BUILTIN_SKILLS, GLOBAL_PACKS_DEFAULT, PACK_DIR_ENTRIES, isYamlPath;
+var fs3, os2, path5, import_module, import_zod7, ProfileDefSchema, LanguagePackDefSchema, PackSkillSchema, PackInstructionBlockSchema, PackInstructionsSchema, PatternDefSchema, AssertionSelectorSchema, assertionBase, PackAssertionSchema, DeclarativePackSchema, EXTENDABLE_BUILTIN_SKILLS, GLOBAL_PACKS_DEFAULT, PACK_DIR_ENTRIES, isYamlPath;
 var init_extensions = __esm({
   "src/core/extensions.ts"() {
     "use strict";
     fs3 = __toESM(require("fs"));
     os2 = __toESM(require("os"));
-    path4 = __toESM(require("path"));
+    path5 = __toESM(require("path"));
     import_module = require("module");
     import_zod7 = require("zod");
     init_yaml();
@@ -2081,7 +2189,7 @@ var init_extensions = __esm({
        */
       applyByDefault: import_zod7.z.boolean().default(false)
     });
-    EXTENDABLE_BUILTIN_SKILLS = ["sdd-architect", "sdd-narrative", "sdd-auditor", "sdd-implement"];
+    EXTENDABLE_BUILTIN_SKILLS = ["sdd-architect", "sdd-narrative", "sdd-auditor", "sdd-implement", "sdd-delegate"];
     GLOBAL_PACKS_DEFAULT = false;
     PACK_DIR_ENTRIES = ["pack.yaml", "pack.yml", "pack.cjs", "pack.js", "index.cjs", "index.js"];
     isYamlPath = (p) => /\.ya?ml$/i.test(p);
@@ -2884,7 +2992,7 @@ var init_openapi = __esm({
 
 // src/core/surfaces.ts
 function surfacesDir(rootDir) {
-  return path5.join(rootDir, ".wai", SURFACES_DIRNAME);
+  return path6.join(rootDir, ".wai", SURFACES_DIRNAME);
 }
 function audienceRank(audience) {
   const idx = SURFACE_AUDIENCES.indexOf(audience ?? "instance");
@@ -3047,7 +3155,7 @@ function listSnapshots(rootDir = getProjectRoot()) {
   for (const file of fs4.readdirSync(dir)) {
     if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
     try {
-      out.push(SurfaceSnapshotSchema.parse(readYamlFile(path5.join(dir, file))));
+      out.push(SurfaceSnapshotSchema.parse(readYamlFile(path6.join(dir, file))));
     } catch {
     }
   }
@@ -3062,13 +3170,13 @@ function snapshotFilename(projectName) {
 function saveSnapshot(snapshot, rootDir = getProjectRoot()) {
   const dir = surfacesDir(rootDir);
   fs4.mkdirSync(dir, { recursive: true });
-  const p = path5.join(dir, snapshotFilename(snapshot.projectName));
+  const p = path6.join(dir, snapshotFilename(snapshot.projectName));
   writeYamlFile(p, SurfaceSnapshotSchema.parse(snapshot));
   return p;
 }
 function removeSnapshot(projectName, rootDir = getProjectRoot()) {
   const dir = surfacesDir(rootDir);
-  const direct = path5.join(dir, snapshotFilename(projectName));
+  const direct = path6.join(dir, snapshotFilename(projectName));
   if (fs4.existsSync(direct)) {
     fs4.unlinkSync(direct);
     return true;
@@ -3076,7 +3184,7 @@ function removeSnapshot(projectName, rootDir = getProjectRoot()) {
   if (!fs4.existsSync(dir)) return false;
   for (const file of fs4.readdirSync(dir)) {
     if (!file.endsWith(".yaml") && !file.endsWith(".yml")) continue;
-    const p = path5.join(dir, file);
+    const p = path6.join(dir, file);
     try {
       const snap = SurfaceSnapshotSchema.parse(readYamlFile(p));
       if (snap.projectName === projectName) {
@@ -3100,13 +3208,13 @@ function selectPortalSpec(renderedSet, portalId) {
   return [hit];
 }
 function perPortalPath(resolvedOut, portalId) {
-  const ext = path5.extname(resolvedOut);
+  const ext = path6.extname(resolvedOut);
   const stem = ext ? resolvedOut.slice(0, -ext.length) : resolvedOut;
   return `${stem}.${safeFilenamePart(portalId)}${ext}`;
 }
 function writeSurfaceFile(outPath, snapshot, renderedSet) {
-  const resolved = path5.resolve(outPath);
-  fs4.mkdirSync(path5.dirname(resolved), { recursive: true });
+  const resolved = path6.resolve(outPath);
+  fs4.mkdirSync(path6.dirname(resolved), { recursive: true });
   if (!renderedSet || renderedSet.length === 0) {
     writeYamlFile(resolved, snapshot);
     return [resolved];
@@ -3139,14 +3247,14 @@ function exportSurface(maxAudience, format, outPath, portalId) {
   return exportResult(snapshot, renderedSet, writtenPaths);
 }
 function importSurface(sourcePath, origin) {
-  const resolved = path5.resolve(sourcePath);
+  const resolved = path6.resolve(sourcePath);
   if (!fs4.existsSync(resolved)) {
     throw new Error(`Surface document not found: ${resolved}`);
   }
   const body = fs4.readFileSync(resolved, "utf8");
   let snapshot;
   if (isOpenApiDocument(body)) {
-    const projectName = path5.basename(resolved).replace(/\.(json|ya?ml)$/i, "");
+    const projectName = path6.basename(resolved).replace(/\.(json|ya?ml)$/i, "");
     snapshot = fromOpenApi(body, projectName);
     snapshot = { ...snapshot, origin };
   } else {
@@ -3172,7 +3280,7 @@ function generateChildSnapshots(rootDir = getProjectRoot()) {
   };
   const written = [];
   for (const child of children) {
-    const childDir = path5.resolve(rootDir, child.projectPath);
+    const childDir = path6.resolve(rootDir, child.projectPath);
     if (!fs4.existsSync(childDir)) continue;
     written.push(saveSnapshot(familySnapshot, childDir));
     for (const sibling of topLevel) {
@@ -3217,7 +3325,7 @@ function checkChildSurfaceFreshness(rootDir = getProjectRoot()) {
   const current2 = surfaceContentKey(projectChildSurface());
   const issues = [];
   for (const child of children) {
-    const childDir = path5.resolve(rootDir, child.projectPath);
+    const childDir = path6.resolve(rootDir, child.projectPath);
     const held = getSnapshot(system.name, childDir);
     if (!held || held.origin !== "generated") continue;
     if (surfaceContentKey(held) !== current2) {
@@ -3231,12 +3339,12 @@ function checkChildSurfaceFreshness(rootDir = getProjectRoot()) {
   }
   return issues;
 }
-var fs4, path5, SURFACES_DIRNAME, CROSS_BOUNDARY_TARGETS;
+var fs4, path6, SURFACES_DIRNAME, CROSS_BOUNDARY_TARGETS;
 var init_surfaces = __esm({
   "src/core/surfaces.ts"() {
     "use strict";
     fs4 = __toESM(require("fs"));
-    path5 = __toESM(require("path"));
+    path6 = __toESM(require("path"));
     init_fs();
     init_yaml();
     init_filenames();
@@ -3346,13 +3454,13 @@ var init_contracts = __esm({
     init_namespace();
     contractsRule = {
       name: "contract-symmetry-and-narratives",
-      description: "Implementations mirror their contract method-for-method. Narrative call steps must name an existing component and method, the caller must declare the dependency, and asserted semantic guarantees must be backed by the target contract.",
+      description: "Implementations mirror their contract method-for-method. Narrative call steps (and register handoffs, which share the identical target shape) must name an existing component and method, the caller must declare the dependency, and asserted semantic guarantees must be backed by the target contract.",
       codes: [
         { code: "UNEXPECTED_IMPLEMENTATION_METHOD", defaultSeverity: "error", summary: "Implementation method not present on the contract" },
         { code: "MISSING_IMPLEMENTATION_METHOD", defaultSeverity: "error", summary: "Contract method missing from the implementation" },
-        { code: "MISSING_TARGET_COMPONENT", defaultSeverity: "error", summary: "Call step missing targetComponent" },
-        { code: "MISSING_TARGET_METHOD", defaultSeverity: "error", summary: "Call step missing targetMethod" },
-        { code: "INVALID_TARGET_COMPONENT_REFERENCE", defaultSeverity: "error", summary: "Call step targets a non-existent component" },
+        { code: "MISSING_TARGET_COMPONENT", defaultSeverity: "error", summary: "Call/register step missing targetComponent" },
+        { code: "MISSING_TARGET_METHOD", defaultSeverity: "error", summary: "Call/register step missing targetMethod" },
+        { code: "INVALID_TARGET_COMPONENT_REFERENCE", defaultSeverity: "error", summary: "Call/register step targets a non-existent component" },
         { code: "CROSS_TREE_REF_UNRESOLVED", defaultSeverity: "warning", summary: "Cross-tree reference (super::/:: form) with no surface snapshot covering it \u2014 only the parent project can verify it" },
         { code: "SURFACE_REF_NOT_EXPOSED", defaultSeverity: "error", summary: "Cross-tree reference resolves to a surface snapshot that does not expose the called method/capability" },
         { code: "UNDECLARED_DEPENDENCY_CALL", defaultSeverity: "error", summary: "Call step targets a component the caller does not depend on or own" },
@@ -3390,7 +3498,7 @@ var init_contracts = __esm({
           }
           for (const implMethod of impl.methods) {
             for (const step of implMethod.narrative) {
-              if (step.type !== "call" && step.type !== "dispatch") continue;
+              if (step.type !== "call" && step.type !== "dispatch" && step.type !== "register") continue;
               if (!step.targetComponent) {
                 ctx.addIssue(
                   "error",
@@ -3450,11 +3558,12 @@ var init_contracts = __esm({
                 }
                 continue;
               }
+              const verb = step.type === "register" ? "registers callback" : "calls";
               if (!step.targetMethod) {
                 ctx.addIssue(
                   "error",
                   "MISSING_TARGET_METHOD",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" has a call step (${step.stepNumber}) missing "targetMethod".`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" has a ${step.type} step (${step.stepNumber}) missing "targetMethod".`,
                   impl.id,
                   isDraftCtx
                 );
@@ -3470,7 +3579,7 @@ var init_contracts = __esm({
                       ctx.addIssue(
                         "error",
                         "SURFACE_REF_NOT_EXPOSED",
-                        `Method "${implMethod.name}" in implementation "${impl.id}" calls "${step.targetMethod}" on cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), but the surface snapshot of "${resolved.snapshot.projectName}" does not expose that method on "${resolved.entry.id}".`,
+                        `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} "${step.targetMethod}" on cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), but the surface snapshot of "${resolved.snapshot.projectName}" does not expose that method on "${resolved.entry.id}".`,
                         impl.id,
                         isDraftCtx,
                         true
@@ -3495,7 +3604,7 @@ var init_contracts = __esm({
                   ctx.addIssue(
                     "warning",
                     "CROSS_TREE_REF_UNRESOLVED",
-                    `Method "${implMethod.name}" in implementation "${impl.id}" calls cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), and no surface snapshot covers it \u2014 validate from the parent project, or import/generate the producing project's surface.`,
+                    `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} cross-tree component "${step.targetComponent}" (step ${step.stepNumber}), and no surface snapshot covers it \u2014 validate from the parent project, or import/generate the producing project's surface.`,
                     impl.id,
                     isDraftCtx
                   );
@@ -3503,7 +3612,7 @@ var init_contracts = __esm({
                   ctx.addIssue(
                     "error",
                     "INVALID_TARGET_COMPONENT_REFERENCE",
-                    `Method "${implMethod.name}" in implementation "${impl.id}" calls component "${step.targetComponent}" which does not exist (step ${step.stepNumber}).`,
+                    `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} component "${step.targetComponent}" which does not exist (step ${step.stepNumber}).`,
                     impl.id,
                     isDraftCtx
                   );
@@ -3516,7 +3625,7 @@ var init_contracts = __esm({
                   ctx.addIssue(
                     "error",
                     "UNDECLARED_DEPENDENCY_CALL",
-                    `Method "${implMethod.name}" in implementation "${impl.id}" (component "${callingComponent.id}") calls component "${step.targetComponent}" (step ${step.stepNumber}) but component "${callingComponent.id}" does not list "${step.targetComponent}" as a dependency.`,
+                    `Method "${implMethod.name}" in implementation "${impl.id}" (component "${callingComponent.id}") ${verb} component "${step.targetComponent}" (step ${step.stepNumber}) but component "${callingComponent.id}" does not list "${step.targetComponent}" as a dependency.`,
                     impl.id,
                     isDraftCtx || ctx.isComponentDraft(callingComponent.id)
                   );
@@ -3535,7 +3644,7 @@ var init_contracts = __esm({
                 ctx.addIssue(
                   "error",
                   "INVALID_TARGET_METHOD_REFERENCE",
-                  `Method "${implMethod.name}" in implementation "${impl.id}" calls method "${step.targetMethod}" on component "${step.targetComponent}" which is not defined on any of its interfaces (step ${step.stepNumber}).`,
+                  `Method "${implMethod.name}" in implementation "${impl.id}" ${verb} method "${step.targetMethod}" on component "${step.targetComponent}" which is not defined on any of its interfaces (step ${step.stepNumber}).`,
                   impl.id,
                   isDraftCtx || ctx.isComponentDraft(step.targetComponent)
                 );
@@ -3604,6 +3713,7 @@ function stepGraph(steps) {
     switch (s.type) {
       case "local":
       case "call":
+      case "register":
       case "dispatch":
         succ.push(fallNext(n));
         break;
@@ -3699,6 +3809,7 @@ var init_narrative_flow = __esm({
               switch (s.type) {
                 case "local":
                 case "call":
+                case "register":
                 case "dispatch": {
                   const extra = flowConfigOn(s);
                   if (extra.length) malformed(`step ${s.stepNumber} (${s.type}) carries flow config (${extra.join(", ")}) \u2014 use a flow step type instead.`);
@@ -3853,7 +3964,7 @@ var init_narrative_flow = __esm({
               if (s.finallyStep !== void 0) handlerStarts.add(s.finallyStep);
               const last = byNum.get(s.endStep);
               const nxt = nextOf(s.endStep);
-              if (last && (last.type === "local" || last.type === "call" || last.type === "dispatch") && nxt !== void 0 && handlerStarts.has(nxt)) {
+              if (last && (last.type === "local" || last.type === "call" || last.type === "register" || last.type === "dispatch") && nxt !== void 0 && handlerStarts.has(nxt)) {
                 ctx.addIssue(
                   "warning",
                   "FALLTHROUGH_INTO_HANDLER",
@@ -3963,7 +4074,7 @@ function resolveTypeScript(projectRoot) {
     return cached.ts;
   }
   let ts = null;
-  const bases = [path6.join(projectRoot, "package.json"), __filename];
+  const bases = [path7.join(projectRoot, "package.json"), __filename];
   for (const base of bases) {
     try {
       const req = (0, import_module2.createRequire)(base);
@@ -4119,7 +4230,7 @@ function walkExact(ts, sourceText, fileName) {
 }
 function resolveRelativeModule(fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
-  const base = path6.resolve(path6.dirname(fromFile), specifier);
+  const base = path7.resolve(path7.dirname(fromFile), specifier);
   const candidates = [
     base,
     base.replace(/\.js$/, ".ts"),
@@ -4127,8 +4238,8 @@ function resolveRelativeModule(fromFile, specifier) {
     `${base}.ts`,
     `${base}.tsx`,
     `${base}.js`,
-    path6.join(base, "index.ts"),
-    path6.join(base, "index.js")
+    path7.join(base, "index.ts"),
+    path7.join(base, "index.js")
   ];
   for (const c of candidates) {
     try {
@@ -4142,7 +4253,7 @@ function chaseStarExports(ts, facts, filePath, projectRoot, visited, exactCache)
   for (const spec of facts.starExports) {
     const target = resolveRelativeModule(filePath, spec);
     if (!target || visited.has(target)) continue;
-    if (path6.relative(projectRoot, target).startsWith("..")) continue;
+    if (path7.relative(projectRoot, target).startsWith("..")) continue;
     visited.add(target);
     let targetFacts = exactCache.get(target);
     if (targetFacts === void 0) {
@@ -4187,12 +4298,12 @@ function buildCodeModel(implementations, projectRoot) {
     if (seen.has(sourcePath)) continue;
     seen.add(sourcePath);
     const empty = { declaredNames: [], anchoredNames: [], exportedNames: [], imports: [], reexports: [] };
-    if (path6.isAbsolute(sourcePath) || path6.normalize(sourcePath).split(path6.sep)[0] === "..") {
+    if (path7.isAbsolute(sourcePath) || path7.normalize(sourcePath).split(path7.sep)[0] === "..") {
       files.push({ path: sourcePath, status: "escaped", ...empty });
       continue;
     }
-    const absolute = path6.resolve(projectRoot, sourcePath);
-    if (path6.relative(projectRoot, absolute).startsWith("..")) {
+    const absolute = path7.resolve(projectRoot, sourcePath);
+    if (path7.relative(projectRoot, absolute).startsWith("..")) {
       files.push({ path: sourcePath, status: "escaped", ...empty });
       continue;
     }
@@ -4213,7 +4324,7 @@ function buildCodeModel(implementations, projectRoot) {
       continue;
     }
     const text = buffer.toString("utf8");
-    const language = EXTENSION_LANGUAGE[path6.extname(sourcePath).toLowerCase()];
+    const language = EXTENSION_LANGUAGE[path7.extname(sourcePath).toLowerCase()];
     let analyzed;
     if (language === "typescript" || language === "javascript") {
       const ts = resolveTypeScript(projectRoot);
@@ -4247,12 +4358,12 @@ function buildCodeModel(implementations, projectRoot) {
   }
   return { files, projectRoot };
 }
-var fs5, path6, import_module2, EXTENSION_LANGUAGE, C_FAMILY_COMMENTS, JS_PATTERNS, LANGUAGE_PATTERNS, PATTERN_ANALYSIS_MAX_BYTES, IDENTIFIER_RE, STRING_RE, tsResolutionCache, TS_RESOLUTION_RETRY_MS;
+var fs5, path7, import_module2, EXTENSION_LANGUAGE, C_FAMILY_COMMENTS, JS_PATTERNS, LANGUAGE_PATTERNS, PATTERN_ANALYSIS_MAX_BYTES, IDENTIFIER_RE, STRING_RE, tsResolutionCache, TS_RESOLUTION_RETRY_MS;
 var init_source_analysis = __esm({
   "src/core/source-analysis.ts"() {
     "use strict";
     fs5 = __toESM(require("fs"));
-    path6 = __toESM(require("path"));
+    path7 = __toESM(require("path"));
     import_module2 = require("module");
     EXTENSION_LANGUAGE = {
       ".ts": "typescript",
@@ -5763,6 +5874,7 @@ var init_public_surface = __esm({
 // src/core/rules/graph.ts
 function walkNarrativeGraph(ctx, seeds, opts = {}) {
   const followDispatchTables = opts.followDispatchTables ?? true;
+  const followRegisterEdges = opts.followRegisterEdges ?? true;
   const reachedComponents = /* @__PURE__ */ new Set();
   const reachedMethods = /* @__PURE__ */ new Set();
   const queue = [];
@@ -5821,6 +5933,10 @@ function walkNarrativeGraph(ctx, seeds, opts = {}) {
         reachComponent(step.targetComponent);
         enqueueMethod(step.targetComponent, step.targetMethod);
       }
+      if (followRegisterEdges && step.type === "register" && step.targetComponent && step.targetMethod) {
+        reachComponent(step.targetComponent);
+        enqueueMethod(step.targetComponent, step.targetMethod);
+      }
       if (step.type === "dispatch" && step.targetComponent) {
         reachComponent(step.targetComponent);
         const portal = ctx.componentMap.get(step.targetComponent);
@@ -5906,11 +6022,13 @@ var init_graph = __esm({
     methodKey = (compId, methodName) => `${compId}#${methodName}`;
     reachabilityRule = {
       name: "unused-detection",
-      description: "Walks the narrative execution graph (call steps, dispatch-table routing, lifecycle flows) from every entrypoint (Portal/Observer/published component/lifecycle entrypoint) and flags components and methods no execution chain reaches, plus types no field or signature references.",
+      description: "Walks the narrative execution graph (call steps, register handoffs, dispatch-table routing, lifecycle flows) from every entrypoint (Portal/Observer/published component/lifecycle entrypoint/invokedBy-declared method) and flags components and methods no execution chain reaches, plus types no field or signature references. An interface method declaring invokedBy (a real caller outside the modeled graph) seeds the walk, so its narrative propagates reachability; the declaration itself is audited (thin caller prose, or a method the internal walk already reaches).",
       codes: [
         { code: "UNUSED_COMPONENT", defaultSeverity: "warning", summary: "Component never reached by any narrative call chain" },
         { code: "UNUSED_METHOD", defaultSeverity: "warning", summary: "Method never called by any narrative step" },
-        { code: "UNUSED_TYPE", defaultSeverity: "warning", summary: "Type never referenced by fields or signatures" }
+        { code: "UNUSED_TYPE", defaultSeverity: "warning", summary: "Type never referenced by fields or signatures" },
+        { code: "INVOKED_BY_UNDESCRIBED", defaultSeverity: "warning", summary: "invokedBy declaration whose caller prose is missing or placeholder-thin" },
+        { code: "INVOKED_BY_REDUNDANT", defaultSeverity: "warning", summary: "invokedBy declaration on a method the internal narrative walk already reaches \u2014 stale, remove it" }
       ],
       check(ctx) {
         const seeds = [];
@@ -5929,7 +6047,37 @@ var init_graph = __esm({
             seeds.push({ compId: le.component, methodName: le.method });
           }
         }
-        const { reachedComponents, reachedMethods } = walkNarrativeGraph(ctx, seeds);
+        const baseWalk = walkNarrativeGraph(ctx, seeds);
+        const invokedBySeeds = [];
+        for (const intf of ctx.interfaces) {
+          if (!ctx.componentMap.has(intf.component)) continue;
+          const comp = ctx.componentMap.get(intf.component);
+          for (const m of intf.methods) {
+            if (!m.invokedBy) continue;
+            invokedBySeeds.push({ compId: intf.component, methodName: m.name });
+            if (!ctx.isSpecInScope(intf.id)) continue;
+            const isDraftCtx = comp.status === "draft" || comp.status === "design" || intf.status === "draft" || intf.status === "design";
+            if (!passesIntentFloor(m.invokedBy.caller, m.name)) {
+              ctx.addIssue(
+                "warning",
+                "INVOKED_BY_UNDESCRIBED",
+                `Method "${m.name}" on component "${intf.component}" declares invokedBy (${m.invokedBy.kind}) but its "caller" prose is missing or placeholder-thin \u2014 state WHO invokes it and when, so the entrypoint claim stays reviewable.`,
+                intf.id,
+                isDraftCtx
+              );
+            }
+            if (baseWalk.reachedMethods.has(methodKey(intf.component, m.name))) {
+              ctx.addIssue(
+                "warning",
+                "INVOKED_BY_REDUNDANT",
+                `Method "${m.name}" on component "${intf.component}" declares invokedBy (${m.invokedBy.kind}), but the internal narrative walk already reaches it \u2014 the declaration is stale; remove it.`,
+                intf.id,
+                isDraftCtx
+              );
+            }
+          }
+        }
+        const { reachedComponents, reachedMethods } = invokedBySeeds.length ? walkNarrativeGraph(ctx, [...seeds, ...invokedBySeeds]) : baseWalk;
         for (const comp of ctx.components) {
           if (!ctx.isSpecInScope(comp.id)) continue;
           if (!reachedComponents.has(comp.id)) {
@@ -6264,7 +6412,7 @@ var init_semantic_edges = __esm({
             }
           }
         }
-        const initReach = initSeeds.length ? walkNarrativeGraph(ctx, initSeeds, { followDispatchTables: false }) : null;
+        const initReach = initSeeds.length ? walkNarrativeGraph(ctx, initSeeds, { followDispatchTables: false, followRegisterEdges: false }) : null;
         for (const comp of ctx.components) {
           const isDraftCtx = ctx.isComponentDraft(comp.id);
           if (comp.componentType !== "Store") continue;
@@ -6662,6 +6810,7 @@ function isTerminal(step, nextOf) {
   switch (step.type) {
     case "local":
     case "call":
+    case "register":
     case "dispatch":
       return nextOf(n) === void 0;
     case "branch":
@@ -6862,11 +7011,11 @@ var init_narrative_antipatterns = __esm({
           const memberEdges = keys.flatMap((k) => (adjacency.get(k) ?? []).filter((e) => inScc.has(e.toKey)));
           if (memberEdges.length === 0) continue;
           const anchor = [...memberEdges].sort((a, b) => a.fromKey.localeCompare(b.fromKey))[0];
-          const path23 = [...keys].sort().join(" \u2192 ");
+          const path24 = [...keys].sort().join(" \u2192 ");
           ctx.addIssue(
             "warning",
             "UNCONDITIONAL_CALL_CYCLE",
-            `Call cycle with no guard: ${path23} \u2014 every call edge in this cycle is unavoidable on all paths of its narrative (e.g. step ${anchor.stepNumber} of "${anchor.methodName}" in "${anchor.impl.id}" always calls ${anchor.toLabel}). This recurses without a base case, by construction. Guard at least one edge with a branch/return before the call, or lint.allow with the termination argument.`,
+            `Call cycle with no guard: ${path24} \u2014 every call edge in this cycle is unavoidable on all paths of its narrative (e.g. step ${anchor.stepNumber} of "${anchor.methodName}" in "${anchor.impl.id}" always calls ${anchor.toLabel}). This recurses without a base case, by construction. Guard at least one edge with a branch/return before the call, or lint.allow with the termination argument.`,
             anchor.impl.id,
             memberEdges.some((e) => ctx.isImplementationDraft(e.impl))
           );
@@ -7582,7 +7731,7 @@ var init_naming = __esm({
 // src/core/rules/integration-conformance.ts
 function resolveAgainst(mapped, fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
-  const joined = normalizePath(path7.posix.normalize(path7.posix.join(path7.posix.dirname(fromFile), specifier)));
+  const joined = normalizePath(path8.posix.normalize(path8.posix.join(path8.posix.dirname(fromFile), specifier)));
   const candidates = [
     joined,
     joined.replace(/\.js$/, ".ts"),
@@ -7598,11 +7747,11 @@ function resolveAgainst(mapped, fromFile, specifier) {
   }
   return null;
 }
-var path7, normalizePath, integrationConformanceRule;
+var path8, normalizePath, integrationConformanceRule;
 var init_integration_conformance = __esm({
   "src/core/rules/integration-conformance.ts"() {
     "use strict";
-    path7 = __toESM(require("path"));
+    path8 = __toESM(require("path"));
     init_source_analysis();
     init_conformance();
     normalizePath = normalizeSourcePath;
@@ -7806,7 +7955,7 @@ var init_hidden_state = __esm({
 // src/core/rules/dependency-conformance.ts
 function resolveAgainst2(mapped, fromFile, specifier) {
   if (!specifier.startsWith(".")) return null;
-  const joined = normalizePath2(path8.posix.normalize(path8.posix.join(path8.posix.dirname(fromFile), specifier)));
+  const joined = normalizePath2(path9.posix.normalize(path9.posix.join(path9.posix.dirname(fromFile), specifier)));
   const candidates = [
     joined,
     joined.replace(/\.js$/, ".ts"),
@@ -7822,11 +7971,11 @@ function resolveAgainst2(mapped, fromFile, specifier) {
   }
   return null;
 }
-var path8, normalizePath2, dependencyConformanceRule;
+var path9, normalizePath2, dependencyConformanceRule;
 var init_dependency_conformance = __esm({
   "src/core/rules/dependency-conformance.ts"() {
     "use strict";
-    path8 = __toESM(require("path"));
+    path9 = __toESM(require("path"));
     init_source_analysis();
     init_conformance();
     normalizePath2 = normalizeSourcePath;
@@ -8700,17 +8849,17 @@ function readLockRecord() {
 }
 function writeLockRecord(record) {
   const p = lockPath();
-  fs6.mkdirSync(path9.dirname(p), { recursive: true });
+  fs6.mkdirSync(path10.dirname(p), { recursive: true });
   const tmp = `${p}.tmp`;
   fs6.writeFileSync(tmp, JSON.stringify(record, null, 2) + "\n");
   fs6.renameSync(tmp, p);
 }
-var fs6, path9;
+var fs6, path10;
 var init_lockfile = __esm({
   "src/core/lockfile.ts"() {
     "use strict";
     fs6 = __toESM(require("fs"));
-    path9 = __toESM(require("path"));
+    path10 = __toESM(require("path"));
     init_fs();
   }
 });
@@ -9242,6 +9391,9 @@ function buildCanvasModel(issues = []) {
             text: s.description,
             kind: s.type,
             ...s.type === "call" && s.targetComponent && s.targetMethod ? { call: { component: s.targetComponent, method: s.targetMethod } } : {},
+            // Register (runtime-callback handoff) carries its target like a
+            // call step — rendered as an edge, labeled by its own kind.
+            ...s.type === "register" && s.targetComponent && s.targetMethod ? { call: { component: s.targetComponent, method: s.targetMethod } } : {},
             ...s.type === "dispatch" && s.targetComponent && s.capability ? { call: { component: s.targetComponent, method: `\u27E8${s.capability}\u27E9` } } : {},
             ...s.condition ? { cond: s.condition } : {},
             ...s.onTrueStep !== void 0 ? { onTrue: s.onTrueStep } : {},
@@ -9440,9 +9592,9 @@ function embedJson(value) {
 }
 function loadCytoscapeLib() {
   const candidates = [
-    path10.resolve(__dirname, "..", "templates", "canvas", "cytoscape.min.js"),
+    path11.resolve(__dirname, "..", "templates", "canvas", "cytoscape.min.js"),
     // src/core & dist/cli
-    path10.resolve(__dirname, "templates", "canvas", "cytoscape.min.js")
+    path11.resolve(__dirname, "templates", "canvas", "cytoscape.min.js")
     // dist (library entry)
   ];
   for (const p of candidates) {
@@ -9459,12 +9611,12 @@ function renderCanvasHtml(model) {
 function escapeHtml(s) {
   return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
 }
-var fs7, path10, CANVAS_TEMPLATE;
+var fs7, path11, CANVAS_TEMPLATE;
 var init_canvas = __esm({
   "src/core/canvas.ts"() {
     "use strict";
     fs7 = __toESM(require("fs"));
-    path10 = __toESM(require("path"));
+    path11 = __toESM(require("path"));
     init_specs2();
     init_type_analysis();
     init_diagram_export();
@@ -12848,6 +13000,7 @@ var MODEL = __MODEL_JSON__;
       case 'try': return s.n + '. \\u26E8 try \\u2014 ' + s.text;
       case 'parallel': return s.n + '. \\u2225 ' + s.text;
       case 'jump': return s.n + '. \\u21B7 ' + s.text;
+      case 'register': return s.n + '. \\u27F2 register \\u2014 ' + s.text;
       case 'return': return s.n + '. \\u23CE return' + (s.outcome ? ' \\u2014 ' + s.outcome : '');
       case 'throw': return s.n + '. \\u26A1 throw' + (s.err ? ' ' + s.err : '');
       default: return s.n + '. ' + s.text;
@@ -12871,7 +13024,9 @@ var MODEL = __MODEL_JSON__;
     (graph.joins || []).forEach(function (j2) { joinByHeader[j2.header] = j2; });
     graph.steps.forEach(function (s, i) {
       var id = 'n' + s.n;
-      var isCall = (s.kind === 'call' || s.kind === 'dispatch') && !!s.call;
+      // Register steps render like calls (target edge + label) \u2014 the label
+      // itself says "register", keeping the handoff visually distinct.
+      var isCall = (s.kind === 'call' || s.kind === 'dispatch' || s.kind === 'register') && !!s.call;
       // A detached call's target renders as a separate ghost node (below), so
       // the step node itself stays plain and undrillable.
       var isDetached = isCall && !!s.detach;
@@ -13126,7 +13281,7 @@ var MODEL = __MODEL_JSON__;
     comps.push({ id: 'start', name: flowTitle() + '()', subsystem: 'flow', componentType: 'Start', public: false, owns: [] });
     graph.steps.forEach(function (s) {
       var name = flowStepLabel(s) + (s.call && !s.detach ? ' \\u2192 ' + s.call.component + '.' + s.call.method + '()' : '');
-      comps.push({ id: 'n' + s.n, name: name, subsystem: 'flow', componentType: (s.kind === 'call' || s.kind === 'dispatch') ? 'Call' : 'Step', public: false, owns: [] });
+      comps.push({ id: 'n' + s.n, name: name, subsystem: 'flow', componentType: (s.kind === 'call' || s.kind === 'dispatch' || s.kind === 'register') ? 'Call' : 'Step', public: false, owns: [] });
     });
     // Virtual flow nodes (join bars, detached-call ghosts) export as plain
     // steps so the editable diagrams keep the fan-out/join and detachment.
@@ -13636,7 +13791,7 @@ var init_repository = __esm({
 
 // src/core/variants.ts
 function globalVariantsDir() {
-  return process.env.WAIRON_VARIANTS_DIR ?? path11.join(os3.homedir(), ".wairon", "variants");
+  return process.env.WAIRON_VARIANTS_DIR ?? path12.join(os3.homedir(), ".wairon", "variants");
 }
 function readVariantsDir(dir) {
   let entries;
@@ -13648,7 +13803,7 @@ function readVariantsDir(dir) {
   const out = [];
   for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
     if (!e.isFile() || !/\.ya?ml$/i.test(e.name)) continue;
-    const full = path11.join(dir, e.name);
+    const full = path12.join(dir, e.name);
     try {
       const raw = readYamlFile(full);
       if (raw == null) continue;
@@ -13695,19 +13850,19 @@ function loadProjectVariants() {
   try {
     const byId = /* @__PURE__ */ new Map();
     for (const v of readVariantsDir(globalVariantsDir())) byId.set(v.id, v);
-    for (const v of readVariantsDir(path11.join(getProjectRoot(), ".wai", "variants"))) byId.set(v.id, v);
+    for (const v of readVariantsDir(path12.join(getProjectRoot(), ".wai", "variants"))) byId.set(v.id, v);
     return [...byId.values()];
   } catch {
     return [];
   }
 }
-var fs8, os3, path11, import_zod8, VariantDefSchema;
+var fs8, os3, path12, import_zod8, VariantDefSchema;
 var init_variants = __esm({
   "src/core/variants.ts"() {
     "use strict";
     fs8 = __toESM(require("fs"));
     os3 = __toESM(require("os"));
-    path11 = __toESM(require("path"));
+    path12 = __toESM(require("path"));
     import_zod8 = require("zod");
     init_yaml();
     init_fs();
@@ -14393,6 +14548,17 @@ function generateSequenceDiagram(componentId, methodName, options) {
           }
           break;
         }
+        case "register": {
+          if (!step.targetComponent || !step.targetMethod) break;
+          const regTarget = componentById.get(step.targetComponent);
+          if (!regTarget) {
+            lines.push(`  Note over ${selfId}: ${escapeLabel(`registers callback on unknown "${step.targetComponent}"`)}`);
+            break;
+          }
+          const regTargetId = declare(regTarget);
+          lines.push(`  ${selfId}--)${regTargetId}: ${escapeLabel(`register ${step.targetMethod}()`)}`);
+          break;
+        }
         case "call": {
           if (!step.targetComponent || !step.targetMethod) break;
           const target = componentById.get(step.targetComponent);
@@ -14600,16 +14766,16 @@ function relativizeId(id, prefix) {
   return `${"super::".repeat(prefixParts.length - common)}${idParts.slice(common).join("::")}`;
 }
 function isWithin(dir, file) {
-  const d = path12.resolve(dir);
-  const f = path12.resolve(file);
-  return f === d || f.startsWith(d + path12.sep);
+  const d = path13.resolve(dir);
+  const f = path13.resolve(file);
+  return f === d || f.startsWith(d + path13.sep);
 }
 function projectPathEscapesRoot(projectRoot, projectPath, resolvedChildDir) {
-  return path12.isAbsolute(projectPath) || !isWithin(projectRoot, resolvedChildDir);
+  return path13.isAbsolute(projectPath) || !isWithin(projectRoot, resolvedChildDir);
 }
 function assertContainedProjectPath(projectRoot, projectPath) {
-  const root = path12.resolve(projectRoot);
-  const resolved = path12.resolve(root, projectPath);
+  const root = path13.resolve(projectRoot);
+  const resolved = path13.resolve(root, projectPath);
   if (projectPathEscapesRoot(root, projectPath, resolved)) {
     throw new Error(
       `projectPath "${projectPath}" must resolve within the project root "${root}", but resolves to "${resolved}"; absolute paths and ../-escaping paths are rejected so a chained subproject is always contained by its parent.`
@@ -14620,11 +14786,11 @@ function assertContainedProjectPath(projectRoot, projectPath) {
 function findChainingParent(childRoot) {
   let childResolved;
   try {
-    childResolved = path12.resolve(childRoot);
+    childResolved = path13.resolve(childRoot);
   } catch {
     return null;
   }
-  let dir = path12.dirname(childResolved);
+  let dir = path13.dirname(childResolved);
   for (let hops = 0; hops < 32; hops++) {
     const specsDir = aiPathsAt(dir).specsDir();
     if (pathExists(specsDir)) {
@@ -14639,7 +14805,7 @@ function findChainingParent(childRoot) {
           const projectPath = raw.projectPath;
           if (typeof projectPath === "string" && projectPath.trim() !== "") {
             try {
-              if (path12.resolve(dir, projectPath) === childResolved) {
+              if (path13.resolve(dir, projectPath) === childResolved) {
                 const id = raw.id;
                 return { parentRoot: dir, subsystemId: typeof id === "string" ? id : "?" };
               }
@@ -14649,7 +14815,7 @@ function findChainingParent(childRoot) {
         }
       }
     }
-    const up = path12.dirname(dir);
+    const up = path13.dirname(dir);
     if (up === dir) break;
     dir = up;
   }
@@ -14754,18 +14920,18 @@ function findOwner(id, components) {
   }) ?? null;
 }
 function moveComponentFolder(fromDir, toDir) {
-  if (path12.normalize(fromDir) === path12.normalize(toDir)) return false;
+  if (path13.normalize(fromDir) === path13.normalize(toDir)) return false;
   if (!fs9.existsSync(fromDir) || fs9.existsSync(toDir)) return false;
-  ensureDir(path12.dirname(toDir));
+  ensureDir(path13.dirname(toDir));
   fs9.renameSync(fromDir, toDir);
   return true;
 }
 function cleanEmptyDirs(filePath, specsRoot) {
-  let dir = path12.dirname(filePath);
+  let dir = path13.dirname(filePath);
   while (dir !== specsRoot && dir.startsWith(specsRoot)) {
     if (fs9.existsSync(dir) && fs9.readdirSync(dir).length === 0) {
       fs9.rmdirSync(dir);
-      dir = path12.dirname(dir);
+      dir = path13.dirname(dir);
     } else {
       break;
     }
@@ -14800,7 +14966,7 @@ function computeSpecTreeSignature(dirs) {
   return parts.join("|");
 }
 function workspaceFor(rootDir) {
-  const key = path12.resolve(rootDir);
+  const key = path13.resolve(rootDir);
   let ws = workspaces.get(key);
   if (!ws) {
     ws = new SpecWorkspace(key);
@@ -14939,7 +15105,7 @@ function readLockState() {
   return { state: stateIdEquals(record.stateId, current2) ? "locked" : "stale", record, current: current2 };
 }
 function computeStateIdAt(root) {
-  const resolved = path12.resolve(root);
+  const resolved = path13.resolve(root);
   return runWithProjectRoot(resolved, () => {
     workspaceFor(resolved).invalidate();
     const system = loadSystemSpec();
@@ -14983,12 +15149,12 @@ function findLegacySpecFiles() {
 function updateSpec(kind, id, delta, hooks) {
   return current().updateSpec(kind, id, delta, hooks);
 }
-var fs9, path12, SIGNATURE_TTL_MS, SpecWorkspace, workspaces;
+var fs9, path13, SIGNATURE_TTL_MS, SpecWorkspace, workspaces;
 var init_specs2 = __esm({
   "src/core/specs.ts"() {
     "use strict";
     fs9 = __toESM(require("fs"));
-    path12 = __toESM(require("path"));
+    path13 = __toESM(require("path"));
     init_loader();
     init_fs();
     init_statehash();
@@ -15009,7 +15175,7 @@ var init_specs2 = __esm({
         this.rootSubsystems = /* @__PURE__ */ new Set();
         this.scanVisitedSpecDirs = [];
         this.loaderIssues = [];
-        this.rootDir = path12.resolve(rootDir);
+        this.rootDir = path13.resolve(rootDir);
         this.paths = aiPathsAt(this.rootDir);
       }
       invalidate() {
@@ -15036,7 +15202,7 @@ var init_specs2 = __esm({
         this.rootSubsystems.clear();
         this.cachedRecursive = recursive;
         this.scanVisitedSpecDirs = [];
-        const visited = /* @__PURE__ */ new Set([path12.resolve(this.rootDir)]);
+        const visited = /* @__PURE__ */ new Set([path13.resolve(this.rootDir)]);
         const maxDepth = typeof recursive === "number" ? recursive : recursive ? Infinity : 0;
         this.cachedIndex = this.scanSpecsForProject(this.rootDir, "", visited, maxDepth, 0);
         this.cachedSpecDirs = this.scanVisitedSpecDirs;
@@ -15051,10 +15217,10 @@ var init_specs2 = __esm({
         this.scanVisitedSpecDirs.push(specsDir);
         if (!pathExists(specsDir)) return index;
         const files = listFilesRecursive(specsDir, ".yaml");
-        const systemYaml = path12.normalize(projectPaths.specsSystem());
+        const systemYaml = path13.normalize(projectPaths.specsSystem());
         const localSubprojects = [];
         for (const file of files) {
-          const normFile = path12.normalize(file);
+          const normFile = path13.normalize(file);
           if (normFile === systemYaml) continue;
           let detectedType = "spec";
           try {
@@ -15064,7 +15230,7 @@ var init_specs2 = __esm({
                 severity: "error",
                 code: "INVALID_YAML",
                 message: `Spec file "${file}" is not a valid YAML object or is empty.`,
-                specId: path12.basename(file, ".yaml")
+                specId: path13.basename(file, ".yaml")
               });
               continue;
             }
@@ -15096,8 +15262,8 @@ var init_specs2 = __esm({
               detectedType = "implementation";
               const parsed = ImplementationSpecSchema.parse(raw);
               if (parsed.sourcePath) {
-                const absSourcePath = path12.resolve(projectDir, parsed.sourcePath);
-                parsed.sourcePath = path12.relative(projectDir, absSourcePath).replace(/\\/g, "/");
+                const absSourcePath = path13.resolve(projectDir, parsed.sourcePath);
+                parsed.sourcePath = path13.relative(projectDir, absSourcePath).replace(/\\/g, "/");
               }
               index.implementations.push(parsed);
               index.paths.implementation[parsed.id] = file;
@@ -15119,11 +15285,11 @@ var init_specs2 = __esm({
                 severity: "error",
                 code: "UNKNOWN_SPEC_TYPE",
                 message: `Spec file "${file}" does not match any recognized L1-L4 schema structure.`,
-                specId: path12.basename(file, ".yaml")
+                specId: path13.basename(file, ".yaml")
               });
             }
           } catch (e) {
-            const filename = path12.basename(file, ".yaml");
+            const filename = path13.basename(file, ".yaml");
             this.loaderIssues.push({
               severity: "error",
               code: "SCHEMA_VALIDATION_ERROR",
@@ -15221,7 +15387,7 @@ var init_specs2 = __esm({
         }
         if (currentDepth < maxDepth) {
           for (const subproj of localSubprojects) {
-            const childDir = path12.resolve(projectDir, subproj.projectPath);
+            const childDir = path13.resolve(projectDir, subproj.projectPath);
             if (projectPathEscapesRoot(this.rootDir, subproj.projectPath, childDir)) {
               this.loaderIssues.push({
                 severity: "error",
@@ -15283,7 +15449,7 @@ var init_specs2 = __esm({
           const index = this.scanAll();
           const sub = index.subsystems.find((s) => s.id === currentPrefix);
           if (sub && sub.projectPath) {
-            const nextDir = path12.resolve(currentDir, sub.projectPath);
+            const nextDir = path13.resolve(currentDir, sub.projectPath);
             if (projectPathEscapesRoot(this.rootDir, sub.projectPath, nextDir)) {
               this.loaderIssues.push({
                 severity: "error",
@@ -15335,9 +15501,9 @@ var init_specs2 = __esm({
           return index.paths.subsystem[matches2[0]];
         }
         if (pathExists(this.paths.specsSubsystemsDir()) && listFiles(this.paths.specsSubsystemsDir(), ".yaml").length > 0) {
-          return path12.join(this.paths.specsSubsystemsDir(), `${id}.yaml`);
+          return path13.join(this.paths.specsSubsystemsDir(), `${id}.yaml`);
         }
-        return path12.join(this.paths.specsDir(), id, ".index.yaml");
+        return path13.join(this.paths.specsDir(), id, ".index.yaml");
       }
       getComponentPath(id, subsystemId) {
         const index = this.scanAll();
@@ -15357,21 +15523,21 @@ var init_specs2 = __esm({
         if (owner) {
           const ownerPath = index.paths.component[owner.id];
           if (ownerPath && ownerPath.endsWith(".index.yaml")) {
-            return path12.join(path12.dirname(ownerPath), id, ".index.yaml");
+            return path13.join(path13.dirname(ownerPath), id, ".index.yaml");
           }
         }
         if (subsystemId) {
           const subPath = this.getSubsystemPath(subsystemId);
-          const subDir = path12.dirname(subPath);
+          const subDir = path13.dirname(subPath);
           if (subPath.endsWith(".index.yaml")) {
-            return path12.join(subDir, id, ".index.yaml");
+            return path13.join(subDir, id, ".index.yaml");
           }
         }
         if (pathExists(this.paths.specsComponentsDir()) && listFiles(this.paths.specsComponentsDir(), ".yaml").length > 0) {
-          return path12.join(this.paths.specsComponentsDir(), `${id}.yaml`);
+          return path13.join(this.paths.specsComponentsDir(), `${id}.yaml`);
         }
         const targetSubsystem = subsystemId || "default";
-        return path12.join(this.paths.specsDir(), targetSubsystem, id, ".index.yaml");
+        return path13.join(this.paths.specsDir(), targetSubsystem, id, ".index.yaml");
       }
       getInterfacePath(id, componentId) {
         const index = this.scanAll();
@@ -15397,16 +15563,16 @@ var init_specs2 = __esm({
         }
         if (componentId) {
           const compPath = this.getComponentPath(componentId);
-          const compDir = path12.dirname(compPath);
+          const compDir = path13.dirname(compPath);
           if (compPath.endsWith(".index.yaml")) {
-            return path12.join(compDir, ".interface.yaml");
+            return path13.join(compDir, ".interface.yaml");
           }
         }
         if (pathExists(this.paths.specsInterfacesDir()) && listFiles(this.paths.specsInterfacesDir(), ".yaml").length > 0) {
-          return path12.join(this.paths.specsInterfacesDir(), `${id}.yaml`);
+          return path13.join(this.paths.specsInterfacesDir(), `${id}.yaml`);
         }
         const targetComponent = componentId || "default";
-        return path12.join(this.paths.specsDir(), "default", targetComponent, ".interface.yaml");
+        return path13.join(this.paths.specsDir(), "default", targetComponent, ".interface.yaml");
       }
       getImplementationPath(id, contractId) {
         const index = this.scanAll();
@@ -15432,16 +15598,16 @@ var init_specs2 = __esm({
         }
         if (contractId) {
           const intfPath = this.getInterfacePath(contractId);
-          const intfDir = path12.dirname(intfPath);
+          const intfDir = path13.dirname(intfPath);
           if (intfPath.endsWith(".interface.yaml")) {
-            return path12.join(intfDir, ".implementation.yaml");
+            return path13.join(intfDir, ".implementation.yaml");
           }
         }
         if (pathExists(this.paths.specsImplementationsDir()) && listFiles(this.paths.specsImplementationsDir(), ".yaml").length > 0) {
-          return path12.join(this.paths.specsImplementationsDir(), `${id}.yaml`);
+          return path13.join(this.paths.specsImplementationsDir(), `${id}.yaml`);
         }
         const targetContract = contractId ? contractId.replace(/^i/, "") : "default";
-        return path12.join(this.paths.specsDir(), "default", targetContract, ".implementation.yaml");
+        return path13.join(this.paths.specsDir(), "default", targetContract, ".implementation.yaml");
       }
       getTypePath(id, subsystemId, group) {
         const index = this.scanAll();
@@ -15472,7 +15638,7 @@ var init_specs2 = __esm({
           const groupPath = index.paths.group[targetGroup] || index.paths.group[plainGroup];
           if (groupPath) {
             const localId2 = id.split("::").pop();
-            return path12.join(path12.dirname(groupPath), `${localId2}.yaml`);
+            return path13.join(path13.dirname(groupPath), `${localId2}.yaml`);
           }
         }
         let localId = id;
@@ -15485,12 +15651,12 @@ var init_specs2 = __esm({
         }
         if (subsystemId) {
           const subPath = this.getSubsystemPath(subsystemId);
-          const subDir = path12.dirname(subPath);
+          const subDir = path13.dirname(subPath);
           if (subPath.endsWith(".index.yaml")) {
-            return path12.join(subDir, "types", `${localId}.yaml`);
+            return path13.join(subDir, "types", `${localId}.yaml`);
           }
         }
-        return path12.join(this.paths.specsTypesDir(), `${localId}.yaml`);
+        return path13.join(this.paths.specsTypesDir(), `${localId}.yaml`);
       }
       getGroupPath(id, subsystemId) {
         const index = this.scanAll();
@@ -15524,12 +15690,12 @@ var init_specs2 = __esm({
         }
         if (subsystemId) {
           const subPath = this.getSubsystemPath(subsystemId);
-          const subDir = path12.dirname(subPath);
+          const subDir = path13.dirname(subPath);
           if (subPath.endsWith(".index.yaml")) {
-            return path12.join(subDir, "types", localId, ".index.yaml");
+            return path13.join(subDir, "types", localId, ".index.yaml");
           }
         }
-        return path12.join(this.paths.specsTypesDir(), localId, ".index.yaml");
+        return path13.join(this.paths.specsTypesDir(), localId, ".index.yaml");
       }
       // -------------------------------------------------------------------------
       // Level 0: System
@@ -15552,7 +15718,7 @@ var init_specs2 = __esm({
       }
       saveSystemSpec(spec) {
         const p = this.paths.specsSystem();
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         writeYamlFile(p, parseOrThrow(SystemSpecSchema, spec, "system", spec.name));
         invalidateSpecCache();
       }
@@ -15670,7 +15836,7 @@ var init_specs2 = __esm({
       }
       saveSubsystemSpec(spec) {
         const p = this.getSubsystemPath(spec.id);
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         const { prefix } = splitNamespace(spec.id);
         if (!prefix && spec.projectPath && spec.projectPath.trim() !== "") {
           assertContainedProjectPath(this.rootDir, spec.projectPath);
@@ -15703,7 +15869,7 @@ var init_specs2 = __esm({
         const p = this.getSubsystemPath(id);
         if (!fs9.existsSync(p)) return false;
         fs9.unlinkSync(p);
-        cleanEmptyDirs(p, path12.resolve(this.paths.specsDir()));
+        cleanEmptyDirs(p, path13.resolve(this.paths.specsDir()));
         invalidateSpecCache();
         return true;
       }
@@ -15736,7 +15902,7 @@ var init_specs2 = __esm({
       saveComponentSpec(spec, opts) {
         const notices = [];
         const p = this.getComponentPath(spec.id, spec.subsystem);
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         const specToWrite = this.prepareComponentForWrite(spec);
         const existing = this.loadComponentSpec(spec.id);
         if (existing) {
@@ -15753,7 +15919,7 @@ var init_specs2 = __esm({
         const subsystemChanged = existing && existing.subsystem !== spec.subsystem && splitNamespace(existing.subsystem).localId !== splitNamespace(spec.subsystem).localId;
         if (subsystemChanged && !p.endsWith(".index.yaml")) {
           notices.push(
-            `component "${spec.id}" already exists at ${path12.relative(this.rootDir, p)} \u2014 the flat layout re-saves in place and never relocates the file. The subsystem field is now "${spec.subsystem}" (was "${existing.subsystem}").`
+            `component "${spec.id}" already exists at ${path13.relative(this.rootDir, p)} \u2014 the flat layout re-saves in place and never relocates the file. The subsystem field is now "${spec.subsystem}" (was "${existing.subsystem}").`
           );
         }
         specToWrite.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -15766,7 +15932,7 @@ var init_specs2 = __esm({
         const p = this.getComponentPath(id);
         if (!fs9.existsSync(p)) return false;
         fs9.unlinkSync(p);
-        cleanEmptyDirs(p, path12.resolve(this.paths.specsDir()));
+        cleanEmptyDirs(p, path13.resolve(this.paths.specsDir()));
         invalidateSpecCache();
         return true;
       }
@@ -15779,12 +15945,12 @@ var init_specs2 = __esm({
         if (owner) {
           const ownerPath = index.paths.component[owner.id];
           if (ownerPath && ownerPath.endsWith(".index.yaml")) {
-            const ownerSubDir = path12.dirname(this.getSubsystemPath(owner.subsystem));
-            return path12.join(ownerSubDir, owner.id, comp.id);
+            const ownerSubDir = path13.dirname(this.getSubsystemPath(owner.subsystem));
+            return path13.join(ownerSubDir, owner.id, comp.id);
           }
         }
-        const subDir = path12.dirname(this.getSubsystemPath(comp.subsystem));
-        return path12.join(subDir, comp.id);
+        const subDir = path13.dirname(this.getSubsystemPath(comp.subsystem));
+        return path13.join(subDir, comp.id);
       }
       /**
        * Move component folders so the physical tree mirrors ownership: each owned
@@ -15800,7 +15966,7 @@ var init_specs2 = __esm({
           if (!currentPath) continue;
           const desiredDir = this.desiredComponentDir(comp, index);
           if (!desiredDir) continue;
-          if (moveComponentFolder(path12.dirname(currentPath), desiredDir)) moved.push(comp.id);
+          if (moveComponentFolder(path13.dirname(currentPath), desiredDir)) moved.push(comp.id);
         }
         if (moved.length) invalidateSpecCache();
         return moved;
@@ -15834,12 +16000,12 @@ var init_specs2 = __esm({
       saveInterfaceSpec(spec, opts) {
         const notices = [];
         const p = this.getInterfacePath(spec.id, spec.component);
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         const specToWrite = this.prepareInterfaceForWrite(spec);
         const existing = this.loadInterfaceSpec(spec.id);
         if (existing && existing.component !== spec.component && splitNamespace(existing.component).localId !== splitNamespace(spec.component).localId) {
           notices.push(
-            `interface "${spec.id}" already exists at ${path12.relative(this.rootDir, p)} \u2014 re-saving updates the component binding field in place (now "${spec.component}", was "${existing.component}") and never moves the file.`
+            `interface "${spec.id}" already exists at ${path13.relative(this.rootDir, p)} \u2014 re-saving updates the component binding field in place (now "${spec.component}", was "${existing.component}") and never moves the file.`
           );
         }
         if (existing) {
@@ -15864,7 +16030,7 @@ var init_specs2 = __esm({
         const p = this.getInterfacePath(id);
         if (!fs9.existsSync(p)) return false;
         fs9.unlinkSync(p);
-        cleanEmptyDirs(p, path12.resolve(this.paths.specsDir()));
+        cleanEmptyDirs(p, path13.resolve(this.paths.specsDir()));
         invalidateSpecCache();
         return true;
       }
@@ -15897,12 +16063,12 @@ var init_specs2 = __esm({
       saveImplementationSpec(spec, opts) {
         const notices = [];
         const p = this.getImplementationPath(spec.id, spec.contract);
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         const specToWrite = this.prepareImplementationForWrite(spec);
         const existing = this.loadImplementationSpec(spec.id);
         if (existing && existing.contract !== spec.contract && splitNamespace(existing.contract).localId !== splitNamespace(spec.contract).localId) {
           notices.push(
-            `implementation "${spec.id}" already exists at ${path12.relative(this.rootDir, p)} \u2014 re-saving updates the contract binding field in place (now "${spec.contract}", was "${existing.contract}") and never moves the file.`
+            `implementation "${spec.id}" already exists at ${path13.relative(this.rootDir, p)} \u2014 re-saving updates the contract binding field in place (now "${spec.contract}", was "${existing.contract}") and never moves the file.`
           );
         }
         if (existing) {
@@ -15920,7 +16086,7 @@ var init_specs2 = __esm({
         const p = this.getImplementationPath(id);
         if (!fs9.existsSync(p)) return false;
         fs9.unlinkSync(p);
-        cleanEmptyDirs(p, path12.resolve(this.paths.specsDir()));
+        cleanEmptyDirs(p, path13.resolve(this.paths.specsDir()));
         invalidateSpecCache();
         return true;
       }
@@ -15945,11 +16111,11 @@ var init_specs2 = __esm({
         const existing = this.loadTypeSpec(spec.id);
         const group = spec.group || (existing ? existing.group : void 0);
         const p = this.getTypePath(spec.id, spec.subsystem, group);
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         const subsystemChanged = existing && (existing.subsystem ?? "") !== (spec.subsystem ?? "") && splitNamespace(existing.subsystem ?? "").localId !== splitNamespace(spec.subsystem ?? "").localId;
         if (subsystemChanged) {
           notices.push(
-            `type "${spec.id}" already exists at ${path12.relative(this.rootDir, p)} \u2014 re-saving updates fields in place and never relocates the file. The subsystem field is now "${spec.subsystem ?? "(none)"}" (was "${existing.subsystem ?? "(none)"}").`
+            `type "${spec.id}" already exists at ${path13.relative(this.rootDir, p)} \u2014 re-saving updates fields in place and never relocates the file. The subsystem field is now "${spec.subsystem ?? "(none)"}" (was "${existing.subsystem ?? "(none)"}").`
           );
         }
         if (spec.subsystem && (!existing || subsystemChanged) && !this.getSubsystemPath(spec.subsystem).endsWith(".index.yaml")) {
@@ -15974,7 +16140,7 @@ var init_specs2 = __esm({
         const p = this.getTypePath(id, spec?.subsystem, spec?.group);
         if (!fs9.existsSync(p)) return false;
         fs9.unlinkSync(p);
-        cleanEmptyDirs(p, path12.resolve(this.paths.specsDir()));
+        cleanEmptyDirs(p, path13.resolve(this.paths.specsDir()));
         invalidateSpecCache();
         return true;
       }
@@ -15989,7 +16155,7 @@ var init_specs2 = __esm({
       }
       saveGroupSpec(spec) {
         const p = this.getGroupPath(spec.id);
-        ensureDir(path12.dirname(p));
+        ensureDir(path13.dirname(p));
         const specToWrite = this.prepareGroupForWrite(spec);
         const existing = this.loadGroupSpec(spec.id);
         if (existing) {
@@ -16003,7 +16169,7 @@ var init_specs2 = __esm({
         const p = this.getGroupPath(id);
         if (!fs9.existsSync(p)) return false;
         fs9.unlinkSync(p);
-        cleanEmptyDirs(p, path12.resolve(this.paths.specsDir()));
+        cleanEmptyDirs(p, path13.resolve(this.paths.specsDir()));
         invalidateSpecCache();
         return true;
       }
@@ -16088,11 +16254,11 @@ var init_specs2 = __esm({
         const files = /* @__PURE__ */ new Set();
         const sysPath = this.paths.specsSystem();
         if (pathExists(sysPath)) {
-          files.add(path12.resolve(sysPath));
+          files.add(path13.resolve(sysPath));
         }
         for (const group of Object.values(index.paths)) {
           for (const file of Object.values(group)) {
-            files.add(path12.resolve(file));
+            files.add(path13.resolve(file));
           }
         }
         for (const file of files) {
@@ -16111,20 +16277,20 @@ var init_specs2 = __esm({
         const files = listFilesRecursive(specsDir, ".yaml");
         const legacy = [];
         for (const f of files) {
-          const base = path12.basename(f);
-          const dir = path12.dirname(f);
+          const base = path13.basename(f);
+          const dir = path13.dirname(f);
           if (base === "system.yaml") {
-            legacy.push({ path: f, expected: path12.join(dir, ".index.yaml") });
+            legacy.push({ path: f, expected: path13.join(dir, ".index.yaml") });
           } else if (base === "subsystem.yaml") {
-            legacy.push({ path: f, expected: path12.join(dir, ".index.yaml") });
+            legacy.push({ path: f, expected: path13.join(dir, ".index.yaml") });
           } else if (base === "component.yaml") {
-            legacy.push({ path: f, expected: path12.join(dir, ".index.yaml") });
+            legacy.push({ path: f, expected: path13.join(dir, ".index.yaml") });
           } else if (base === "group.yaml") {
-            legacy.push({ path: f, expected: path12.join(dir, ".index.yaml") });
+            legacy.push({ path: f, expected: path13.join(dir, ".index.yaml") });
           } else if (base === "interface.yaml") {
-            legacy.push({ path: f, expected: path12.join(dir, ".interface.yaml") });
+            legacy.push({ path: f, expected: path13.join(dir, ".interface.yaml") });
           } else if (base === "implementation.yaml") {
-            legacy.push({ path: f, expected: path12.join(dir, ".implementation.yaml") });
+            legacy.push({ path: f, expected: path13.join(dir, ".implementation.yaml") });
           }
         }
         return legacy;
@@ -16523,11 +16689,13 @@ var init_specs2 = __esm({
 // src/core/agent_resolver.ts
 var agent_resolver_exports = {};
 __export(agent_resolver_exports, {
+  UnknownAgentError: () => UnknownAgentError,
+  composeAgentBrief: () => composeAgentBrief,
   resolveAgentTopology: () => resolveAgentTopology
 });
 function listFilesRecursiveSafe(dirPath, ext) {
   if (!fs10.existsSync(dirPath)) return [];
-  const nameLower = path13.basename(dirPath).toLowerCase();
+  const nameLower = path14.basename(dirPath).toLowerCase();
   const IGNORED_DIRS = /* @__PURE__ */ new Set([
     "node_modules",
     "target",
@@ -16545,7 +16713,7 @@ function listFilesRecursiveSafe(dirPath, ext) {
   const entries = fs10.readdirSync(dirPath, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {
-    const fullPath = path13.join(dirPath, entry.name);
+    const fullPath = path14.join(dirPath, entry.name);
     if (entry.isDirectory()) {
       files.push(...listFilesRecursiveSafe(fullPath, ext));
     } else if (entry.isFile() && entry.name.endsWith(ext)) {
@@ -16558,8 +16726,8 @@ function getProjectFiles(projectDir) {
   let files = projectFilesCache.get(projectDir);
   if (!files) {
     files = [];
-    const srcDir = path13.join(projectDir, "src");
-    const legacySrcDir = path13.join(projectDir, "legacy-src");
+    const srcDir = path14.join(projectDir, "src");
+    const legacySrcDir = path14.join(projectDir, "legacy-src");
     let searchDir = projectDir;
     if (pathExists(srcDir)) {
       searchDir = srcDir;
@@ -16574,7 +16742,7 @@ function getProjectFiles(projectDir) {
       files.push(...listFilesRecursiveSafe(searchDir, ext));
     }
     const rootDir = getProjectRoot();
-    files = files.map((f) => path13.relative(rootDir, f).replace(/\\/g, "/"));
+    files = files.map((f) => path14.relative(rootDir, f).replace(/\\/g, "/"));
     projectFilesCache.set(projectDir, files);
   }
   return files;
@@ -16599,8 +16767,8 @@ function inferSourcePathForComponent(comp, subsystems) {
     let bestFile = null;
     let bestScore = -1;
     for (const f of files) {
-      const ext = path13.extname(f);
-      const base = path13.basename(f, ext).toLowerCase();
+      const ext = path14.extname(f);
+      const base = path14.basename(f, ext).toLowerCase();
       if (candidates.has(base)) {
         let score = 0;
         const normalizedPath = f.toLowerCase();
@@ -16696,7 +16864,7 @@ function resolveAgentTopology() {
   });
   for (const sub of subsystems) {
     if (sub.projectPath) {
-      const mountSpecPath = path13.relative(getProjectRoot(), getSubsystemPath(sub.id)).replace(/\\/g, "/");
+      const mountSpecPath = path14.relative(getProjectRoot(), getSubsystemPath(sub.id)).replace(/\\/g, "/");
       agents.push({
         id: `${sub.id}-owner`,
         name: `${sub.name} (chained subproject)`,
@@ -16718,9 +16886,9 @@ function resolveAgentTopology() {
     }
     const subComponents = components.filter((c) => c.subsystem === sub.id);
     const ownedPaths = [];
-    ownedPaths.push(path13.relative(getProjectRoot(), getSubsystemPath(sub.id)).replace(/\\/g, "/"));
+    ownedPaths.push(path14.relative(getProjectRoot(), getSubsystemPath(sub.id)).replace(/\\/g, "/"));
     for (const c of subComponents) {
-      ownedPaths.push(path13.relative(getProjectRoot(), getComponentPath(c.id, sub.id)).replace(/\\/g, "/"));
+      ownedPaths.push(path14.relative(getProjectRoot(), getComponentPath(c.id, sub.id)).replace(/\\/g, "/"));
     }
     if (!config.rules.generateComponentImplementers) {
       for (const comp of subComponents) {
@@ -16793,10 +16961,10 @@ function resolveAgentTopology() {
       }
       const dependencies = comp.dependsOn.map((depId) => `${depId}-implementer`);
       const readPaths = [
-        path13.relative(getProjectRoot(), AI_PATHS.specsSystem()).replace(/\\/g, "/"),
-        path13.relative(getProjectRoot(), getComponentPath(comp.id, comp.subsystem)).replace(/\\/g, "/"),
-        ...compInterfaces.map((i) => path13.relative(getProjectRoot(), getInterfacePath(i.id, comp.id)).replace(/\\/g, "/")),
-        ...compImpls.map((impl) => path13.relative(getProjectRoot(), getImplementationPath(impl.id, impl.contract)).replace(/\\/g, "/"))
+        path14.relative(getProjectRoot(), AI_PATHS.specsSystem()).replace(/\\/g, "/"),
+        path14.relative(getProjectRoot(), getComponentPath(comp.id, comp.subsystem)).replace(/\\/g, "/"),
+        ...compInterfaces.map((i) => path14.relative(getProjectRoot(), getInterfacePath(i.id, comp.id)).replace(/\\/g, "/")),
+        ...compImpls.map((impl) => path14.relative(getProjectRoot(), getImplementationPath(impl.id, impl.contract)).replace(/\\/g, "/"))
       ];
       agents.push({
         id: `${comp.id}-implementer`,
@@ -16840,17 +17008,64 @@ function resolveAgentTopology() {
   }
   return agents;
 }
-var path13, fs10, projectFilesCache;
+function composeAgentBrief(agentId) {
+  const records = resolveAgentTopology();
+  const record = records.find((r) => r.id === agentId);
+  if (!record) {
+    throw new UnknownAgentError(agentId, records.map((r) => r.id));
+  }
+  const template = loadTemplate(record.template, loadProjectConfig().globalTemplatesDir);
+  let instructions = renderTemplateInstructions(template, {
+    agentId: record.id,
+    agentName: record.name,
+    agentDescription: record.description,
+    ownedPaths: record.ownedPaths.join("\n"),
+    tags: record.tags.join(", "),
+    renderContext: "root",
+    contextNote: "",
+    domainPath: ".",
+    domainName: "",
+    variantGuidance: record.variantGuidance ?? ""
+  });
+  const guidance = loadAgentOverride(agentId);
+  if (guidance !== null) {
+    instructions = `${instructions.trimEnd()}
+
+## Project guidance
+
+${guidance.trim()}
+`;
+  }
+  return {
+    agentId: record.id,
+    name: record.name,
+    template: record.template,
+    domainRoot: record.domainRoot,
+    ownedPaths: record.ownedPaths,
+    readPaths: record.readPaths,
+    instructions,
+    variantGuidance: record.variantGuidance || void 0
+  };
+}
+var path14, fs10, projectFilesCache, UnknownAgentError;
 var init_agent_resolver = __esm({
   "src/core/agent_resolver.ts"() {
     "use strict";
-    path13 = __toESM(require("path"));
+    path14 = __toESM(require("path"));
     fs10 = __toESM(require("fs"));
     init_loader();
     init_fs();
+    init_errors();
+    init_templates();
     init_specs2();
     init_variants();
     projectFilesCache = /* @__PURE__ */ new Map();
+    UnknownAgentError = class extends WaironError {
+      constructor(agentId, knownIds) {
+        super(`Unknown agent id: "${agentId}". Known agent ids: ${knownIds.join(", ")}`);
+        this.name = "UnknownAgentError";
+      }
+    };
   }
 });
 
@@ -16868,12 +17083,12 @@ __export(loader_exports, {
   saveTopologyConfig: () => saveTopologyConfig
 });
 function aiPathsAt(rootDir) {
-  const resolvedRoot = path14.resolve(rootDir);
+  const resolvedRoot = path15.resolve(rootDir);
   const aiDirAt = (...segments) => {
-    const waiPath = path14.join(resolvedRoot, ".wai");
-    const waironPath = path14.join(resolvedRoot, ".wairon");
+    const waiPath = path15.join(resolvedRoot, ".wai");
+    const waironPath = path15.join(resolvedRoot, ".wairon");
     const base = !fs11.existsSync(waiPath) && fs11.existsSync(waironPath) ? waironPath : waiPath;
-    return path14.join(base, ...segments);
+    return path15.join(base, ...segments);
   };
   const specsDir = () => {
     try {
@@ -16881,7 +17096,7 @@ function aiPathsAt(rootDir) {
       if (pathExists(projConfig)) {
         const raw = readYamlFile(projConfig);
         if (raw && raw.paths && raw.paths.specsDir) {
-          return path14.resolve(resolvedRoot, raw.paths.specsDir);
+          return path15.resolve(resolvedRoot, raw.paths.specsDir);
         }
       }
     } catch {
@@ -16902,12 +17117,12 @@ function aiPathsAt(rootDir) {
     contextDomainsMd: () => aiDirAt("context", "domains.md"),
     contextWaironGuideMd: () => aiDirAt("context", "wairon-guide.md"),
     specsDir,
-    specsSystem: () => path14.join(specsDir(), ".index.yaml"),
-    specsSubsystemsDir: () => path14.join(specsDir(), "subsystems"),
-    specsComponentsDir: () => path14.join(specsDir(), "components"),
-    specsInterfacesDir: () => path14.join(specsDir(), "interfaces"),
-    specsImplementationsDir: () => path14.join(specsDir(), "implementations"),
-    specsTypesDir: () => path14.join(specsDir(), "types")
+    specsSystem: () => path15.join(specsDir(), ".index.yaml"),
+    specsSubsystemsDir: () => path15.join(specsDir(), "subsystems"),
+    specsComponentsDir: () => path15.join(specsDir(), "components"),
+    specsInterfacesDir: () => path15.join(specsDir(), "interfaces"),
+    specsImplementationsDir: () => path15.join(specsDir(), "implementations"),
+    specsTypesDir: () => path15.join(specsDir(), "types")
   };
 }
 function isProjectInitialized() {
@@ -16950,12 +17165,12 @@ function loadTopologyConfig() {
 function saveTopologyConfig(config) {
   writeYamlFile(AI_PATHS.topologyConfig(), config);
 }
-var fs11, path14, AI_PATHS;
+var fs11, path15, AI_PATHS;
 var init_loader = __esm({
   "src/config/loader.ts"() {
     "use strict";
     fs11 = __toESM(require("fs"));
-    path14 = __toESM(require("path"));
+    path15 = __toESM(require("path"));
     init_fs();
     init_yaml();
     init_errors();
@@ -16995,7 +17210,7 @@ __export(domains_exports, {
   resolveDomains: () => resolveDomains
 });
 function rel(p) {
-  return path16.relative(process.cwd(), p).replace(/\\/g, "/");
+  return path17.relative(process.cwd(), p).replace(/\\/g, "/");
 }
 function deriveSubsystemDomains() {
   const subsystems = loadSubsystemSpecs();
@@ -17045,11 +17260,11 @@ function removeFreeStandingDomain(id) {
   config.domains.splice(idx, 1);
   saveTopologyConfig(config);
 }
-var path16;
+var path17;
 var init_domains = __esm({
   "src/core/domains.ts"() {
     "use strict";
-    path16 = __toESM(require("path"));
+    path17 = __toESM(require("path"));
     init_loader();
     init_specs2();
     init_errors();
@@ -17062,8 +17277,10 @@ __export(src_exports, {
   AI_PATHS: () => AI_PATHS,
   ARCHITECT_AGENT_ID: () => ARCHITECT_AGENT_ID,
   ARCHITECT_TEMPLATE_ID: () => ARCHITECT_TEMPLATE_ID,
+  AgentBriefSchema: () => AgentBriefSchema,
   AgentRecordSchema: () => AgentRecordSchema,
   AgentStatusSchema: () => AgentStatusSchema,
+  AgentTemplateSchema: () => AgentTemplateSchema,
   AssertionSelectorSchema: () => AssertionSelectorSchema,
   BACKEND_COMMANDS: () => BACKEND_COMMANDS,
   BUILTIN_PROFILES: () => BUILTIN_PROFILES,
@@ -17175,6 +17392,7 @@ __export(src_exports, {
   TypeMethodSchema: () => TypeMethodSchema,
   TypeSpecSchema: () => TypeSpecSchema,
   UNVERSIONED: () => UNVERSIONED,
+  UnknownAgentError: () => UnknownAgentError,
   VariantDefSchema: () => VariantDefSchema,
   WAIRON_MANAGED_BANNER: () => WAIRON_MANAGED_BANNER,
   WAIRON_MANAGED_MARKER: () => WAIRON_MANAGED_MARKER,
@@ -17200,6 +17418,7 @@ __export(src_exports, {
   checkSkillFreshness: () => checkSkillFreshness,
   clearLoaderIssues: () => clearLoaderIssues,
   collectPromotableSpecs: () => collectPromotableSpecs,
+  composeAgentBrief: () => composeAgentBrief,
   composeRuleSequence: () => composeRuleSequence,
   composeVariantGuidance: () => composeVariantGuidance,
   computeGateStateId: () => computeGateStateId,
@@ -17288,6 +17507,7 @@ __export(src_exports, {
   listSkillResources: () => listSkillResources,
   listSnapshots: () => listSnapshots,
   listTemplateIds: () => listTemplateIds,
+  loadAgentOverride: () => loadAgentOverride,
   loadComponentSpec: () => loadComponentSpec,
   loadComponentSpecs: () => loadComponentSpecs,
   loadExtensionPacks: () => loadExtensionPacks,
@@ -17351,6 +17571,7 @@ __export(src_exports, {
   resolveAgentTopology: () => resolveAgentTopology,
   resolveChainingParent: () => resolveChainingParent,
   resolveDomains: () => resolveDomains,
+  resolveExpectedOutputPaths: () => resolveExpectedOutputPaths,
   resolveInstalledPack: () => resolveInstalledPack,
   resolvePackRef: () => resolvePackRef,
   resolveSubprojectForNamespace: () => resolveSubprojectForNamespace,
@@ -17405,7 +17626,7 @@ init_loader();
 
 // src/core/detection.ts
 var fs12 = __toESM(require("fs"));
-var path15 = __toESM(require("path"));
+var path16 = __toESM(require("path"));
 init_defaults();
 var PACKAGE_MARKERS = [
   "package.json",
@@ -17479,7 +17700,7 @@ function parseGitmodules(filePath) {
   return entries;
 }
 function detectGitSubmodules(projectRoot) {
-  const gitmodulesPath = path15.join(projectRoot, ".gitmodules");
+  const gitmodulesPath = path16.join(projectRoot, ".gitmodules");
   if (!fs12.existsSync(gitmodulesPath)) return [];
   return parseGitmodules(gitmodulesPath).map((entry) => ({
     suggestedId: pathToId(entry.path),
@@ -17505,10 +17726,10 @@ function walkForGit(projectRoot, currentDir, depth, results) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (SCAN_EXCLUDE_DIRS.has(entry.name)) continue;
-    const fullPath = path15.join(currentDir, entry.name);
-    const relPath = normalizePath3(path15.relative(projectRoot, fullPath));
+    const fullPath = path16.join(currentDir, entry.name);
+    const relPath = normalizePath3(path16.relative(projectRoot, fullPath));
     if (relPath === "" || relPath === ".") continue;
-    const gitPath = path15.join(fullPath, ".git");
+    const gitPath = path16.join(fullPath, ".git");
     if (fs12.existsSync(gitPath)) {
       results.push({
         suggestedId: pathToId(relPath),
@@ -17538,10 +17759,10 @@ function walkForPackages(projectRoot, currentDir, depth, results) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     if (SCAN_EXCLUDE_DIRS.has(entry.name)) continue;
-    const fullPath = path15.join(currentDir, entry.name);
-    const relPath = normalizePath3(path15.relative(projectRoot, fullPath));
+    const fullPath = path16.join(currentDir, entry.name);
+    const relPath = normalizePath3(path16.relative(projectRoot, fullPath));
     if (relPath === "" || relPath === ".") continue;
-    const hasMarker = PACKAGE_MARKERS.some((m) => fs12.existsSync(path15.join(fullPath, m)));
+    const hasMarker = PACKAGE_MARKERS.some((m) => fs12.existsSync(path16.join(fullPath, m)));
     if (hasMarker) {
       results.push({
         suggestedId: pathToId(relPath),
@@ -17555,7 +17776,7 @@ function walkForPackages(projectRoot, currentDir, depth, results) {
   }
 }
 function pathToId(relPath) {
-  const basename9 = path15.basename(relPath);
+  const basename9 = path16.basename(relPath);
   return basename9.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
 }
 function pathToName(relPath) {
@@ -17568,58 +17789,7 @@ function normalizePath3(p) {
 
 // src/core/index.ts
 init_domains();
-
-// src/core/templates.ts
-var path17 = __toESM(require("path"));
-init_fs();
-init_yaml();
-init_errors();
-init_template();
-init_loader();
-init_defaults();
-function builtinTemplatesDir() {
-  return path17.resolve(__dirname, "..", "templates");
-}
-function loadTemplate(id, globalOverride) {
-  const dirs = templateSearchDirs(globalOverride);
-  for (const dir of dirs) {
-    const filePath = path17.join(dir, `${id}.yaml`);
-    if (pathExists(filePath)) {
-      const raw = readYamlFile(filePath);
-      return TemplateSchema.parse(raw);
-    }
-  }
-  throw new TemplateNotFoundError(id);
-}
-function listTemplateIds(globalOverride) {
-  const seen = /* @__PURE__ */ new Set();
-  for (const dir of templateSearchDirs(globalOverride)) {
-    for (const file of listFiles(dir, ".yaml")) {
-      seen.add(path17.basename(file, ".yaml"));
-    }
-  }
-  return Array.from(seen).sort();
-}
-function templateSearchDirs(globalOverride) {
-  return [
-    AI_PATHS.templatesDir(),
-    // 1. project-local
-    globalTemplatesDir(globalOverride),
-    // 2. global user/org
-    builtinTemplatesDir()
-    // 3. built-in fallback
-  ];
-}
-function renderTemplateInstructions(template, vars) {
-  return template.instructions.replace(/\{\{(\w+)\}\}/g, (_match, key) => {
-    return key in vars ? vars[key] : `{{${key}}}`;
-  });
-}
-function parseTemplate(yamlContent) {
-  return TemplateSchema.parse(parseYaml(yamlContent));
-}
-
-// src/core/index.ts
+init_templates();
 init_validation();
 init_extensions();
 init_variants();
@@ -17649,6 +17819,9 @@ function defaultProjectConfig(name, now) {
       // a large tree/subproject with per-component implementers emits thousands
       // of agents that every session then loads. Opt in with `true` on small trees.
       generateComponentImplementers: false,
+      // Files are the opt-in materialized view of the live briefs — off means
+      // `generate` reconciles to zero agent files.
+      materializeAgentFiles: false,
       sddRuleSeverity: {}
     },
     paths: { specsDir: ".wai/specs" },
@@ -18118,7 +18291,17 @@ before you design anything**, and the others when their turn comes \u2014 they c
 architecture standard, the narrative step reference, and the review checklist that
 this briefing only points at:
 
-${skillPointers(skills)}`;
+${skillPointers(skills)}
+
+## Delegating implementation
+
+Delegate component work from a LIVE agent brief, never a generated file: discover
+agents via \`listAgents\` (or the \`wairon-agent://\` resources), fetch the target's
+brief with \`sdd_get_agent_brief\`, and spawn a scoped subagent from it \u2014 its
+\`instructions\` as prompt, its \`ownedPaths\` as write fence. Briefs are composed
+from the current spec tree on every call, so a re-lock never requires a session
+restart \u2014 fetch fresh per delegation. \`wairon-skill://sdd-delegate\` carries the
+full flow.`;
 }
 function buildServerInstructions() {
   const profile = governingProfile();
@@ -18144,7 +18327,7 @@ ${block.text.trim()}`);
 }
 
 // src/core/skills.ts
-var SKILL_NAMES = ["sdd-architect", "sdd-narrative", "sdd-auditor", "sdd-implement"];
+var SKILL_NAMES = ["sdd-architect", "sdd-narrative", "sdd-auditor", "sdd-implement", "sdd-delegate"];
 function loadProjectExtensions2() {
   return loadProjectExtensions();
 }
@@ -18345,7 +18528,7 @@ If \`.wai/specs/\` exists, the wairon SDD workflow is active; otherwise ignore i
   1. **Skills**: Use \`sdd-architect\` to design (and \`sdd-implement\`, \`sdd-narrative\`, \`sdd-auditor\`). Refer to project's local guide file for detailed constraints.
   2. **MCP Tools Only**: Author/validate specs *only* via \`sdd_*\` tools (e.g. \`sdd_initialize_system\`, \`sdd_validate_tree\`).
   3. **No CLI Exec**: Do not run the \`wairon\` CLI (human tool). Use MCP tools \`sdd_validate_tree\` and \`sdd_get_status\` instead.
-  4. **Subagents**: Spawn generated \`<component>-implementer\` subagents for coding.
+  4. **Delegation**: Delegate implementation via the \`sdd-delegate\` skill \u2014 live agent briefs (\`sdd_get_agent_brief\` MCP tool / \`wairon-agent://\` resource) are composed per call and always current; no session restart. Generated agent files are an optional materialized view of the same topology. User-owned per-agent guidance may live in \`.wai/agents/<agent-id>.md\` (folded into every brief; scaffold via \`wairon agent customize <id>\`).
   5. **Design First**: Complete spec and pass \`sdd_validate_tree\` before writing code.
   6. **Consistency**: Code must match L3 interfaces and L5 narratives exactly. If the spec is wrong, stop and update the spec.
   7. **Subprojects & Namespacing**: If a subsystem uses \`projectPath\` delegation, target its specs using namespaced IDs (e.g. \`subsystem::component\`). Use leading \`::\` to target root (e.g. \`::shared::type\`) and \`super::\` to go up a level (e.g. \`super::sibling\`). wairon automatically resolves the path and strips the prefix on writes.`;
@@ -18492,6 +18675,7 @@ init_surfaces();
 init_openapi();
 init_packstore();
 init_extensions();
+init_agent_resolver();
 
 // src/exporters/base.ts
 var WAIRON_MANAGED_MARKER = "wairon:managed";
@@ -18596,6 +18780,7 @@ function yamlString(value) {
 }
 
 // src/exporters/generate.ts
+var path23 = __toESM(require("path"));
 init_fs();
 
 // src/exporters/registry.ts
@@ -18626,7 +18811,7 @@ function generateAgent(agent, projectConfig, options = {}) {
   const projectRoot = options.projectRoot ?? getProjectRoot();
   const template = loadTemplate(agent.template, projectConfig.globalTemplatesDir);
   const rendered = `${WAIRON_MANAGED_BANNER}
-${renderTemplateInstructions(template, buildVars(agent))}`;
+${composeAgentBrief(agent.id).instructions}`;
   const results = [];
   for (const agentTarget of agent.targets) {
     const targetConfig = resolveTargetConfig(agentTarget, projectConfig);
@@ -18655,19 +18840,17 @@ function generateAll(agents, projectConfig, options = {}) {
   }
   return pool.map((agent) => generateAgent(agent, projectConfig, options));
 }
-function buildVars(agent) {
-  return {
-    agentId: agent.id,
-    agentName: agent.name,
-    agentDescription: agent.description,
-    ownedPaths: agent.ownedPaths.join("\n"),
-    tags: agent.tags.join(", "),
-    renderContext: "root",
-    contextNote: "",
-    domainPath: ".",
-    domainName: "",
-    variantGuidance: agent.variantGuidance ?? ""
-  };
+function resolveExpectedOutputPaths(agents, projectConfig, projectRoot = getProjectRoot()) {
+  const expected = /* @__PURE__ */ new Set();
+  for (const agent of agents) {
+    for (const agentTarget of agent.targets) {
+      const targetConfig = resolveTargetConfig(agentTarget, projectConfig);
+      if (!targetConfig) continue;
+      const ctx = { agent, projectRoot, target: targetConfig };
+      expected.add(path23.resolve(getExporter(targetConfig).outputPath(ctx)));
+    }
+  }
+  return expected;
 }
 function resolveTargetConfig(agentTarget, projectConfig) {
   const targetType = typeof agentTarget === "string" ? agentTarget : agentTarget.type;
@@ -18741,8 +18924,10 @@ init_yaml();
   AI_PATHS,
   ARCHITECT_AGENT_ID,
   ARCHITECT_TEMPLATE_ID,
+  AgentBriefSchema,
   AgentRecordSchema,
   AgentStatusSchema,
+  AgentTemplateSchema,
   AssertionSelectorSchema,
   BACKEND_COMMANDS,
   BUILTIN_PROFILES,
@@ -18854,6 +19039,7 @@ init_yaml();
   TypeMethodSchema,
   TypeSpecSchema,
   UNVERSIONED,
+  UnknownAgentError,
   VariantDefSchema,
   WAIRON_MANAGED_BANNER,
   WAIRON_MANAGED_MARKER,
@@ -18879,6 +19065,7 @@ init_yaml();
   checkSkillFreshness,
   clearLoaderIssues,
   collectPromotableSpecs,
+  composeAgentBrief,
   composeRuleSequence,
   composeVariantGuidance,
   computeGateStateId,
@@ -18967,6 +19154,7 @@ init_yaml();
   listSkillResources,
   listSnapshots,
   listTemplateIds,
+  loadAgentOverride,
   loadComponentSpec,
   loadComponentSpecs,
   loadExtensionPacks,
@@ -19030,6 +19218,7 @@ init_yaml();
   resolveAgentTopology,
   resolveChainingParent,
   resolveDomains,
+  resolveExpectedOutputPaths,
   resolveInstalledPack,
   resolvePackRef,
   resolveSubprojectForNamespace,