stagent 0.3.6 → 0.5.0

package/src/lib/agents/__tests__/browser-mcp.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock the settings helpers before importing the module under test
+vi.mock("@/lib/settings/helpers", () => ({
+  getSetting: vi.fn(),
+}));
+
+import { getSetting } from "@/lib/settings/helpers";
+import {
+  getBrowserMcpServers,
+  getBrowserAllowedToolPatterns,
+  isBrowserTool,
+  isBrowserReadOnly,
+} from "@/lib/agents/browser-mcp";
+
+const mockGetSetting = vi.mocked(getSetting);
+
+describe("browser-mcp", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe("getBrowserMcpServers", () => {
+    it("returns empty object when neither server is enabled", async () => {
+      mockGetSetting.mockResolvedValue(null);
+      const servers = await getBrowserMcpServers();
+      expect(servers).toEqual({});
+    });
+
+    it("returns chrome-devtools config when enabled", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.chromeDevtoolsEnabled") return "true";
+        return null;
+      });
+
+      const servers = await getBrowserMcpServers();
+      expect(servers["chrome-devtools"]).toBeDefined();
+      expect(servers["chrome-devtools"].command).toBe("npx");
+      expect(servers["chrome-devtools"].args).toContain("chrome-devtools-mcp@latest");
+      expect(servers.playwright).toBeUndefined();
+    });
+
+    it("returns playwright config when enabled", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.playwrightEnabled") return "true";
+        return null;
+      });
+
+      const servers = await getBrowserMcpServers();
+      expect(servers.playwright).toBeDefined();
+      expect(servers.playwright.command).toBe("npx");
+      expect(servers.playwright.args).toContain("@playwright/mcp@latest");
+      expect(servers["chrome-devtools"]).toBeUndefined();
+    });
+
+    it("returns both when both enabled", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.chromeDevtoolsEnabled") return "true";
+        if (key === "browser.playwrightEnabled") return "true";
+        return null;
+      });
+
+      const servers = await getBrowserMcpServers();
+      expect(Object.keys(servers)).toHaveLength(2);
+      expect(servers["chrome-devtools"]).toBeDefined();
+      expect(servers.playwright).toBeDefined();
+    });
+
+    it("appends extra args from config", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.chromeDevtoolsEnabled") return "true";
+        if (key === "browser.chromeDevtoolsConfig") return "--headless --browser-url http://localhost:9222";
+        return null;
+      });
+
+      const servers = await getBrowserMcpServers();
+      expect(servers["chrome-devtools"].args).toContain("--headless");
+      expect(servers["chrome-devtools"].args).toContain("--browser-url");
+      expect(servers["chrome-devtools"].args).toContain("http://localhost:9222");
+    });
+
+    it("handles JSON array config format", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.playwrightEnabled") return "true";
+        if (key === "browser.playwrightConfig") return '["--browser", "firefox"]';
+        return null;
+      });
+
+      const servers = await getBrowserMcpServers();
+      expect(servers.playwright.args).toContain("--browser");
+      expect(servers.playwright.args).toContain("firefox");
+    });
+
+    it("handles invalid JSON config as space-separated args", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.chromeDevtoolsEnabled") return "true";
+        if (key === "browser.chromeDevtoolsConfig") return "[invalid json";
+        return null;
+      });
+
+      const servers = await getBrowserMcpServers();
+      // Invalid JSON starting with [ falls back to space-split
+      expect(servers["chrome-devtools"].args).toEqual(["-y", "chrome-devtools-mcp@latest", "[invalid", "json"]);
+    });
+  });
+
+  describe("getBrowserAllowedToolPatterns", () => {
+    it("returns empty when nothing enabled", async () => {
+      mockGetSetting.mockResolvedValue(null);
+      const patterns = await getBrowserAllowedToolPatterns();
+      expect(patterns).toEqual([]);
+    });
+
+    it("returns chrome pattern when chrome enabled", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.chromeDevtoolsEnabled") return "true";
+        return null;
+      });
+
+      const patterns = await getBrowserAllowedToolPatterns();
+      expect(patterns).toContain("mcp__chrome-devtools__*");
+      expect(patterns).not.toContain("mcp__playwright__*");
+    });
+
+    it("returns both patterns when both enabled", async () => {
+      mockGetSetting.mockImplementation(async (key: string) => {
+        if (key === "browser.chromeDevtoolsEnabled") return "true";
+        if (key === "browser.playwrightEnabled") return "true";
+        return null;
+      });
+
+      const patterns = await getBrowserAllowedToolPatterns();
+      expect(patterns).toContain("mcp__chrome-devtools__*");
+      expect(patterns).toContain("mcp__playwright__*");
+    });
+  });
+
+  describe("isBrowserTool", () => {
+    it("identifies chrome devtools tools", () => {
+      expect(isBrowserTool("mcp__chrome-devtools__click")).toBe(true);
+      expect(isBrowserTool("mcp__chrome-devtools__take_screenshot")).toBe(true);
+    });
+
+    it("identifies playwright tools", () => {
+      expect(isBrowserTool("mcp__playwright__browser_navigate")).toBe(true);
+      expect(isBrowserTool("mcp__playwright__browser_snapshot")).toBe(true);
+    });
+
+    it("rejects non-browser tools", () => {
+      expect(isBrowserTool("mcp__stagent__list_tasks")).toBe(false);
+      expect(isBrowserTool("Read")).toBe(false);
+      expect(isBrowserTool("Bash")).toBe(false);
+    });
+  });
+
+  describe("isBrowserReadOnly", () => {
+    it("identifies read-only chrome devtools tools", () => {
+      expect(isBrowserReadOnly("mcp__chrome-devtools__take_screenshot")).toBe(true);
+      expect(isBrowserReadOnly("mcp__chrome-devtools__list_pages")).toBe(true);
+      expect(isBrowserReadOnly("mcp__chrome-devtools__lighthouse_audit")).toBe(true);
+    });
+
+    it("identifies read-only playwright tools", () => {
+      expect(isBrowserReadOnly("mcp__playwright__browser_snapshot")).toBe(true);
+      expect(isBrowserReadOnly("mcp__playwright__browser_tabs")).toBe(true);
+    });
+
+    it("rejects mutation browser tools", () => {
+      expect(isBrowserReadOnly("mcp__chrome-devtools__click")).toBe(false);
+      expect(isBrowserReadOnly("mcp__chrome-devtools__fill")).toBe(false);
+      expect(isBrowserReadOnly("mcp__playwright__browser_navigate")).toBe(false);
+      expect(isBrowserReadOnly("mcp__playwright__browser_click")).toBe(false);
+    });
+  });
+});

package/src/lib/agents/__tests__/claude-agent.test.ts

@@ -132,6 +132,9 @@ vi.mock("@/lib/agents/pattern-extractor", () => ({
 vi.mock("@/lib/agents/sweep", () => ({
   processSweepResult: mockProcessSweepResult,
 }));
+vi.mock("@/lib/agents/browser-mcp", () => ({
+  getBrowserMcpServers: vi.fn().mockResolvedValue({}),
+}));
 
 // Static imports (works because vi.mock is hoisted)
 import { query } from "@anthropic-ai/claude-agent-sdk";

package/src/lib/agents/browser-mcp.ts

@@ -0,0 +1,119 @@
+import { getSetting } from "@/lib/settings/helpers";
+import { SETTINGS_KEYS } from "@/lib/constants/settings";
+
+// ── MCP server config type (matches Claude Agent SDK shape) ──────────
+
+interface McpServerConfig {
+  command: string;
+  args: string[];
+}
+
+// ── Read-only browser tools — auto-approved in chat & task permission callbacks
+
+export const BROWSER_READ_ONLY_TOOLS = new Set([
+  // Chrome DevTools MCP — read-only
+  "mcp__chrome-devtools__take_screenshot",
+  "mcp__chrome-devtools__take_snapshot",
+  "mcp__chrome-devtools__take_memory_snapshot",
+  "mcp__chrome-devtools__list_pages",
+  "mcp__chrome-devtools__list_console_messages",
+  "mcp__chrome-devtools__list_network_requests",
+  "mcp__chrome-devtools__get_console_message",
+  "mcp__chrome-devtools__get_network_request",
+  "mcp__chrome-devtools__lighthouse_audit",
+  "mcp__chrome-devtools__performance_start_trace",
+  "mcp__chrome-devtools__performance_stop_trace",
+  "mcp__chrome-devtools__performance_analyze_insight",
+  // Playwright MCP — read-only
+  "mcp__playwright__browser_snapshot",
+  "mcp__playwright__browser_console_messages",
+  "mcp__playwright__browser_network_requests",
+  "mcp__playwright__browser_tabs",
+  "mcp__playwright__browser_take_screenshot",
+]);
+
+// ── Helper: check if a tool name belongs to a browser MCP server ─────
+
+export function isBrowserTool(toolName: string): boolean {
+  return (
+    toolName.startsWith("mcp__chrome-devtools__") ||
+    toolName.startsWith("mcp__playwright__")
+  );
+}
+
+export function isBrowserReadOnly(toolName: string): boolean {
+  return BROWSER_READ_ONLY_TOOLS.has(toolName);
+}
+
+// ── Config builder ───────────────────────────────────────────────────
+
+function parseExtraArgs(config: string | null): string[] {
+  if (!config) return [];
+  const trimmed = config.trim();
+  if (!trimmed) return [];
+
+  // Try JSON array first (e.g. '["--browser", "firefox"]')
+  if (trimmed.startsWith("[")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (Array.isArray(parsed)) return parsed.filter((a): a is string => typeof a === "string");
+    } catch {
+      // Fall through to space-split
+    }
+  }
+
+  // Plain string: split on whitespace (e.g. "--headless --browser-url http://localhost:9222")
+  return trimmed.split(/\s+/).filter(Boolean);
+}
+
+/**
+ * Read browser MCP settings from DB and return MCP server configs
+ * for any enabled browser servers.
+ *
+ * Returns `{}` when neither server is enabled — zero overhead.
+ */
+export async function getBrowserMcpServers(): Promise<Record<string, McpServerConfig>> {
+  const [chromeEnabled, playwrightEnabled, chromeConfig, playwrightConfig] =
+    await Promise.all([
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_CHROME_DEVTOOLS_ENABLED),
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_PLAYWRIGHT_ENABLED),
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_CHROME_DEVTOOLS_CONFIG),
+      getSetting(SETTINGS_KEYS.BROWSER_MCP_PLAYWRIGHT_CONFIG),
+    ]);
+
+  const servers: Record<string, McpServerConfig> = {};
+
+  if (chromeEnabled === "true") {
+    const extraArgs = parseExtraArgs(chromeConfig);
+    servers["chrome-devtools"] = {
+      command: "npx",
+      args: ["-y", "chrome-devtools-mcp@latest", ...extraArgs],
+    };
+  }
+
+  if (playwrightEnabled === "true") {
+    const extraArgs = parseExtraArgs(playwrightConfig);
+    servers.playwright = {
+      command: "npx",
+      args: ["-y", "@playwright/mcp@latest", ...extraArgs],
+    };
+  }
+
+  return servers;
+}
+
+/**
+ * Build the allowedTools glob patterns for enabled browser MCP servers.
+ * Returns an empty array when no browser servers are enabled.
+ */
+export async function getBrowserAllowedToolPatterns(): Promise<string[]> {
+  const [chromeEnabled, playwrightEnabled] = await Promise.all([
+    getSetting(SETTINGS_KEYS.BROWSER_MCP_CHROME_DEVTOOLS_ENABLED),
+    getSetting(SETTINGS_KEYS.BROWSER_MCP_PLAYWRIGHT_ENABLED),
+  ]);
+
+  const patterns: string[] = [];
+  if (chromeEnabled === "true") patterns.push("mcp__chrome-devtools__*");
+  if (playwrightEnabled === "true") patterns.push("mcp__playwright__*");
+  return patterns;
+}

package/src/lib/agents/claude-agent.ts

@@ -17,9 +17,11 @@ import { resolveProfileRuntimePayload, type ResolvedProfileRuntimePayload } from
 import type { CanUseToolPolicy } from "./profiles/types";
 import { buildClaudeSdkEnv } from "./runtime/claude-sdk";
 import { getActiveLearnedContext } from "./learned-context";
-import { getLaunchCwd } from "@/lib/environment/workspace-context";
+import { getLaunchCwd, getWorkspaceContext } from "@/lib/environment/workspace-context";
 import { analyzeForLearnedPatterns } from "./pattern-extractor";
 import { processSweepResult } from "./sweep";
+import { getBrowserMcpServers } from "./browser-mcp";
+import { persistScreenshot, SCREENSHOT_TOOL_NAMES } from "@/lib/screenshots/persist";
 import {
   extractUsageSnapshot,
   mergeUsageSnapshot,
@@ -210,6 +212,9 @@ async function processAgentStream(
   let receivedResult = false;
   let turnCount = 0;
 
+  // Screenshot interception state
+  const pendingScreenshotTools = new Set<string>();
+
   for await (const raw of response) {
     const message = raw as AgentStreamMessage;
     applyUsageSnapshot(usageState, raw);
@@ -266,6 +271,10 @@ async function processAgentStream(
       turnCount++;
       for (const block of message.message.content) {
         if (block.type === "tool_use") {
+          // Track screenshot tool_use IDs for result interception
+          if (typeof block.name === "string" && SCREENSHOT_TOOL_NAMES.has(block.name) && typeof block.id === "string") {
+            pendingScreenshotTools.add(block.id);
+          }
           await db.insert(agentLogs).values({
             id: crypto.randomUUID(),
             taskId,
@@ -281,6 +290,47 @@ async function processAgentStream(
       }
     }
 
+    // Intercept tool results containing screenshot image data
+    if (message.type === "user" && pendingScreenshotTools.size > 0) {
+      const userMsg = (raw as Record<string, unknown>).message as Record<string, unknown> | undefined;
+      const userContent = userMsg?.content as Array<Record<string, unknown>> | undefined;
+      if (userContent) {
+        for (const block of userContent) {
+          if (block.type === "tool_result" && typeof block.tool_use_id === "string" && pendingScreenshotTools.has(block.tool_use_id)) {
+            pendingScreenshotTools.delete(block.tool_use_id);
+            const resultContent = block.content as Array<Record<string, unknown>> | undefined;
+            if (resultContent) {
+              for (const item of resultContent) {
+                if (item.type === "image" && typeof item.source === "object" && item.source !== null) {
+                  const source = item.source as Record<string, unknown>;
+                  if (source.type === "base64" && typeof source.data === "string") {
+                    const attachment = await persistScreenshot(source.data, {
+                      taskId,
+                      toolName: `screenshot_${block.tool_use_id}`,
+                    });
+                    if (attachment) {
+                      await db.insert(agentLogs).values({
+                        id: crypto.randomUUID(),
+                        taskId,
+                        agentType: agentProfileId,
+                        event: "screenshot",
+                        payload: JSON.stringify({
+                          documentId: attachment.documentId,
+                          thumbnailUrl: attachment.thumbnailUrl,
+                          toolName: `screenshot_${block.tool_use_id}`,
+                        }),
+                        timestamp: new Date(),
+                      });
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+
     // Handle result — skip if task was cancelled mid-stream
     if (message.type === "result" && "result" in raw) {
       if (abortController.signal.aborted) {
@@ -415,11 +465,6 @@ async function buildTaskQueryContext(
     ? `## Learned Context\nPatterns and insights learned from previous tasks:\n\n${learnedCtx}`
     : "";
 
-  // F1: Separate system instructions from user content
-  const systemInstructions = [profileInstructions, learnedCtxBlock, docContext, outputInstructions]
-    .filter(Boolean)
-    .join("\n\n");
-
   // Resolve working directory: project's workingDirectory > launch cwd
   let cwd = getLaunchCwd();
   if (task.projectId) {
@@ -432,6 +477,17 @@ async function buildTaskQueryContext(
     }
   }
 
+  // Add worktree guidance when running inside a git worktree
+  const ws = getWorkspaceContext();
+  const worktreeNote = ws.isWorktree
+    ? `## Workspace Note\nYou are operating inside a git worktree (branch: ${ws.gitBranch ?? "unknown"}). All file operations MUST use paths relative to the working directory: ${cwd}. Do NOT navigate to or create files in the main repository directory.`
+    : "";
+
+  // F1: Separate system instructions from user content
+  const systemInstructions = [worktreeNote, profileInstructions, learnedCtxBlock, docContext, outputInstructions]
+    .filter(Boolean)
+    .join("\n\n");
+
   // F9: Use profile maxTurns or fall back to default
   const maxTurns = profile?.maxTurns ?? DEFAULT_MAX_TURNS;
 
@@ -464,6 +520,11 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
     await prepareTaskOutputDirectory(taskId, { clearExisting: true });
     const ctx = await buildTaskQueryContext(task, agentProfileId);
 
+    // Merge browser MCP servers when enabled globally
+    const browserServers = await getBrowserMcpServers();
+    const profileMcpServers = ctx.payload?.mcpServers ?? {};
+    const mergedMcpServers = { ...profileMcpServers, ...browserServers };
+
     const authEnv = await getAuthEnv();
     const response = query({
       prompt: ctx.userPrompt,
@@ -481,10 +542,9 @@ export async function executeClaudeTask(taskId: string): Promise<void> {
         // F4: Per-execution budget cap
         maxBudgetUsd: DEFAULT_MAX_BUDGET_USD,
         ...(ctx.payload?.allowedTools && { allowedTools: ctx.payload.allowedTools }),
-        ...(ctx.payload?.mcpServers &&
-          Object.keys(ctx.payload.mcpServers).length > 0 && {
-            mcpServers: ctx.payload.mcpServers,
-          }),
+        ...(Object.keys(mergedMcpServers).length > 0 && {
+          mcpServers: mergedMcpServers,
+        }),
         // @ts-expect-error Agent SDK canUseTool types are incomplete — our async handler is compatible at runtime
         canUseTool: async (
           toolName: string,
@@ -570,6 +630,11 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
     await prepareTaskOutputDirectory(taskId);
     const ctx = await buildTaskQueryContext(task, profileId);
 
+    // Merge browser MCP servers when enabled globally
+    const browserServers = await getBrowserMcpServers();
+    const profileMcpServers = ctx.payload?.mcpServers ?? {};
+    const mergedMcpServers = { ...profileMcpServers, ...browserServers };
+
     const authEnv = await getAuthEnv();
     const response = query({
       prompt: ctx.userPrompt,
@@ -588,10 +653,9 @@ export async function resumeClaudeTask(taskId: string): Promise<void> {
         // F4: Per-execution budget cap
         maxBudgetUsd: DEFAULT_MAX_BUDGET_USD,
         ...(ctx.payload?.allowedTools && { allowedTools: ctx.payload.allowedTools }),
-        ...(ctx.payload?.mcpServers &&
-          Object.keys(ctx.payload.mcpServers).length > 0 && {
-            mcpServers: ctx.payload.mcpServers,
-          }),
+        ...(Object.keys(mergedMcpServers).length > 0 && {
+          mcpServers: mergedMcpServers,
+        }),
         // @ts-expect-error Agent SDK canUseTool types are incomplete — our async handler is compatible at runtime
         canUseTool: async (
           toolName: string,

package/src/lib/book/chapter-generator.ts

@@ -0,0 +1,193 @@
+import { readFileSync, existsSync } from "fs";
+import { join } from "path";
+import { CHAPTER_MAPPING } from "./chapter-mapping";
+import { getChapter } from "./content";
+
+/** Shared context gathered from disk for prompt assembly */
+interface ChapterContext {
+  chapterId: string;
+  chapterNumber: number;
+  title: string;
+  subtitle: string;
+  partNumber: number;
+  partTitle: string;
+  readingTime: number;
+  slug: string;
+  relatedDocs: string[];
+  relatedJourney: string | undefined;
+  currentMarkdown: string | null;
+  sourceContents: string[];
+  strategy: string | null;
+}
+
+/** Gather all context needed for chapter generation from disk */
+export function gatherChapterContext(chapterId: string): ChapterContext {
+  const chapter = getChapter(chapterId);
+  if (!chapter) {
+    throw new Error(`Chapter not found: ${chapterId}`);
+  }
+
+  const mapping = CHAPTER_MAPPING[chapterId];
+  const sourceDocSlugs = mapping?.docs ?? [];
+  const slug = chapterIdToSlug(chapterId);
+
+  // Read the current chapter markdown (if it exists)
+  const chapterMdPath = join(process.cwd(), "book", "chapters", `${slug}.md`);
+  const currentMarkdown = existsSync(chapterMdPath)
+    ? readFileSync(chapterMdPath, "utf-8")
+    : null;
+
+  // Read related playbook docs for content
+  const sourceContents: string[] = [];
+  for (const docSlug of sourceDocSlugs) {
+    const docPath = join(process.cwd(), "docs", "features", `${docSlug}.md`);
+    if (existsSync(docPath)) {
+      const content = readFileSync(docPath, "utf-8");
+      sourceContents.push(`### Feature: ${docSlug}\n${content}`);
+    }
+  }
+
+  // Read the book strategy document
+  const strategyPath = join(process.cwd(), "ai-native-notes", "ai-native-book-strategy.md");
+  const strategy = existsSync(strategyPath)
+    ? readFileSync(strategyPath, "utf-8")
+    : null;
+
+  return {
+    chapterId,
+    chapterNumber: chapter.number,
+    title: chapter.title,
+    subtitle: chapter.subtitle,
+    partNumber: chapter.part.number,
+    partTitle: chapter.part.title,
+    readingTime: chapter.readingTime,
+    slug,
+    relatedDocs: chapter.relatedDocs ?? [],
+    relatedJourney: chapter.relatedJourney,
+    currentMarkdown,
+    sourceContents,
+    strategy,
+  };
+}
+
+/**
+ * Build an agent prompt for generating or regenerating a book chapter.
+ * Assembles context from the current chapter, source files,
+ * and the book strategy document.
+ */
+export function buildChapterRegenerationPrompt(chapterId: string): string {
+  const ctx = gatherChapterContext(chapterId);
+  const isNew = ctx.currentMarkdown === null;
+  const verb = isNew ? "generating" : "regenerating";
+  const outputPath = `book/chapters/${ctx.slug}.md`;
+
+  // Assemble the prompt
+  const sections: string[] = [
+    `# Chapter ${isNew ? "Generation" : "Regeneration"}: ${ctx.title}`,
+    "",
+    `You are ${verb} Chapter ${ctx.chapterNumber}: "${ctx.title}" — ${ctx.subtitle}`,
+    `This chapter belongs to Part ${ctx.partNumber}: ${ctx.partTitle}.`,
+    "",
+    "## Instructions",
+    "",
+    `${isNew ? "Write" : "Regenerate"} this book chapter following these rules:`,
+    "1. **Narrative voice**: Write in first-person plural ('we') with a technical-but-approachable tone",
+    "2. **Structure**: Follow the Problem → Solution → Implementation → Lessons pattern",
+    "3. **Code examples**: Include real code snippets from the Stagent codebase with filename comments",
+    "4. **Markdown format**: Use the conventions below for content blocks",
+    "5. **Reading time**: Target approximately " + ctx.readingTime + " minutes",
+    ...(isNew ? [] : ["6. **Preserve Author's Notes**: Keep any existing `> [!authors-note]` blocks unchanged"]),
+    "",
+    "## Tools Available",
+    "",
+    "You have access to **Read**, **Write**, and **Edit** tools.",
+    "- Use **Read** to examine Stagent source code files for real code examples",
+    "- Use **Write** to create the final chapter file",
+    "",
+    "## Markdown Conventions",
+    "",
+    "- Sections: `## Section Title`",
+    "- Code blocks: ` ```language ` with `<!-- filename: path -->` before the block",
+    "- Callouts: `> [!tip]`, `> [!warning]`, `> [!info]`, `> [!lesson]`, `> [!authors-note]`",
+    "- Interactive links: `[Try: label](href)`",
+    "- Images: `![alt](src \"caption\")`",
+    "",
+  ];
+
+  if (ctx.currentMarkdown) {
+    sections.push(
+      "## Current Chapter Content",
+      "",
+      "Update this content to reflect any changes in the source material:",
+      "",
+      "```markdown",
+      ctx.currentMarkdown,
+      "```",
+      ""
+    );
+  }
+
+  if (ctx.sourceContents.length > 0) {
+    sections.push(
+      "## Source Material (Playbook Feature Docs)",
+      "",
+      "Use these feature docs as the primary source of technical details:",
+      "",
+      ...ctx.sourceContents,
+      ""
+    );
+  }
+
+  if (ctx.strategy) {
+    sections.push(
+      "## Book Strategy Reference",
+      "",
+      "Follow the themes and narrative arc described here:",
+      "",
+      ctx.strategy.slice(0, 4000), // Truncate to avoid excessive context
+      ""
+    );
+  }
+
+  const now = new Date().toISOString();
+  sections.push(
+    "## Output",
+    "",
+    `Write the chapter to the file: \`${outputPath}\``,
+    "",
+    "The file must include this frontmatter at the top:",
+    "",
+    "```yaml",
+    "---",
+    `title: "${ctx.title}"`,
+    `subtitle: "${ctx.subtitle}"`,
+    `chapter: ${ctx.chapterNumber}`,
+    `part: ${ctx.partNumber}`,
+    `readingTime: ${ctx.readingTime}`,
+    `lastGeneratedBy: "${now}"`,
+    ...(ctx.relatedDocs.length > 0 ? [`relatedDocs: ${JSON.stringify(ctx.relatedDocs)}`] : []),
+    ...(ctx.relatedJourney ? [`relatedJourney: "${ctx.relatedJourney}"`] : []),
+    "---",
+    "```",
+    "",
+    "After the frontmatter, write the chapter body starting with the first `## Section Title` heading.",
+  );
+
+  return sections.join("\n");
+}
+
+/** Map chapter ID to markdown filename slug */
+function chapterIdToSlug(chapterId: string): string {
+  const slugMap: Record<string, string> = {
+    "ch-1": "ch-1-project-management",
+    "ch-2": "ch-2-task-execution",
+    "ch-3": "ch-3-document-processing",
+    "ch-4": "ch-4-workflow-orchestration",
+    "ch-5": "ch-5-scheduled-intelligence",
+    "ch-6": "ch-6-agent-self-improvement",
+    "ch-7": "ch-7-multi-agent-swarms",
+    "ch-8": "ch-8-human-in-the-loop",
+    "ch-9": "ch-9-autonomous-organization",
+  };
+  return slugMap[chapterId] ?? chapterId;
+}