@design-ai/cli 4.55.0 → 4.56.0

package/cli/lib/site-bundle-handoff-summary.mjs

@@ -0,0 +1,183 @@
+import {
+  buildBundleCheckCommand,
+  buildBundleCheckCommandArgs,
+  buildBundleHandoffCommand,
+  buildBundleHandoffCommandArgs,
+  buildBundleSourceCommandSafety,
+  buildBundleTaskHandoffCommand,
+  buildBundleTaskHandoffCommandArgs,
+  buildBundleTaskHandoffCommandSafety,
+  taskHandoffOutFile,
+} from "./site-bundle-commands.mjs";
+import { orderedRefactorTasks } from "./site-prompts.mjs";
+import { normalizeStringArray } from "./site-strings.mjs";
+
+export const SITE_TARGET_REPO_EXECUTION_CHECKLIST = [
+  {
+    id: "confirm-target-repo",
+    label: "Confirm target repo working directory",
+    required: true,
+    evidence: "State the target repo path and confirm it is not the design-ai repo before editing.",
+  },
+  {
+    id: "inspect-architecture",
+    label: "Inspect existing architecture and design system",
+    required: true,
+    evidence: "Name the routing, component, styling, token, and test/build surfaces inspected before implementation.",
+  },
+  {
+    id: "apply-focused-task",
+    label: "Apply one focused Website Improvement task",
+    required: true,
+    evidence: "Identify the completed task id/title, changed files, and why the scope stayed limited.",
+  },
+  {
+    id: "verify-quality-gates",
+    label: "Run target repo quality gates",
+    required: true,
+    evidence: "Record lint/typecheck/build/test results plus browser, viewport, accessibility, and deployment checks that were available.",
+  },
+  {
+    id: "record-handoff-evidence",
+    label: "Record implementation evidence and remaining risks",
+    required: true,
+    evidence: "Return executed work, verification results, remaining risks, next actions, and the bundle digest used.",
+  },
+];
+
+function summarizeBundleTaskItem(task, index, directory) {
+  return {
+    number: index + 1,
+    id: task.id,
+    title: task.title,
+    category: task.category,
+    priority: task.priority,
+    impact: task.impact,
+    effort: task.effort,
+    pages: normalizeStringArray(task.pages),
+    recommendedMcp: normalizeStringArray(task.recommendedMcp),
+    handoffTaskArg: task.id,
+    handoffOutFile: taskHandoffOutFile(task),
+    handoffCommand: buildBundleTaskHandoffCommand(directory, task),
+    handoffCommandArgs: buildBundleTaskHandoffCommandArgs(directory, task),
+    handoffCommandRunPolicy: "writes-local-file",
+    handoffCommandSafety: buildBundleTaskHandoffCommandSafety(task),
+    strictHandoffCommand: buildBundleTaskHandoffCommand(directory, task, { strict: true }),
+    strictHandoffCommandArgs: buildBundleTaskHandoffCommandArgs(directory, task, { strict: true }),
+    strictHandoffCommandRunPolicy: "writes-local-file",
+    strictHandoffCommandSafety: buildBundleTaskHandoffCommandSafety(task, { strict: true }),
+  };
+}
+
+export function summarizeBundleTaskCatalog(workspace, directory, selectedTask = null) {
+  const items = orderedRefactorTasks(workspace).map((task, index) => summarizeBundleTaskItem(task, index, directory));
+  const selectedTaskId = selectedTask?.id || "";
+  return {
+    source: "website-workspace.tasks.json",
+    count: items.length,
+    defaultTaskId: items[0]?.id || "",
+    selectedTaskId,
+    selectionMode: selectedTaskId ? "explicit" : "bundled-default",
+    items,
+  };
+}
+
+export function emptyBundleTaskCatalog(error = "") {
+  return {
+    source: "website-workspace.tasks.json",
+    count: 0,
+    defaultTaskId: "",
+    selectedTaskId: "",
+    selectionMode: "unavailable",
+    items: [],
+    error,
+  };
+}
+
+export function summarizeSelectedTask(task, taskSelector, source, directory = "") {
+  if (!task) return null;
+  return {
+    id: task.id,
+    title: task.title,
+    category: task.category,
+    priority: task.priority,
+    impact: task.impact,
+    effort: task.effort,
+    selector: String(taskSelector || "").trim(),
+    source,
+    handoffTaskArg: task.id,
+    handoffOutFile: taskHandoffOutFile(task),
+    handoffCommand: directory ? buildBundleTaskHandoffCommand(directory, task) : "",
+    handoffCommandArgs: directory ? buildBundleTaskHandoffCommandArgs(directory, task) : [],
+    handoffCommandRunPolicy: directory ? "writes-local-file" : "",
+    handoffCommandSafety: directory ? buildBundleTaskHandoffCommandSafety(task) : null,
+    strictHandoffCommand: directory ? buildBundleTaskHandoffCommand(directory, task, { strict: true }) : "",
+    strictHandoffCommandArgs: directory ? buildBundleTaskHandoffCommandArgs(directory, task, { strict: true }) : [],
+    strictHandoffCommandRunPolicy: directory ? "writes-local-file" : "",
+    strictHandoffCommandSafety: directory ? buildBundleTaskHandoffCommandSafety(task, { strict: true }) : null,
+  };
+}
+
+export function formatBundleHandoffTaskCatalogLines(taskCatalog) {
+  if (!taskCatalog || !Array.isArray(taskCatalog.items) || taskCatalog.items.length === 0) {
+    const reason = taskCatalog?.error ? ` ${taskCatalog.error}` : "";
+    return [`- No bundle task catalog is available.${reason}`];
+  }
+  return taskCatalog.items.map((task) => {
+    const pages = task.pages.length ? task.pages.join(", ") : "all pages";
+    const mcps = task.recommendedMcp.length ? task.recommendedMcp.join(", ") : "none";
+    const command = task.strictHandoffCommand || task.handoffCommand || `design-ai site <bundle-dir> --bundle-handoff --task ${task.handoffTaskArg}`;
+    return `- ${task.number}. [${task.priority}/${task.impact}/${task.effort}] ${task.id}: ${task.title} (pages: ${pages}; MCP: ${mcps}; command: \`${command}\`)`;
+  });
+}
+
+export function formatBundleHandoffIssueLines(issues) {
+  const actionable = issues.filter((issue) => issue.level !== "pass");
+  if (actionable.length === 0) return "- No blocking bundle-check issues were found.";
+  return actionable.map((issue) => `- [${issue.level}] ${issue.id}: ${issue.message}`).join("\n");
+}
+
+export function buildSiteBundleHandoffBoundaries(checkReport) {
+  return Array.from(new Set([
+    ...normalizeStringArray(checkReport?.boundaries),
+    "target-repo-work-after-handoff",
+  ]));
+}
+
+export function summarizeSiteBundleHandoffSource(checkReport) {
+  return {
+    directory: checkReport.directory,
+    sourceWorkspace: checkReport.summary.source || "",
+    siteName: checkReport.summary.siteName || "",
+    status: checkReport.status,
+    valid: checkReport.valid,
+    workspaceStatus: checkReport.workspaceStatus || "unknown",
+    mcpStatus: checkReport.mcpStatus || "unknown",
+    mcpProbeStatus: checkReport.mcpProbeStatus || "unknown",
+    checksumAlgorithm: checkReport.summary.checksumAlgorithm || "",
+    checksumBundleDigest: checkReport.summary.checksumBundleDigest || "",
+    verifiedChecksumFiles: checkReport.counts.verifiedChecksumFiles,
+    expectedChecksumFiles: checkReport.counts.expectedChecksumFiles,
+    verifiedGeneratedFiles: checkReport.counts.verifiedGeneratedFiles,
+    expectedGeneratedFiles: checkReport.counts.expectedGeneratedFiles,
+    issueCount: checkReport.issues.length,
+    warningCount: checkReport.counts.warnings,
+    failureCount: checkReport.counts.failures,
+    checkCommand: buildBundleCheckCommand(checkReport.directory),
+    checkCommandArgs: buildBundleCheckCommandArgs(checkReport.directory),
+    checkCommandRunPolicy: "read-only",
+    checkCommandSafety: buildBundleSourceCommandSafety(),
+    strictCheckCommand: buildBundleCheckCommand(checkReport.directory, { strict: true }),
+    strictCheckCommandArgs: buildBundleCheckCommandArgs(checkReport.directory, { strict: true }),
+    strictCheckCommandRunPolicy: "read-only",
+    strictCheckCommandSafety: buildBundleSourceCommandSafety({ strict: true }),
+    handoffCommand: buildBundleHandoffCommand(checkReport.directory),
+    handoffCommandArgs: buildBundleHandoffCommandArgs(checkReport.directory),
+    handoffCommandRunPolicy: "read-only",
+    handoffCommandSafety: buildBundleSourceCommandSafety(),
+    strictHandoffCommand: buildBundleHandoffCommand(checkReport.directory, { strict: true }),
+    strictHandoffCommandArgs: buildBundleHandoffCommandArgs(checkReport.directory, { strict: true }),
+    strictHandoffCommandRunPolicy: "read-only",
+    strictHandoffCommandSafety: buildBundleSourceCommandSafety({ strict: true }),
+  };
+}

package/cli/lib/site-bundle-handoff.mjs

@@ -0,0 +1,271 @@
+// Target-repo handoff reports for Website Improvement bundles.
+
+import {
+  existsSync,
+  readFileSync,
+  statSync,
+} from "node:fs";
+import path from "node:path";
+
+import {
+  buildSitePrompt,
+  resolveSitePromptTask,
+} from "./site-prompts.mjs";
+import { analyzeSiteWorkspace } from "./site-analysis.mjs";
+import { buildBundleCheckCommand } from "./site-bundle-commands.mjs";
+import { formatBundleRepairGuidanceLines } from "./site-bundle-repair.mjs";
+import { buildSiteBundleCheckReport } from "./site-bundle-check.mjs";
+import {
+  buildBundleHandoffCommandManifest,
+  buildBundleHandoffOperatorRunbook,
+  formatBundleHandoffOperatorRunbookLines,
+} from "./site-bundle-handoff-runbook.mjs";
+import {
+  SITE_TARGET_REPO_EXECUTION_CHECKLIST,
+  buildSiteBundleHandoffBoundaries,
+  emptyBundleTaskCatalog,
+  formatBundleHandoffIssueLines,
+  formatBundleHandoffTaskCatalogLines,
+  summarizeBundleTaskCatalog,
+  summarizeSelectedTask,
+  summarizeSiteBundleHandoffSource,
+} from "./site-bundle-handoff-summary.mjs";
+import { readBundleTextIfPresent } from "./site-bundle-files.mjs";
+import { formatGeneratedContractDriftSummary } from "./site-bundle-contract.mjs";
+
+function loadSiteBundleWorkspace(directory) {
+  const relativePath = "website-workspace.tasks.json";
+  const targetPath = path.join(directory, relativePath);
+  if (!existsSync(targetPath) || !statSync(targetPath).isFile()) {
+    throw new Error(`Cannot select a handoff task because ${relativePath} is missing from the bundle`);
+  }
+
+  let raw;
+  try {
+    raw = JSON.parse(readFileSync(targetPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Cannot select a handoff task because ${relativePath} is invalid JSON: ${error.message}`);
+  }
+
+  return analyzeSiteWorkspace(raw, { filePath: targetPath }).workspace;
+}
+
+function buildSiteBundleHandoffPrompt(checkReport, bundleTexts) {
+  const bundleDigest = checkReport.summary.checksumBundleDigest || "not recorded";
+  const checksumStatus = `${checkReport.counts.verifiedChecksumFiles}/${checkReport.counts.expectedChecksumFiles} verified`;
+  const handoffBoundaries = buildSiteBundleHandoffBoundaries(checkReport);
+  const taskSelectionLine = bundleTexts.selectedTask
+    ? `${bundleTexts.selectedTask.id} (${bundleTexts.selectedTask.title}; ${bundleTexts.selectedTask.source})`
+    : "bundled codex-implementation.md default";
+  const bundleReadinessLine = checkReport.status === "pass"
+    ? "The bundle passed local bundle-check validation. Proceed in the target website repo after confirming the repo path."
+    : "The bundle did not fully pass local bundle-check validation. Resolve the listed bundle issues before treating this as implementation authority.";
+  return [
+    "# Website improvement target-repo handoff prompt",
+    "",
+    "You are Codex working in the target website repository, not in the design-ai repository.",
+    "Use this verified Website Improvement handoff bundle as read-only planning evidence. Do not modify the design-ai repo while executing this prompt.",
+    "",
+    "## Verified Bundle",
+    `- Bundle directory: ${checkReport.directory}`,
+    `- Source bundle provenance: ${checkReport.status}/${checkReport.valid ? "valid" : "invalid"} from ${checkReport.directory}`,
+    `- Source bundle strict check command: \`${buildBundleCheckCommand(checkReport.directory, { strict: true })}\``,
+    `- Site: ${checkReport.summary.siteName || "unknown"}`,
+    `- Source workspace: ${checkReport.summary.source || "unknown"}`,
+    `- Bundle status: ${checkReport.status}`,
+    `- Workspace status: ${checkReport.workspaceStatus}`,
+    `- MCP status: ${checkReport.mcpStatus}`,
+    `- MCP probe status: ${checkReport.mcpProbeStatus}`,
+    `- MCP probes: ${checkReport.mcpProbeCounts.pass}/${checkReport.mcpProbeCounts.count} passing, ${checkReport.mcpProbeCounts.warn} warning, ${checkReport.mcpProbeCounts.fail} failing`,
+    `- Tasks: ${checkReport.summary.totalTasks}`,
+    `- Primary task selection: ${taskSelectionLine}`,
+    `- Evidence counts: executed work ${checkReport.summary.implementationEvidence.executedWork}, verification ${checkReport.summary.implementationEvidence.verificationResults}, risks ${checkReport.summary.implementationEvidence.remainingRisks}, next actions ${checkReport.summary.implementationEvidence.nextActions}`,
+    `- Generated files: ${checkReport.counts.verifiedGeneratedFiles}/${checkReport.counts.expectedGeneratedFiles} match the current CLI bundle contract`,
+    `- Generated drift files: ${formatGeneratedContractDriftSummary(checkReport.generatedContract)}`,
+    `- SHA-256 bundle digest: ${bundleDigest}`,
+    `- Checksums: ${checksumStatus}`,
+    `- Handoff generation boundary flags: external calls no; target repo mutation no`,
+    `- Handoff boundaries: ${handoffBoundaries.join(", ")}`,
+    "",
+    "## Available Bundle Tasks",
+    `Task catalog source: ${bundleTexts.taskCatalog?.source || "unknown"}`,
+    `Default task: ${bundleTexts.taskCatalog?.defaultTaskId || "none"}`,
+    ...(bundleTexts.defaultTask?.strictHandoffCommand
+      ? [`Default task strict command: \`${bundleTexts.defaultTask.strictHandoffCommand}\``]
+      : []),
+    `Selected task: ${bundleTexts.taskCatalog?.selectedTaskId || "none"}`,
+    ...(bundleTexts.selectedTask?.strictHandoffCommand
+      ? [`Selected task strict command: \`${bundleTexts.selectedTask.strictHandoffCommand}\``]
+      : []),
+    `Effective task: ${bundleTexts.effectiveTask?.id || "none"}`,
+    ...(bundleTexts.effectiveTask?.strictHandoffCommand
+      ? [`Effective task strict command: \`${bundleTexts.effectiveTask.strictHandoffCommand}\``]
+      : []),
+    "To choose a specific task, re-run this handoff with `--task <number-or-id>`.",
+    ...formatBundleHandoffTaskCatalogLines(bundleTexts.taskCatalog),
+    "",
+    "## Operator Runbook",
+    `Runbook stages: ${bundleTexts.operatorRunbook?.stageCount || 0} (${bundleTexts.operatorRunbook?.requiredStageCount || 0} required, ${bundleTexts.operatorRunbook?.optionalStageCount || 0} optional)`,
+    `Next command key: ${bundleTexts.operatorRunbook?.nextCommandKey || "none"}`,
+    ...formatBundleHandoffOperatorRunbookLines(bundleTexts.operatorRunbook),
+    "",
+    "## Bundle Gate",
+    bundleReadinessLine,
+    formatBundleHandoffIssueLines(checkReport.issues),
+    "",
+    "Repair guidance:",
+    ...formatBundleRepairGuidanceLines(checkReport.repairGuidance),
+    "",
+    "## Operating Rules",
+    "1. Confirm the current working directory is the target website repo before editing files.",
+    "2. Inspect the target repo architecture, existing components, design tokens, routing, styling, and test scripts before implementation.",
+    "3. Reuse existing UI/system patterns and keep the change scoped to the selected improvement task.",
+    "4. Do not add production dependencies unless the target repo clearly requires them and the tradeoff is documented.",
+    "5. Preserve WCAG 2.1 AA expectations: visible focus, keyboard reachability, semantic structure, and text contrast.",
+    "6. Verify desktop, tablet, and mobile behavior plus target repo lint/typecheck/build commands when available.",
+    "7. Keep the handoff bundle files read-only; record implementation evidence in the target repo final response or report.",
+    "",
+    "## Target Repo Execution Checklist",
+    ...SITE_TARGET_REPO_EXECUTION_CHECKLIST.map((item) => `- [ ] ${item.label}: ${item.evidence}`),
+    "",
+    "## Primary Codex Implementation Prompt",
+    bundleTexts.codexImplementation || "_codex-implementation.md was not readable from the bundle._",
+    "",
+    "## Additional Bundle Context",
+    "Use these files only as supporting evidence:",
+    "- `website-handoff.md`: audit summary, priority recommendations, and remaining risk context.",
+    "- `mcp-probes.json`: read-only MCP probe evidence for repo, Figma, Browser, and deployment references.",
+    "- `mcp-action-plan.md`: MCP readiness gaps and operator sequence.",
+    "- `website-prompts.md`: alternate Codex/Claude review, QA, deployment, research, and copy prompts.",
+    "- `summary.json`: bundle manifest, source workspace, task count, and checksum digest.",
+    "",
+    "### Handoff Report Snapshot",
+    bundleTexts.websiteHandoff || "_website-handoff.md was not readable from the bundle._",
+    "",
+    "## Required Final Response",
+    "Return a concise implementation report with:",
+    "- Files changed in the target repo",
+    "- The specific website improvement task completed",
+    "- Verification commands and browser/viewport checks performed",
+    "- Remaining risks or follow-up work",
+    `- Bundle digest used for handoff: ${bundleDigest}`,
+  ].join("\n");
+}
+
+export function buildSiteBundleHandoffReport({
+  target,
+  cwd = process.cwd(),
+  taskSelector = "",
+} = {}) {
+  const checkReport = buildSiteBundleCheckReport({ target, cwd });
+  const includedFilePaths = [
+    "summary.json",
+    "mcp-probes.json",
+    "mcp-action-plan.md",
+    "website-handoff.md",
+    "website-prompts.md",
+    "codex-implementation.md",
+  ];
+  let bundleWorkspace = null;
+  let taskCatalogError = "";
+  let selectedTask = null;
+  let codexImplementation = readBundleTextIfPresent(checkReport.directory, "codex-implementation.md");
+  try {
+    bundleWorkspace = loadSiteBundleWorkspace(checkReport.directory);
+  } catch (error) {
+    taskCatalogError = error.message;
+  }
+  if (String(taskSelector || "").trim()) {
+    if (!bundleWorkspace) {
+      throw new Error(taskCatalogError || "Cannot select a handoff task because the bundle workspace is unavailable");
+    }
+    const task = resolveSitePromptTask(bundleWorkspace, taskSelector);
+    selectedTask = summarizeSelectedTask(task, taskSelector, "bundle-workspace", checkReport.directory);
+    codexImplementation = buildSitePrompt(bundleWorkspace, "codex-implementation", { taskSelector });
+  }
+  const taskCatalog = bundleWorkspace
+    ? summarizeBundleTaskCatalog(bundleWorkspace, checkReport.directory, selectedTask)
+    : emptyBundleTaskCatalog(taskCatalogError);
+  const defaultTask = taskCatalog.items[0] || null;
+  const effectiveTask = selectedTask || defaultTask;
+
+  const bundleTexts = {
+    taskCatalog,
+    defaultTask,
+    effectiveTask,
+    selectedTask,
+    codexImplementation,
+    websiteHandoff: readBundleTextIfPresent(checkReport.directory, "website-handoff.md"),
+  };
+  const boundaries = buildSiteBundleHandoffBoundaries(checkReport);
+  const sourceBundle = summarizeSiteBundleHandoffSource(checkReport);
+  const commandManifest = buildBundleHandoffCommandManifest({
+    sourceBundle,
+    taskCatalog,
+    defaultTask,
+    selectedTask,
+    effectiveTask,
+  });
+  const operatorRunbook = buildBundleHandoffOperatorRunbook(commandManifest);
+  const runbookPrompt = buildSiteBundleHandoffPrompt(checkReport, {
+    ...bundleTexts,
+    operatorRunbook,
+  });
+  return {
+    status: checkReport.status,
+    valid: checkReport.valid,
+    directory: checkReport.directory,
+    sourceBundle,
+    commandManifest,
+    operatorRunbook,
+    boundaries,
+    externalCalls: false,
+    targetRepoMutation: false,
+    bundle: {
+      directory: checkReport.directory,
+      siteName: checkReport.summary.siteName || "",
+      source: checkReport.summary.source || "",
+      sourceBundle,
+      workspaceStatus: checkReport.workspaceStatus || "unknown",
+      mcpStatus: checkReport.mcpStatus || "unknown",
+      mcpProbeStatus: checkReport.mcpProbeStatus || "unknown",
+      mcpProbeCounts: { ...checkReport.mcpProbeCounts },
+      totalTasks: checkReport.summary.totalTasks || 0,
+      implementationEvidence: { ...checkReport.summary.implementationEvidence },
+      checksumAlgorithm: checkReport.summary.checksumAlgorithm || "",
+      checksumBundleDigest: checkReport.summary.checksumBundleDigest || "",
+      expectedChecksumFiles: checkReport.counts.expectedChecksumFiles,
+      verifiedChecksumFiles: checkReport.counts.verifiedChecksumFiles,
+      checksumFailures: checkReport.counts.checksumFailures,
+      expectedGeneratedFiles: checkReport.counts.expectedGeneratedFiles,
+      verifiedGeneratedFiles: checkReport.counts.verifiedGeneratedFiles,
+      generatedFailures: checkReport.counts.generatedFailures,
+      generatedDriftFiles: [...checkReport.generatedContract.driftFiles],
+      taskCatalog,
+      defaultTask,
+      effectiveTask,
+      selectedTask,
+      commandManifest,
+      operatorRunbook,
+      boundaries,
+      externalCalls: false,
+      targetRepoMutation: false,
+      repairGuidance: { ...checkReport.repairGuidance },
+      executionChecklist: SITE_TARGET_REPO_EXECUTION_CHECKLIST,
+    },
+    prompt: runbookPrompt,
+    files: checkReport.files.map((file) => ({
+      ...file,
+      included: includedFilePaths.includes(file.path),
+    })),
+    issues: checkReport.issues,
+  };
+}
+
+export function formatSiteBundleHandoffJson(report) {
+  return JSON.stringify(report, null, 2);
+}
+
+export function formatSiteBundleHandoffHuman(report) {
+  return report.prompt;
+}

package/cli/lib/site-bundle-readme.mjs

@@ -0,0 +1,98 @@
+// README and handoff guidance builders for Website Improvement bundles.
+
+import { markdownTable } from "./site-strings.mjs";
+import { SITE_TARGET_REPO_EXECUTION_CHECKLIST } from "./site-bundle-handoff-summary.mjs";
+
+export function buildSiteBundleHandoffGuidance(bundleStatus) {
+  const strictCommand = "design-ai site <bundle-dir> --bundle-handoff --strict --out target-repo-handoff.md";
+  const draftCommand = "design-ai site <bundle-dir> --bundle-handoff --out target-repo-handoff.md";
+  const verifyCommand = "design-ai site <bundle-dir> --bundle-check --strict --json";
+  const strictReady = bundleStatus === "pass";
+  return {
+    strictReady,
+    readiness: strictReady ? "ready-for-strict-handoff" : "review-warnings-before-strict-handoff",
+    recommendedCommand: strictReady ? strictCommand : draftCommand,
+    strictCommand,
+    draftCommand,
+    verifyCommand,
+    note: strictReady
+      ? "Use the strict handoff command before target-repo implementation."
+      : "Use the draft handoff command only for planning while readiness warnings remain; use the strict handoff command before treating the bundle as implementation authority.",
+    executionChecklist: SITE_TARGET_REPO_EXECUTION_CHECKLIST,
+  };
+}
+
+export function buildSiteBundleReadme(workspace, bundleSummary, mcpReport, mcpProbeReport, filePaths) {
+  const commandTarget = bundleSummary.source === "stdin" ? "<workspace.json>" : bundleSummary.source;
+  const handoff = bundleSummary.handoff;
+  return [
+    `# Website improvement handoff bundle: ${workspace.siteProfile.name}`,
+    "",
+    "> Generated by `design-ai site --bundle` from a Website Improvement Console workspace export.",
+    "",
+    "## Contents",
+    markdownTable(
+      ["File", "Purpose"],
+      filePaths.map((filePath) => {
+        const purpose = {
+          "summary.json": "Machine-readable bundle manifest and readiness summary",
+          "website-workspace.tasks.json": "Workspace JSON with deterministic starter refactor tasks added",
+          "mcp-check.json": "Machine-readable MCP readiness gate output",
+          "mcp-probes.json": "Machine-readable read-only MCP probe readiness output",
+          "mcp-action-plan.md": "Operator-facing MCP readiness action plan",
+          "website-handoff.md": "Markdown handoff report for implementation planning",
+          "website-prompts.md": "Full Codex and Claude prompt bundle",
+          "codex-implementation.md": "Top-priority Codex implementation prompt",
+        }[filePath] || "Bundle artifact";
+        return [filePath, purpose];
+      }),
+    ),
+    "",
+    "## Status",
+    `- Bundle status: ${mcpReport.status}`,
+    `- Workspace status: ${bundleSummary.workspaceStatus}`,
+    `- Source: ${bundleSummary.source}`,
+    `- Site: ${workspace.siteProfile.name}`,
+    `- Live URL: ${workspace.siteProfile.liveUrl || "not provided"}`,
+    `- Repo: ${workspace.siteProfile.repoUrl || workspace.siteProfile.localPath || "not provided"}`,
+    `- Tasks: ${bundleSummary.taskGeneration.totalTasks}`,
+    `- Evidence entries: ${bundleSummary.implementationEvidence.executedWork + bundleSummary.implementationEvidence.verificationResults}`,
+    `- MCP ready: ${mcpReport.counts.ready}/${mcpReport.counts.total}`,
+    `- MCP probes: ${mcpProbeReport.pass}/${mcpProbeReport.count} passing`,
+    "",
+    "## Handoff Readiness",
+    `- Strict-ready: ${handoff.strictReady ? "yes" : "no"}`,
+    `- Readiness: ${handoff.readiness}`,
+    `- Recommended command: \`${handoff.recommendedCommand}\``,
+    `- Strict command: \`${handoff.strictCommand}\``,
+    `- Draft command: \`${handoff.draftCommand}\``,
+    `- Verify command: \`${handoff.verifyCommand}\``,
+    `- Note: ${handoff.note}`,
+    "",
+    "## Target Repo Execution Checklist",
+    ...handoff.executionChecklist.map((item) => `- [ ] ${item.label}: ${item.evidence}`),
+    "",
+    "## Suggested Sequence",
+    "1. Read `summary.json`, `mcp-check.json`, `mcp-probes.json`, and `mcp-action-plan.md` first.",
+    "2. Run `design-ai site <bundle-dir> --bundle-check --strict --json`; if it exits non-zero, review the warnings or failures before implementation.",
+    "3. Run the recommended handoff command above. Use the draft command only for planning while readiness warnings remain.",
+    "4. Use `codex-implementation.md` in the target website repo for the top-priority task when you need the raw task prompt.",
+    "5. Use `website-prompts.md` for deeper Codex/Claude review, visual QA, deployment verification, competitor research, and final handoff.",
+    "6. Record target-repo executed work, verification results, remaining risks, and next actions in `website-handoff.md` after implementation.",
+    "",
+    "## Regenerate",
+    `- \`design-ai site ${commandTarget} --bundle --out website-handoff-bundle --force\``,
+    `- \`design-ai site ${commandTarget} --mcp-check --strict --json\``,
+    `- \`design-ai site website-handoff-bundle --bundle-check --strict --json\``,
+    `- \`design-ai site website-handoff-bundle --bundle-handoff --strict --out target-repo-handoff.md\``,
+    "",
+    "## Checksum Verification",
+    "- `summary.json` records SHA-256 checksums for every generated bundle file except `summary.json` itself.",
+    "- `summary.json.checksums.bundleDigest` records a deterministic fingerprint of the checksum manifest for quick bundle identity comparison.",
+    "- `design-ai site <bundle-dir> --bundle-check --strict --json` recomputes those checksums so transferred or manually edited bundles fail before target-repo handoff.",
+    "",
+    "## Boundaries",
+    "- This bundle is deterministic and local.",
+    "- It does not call external MCPs, mutate the target website repo, run Lighthouse/axe, capture screenshots, or write to deployment/CMS/Sentry systems.",
+  ].join("\n");
+}