@amg555/frameforge-mcp 2.7.6 → 2.7.7

package/.agent/skills/gstack-make-pdf/SKILL.md.tmpl

@@ -1,253 +0,0 @@
----
-name: make-pdf
-preamble-tier: 1
-version: 1.0.0
-description: |
-  Turn any markdown file into a publication-quality PDF. Proper 1in margins,
-  intelligent page breaks, page numbers, cover pages, running headers, curly
-  quotes and em dashes, clickable TOC, diagonal DRAFT watermark. Not a draft
-  artifact — a finished artifact. Use when asked to "make a PDF", "export to
-  PDF", "turn this markdown into a PDF", or "generate a document". (gstack)
-voice-triggers:
-  - "make this a pdf"
-  - "make it a pdf"
-  - "export to pdf"
-  - "turn this into a pdf"
-  - "turn this markdown into a pdf"
-  - "generate a pdf"
-  - "make a pdf from"
-  - "pdf this markdown"
-triggers:
-  - markdown to pdf
-  - generate pdf
-  - make pdf
-  - export pdf
-allowed-tools:
-  - Bash
-  - Read
-  - AskUserQuestion
----
-
-{{PREAMBLE}}
-
-# make-pdf: publication-quality PDFs from markdown
-
-Turn `.md` files into PDFs that look like Faber & Faber essays: 1in margins,
-left-aligned body, Helvetica throughout, curly quotes and em dashes, optional
-cover page and clickable TOC, diagonal DRAFT watermark when you need it.
-Copy-paste from the PDF produces clean words, never "S a i l i n g".
-
-On Linux, install `fonts-liberation` for correct rendering — Helvetica and Arial
-aren't present by default, and Liberation Sans is the standard metric-compatible
-fallback. CI and Docker builds install it automatically via Dockerfile.ci.
-
-Emoji need a color-emoji font. macOS (Apple Color Emoji) and Windows (Segoe UI
-Emoji) ship one; most Linux distros and containers ship none, so emoji render as
-empty boxes (▯). `./setup` auto-installs `fonts-noto-color-emoji` on Linux
-(apt/dnf/pacman/apk, best-effort) and the print CSS falls back through Apple /
-Segoe / Noto emoji families. Set `GSTACK_SKIP_FONTS=1` to skip the install (CI
-without sudo, managed or offline machines). These matter on the gstack-browser
-fallback; Aside renders with the fonts already on the Mac.
-
-PDF output prints through the Aside browser (macOS 15+, aside.com) when it is
-running, and falls back to gstack's own headless browser (built by `./setup`;
-`GSTACK_BROWSE_BIN` / `BROWSE_BIN` point at a different build) everywhere
-else — Linux, Windows, or a closed Aside app. Exit 4 means neither browser is
-available. `--to html` and `--to docx` need no browser at all (diagrams in
-DOCX need one to rasterize; without it they embed as source text).
-
-## Core patterns
-
-### 80% case — memo/letter
-
-One command, no flags. Gets a clean PDF with running header + page numbers
-+ CONFIDENTIAL footer by default.
-
-```bash
-"$P" generate letter.md                 # writes /tmp/letter.pdf
-"$P" generate letter.md letter.pdf      # explicit output path
-```
-
-### Publication mode — cover + TOC + chapter breaks
-
-```bash
-"$P" generate --cover --toc --author "Garry Tan" --title "On Horizons" \
-  essay.md essay.pdf
-```
-
-Each top-level H1 in the markdown starts a new page. Disable with
-`--no-chapter-breaks` for memos that happen to have multiple H1s.
-
-### Draft-stage watermark
-
-```bash
-"$P" generate --watermark DRAFT memo.md draft.pdf
-```
-
-Diagonal 10% opacity DRAFT across every page. When the draft is final, drop
-the flag and regenerate.
-
-### Fast iteration via preview
-
-```bash
-"$P" preview essay.md
-```
-
-Renders HTML with the same print CSS and opens it in your browser. Refresh
-as you edit the markdown. Skip the PDF round trip until you're ready.
-
-### Brand-free (no CONFIDENTIAL footer)
-
-```bash
-"$P" generate --no-confidential memo.md memo.pdf
-```
-
-### Diagrams — mermaid and excalidraw fences render as pictures
-
-A column-0 ` ```mermaid ` or ` ```excalidraw ` fence in the markdown renders
-as a crisp vector diagram, fully offline (vendored bundle, no CDN). Indented
-fences (inside lists) stay plain code blocks by design. A broken fence
-produces a visible red diagnostic block with the parse error — never silent
-raw code.
-
-Fence info-string options:
-
-```
-```mermaid title="Auth flow"        ← caption + aria-label
-```mermaid render=false             ← keep it as a code block
-```mermaid page=landscape           ← force this diagram onto a landscape page
-```mermaid page=portrait            ← veto auto-landscape for this diagram
-```
-
-A ` ```excalidraw ` fence contains a full .excalidraw scene file (what
-excalidraw.com saves). Authoring NEW diagrams from English is `/diagram`'s
-job — it emits an editable triplet (source, .excalidraw, SVG/PNG) and pairs
-with this skill: embed the `.mmd` source in your markdown, not the PNG.
-
-### Images — scaled right, never truncated
-
-Local images inline automatically (relative paths resolve against the
-markdown file). Every image caps at the content box — zero truncation, ever.
-Oversized photos downscale to print resolution (300dpi) so payloads stay
-small with no visible quality loss.
-
-Remote (http/https) images are **blocked with a visible placeholder** by
-default — offline posture; pass `--allow-network` to fetch them. An image
-that resolves outside the markdown's directory (even via symlink) still
-inlines, but warns loudly; `--strict` makes it fatal. Files over 64MB or
-non-regular files (fifos, devices) degrade to a placeholder instead of
-hanging the run.
-
-Per-image directives, written immediately after the image:
-
-```
-![chart](data.png){width=full}      ← stretch to content-box width
-![chart](data.png){width=50%}       ← percentage or 3in/8cm/200px
-![wide](arch.png){page=landscape}   ← give it its own landscape page
-![wide](shot.png){page=portrait}    ← veto auto-landscape
-```
-
-Wide, small-text diagram images auto-promote to their own landscape page
-(conservative: aspect ≥ 1.8, width over ~2.5x the content box, AND a
-diagram-ish alt word — diagram/architecture/flowchart/chart/graph). The
-promoted page is vertically centered. When the heuristic guesses wrong,
-`{page=portrait}` vetoes it; false negatives just need `{page=landscape}`.
-
-### Other formats — single-file HTML and Word
-
-```bash
-"$P" generate readme.md out.html --to html    # ONE self-contained file: inline
-                                            # SVG diagrams, data-URI images,
-                                            # zero network refs, screen-readable
-"$P" generate readme.md out.docx --to docx    # Word: content fidelity (headings,
-                                            # tables, code, diagrams as PNG) —
-                                            # layout is Word's, not ours
-```
-
-`--to` is the output format. `--format` is something else entirely (a
-`--page-size` alias) — don't confuse them.
-
-### CI mode — fail loud on missing assets
-
-```bash
-"$P" generate docs.md --strict     # missing, remote, out-of-tree, oversized,
-                                 # and non-regular-file images exit non-zero
-                                 # instead of warn + placeholder
-```
-
-## Common flags
-
-```
-Page layout:
-  --margins <dim>            1in (default) | 72pt | 2.54cm | 25mm
-  --page-size letter|a4|legal
-
-Structure:
-  --cover                    Cover page (title, author, date, hairline rule)
-  --toc                      Clickable TOC with page numbers
-  --no-chapter-breaks        Don't start a new page at every H1
-
-Branding:
-  --watermark <text>         Diagonal watermark ("DRAFT", "CONFIDENTIAL")
-  --header-template <html>   Custom running header
-  --footer-template <html>   Custom footer (mutex with --page-numbers)
-  --no-confidential          Suppress the CONFIDENTIAL right-footer
-
-Output:
-  --to pdf|html|docx         Output format (default: pdf). html = single
-                             self-contained file; docx = content fidelity.
-  --strict                   Missing, remote, out-of-tree, oversized, or
-                             non-regular-file images fail the run (CI mode).
-  --page-numbers             "N of M" footer (default on)
-  --tagged                   Accessible PDF (default on)
-  --outline                  PDF bookmarks from headings (default on)
-  --quiet                    Suppress progress on stderr
-  --verbose                  Per-stage timings
-
-Network:
-  --allow-network            Fetch external images. Off by default: remote
-                             images render as a visible blocked placeholder
-                             (no tracking pixels fetch at print time).
-
-Metadata:
-  --title "..."              Document title (defaults to first H1)
-  --author "..."             Author for cover + PDF metadata
-  --date "..."               Date for cover (defaults to today)
-```
-
-## When to run it
-
-Run `"$P" generate` when the user wants markdown as a PDF. If the user has a `.md`
-file open and says "make it look nice", propose `"$P" generate --cover --toc` and ask
-before running.
-
-## Debugging
-
-- Exit 4 / "no browser available" → neither the Aside browser (macOS 15+,
-  aside.com) nor gstack's own headless browser is usable. Open Aside, or run
-  `./setup` in the gstack repo to build the fallback, re-run. `"$P" setup` checks
-  the whole chain and says which browser it found.
-- Diagram shows a red "failed to render" block → the parse error is printed in
-  the block. If EVERY diagram fails with "diagram renderer:", the browser went
-  away mid-run (Aside closed, or the fallback daemon died).
-- Fragmented text on copy-paste → remove fenced code blocks and regenerate
-  (no flag turns code styling off).
-- Exit 3 (`$P: --toc: …`) → TOC page numbers could not be verified against the printed PDF; the message says why. Drop `--toc`, or shorten very long TOC headings if it says the numbers did not settle.
-- "[remote image blocked]" placeholder in the output → add `--allow-network`
-  (understand you're giving the markdown file permission to fetch from its
-  image URLs).
-- Generated PDF too tall/wide → `--page-size a4` or `--margins 0.75in`.
-
-## Output contract
-
-```
-stdout: /tmp/letter.pdf          ← just the path, one line
-stderr: Rendering HTML...        ← progress spinner (unless --quiet)
-        Rendering PDF through Aside...   ← or "through gstack's browser"
-        Done in 11.2s. 43 words · 22KB · /tmp/letter.pdf
-
-exit code: 0 success / 1 bad args / 2 render error / 3 TOC page numbers failed
-           / 4 no browser available (Aside not open, fallback not built)
-```
-
-Capture the path: `PDF=$("$P" generate letter.md)` — then use `$PDF`.

package/.agent/skills/gstack-make-pdf/src/asideClient.ts

@@ -1,114 +0,0 @@
-/**
- * make-pdf's render client: final HTML → PDF through lib/aside-render's
- * `render()` — the Aside browser (macOS 15+, aside.com) when it is running,
- * otherwise gstack's own headless browser (the browse daemon; GSTACK_BROWSE_BIN
- * / BROWSE_BIN override where it lives). The HTML is staged into a private
- * dir, served over loopback for the duration of the render, printed, and the
- * PDF copied to `output`. No browser at all is exit 4 (BrowserUnavailableError).
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import {
-  NO_BROWSER,
-  PAGE_NUMBER_FOOTER,
-  lengthToInches,
-  paperInches,
-  render,
-  renderTmpDir,
-  type PdfStepOptions,
-  type RenderEngine,
-} from "../../lib/aside-render";
-import { BrowserUnavailableError } from "./types";
-
-export interface PdfOptions {
-  output: string;
-  format?: string;
-  width?: string;
-  height?: string;
-  marginTop?: string;
-  marginRight?: string;
-  marginBottom?: string;
-  marginLeft?: string;
-  headerTemplate?: string;
-  footerTemplate?: string;
-  pageNumbers?: boolean;
-  tagged?: boolean;
-  outline?: boolean;
-  printBackground?: boolean;
-  preferCSSPageSize?: boolean;
-}
-
-/**
- * make-pdf's option shape → CDP Page.printToPDF options (inches). Same
- * mapping the browse `pdf` command applies: Letter when no size is
- * given, empty `<div></div>` for whichever header/footer slot is unset so
- * Chromium never prints its default URL/date, margins default to none.
- */
-export function pdfStepOptions(opts: PdfOptions): PdfStepOptions {
-  const o: PdfStepOptions = {};
-
-  if (opts.format) {
-    const paper = paperInches(opts.format);
-    if (!paper) throw new Error(`unknown page size: ${opts.format}`);
-    [o.paperWidth, o.paperHeight] = paper;
-  } else if (opts.width && opts.height) {
-    o.paperWidth = lengthToInches(opts.width);
-    o.paperHeight = lengthToInches(opts.height);
-  } else {
-    [o.paperWidth, o.paperHeight] = paperInches("letter")!;
-  }
-
-  o.marginTop = lengthToInches(opts.marginTop) ?? 0;
-  o.marginRight = lengthToInches(opts.marginRight) ?? 0;
-  o.marginBottom = lengthToInches(opts.marginBottom) ?? 0;
-  o.marginLeft = lengthToInches(opts.marginLeft) ?? 0;
-
-  if (opts.headerTemplate !== undefined || opts.footerTemplate !== undefined || opts.pageNumbers === true) {
-    o.displayHeaderFooter = true;
-    o.headerTemplate = opts.headerTemplate ?? "<div></div>";
-    o.footerTemplate = opts.pageNumbers ? PAGE_NUMBER_FOOTER : (opts.footerTemplate ?? "<div></div>");
-  }
-
-  if (opts.tagged === true) o.generateTaggedPDF = true;
-  if (opts.outline === true) o.generateDocumentOutline = true;
-  if (opts.printBackground === true) o.printBackground = true;
-  if (opts.preferCSSPageSize === true) o.preferCSSPageSize = true;
-  return o;
-}
-
-/**
- * Render a self-contained HTML document to `opts.output`. Everything the page
- * needs must be inline (the orchestrator inlines images as data URIs): only
- * the staging dir is served.
- */
-export async function renderPdf(
-  html: string,
-  opts: PdfOptions,
-  renderFn: typeof render = render,
-): Promise<RenderEngine | undefined> {
-  const dir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-"));
-  try {
-    const file = path.join(dir, "document.html");
-    fs.writeFileSync(file, html, "utf8");
-    const result = await renderFn({
-      file,
-      steps: [{ kind: "pdf", out: path.resolve(opts.output), options: pdfStepOptions(opts) }],
-    });
-    if (!result.ok) throw renderFailure(result.error ?? "unknown error");
-    return result.engine;
-  } finally {
-    fs.rmSync(dir, { recursive: true, force: true });
-  }
-}
-
-/**
- * Classify a failed render: a BrowserUnavailableError (exit 4) when neither
- * browser could run at all, otherwise a plain render error (exit 2).
- */
-export function renderFailure(detail: string): Error {
-  return detail.startsWith(NO_BROWSER)
-    ? new BrowserUnavailableError(detail)
-    : new Error(`PDF render failed: ${detail}`);
-}

package/.agent/skills/gstack-make-pdf/src/cli.ts

@@ -1,294 +0,0 @@
-#!/usr/bin/env bun
-/**
- * make-pdf CLI — argv parse, dispatch, exit.
- *
- * Output contract (per CEO plan DX spec):
- *   stdout: ONLY the output path on success. One line. Nothing else.
- *   stderr: progress spinner per stage, final "Done in Xs. N pages."
- *   --quiet: suppress progress. Errors still print.
- *   --verbose: per-stage timings.
- *   exit 0 success / 1 bad args / 2 render error / 3 TOC page numbers failed / 4 no browser
- *   (Aside not running AND gstack's own browser not built).
- */
-
-import { COMMANDS } from "./commands";
-import { ExitCode, BrowserUnavailableError } from "./types";
-import type { GenerateOptions, PreviewOptions } from "./types";
-
-interface ParsedArgs {
-  command: string;
-  positional: string[];
-  flags: Record<string, string | boolean>;
-}
-
-/**
- * Flags that never take a value (#2514). The parser used to treat ANY
- * following non-flag token as the flag's value, so the skill's own
- * documented usage — `$P generate --cover --toc essay.md essay.pdf` — worked
- * only by luck of flag adjacency, while `$P generate --toc essay.md` ate
- * `essay.md` as --toc's value and failed with "missing input".
- */
-export const BOOLEAN_FLAGS = new Set([
-  "cover", "toc", "no-chapter-breaks", "confidential", "no-confidential",
-  "page-numbers", "no-page-numbers", "tagged", "no-tagged",
-  "outline", "no-outline", "quiet", "verbose", "allow-network", "strict",
-]);
-
-export function parseArgs(argv: string[]): ParsedArgs {
-  const args = argv.slice(2);
-  if (args.length === 0) {
-    printUsage();
-    process.exit(ExitCode.Success);
-  }
-  // setup's and gstack-doctor's launch probe (#2595): the version command needs no browser.
-  if (args[0] === "--version") return { command: "version", positional: [], flags: {} };
-
-  // First non-flag arg is the command.
-  let command = "";
-  const positional: string[] = [];
-  const flags: Record<string, string | boolean> = {};
-
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a.startsWith("--")) {
-      const key = a.slice(2);
-      const next = args[i + 1];
-      if (!BOOLEAN_FLAGS.has(key) && next !== undefined && !next.startsWith("--")) {
-        flags[key] = next;
-        i++;
-      } else {
-        flags[key] = true;
-      }
-    } else if (!command) {
-      command = a;
-    } else {
-      positional.push(a);
-    }
-  }
-
-  return { command, positional, flags };
-}
-
-function printUsage(): void {
-  const lines = [
-    "make-pdf — turn markdown into publication-quality PDFs",
-    "",
-    "Usage:",
-  ];
-  for (const [name, info] of COMMANDS) {
-    lines.push(`  $P ${info.usage}`);
-    lines.push(`      ${info.description}`);
-  }
-  lines.push("");
-  lines.push("Output format:");
-  lines.push("  --to pdf|html|docx        What to produce (default: pdf).");
-  lines.push("                            html = single self-contained file, no network refs.");
-  lines.push("                            docx = content fidelity, diagrams as PNG.");
-  lines.push("");
-  lines.push("Page layout:");
-  lines.push("  --margins <dim>           All four margins (default: 1in). in, pt, cm, mm.");
-  lines.push("  --page-size letter|a4|legal  (aliases: --format — page SIZE, not output format)");
-  lines.push("");
-  lines.push("Document structure:");
-  lines.push("  --cover                   Add a cover page.");
-  lines.push("  --toc                     Generate clickable table of contents with page numbers.");
-  lines.push("  --no-chapter-breaks       Don't start a new page at every H1.");
-  lines.push("");
-  lines.push("Branding:");
-  lines.push("  --watermark <text>        Diagonal watermark on every page.");
-  lines.push("  --header-template <html>");
-  lines.push("  --footer-template <html>  Mutex with --page-numbers.");
-  lines.push("  --no-confidential         Suppress the CONFIDENTIAL footer.");
-  lines.push("");
-  lines.push("Output control:");
-  lines.push("  --page-numbers / --no-page-numbers   (default: on)");
-  lines.push("  --tagged / --no-tagged               (default: on, accessible PDF)");
-  lines.push("  --outline / --no-outline             (default: on, PDF bookmarks)");
-  lines.push("  --quiet                   Suppress progress on stderr.");
-  lines.push("  --verbose                 Per-stage timings on stderr.");
-  lines.push("");
-  lines.push("Diagrams & images:");
-  lines.push("  ```mermaid / ```excalidraw fences render as vector diagrams.");
-  lines.push("  Add render=false to a fence info string to keep it as a code block.");
-  lines.push("  Local images are inlined; oversized rasters downscale to print resolution.");
-  lines.push("  --strict                  Missing/remote images fail the run (CI mode).");
-  lines.push("");
-  lines.push("Network:");
-  lines.push("  --allow-network           Load external images (off by default).");
-  lines.push("");
-  lines.push("Examples:");
-  lines.push("  $P generate letter.md");
-  lines.push("  $P generate --cover --toc essay.md essay.pdf");
-  lines.push("  $P generate --watermark DRAFT memo.md draft.pdf");
-  lines.push("  $P preview letter.md");
-  lines.push("");
-  lines.push("Run `$P setup` to verify the browser (Aside, or gstack's own fallback) + pdftotext install.");
-  console.error(lines.join("\n"));
-}
-
-function generateOptionsFromFlags(parsed: ParsedArgs): GenerateOptions {
-  const p = parsed.positional;
-  if (p.length === 0) {
-    console.error("$P generate: missing <input.md>");
-    console.error("Usage: $P generate <input.md> [output.pdf] [options]");
-    process.exit(ExitCode.BadArgs);
-  }
-  const f = parsed.flags;
-  const booleanFlag = (key: string, def: boolean): boolean => {
-    if (f[key] === true) return true;
-    if (f[`no-${key}`] === true) return false;
-    return def;
-  };
-  const to = typeof f.to === "string" ? f.to.toLowerCase() : "pdf";
-  if (to !== "pdf" && to !== "html" && to !== "docx") {
-    console.error(`$P generate: invalid --to '${f.to}'. Expected pdf, html, or docx.`);
-    console.error("(--format is a --page-size alias, not the output format.)");
-    process.exit(ExitCode.BadArgs);
-  }
-  return {
-    input: p[0],
-    output: p[1],
-    to: to as GenerateOptions["to"],
-    margins: f.margins as string | undefined,
-    marginTop: f["margin-top"] as string | undefined,
-    marginRight: f["margin-right"] as string | undefined,
-    marginBottom: f["margin-bottom"] as string | undefined,
-    marginLeft: f["margin-left"] as string | undefined,
-    pageSize: ((f["page-size"] ?? f.format) as any),
-    cover: f.cover === true,
-    toc: f.toc === true,
-    noChapterBreaks: f["no-chapter-breaks"] === true,
-    watermark: typeof f.watermark === "string" ? f.watermark : undefined,
-    headerTemplate: typeof f["header-template"] === "string"
-      ? f["header-template"] : undefined,
-    footerTemplate: typeof f["footer-template"] === "string"
-      ? f["footer-template"] : undefined,
-    confidential: booleanFlag("confidential", true),
-    pageNumbers: booleanFlag("page-numbers", true),
-    tagged: booleanFlag("tagged", true),
-    outline: booleanFlag("outline", true),
-    quiet: f.quiet === true,
-    verbose: f.verbose === true,
-    allowNetwork: f["allow-network"] === true,
-    strict: f.strict === true,
-    title: typeof f.title === "string" ? f.title : undefined,
-    author: typeof f.author === "string" ? f.author : undefined,
-    date: typeof f.date === "string" ? f.date : undefined,
-  };
-}
-
-function previewOptionsFromFlags(parsed: ParsedArgs): PreviewOptions {
-  const p = parsed.positional;
-  if (p.length === 0) {
-    console.error("$P preview: missing <input.md>");
-    console.error("Usage: $P preview <input.md> [options]");
-    process.exit(ExitCode.BadArgs);
-  }
-  const f = parsed.flags;
-  const booleanFlag = (key: string, def: boolean): boolean => {
-    if (f[key] === true) return true;
-    if (f[`no-${key}`] === true) return false;
-    return def;
-  };
-  return {
-    input: p[0],
-    cover: f.cover === true,
-    toc: f.toc === true,
-    watermark: typeof f.watermark === "string" ? f.watermark : undefined,
-    noChapterBreaks: f["no-chapter-breaks"] === true,
-    confidential: booleanFlag("confidential", true),
-    allowNetwork: f["allow-network"] === true,
-    title: typeof f.title === "string" ? f.title : undefined,
-    author: typeof f.author === "string" ? f.author : undefined,
-    date: typeof f.date === "string" ? f.date : undefined,
-    quiet: f.quiet === true,
-    verbose: f.verbose === true,
-  };
-}
-
-async function main(): Promise<void> {
-  const parsed = parseArgs(process.argv);
-
-  if (!parsed.command) {
-    printUsage();
-    process.exit(ExitCode.BadArgs);
-  }
-
-  if (!COMMANDS.has(parsed.command)) {
-    console.error(`$P: unknown command: ${parsed.command}`);
-    console.error("");
-    printUsage();
-    process.exit(ExitCode.BadArgs);
-  }
-
-  try {
-    switch (parsed.command) {
-      case "version": {
-        // Read from VERSION file or fall back to a hard-coded default.
-        try {
-          const fs = await import("node:fs");
-          const path = await import("node:path");
-          const versionFile = path.resolve(
-            path.dirname(process.argv[1] || ""),
-            "../../VERSION",
-          );
-          const version = fs.readFileSync(versionFile, "utf8").trim();
-          console.log(version);
-        } catch {
-          console.log("make-pdf (version unknown)");
-        }
-        process.exit(ExitCode.Success);
-      }
-
-      case "setup": {
-        const { runSetup } = await import("./setup");
-        await runSetup();
-        process.exit(ExitCode.Success);
-      }
-
-      case "generate": {
-        const opts = generateOptionsFromFlags(parsed);
-        const { generate } = await import("./orchestrator");
-        const outputPath = await generate(opts);
-        // Contract: stdout = output path only
-        console.log(outputPath);
-        process.exit(ExitCode.Success);
-      }
-
-      case "preview": {
-        const opts = previewOptionsFromFlags(parsed);
-        const { preview } = await import("./orchestrator");
-        const htmlPath = await preview(opts);
-        console.log(htmlPath);
-        process.exit(ExitCode.Success);
-      }
-
-      default:
-        // Unreachable: COMMANDS.has guarded above
-        process.exit(ExitCode.BadArgs);
-    }
-  } catch (err: any) {
-    if (err instanceof BrowserUnavailableError) {
-      console.error(`$P: ${err.message}`);
-      process.exit(ExitCode.BrowserUnavailable);
-    }
-    if (err?.code === "ENOENT") {
-      console.error(`$P: file not found: ${err.path ?? err.message}`);
-      process.exit(ExitCode.BadArgs);
-    }
-    if (err?.name === "TocPaginationError") {
-      console.error(`$P: --toc: ${err.message}`);
-      process.exit(ExitCode.TocPagination);
-    }
-    console.error(`$P: ${err?.message ?? String(err)}`);
-    if (parsed.flags.verbose && err?.stack) {
-      console.error(err.stack);
-    }
-    process.exit(ExitCode.RenderError);
-  }
-}
-
-// Guarded so tests can import parseArgs/BOOLEAN_FLAGS without running the CLI.
-if (import.meta.main) {
-  main();
-}