@gotgenes/pi-subagents 6.12.0 → 6.13.0

package/docs/retro/0135-extract-display-helpers.md

@@ -0,0 +1,38 @@
+---
+issue: 135
+issue_title: "Extract display helpers from `agent-widget.ts`"
+---
+
+# Retro: #135 — Extract display helpers from agent-widget.ts
+
+## Final Retrospective (2026-05-22T19:00:00Z)
+
+### Session summary
+
+Extracted 11 helper functions, 3 constants, and 2 types from `agent-widget.ts` into a new `ui/display.ts` module.
+Updated 10 source consumers and 2 test consumers.
+Pure code-motion refactoring — no behavior change, no test-count delta (714 tests throughout).
+
+### Observations
+
+#### What went well
+
+- Plan accurately identified all 10 source and 2 test import sites with no misses — the consumer import table in the plan mapped 1:1 to actual changes.
+- TDD execution was mechanical and smooth: create module → update source imports → rename test file → verify.
+  Zero surprises or deviations from the plan.
+
+#### What caused friction (agent side)
+
+- `rabbit-hole` — During `/ship-issue`, wasted ~6 tool calls investigating whether `pi-subagents-v6.12.0` was at HEAD.
+  Ran `git log --oneline HEAD --not --remotes=origin/main` which dumped the entire repo history (50KB truncation), then misread `git describe --tags --abbrev=0` (nearest ancestor tag) as confirming the tag was at HEAD.
+  `git tag --points-at HEAD` returned empty, disproving the assumption, but I still spent cycles reasoning about CI release-please behavior.
+  Impact: added friction but no rework — the close comment and release-please merge were correct.
+
+#### What caused friction (user side)
+
+- None observed.
+  The issue was unambiguous, the architecture doc prescribed the exact extraction set, and no user intervention was needed during implementation.
+
+### Changes made
+
+1. Created `packages/pi-subagents/docs/retro/0135-extract-display-helpers.md` (this file).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.12.0",
+  "version": "6.13.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/index.ts

@@ -41,6 +41,7 @@ import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
 import { createSteerTool } from "./tools/steer-tool.js";
+import { FsAgentFileOps } from "./ui/agent-file-ops.js";
 import { createAgentsMenuHandler } from "./ui/agent-menu.js";
 import {
   AgentWidget,
@@ -248,6 +249,7 @@ export default function (pi: ExtensionAPI) {
       return getModelLabelFromConfig(cfg.model);
     },
     settings,
+    fileOps: new FsAgentFileOps(),
     personalAgentsDir: join(getAgentDir(), 'agents'),
     projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
   });

package/src/renderer.ts

@@ -1,6 +1,6 @@
 import { Text } from "@earendil-works/pi-tui";
 import type { NotificationDetails } from "./notification.js";
-import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
+import { formatMs, formatTokens, formatTurns } from "./ui/display.js";
 
 /** Narrow theme interface — only the methods the renderer actually calls. */
 interface RendererTheme {

package/src/tools/agent-tool.ts

@@ -9,6 +9,7 @@ import { resolveInvocationModel } from "../model-resolver.js";
 
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import { type UICtx } from "../ui/agent-widget.js";
 import {
   type AgentDetails,
   buildInvocationTags,
@@ -17,8 +18,7 @@ import {
   getDisplayName,
   getPromptModeLabel,
   SPINNER,
-  type UICtx,
-} from "../ui/agent-widget.js";
+} from "../ui/display.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
 import { buildDetails, buildTypeListText, textResult } from "./helpers.js";

package/src/tools/background-spawner.ts

@@ -2,7 +2,7 @@ import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSpawnConfig } from "../agent-manager.js";
 import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import type { AgentDetails } from "../ui/agent-widget.js";
+import type { AgentDetails } from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import { textResult } from "./helpers.js";

package/src/tools/foreground-runner.ts

@@ -8,7 +8,7 @@ import {
   describeActivity,
   formatMs,
   SPINNER,
-} from "../ui/agent-widget.js";
+} from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import {

package/src/tools/get-result-tool.ts

@@ -2,7 +2,7 @@ import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentConfigLookup } from "../agent-types.js";
 import type { AgentRecord } from "../types.js";
-import { formatDuration, getDisplayName } from "../ui/agent-widget.js";
+import { formatDuration, getDisplayName } from "../ui/display.js";
 import { getSessionContextPercent } from "../usage.js";
 import { formatLifetimeTokens, textResult } from "./helpers.js";
 

package/src/tools/helpers.ts

@@ -1,6 +1,6 @@
 import type { AgentConfigLookup } from "../agent-types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import { type AgentDetails, formatTokens } from "../ui/agent-widget.js";
+import { type AgentDetails, formatTokens } from "../ui/display.js";
 import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
 
 /** Parenthetical status note for completed agent result text. */

package/src/ui/agent-config-editor.ts

@@ -0,0 +1,202 @@
+/**
+ * agent-config-editor.ts — Agent detail view with edit/delete/eject/disable/enable transitions.
+ *
+ * Extracted from agent-menu.ts to give each concern a single responsibility.
+ * Receives dependencies via injection — no direct `node:fs` imports.
+ */
+
+import { join } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentTypeRegistry } from "../agent-types.js";
+import type { AgentConfig } from "../types.js";
+import type { AgentFileOps } from "./agent-file-ops.js";
+
+// ---- Deps interface ----
+
+export interface AgentConfigEditorDeps {
+  fileOps: AgentFileOps;
+  registry: AgentTypeRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+
+// ---- Factory ----
+
+export function createAgentConfigEditor(deps: AgentConfigEditorDeps) {
+  function agentDirs(): string[] {
+    return [deps.projectAgentsDir, deps.personalAgentsDir];
+  }
+
+  async function showAgentDetail(ctx: ExtensionContext, name: string) {
+    if (deps.registry.resolveType(name) == null) {
+      ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
+      return;
+    }
+    const cfg = deps.registry.resolveAgentConfig(name);
+
+    const file = deps.fileOps.findAgentFile(name, agentDirs());
+    const isDefault = cfg.isDefault === true;
+    const disabled = cfg.enabled === false;
+
+    let menuOptions: string[];
+    if (disabled && file) {
+      menuOptions = isDefault
+        ? ["Enable", "Edit", "Reset to default", "Delete", "Back"]
+        : ["Enable", "Edit", "Delete", "Back"];
+    } else if (isDefault && !file) {
+      menuOptions = ["Eject (export as .md)", "Disable", "Back"];
+    } else if (isDefault && file) {
+      menuOptions = ["Edit", "Disable", "Reset to default", "Delete", "Back"];
+    } else {
+      menuOptions = ["Edit", "Disable", "Delete", "Back"];
+    }
+
+    const choice = await ctx.ui.select(name, menuOptions);
+    if (!choice || choice === "Back") return;
+
+    if (choice === "Edit" && file) {
+      const content = deps.fileOps.read(file);
+      if (content !== undefined) {
+        const edited = await ctx.ui.editor(`Edit ${name}`, content);
+        if (edited !== undefined && edited !== content) {
+          deps.fileOps.write(file, edited);
+          deps.registry.reload();
+          ctx.ui.notify(`Updated ${file}`, "info");
+        }
+      }
+    } else if (choice === "Delete") {
+      if (file) {
+        const confirmed = await ctx.ui.confirm(
+          "Delete agent",
+          `Delete ${name} (${file})?`,
+        );
+        if (confirmed) {
+          deps.fileOps.remove(file);
+          deps.registry.reload();
+          ctx.ui.notify(`Deleted ${file}`, "info");
+        }
+      }
+    } else if (choice === "Reset to default" && file) {
+      const confirmed = await ctx.ui.confirm(
+        "Reset to default",
+        `Delete override ${file} and restore embedded default?`,
+      );
+      if (confirmed) {
+        deps.fileOps.remove(file);
+        deps.registry.reload();
+        ctx.ui.notify(`Restored default ${name}`, "info");
+      }
+    } else if (choice.startsWith("Eject")) {
+      await ejectAgent(ctx, name, cfg);
+    } else if (choice === "Disable") {
+      await disableAgent(ctx, name);
+    } else if (choice === "Enable") {
+      await enableAgent(ctx, name);
+    }
+  }
+
+  async function ejectAgent(ctx: ExtensionContext, name: string, cfg: AgentConfig) {
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      `Personal (${deps.personalAgentsDir})`,
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project")
+      ? deps.projectAgentsDir
+      : deps.personalAgentsDir;
+
+    const targetPath = join(targetDir, `${name}.md`);
+    if (deps.fileOps.exists(targetPath)) {
+      const overwrite = await ctx.ui.confirm(
+        "Overwrite",
+        `${targetPath} already exists. Overwrite?`,
+      );
+      if (!overwrite) return;
+    }
+
+    const fmFields: string[] = [];
+    fmFields.push(`description: ${cfg.description}`);
+    if (cfg.displayName) fmFields.push(`display_name: ${cfg.displayName}`);
+    fmFields.push(`tools: ${cfg.builtinToolNames?.join(", ") || "all"}`);
+    if (cfg.model) fmFields.push(`model: ${cfg.model}`);
+    if (cfg.thinking) fmFields.push(`thinking: ${cfg.thinking}`);
+    if (cfg.maxTurns) fmFields.push(`max_turns: ${cfg.maxTurns}`);
+    fmFields.push(`prompt_mode: ${cfg.promptMode}`);
+    if (cfg.extensions === false) fmFields.push("extensions: false");
+    else if (Array.isArray(cfg.extensions))
+      fmFields.push(`extensions: ${cfg.extensions.join(", ")}`);
+    if (cfg.skills === false) fmFields.push("skills: false");
+    else if (Array.isArray(cfg.skills))
+      fmFields.push(`skills: ${cfg.skills.join(", ")}`);
+    if (cfg.disallowedTools?.length)
+      fmFields.push(`disallowed_tools: ${cfg.disallowedTools.join(", ")}`);
+    if (cfg.inheritContext) fmFields.push("inherit_context: true");
+    if (cfg.runInBackground) fmFields.push("run_in_background: true");
+    if (cfg.isolated) fmFields.push("isolated: true");
+    if (cfg.memory) fmFields.push(`memory: ${cfg.memory}`);
+    if (cfg.isolation) fmFields.push(`isolation: ${cfg.isolation}`);
+
+    const content = `---\n${fmFields.join("\n")}\n---\n\n${cfg.systemPrompt}\n`;
+
+    deps.fileOps.write(targetPath, content);
+    deps.registry.reload();
+    ctx.ui.notify(`Ejected ${name} to ${targetPath}`, "info");
+  }
+
+  async function disableAgent(ctx: ExtensionContext, name: string) {
+    const file = deps.fileOps.findAgentFile(name, agentDirs());
+    if (file) {
+      const content = deps.fileOps.read(file);
+      if (content?.includes("\nenabled: false\n")) {
+        ctx.ui.notify(`${name} is already disabled.`, "info");
+        return;
+      }
+      if (content) {
+        const updated = content.replace(/^---\n/, "---\nenabled: false\n");
+        deps.fileOps.write(file, updated);
+        deps.registry.reload();
+        ctx.ui.notify(`Disabled ${name} (${file})`, "info");
+      }
+      return;
+    }
+
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      `Personal (${deps.personalAgentsDir})`,
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project")
+      ? deps.projectAgentsDir
+      : deps.personalAgentsDir;
+
+    const targetPath = join(targetDir, `${name}.md`);
+    deps.fileOps.write(targetPath, "---\nenabled: false\n---\n");
+    deps.registry.reload();
+    ctx.ui.notify(`Disabled ${name} (${targetPath})`, "info");
+  }
+
+  async function enableAgent(ctx: ExtensionContext, name: string) {
+    const file = deps.fileOps.findAgentFile(name, agentDirs());
+    if (!file) return;
+
+    const content = deps.fileOps.read(file);
+    if (!content) return;
+
+    const updated = content.replace(/^(---\n)enabled: false\n/, "$1");
+
+    if (updated.trim() === "---\n---" || updated.trim() === "---\n---\n") {
+      deps.fileOps.remove(file);
+      deps.registry.reload();
+      ctx.ui.notify(`Enabled ${name} (removed ${file})`, "info");
+    } else {
+      deps.fileOps.write(file, updated);
+      deps.registry.reload();
+      ctx.ui.notify(`Enabled ${name} (${file})`, "info");
+    }
+  }
+
+  return { showAgentDetail };
+}

package/src/ui/agent-creation-wizard.ts

@@ -0,0 +1,246 @@
+/**
+ * agent-creation-wizard.ts — AI-generation and manual-form agent creation flows.
+ *
+ * Extracted from agent-menu.ts to give each concern a single responsibility.
+ * Receives dependencies via injection — no direct `node:fs` imports.
+ */
+
+import { join } from "node:path";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { BUILTIN_TOOL_NAMES } from "../agent-types.js";
+import type { AgentRecord } from "../types.js";
+import type { AgentFileOps } from "./agent-file-ops.js";
+
+// ---- Deps interface ----
+
+/** Narrow manager interface for agent spawning (generate wizard). */
+export interface WizardManager {
+  spawnAndWait: (
+    ctx: ExtensionContext,
+    type: string,
+    prompt: string,
+    opts: { description: string; maxTurns: number },
+  ) => Promise<AgentRecord>;
+}
+
+/** Narrow registry interface for reloading after creation. */
+export interface WizardRegistry {
+  reload(): void;
+}
+
+export interface AgentCreationWizardDeps {
+  fileOps: AgentFileOps;
+  manager: WizardManager;
+  registry: WizardRegistry;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+
+// ---- Factory ----
+
+export function createAgentCreationWizard(deps: AgentCreationWizardDeps) {
+  async function showCreateWizard(ctx: ExtensionContext) {
+    const location = await ctx.ui.select("Choose location", [
+      "Project (.pi/agents/)",
+      `Personal (${deps.personalAgentsDir})`,
+    ]);
+    if (!location) return;
+
+    const targetDir = location.startsWith("Project")
+      ? deps.projectAgentsDir
+      : deps.personalAgentsDir;
+
+    const method = await ctx.ui.select("Creation method", [
+      "Generate with Claude (recommended)",
+      "Manual configuration",
+    ]);
+    if (!method) return;
+
+    if (method.startsWith("Generate")) {
+      await showGenerateWizard(ctx, targetDir);
+    } else {
+      await showManualWizard(ctx, targetDir);
+    }
+  }
+
+  async function showGenerateWizard(ctx: ExtensionContext, targetDir: string) {
+    const description = await ctx.ui.input("Describe what this agent should do");
+    if (!description) return;
+
+    const name = await ctx.ui.input("Agent name (filename, no spaces)");
+    if (!name) return;
+
+    deps.fileOps.ensureDir(targetDir);
+
+    const targetPath = join(targetDir, `${name}.md`);
+    if (deps.fileOps.exists(targetPath)) {
+      const overwrite = await ctx.ui.confirm(
+        "Overwrite",
+        `${targetPath} already exists. Overwrite?`,
+      );
+      if (!overwrite) return;
+    }
+
+    ctx.ui.notify("Generating agent definition...", "info");
+
+    const generatePrompt = `Create a custom pi sub-agent definition file based on this description: "${description}"
+
+Write a markdown file to: ${targetPath}
+
+The file format is a markdown file with YAML frontmatter and a system prompt body:
+
+\`\`\`markdown
+---
+description: <one-line description shown in UI>
+tools: <comma-separated built-in tools: read, bash, edit, write, grep, find, ls. Use "none" for no tools. Omit for all tools>
+model: <optional model as "provider/modelId", e.g. "anthropic/claude-haiku-4-5-20251001". Omit to inherit parent model>
+thinking: <optional thinking level: off, minimal, low, medium, high, xhigh. Omit to inherit>
+max_turns: <optional max agentic turns. 0 or omit for unlimited (default)>
+prompt_mode: <"replace" (body IS the full system prompt) or "append" (body is appended to default prompt). Default: replace>
+extensions: <true (inherit all MCP/extension tools), false (none), or comma-separated names. Default: true>
+skills: <true (inherit all), false (none), or comma-separated skill names to preload into prompt. Default: true>
+disallowed_tools: <comma-separated tool names to block, even if otherwise available. Omit for none>
+inherit_context: <true to fork parent conversation into agent so it sees chat history. Default: false>
+run_in_background: <true to run in background by default. Default: false>
+isolated: <true for no extension/MCP tools, only built-in tools. Default: false>
+memory: <"user" (global), "project" (per-project), or "local" (gitignored per-project) for persistent memory. Omit for none>
+isolation: <"worktree" to run in isolated git worktree. Omit for normal>
+---
+
+<system prompt body — instructions for the agent>
+\`\`\`
+
+Guidelines for choosing settings:
+- For read-only tasks (review, analysis): tools: read, bash, grep, find, ls
+- For code modification tasks: include edit, write
+- Use prompt_mode: append if the agent should keep the default system prompt and add specialization on top
+- Use prompt_mode: replace for fully custom agents with their own personality/instructions
+- Set inherit_context: true if the agent needs to know what was discussed in the parent conversation
+- Set isolated: true if the agent should NOT have access to MCP servers or other extensions
+- Only include frontmatter fields that differ from defaults — omit fields where the default is fine
+
+Write the file using the write tool. Only write the file, nothing else.`;
+
+    const record = await deps.manager.spawnAndWait(
+      ctx,
+      "general-purpose",
+      generatePrompt,
+      {
+        description: `Generate ${name} agent`,
+        maxTurns: 5,
+      },
+    );
+
+    if (record.status === "error") {
+      ctx.ui.notify(`Generation failed: ${record.error}`, "warning");
+      return;
+    }
+
+    deps.registry.reload();
+
+    if (deps.fileOps.exists(targetPath)) {
+      ctx.ui.notify(`Created ${targetPath}`, "info");
+    } else {
+      ctx.ui.notify(
+        "Agent generation completed but file was not created. Check the agent output.",
+        "warning",
+      );
+    }
+  }
+
+  async function showManualWizard(ctx: ExtensionContext, targetDir: string) {
+    const name = await ctx.ui.input("Agent name (filename, no spaces)");
+    if (!name) return;
+
+    const description = await ctx.ui.input("Description (one line)");
+    if (!description) return;
+
+    const toolChoice = await ctx.ui.select("Tools", [
+      "all",
+      "none",
+      "read-only (read, bash, grep, find, ls)",
+      "custom...",
+    ]);
+    if (!toolChoice) return;
+
+    let tools: string;
+    if (toolChoice === "all") {
+      tools = BUILTIN_TOOL_NAMES.join(", ");
+    } else if (toolChoice === "none") {
+      tools = "none";
+    } else if (toolChoice.startsWith("read-only")) {
+      tools = "read, bash, grep, find, ls";
+    } else {
+      const customTools = await ctx.ui.input(
+        "Tools (comma-separated)",
+        BUILTIN_TOOL_NAMES.join(", "),
+      );
+      if (!customTools) return;
+      tools = customTools;
+    }
+
+    const modelChoice = await ctx.ui.select("Model", [
+      "inherit (parent model)",
+      "haiku",
+      "sonnet",
+      "opus",
+      "custom...",
+    ]);
+    if (!modelChoice) return;
+
+    let modelLine = "";
+    if (modelChoice === "haiku")
+      modelLine = "\nmodel: anthropic/claude-haiku-4-5-20251001";
+    else if (modelChoice === "sonnet")
+      modelLine = "\nmodel: anthropic/claude-sonnet-4-6";
+    else if (modelChoice === "opus")
+      modelLine = "\nmodel: anthropic/claude-opus-4-6";
+    else if (modelChoice === "custom...") {
+      const customModel = await ctx.ui.input("Model (provider/modelId)");
+      if (customModel) modelLine = `\nmodel: ${customModel}`;
+    }
+
+    const thinkingChoice = await ctx.ui.select("Thinking level", [
+      "inherit",
+      "off",
+      "minimal",
+      "low",
+      "medium",
+      "high",
+      "xhigh",
+    ]);
+    if (!thinkingChoice) return;
+
+    let thinkingLine = "";
+    if (thinkingChoice !== "inherit") thinkingLine = `\nthinking: ${thinkingChoice}`;
+
+    const systemPrompt = await ctx.ui.editor("System prompt", "");
+    if (systemPrompt === undefined) return;
+
+    const content = `---
+description: ${description}
+tools: ${tools}${modelLine}${thinkingLine}
+prompt_mode: replace
+---
+
+${systemPrompt}
+`;
+
+    const targetPath = join(targetDir, `${name}.md`);
+
+    if (deps.fileOps.exists(targetPath)) {
+      const overwrite = await ctx.ui.confirm(
+        "Overwrite",
+        `${targetPath} already exists. Overwrite?`,
+      );
+      if (!overwrite) return;
+    }
+
+    deps.fileOps.write(targetPath, content);
+    deps.registry.reload();
+    ctx.ui.notify(`Created ${targetPath}`, "info");
+  }
+
+  return { showCreateWizard };
+}

package/src/ui/agent-file-ops.ts

@@ -0,0 +1,59 @@
+/**
+ * agent-file-ops.ts — Filesystem abstraction for agent .md file operations.
+ *
+ * Decouples menu sub-modules from direct `node:fs` imports, making them
+ * testable via plain stub objects without `vi.mock()`.
+ */
+
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+// ---- Interface ----
+
+/** Filesystem operations for agent `.md` files. */
+export interface AgentFileOps {
+  exists(filePath: string): boolean;
+  read(filePath: string): string | undefined;
+  write(filePath: string, content: string): void;
+  remove(filePath: string): void;
+  ensureDir(dirPath: string): void;
+  findAgentFile(name: string, dirs: string[]): string | undefined;
+}
+
+// ---- Production implementation ----
+
+/** Production implementation wrapping `node:fs` synchronous APIs. */
+export class FsAgentFileOps implements AgentFileOps {
+  exists(filePath: string): boolean {
+    return existsSync(filePath);
+  }
+
+  read(filePath: string): string | undefined {
+    try {
+      return readFileSync(filePath, "utf-8");
+    } catch {
+      return undefined;
+    }
+  }
+
+  write(filePath: string, content: string): void {
+    mkdirSync(dirname(filePath), { recursive: true });
+    writeFileSync(filePath, content, "utf-8");
+  }
+
+  remove(filePath: string): void {
+    unlinkSync(filePath);
+  }
+
+  ensureDir(dirPath: string): void {
+    mkdirSync(dirPath, { recursive: true });
+  }
+
+  findAgentFile(name: string, dirs: string[]): string | undefined {
+    for (const dir of dirs) {
+      const p = join(dir, `${name}.md`);
+      if (existsSync(p)) return p;
+    }
+    return undefined;
+  }
+}