@dev.fast/whiteboard 0.2.5-preview.20261013.113 → 0.2.5-preview.20261015.115

package/instructions/authoring.md

@@ -2,6 +2,7 @@ you are writing an interactive rfc-style whiteboard, for consumption by a staff
 
 **flow**
 follow these first five steps in order, with no tool calls beyond what they need: loading the tools they use (`session_create`, `session_activity_begin`, `session_edit`, `session_get`, and later `session_activity_update` and `session_activity_end`) and, for a PR, reading its description (`gh pr view`).
+
 - create the whiteboard, pinned to the commits/pr the user describes, naming the checkout by its `repositoryPath`. if they name none, use a `worktree` target with no `base`: it reviews the checkout, uncommitted work included, against the default branch. for uncommitted work only, pass `base: "HEAD"`. untracked files are left out: run `git add -N <file>` on new files you want reviewed
 - trigger a subagent with this exact instruction: "Call `session_get_instructions({topic:\"file-lenses\"})` and follow it for whiteboard <sessionId>, whose change is `<base>..<head>` in `<repositoryPath>`."
 - call `session_activity_begin` and pass its `activityId` on every `session_edit`
@@ -9,27 +10,30 @@ follow these first five steps in order, with no tool calls beyond what they need
 - immediately after reading the diff (and the PR description) - put down a first pass at the what/why section.
 
 - whiteboard structure - each of these should be written as a top-level `section`, in this order:
-    - what/why: succinct description of what the change is, + why the change was made (if this context is available to you.)
-    - requirements: as given by the user, in their own words, if this context is available to you. otherwise, omit. write these as short bullet points
-    - design: how the solution works at the level of components, data and control flow, not functions.
-        - pick one diagram that best shows the shape of the change:
-            - `sequence` if participants interact over time (who calls whom, async handoffs)
-            - `flow_diagram` if the interesting part is branches, retries or state transitions
-            - `database_lens` if the interesting part is a schema change to the data stores, and/or who reads/writes it
-        - if the change is mostly a new/changed contract, show the key types / interfaces as `code_peek`(s)
-        plus the main decisions and tradeoffs, and alternatives considered if you have evidence for them (trace, PR discussion). skip for small changes whose design is self-evident.
-    - implementation: how the code delivers the design, at the level of functions and files. walk the changed code in the order a reader should follow it, starting with the entry point.
-        - `call_stack_diff` for the old vs. new path through user flows. always root the flows in the user/agent entry point (eg a button click, CLI command, etc.), including unchanged nodes along the way.
-        - `code_peek` for the few spots that carry the mechanism or an invariant; link everything else inline
+  - what/why: succinct description of what the change is, + why the change was made (if this context is available to you.)
+  - requirements: as given by the user, in their own words, if this context is available to you. otherwise, omit. write these as short bullet points
+  - design: how the solution works at the level of components, data and control flow, not functions.
+    - pick one diagram that best shows the shape of the change:
+      - `sequence` if participants interact over time (who calls whom, async handoffs)
+      - `flow_diagram` if the interesting part is branches, retries or state transitions
+      - `database_lens` if the interesting part is a schema change to the data stores, and/or who reads/writes it
+    - if the change is mostly a new/changed contract, show the key types / interfaces as `code_peek`(s)
+      plus the main decisions and tradeoffs, and alternatives considered if you have evidence for them (trace, PR discussion). skip for small changes whose design is self-evident.
+  - implementation: how the code delivers the design, at the level of functions and files. walk the changed code in the order a reader should follow it, starting with the entry point.
+    - `call_stack_diff` for the old vs. new path through user flows. always root the flows in the user/agent entry point (eg a button click, CLI command, etc.), including unchanged nodes along the way.
+    - `code_peek` for the few spots that carry the mechanism or an invariant; link everything else inline
 
 - before finishing, read the whole whiteboard back with `session_get({sessionId, full: true})` (without `full`, prose is cut short) and fix any contradictions/unverified claims.
 
 **updating existing whiteboard**
+
 - move the whiteboard to the new commits with `session_set_target`
 - read the existing whiteboard (if you haven't already,) read the diff since last whiteboard, make any necessary updates to the whiteboard.
 
 **guidelines**
+
 - IMPORTANT: Write incrementally. The user sees you write on the canvas in real-time. Show them visual progress every few seconds.
+- IMPORTANT: When writing, you have a max budget of 3 sentences at a time in a `markdown` component before you must use a diagram or a visual of some sort (another `content.type`, such as `code_peek`, `sequence`, `flow_diagram`, `call_stack_diff` or `database_lens`). If a visual/diagram covers the same content as prose, use a visual aid. When you do write, write in the ASD-STE100 spec (the full spec is a bit too stringent, so aim for ~80% of that style)
 - use `session_activity_update` to provide regular status updates on your area of focus.
 - keep whiteboards short and sweet when possible (esp. for small changes.) feel free to omit sections.
 - when something (a phrase in the prose, diagram node, etc.) describes actual code in the codebase, always default to attaching/hyperlink code.

package/instructions/file-lenses.md

@@ -3,11 +3,13 @@ you are grouping a code whiteboard's changed files into file lenses for the Diff
 **input:** a whiteboard id, and its change as `<base>..<head>` in a repository path.
 
 **flow**
+
 - call `session_activity_begin` before writing, pass its `activityId` on every `session_lens_edit`, and call `session_activity_end` when done.
 - call `session_lens_get`: before any lens exists, its `uncategorized` lists every changed file
 - categorize all the changes into buckets - leaving nothing in uncategorized changes by the end
-    - first, categorize away non-implementation code:  tests, docs, generated files and lockfiles, config and build, fixtures and snapshots, pure renames and moves, formatting-only changes, imports — all might be reasonable.
-    - then, when left with only implementation code, split it by the part of the design each file serves (e.g. the data model, an API, a UI surface), in the order a reader should take them. keep each lens small enough to read in one sitting, and don't split a file across lenses unless it holds two unrelated changes.
+  - first, categorize away non-implementation code: tests, docs, generated files and lockfiles, config and build, fixtures and snapshots, pure renames and moves, formatting-only changes, imports — all might be reasonable.
+  - then, when left with only implementation code, split it by the part of the design each file serves (e.g. the data model, an API, a UI surface), in the order a reader should take them. keep each lens small enough to read in one sitting, and don't split a file across lenses unless it holds two unrelated changes.
 
 **guidelines**
+
 - to see a file's changes, run `git diff <base> <head> -- <path>` in the repository. otherwise, rely on the file listing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.fast/whiteboard",
-  "version": "0.2.5-preview.20261013.113",
+  "version": "0.2.5-preview.20261015.115",
   "private": false,
   "license": "MIT",
   "repository": {
@@ -18,8 +18,6 @@
     "onboarding.md",
     "dist",
     "instructions",
-    "tutorial",
-    "!tutorial/.bundle",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*test-utils*",
@@ -59,24 +57,27 @@
     "semver": "7.8.5",
     "sharp": "0.35.5",
     "smol-toml": "1.9.0",
+    "undici": "7.29.1",
+    "yauzl": "3.4.0",
     "zod": "4.6.5",
-    "@dev.fast/diffr": "0.1.19"
+    "@dev.fast/diffr": "0.1.20"
   },
   "devDependencies": {
     "@dev.fast/local-vcs": "^0.1.0",
     "@types/node": "24.12.2",
     "@types/semver": "7.7.1",
+    "@types/yauzl": "3.4.0",
     "micromark-extension-math": "3.1.0",
     "pino-pretty": "13.1.3",
     "tsdown": "0.22.14",
     "tsx": "4.21.0",
     "typescript": "6.0.3",
     "vitest": "4.1.11",
-    "@dev.fast/review-protocol": "0.0.0",
     "@dev.fast/json": "0.0.0",
+    "@dev.fast/review-protocol": "0.0.0",
     "@dev.fast/review-share-protocol": "0.1.2",
-    "@dev.fast/trace-protocol": "0.5.0",
-    "@dev.fast/trace-core": "0.0.0"
+    "@dev.fast/trace-core": "0.0.0",
+    "@dev.fast/trace-protocol": "0.5.0"
   },
   "engines": {
     "node": ">=24 <25"
@@ -86,17 +87,11 @@
     "repo": "devdotfast/review",
     "docs": "packages/review/instructions/authoring.md"
   },
-  "gitHead": "c9ba2f7bc95523c617b751c760f4cb2a5fb0c5c3",
+  "gitHead": "fd78e6a852a7f20798854059c5196c661f0df44f",
   "scripts": {
     "prebuild": "pnpm run build:workspace-deps",
     "build": "node --max-old-space-size=8192 node_modules/tsdown/dist/run.mjs",
-    "build:tutorial-assets": "tsx scripts/build-tutorial-assets.ts",
-    "ensure:tutorial-assets": "tsx scripts/ensure-tutorial-assets.ts",
-    "check:tutorial": "tsx scripts/check-tutorial.ts",
     "build:workspace-deps": "pnpm --filter @dev.fast/diffr --filter @dev.fast/json --filter @dev.fast/local-vcs --filter @dev.fast/review-protocol --filter @dev.fast/review-share-protocol --filter @dev.fast/trace-protocol --filter @dev.fast/trace-core build",
-    "pretypecheck": "pnpm run ensure:tutorial-assets",
-    "pretest": "pnpm run ensure:tutorial-assets",
-    "pretest:node": "pnpm run ensure:tutorial-assets",
     "start": "tsx src/cli.ts",
     "review": "tsx src/cli.ts",
     "test": "vitest run --config vitest.config.ts",

package/src/agent-connect.ts

@@ -0,0 +1,507 @@
+import { execFile } from "node:child_process";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { type JsonObject, type JsonValue, isJsonObject } from "@dev.fast/json";
+import type {
+  ReviewConnectAgent,
+  ReviewConnectResult,
+} from "@dev.fast/review-protocol";
+
+import { findExecutable } from "./ask/agents.js";
+import { type McpLaunch, reviewMcpLaunch } from "./connect-prompts.js";
+import { cursorInstallDeeplink } from "./cursor-deeplink.js";
+import { ALL_INSTALL_TARGETS, type InstallTarget } from "./install.js";
+
+const MARKETPLACE = "devdotfast/whiteboard";
+
+const PLUGIN = "whiteboard@devfast";
+
+const STEP_TIMEOUT_MS = 120_000;
+
+interface Harness {
+  name: string;
+  /** The CLI's names on PATH, most specific first. */
+  commands: string[];
+  /** Where its installer puts the CLI when that is not on PATH, under home. */
+  installDirs?: string[];
+  /** A directory under home whose presence means the harness is installed,
+   * for one that is an app rather than a CLI. */
+  homeDir?: string;
+  /** macOS app bundles that mean the harness is installed. */
+  apps?: string[];
+}
+
+const HARNESSES: Record<InstallTarget, Harness> = {
+  claude: {
+    name: "Claude Code",
+    commands: ["claude"],
+    installDirs: [".claude/local", ".local/bin"],
+  },
+  codex: { name: "Codex", commands: ["codex"] },
+  cursor: {
+    name: "Cursor",
+    commands: ["cursor"],
+    homeDir: ".cursor",
+    apps: ["/Applications/Cursor.app"],
+  },
+  opencode: {
+    name: "OpenCode",
+    commands: ["opencode"],
+    installDirs: [".opencode/bin"],
+  },
+  pi: { name: "Pi", commands: ["pi"] },
+  omp: { name: "oh-my-pi", commands: ["omp"], homeDir: ".omp" },
+  copilot: { name: "Copilot CLI", commands: ["copilot"] },
+};
+
+export interface ConnectEnvironment {
+  homeDir?: string;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  /** Whether ~/.local/bin/whiteboard exists for the MCP launch to run. */
+  hasShim: boolean;
+  run?: ConnectRun;
+}
+
+/** Runs one subprocess; never rejects, so a step's failure is its output. */
+export type ConnectRun = (
+  file: string,
+  args: string[],
+) => Promise<{ code: number; output: string }>;
+
+const runProcess: ConnectRun = (file, args) =>
+  new Promise((resolve) => {
+    execFile(
+      file,
+      args,
+      {
+        timeout: STEP_TIMEOUT_MS,
+        maxBuffer: 4 * 1024 * 1024,
+        // A plugin install must never wait on a prompt nobody can see.
+        env: { ...process.env, CI: "1", GIT_TERMINAL_PROMPT: "0" },
+        windowsHide: true,
+      },
+      (error, stdout, stderr) => {
+        const output = `${stdout}${stderr}`.trim();
+
+        // Only success matters to a step, not which failure it was.
+        resolve(
+          error
+            ? { code: 1, output: output || error.message }
+            : { code: 0, output },
+        );
+      },
+    );
+  });
+
+async function exists(target: string): Promise<boolean> {
+  try {
+    await stat(target);
+
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function findHarness(
+  harness: Harness,
+  homeDir: string,
+  env: NodeJS.ProcessEnv,
+): Promise<string | undefined> {
+  const installed = (harness.installDirs ?? []).map((directory) =>
+    path.join(homeDir, directory),
+  );
+
+  for (const command of harness.commands) {
+    const found =
+      (await findExecutable(command, env)) ??
+      (await findExecutable(command, { PATH: installed.join(path.delimiter) }));
+
+    if (found) return found;
+  }
+
+  return undefined;
+}
+
+async function harnessFound(
+  harness: Harness,
+  homeDir: string,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+): Promise<boolean> {
+  if (await findHarness(harness, homeDir, env)) return true;
+
+  if (harness.homeDir && (await exists(path.join(homeDir, harness.homeDir))))
+    return true;
+
+  if (platform !== "darwin") return false;
+
+  for (const app of harness.apps ?? []) if (await exists(app)) return true;
+
+  return false;
+}
+
+async function readJson(file: string): Promise<JsonValue | undefined> {
+  try {
+    return JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Follows `keys` down nested JSON objects. */
+function lookup(value: JsonValue | undefined, ...keys: string[]) {
+  let current = value;
+
+  for (const key of keys) {
+    if (!isJsonObject(current)) return undefined;
+    current = current[key];
+  }
+
+  return current;
+}
+
+/** Whether a `[plugins."…"]` table names the plugin, and does not turn it
+ * off. */
+export function codexHasPlugin(toml: string): boolean {
+  const lines = toml.split("\n");
+
+  const start = lines.findIndex(
+    (line) => line.trim() === `[plugins."${PLUGIN}"]`,
+  );
+
+  if (start === -1) return false;
+
+  for (const line of lines.slice(start + 1)) {
+    const trimmed = line.trim();
+
+    if (trimmed.startsWith("[")) break;
+
+    if (/^enabled\s*=\s*false\b/.test(trimmed)) return false;
+  }
+
+  return true;
+}
+
+/** Whether a harness already has Whiteboard, as its own config records it:
+ * the plugin it installed, or the MCP server added to it. Copilot keeps no
+ * record Whiteboard reads, so it always installs again, which is harmless. */
+async function harnessConnected(
+  target: InstallTarget,
+  homeDir: string,
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+): Promise<boolean> {
+  const claudeDir = env.CLAUDE_CONFIG_DIR ?? path.join(homeDir, ".claude");
+
+  const hasServer = async (file: string, ...keys: string[]) =>
+    lookup(await readJson(file), ...keys, "whiteboard") !== undefined;
+
+  switch (target) {
+    case "claude": {
+      if (platform === "win32")
+        return hasServer(path.join(homeDir, ".claude.json"), "mcpServers");
+
+      const [installed, settings] = await Promise.all([
+        readJson(path.join(claudeDir, "plugins", "installed_plugins.json")),
+        readJson(path.join(claudeDir, "settings.json")),
+      ]);
+
+      const installs = lookup(installed, "plugins", PLUGIN);
+
+      return (
+        Array.isArray(installs) &&
+        installs.length > 0 &&
+        lookup(settings, "enabledPlugins", PLUGIN) !== false
+      );
+    }
+
+    case "codex":
+      try {
+        return codexHasPlugin(
+          await readFile(
+            path.join(
+              env.CODEX_HOME ?? path.join(homeDir, ".codex"),
+              "config.toml",
+            ),
+            "utf8",
+          ),
+        );
+      } catch {
+        return false;
+      }
+
+    case "opencode": {
+      const config = await readJson(
+        path.join(
+          env.XDG_CONFIG_HOME ?? path.join(homeDir, ".config"),
+          "opencode",
+          "opencode.json",
+        ),
+      );
+
+      // Its `mcp add` has written both shapes.
+      return (
+        lookup(config, "mcp", "whiteboard") !== undefined ||
+        lookup(config, "mcp", "servers", "whiteboard") !== undefined
+      );
+    }
+
+    case "pi":
+      return hasServer(
+        path.join(homeDir, ".pi", "agent", "mcp.json"),
+        "mcpServers",
+      );
+    case "omp":
+      return hasServer(
+        path.join(homeDir, ".omp", "agent", "mcp.json"),
+        "mcpServers",
+      );
+    case "cursor":
+      return cursorHasServer(homeDir);
+    case "copilot":
+      return false;
+  }
+}
+
+/** Every harness Whiteboard connects to, whether this machine has it, and
+ * whether it already has Whiteboard. */
+export async function detectConnectAgents(
+  input: Omit<ConnectEnvironment, "hasShim" | "run"> = {},
+): Promise<ReviewConnectAgent[]> {
+  const homeDir = input.homeDir ?? os.homedir();
+  const env = input.env ?? process.env;
+  const platform = input.platform ?? process.platform;
+
+  return Promise.all(
+    ALL_INSTALL_TARGETS.map(async (target) => {
+      const found = await harnessFound(
+        HARNESSES[target],
+        homeDir,
+        env,
+        platform,
+      );
+
+      return {
+        target,
+        name: HARNESSES[target].name,
+        found,
+        connected:
+          found && (await harnessConnected(target, homeDir, env, platform)),
+      };
+    }),
+  );
+}
+
+interface Step {
+  args: string[];
+  /** Output that means the step had already been done. */
+  done?: RegExp;
+  /** Whether a failure leaves the next step to decide the outcome. */
+  optional?: boolean;
+}
+
+const ALREADY = /already/i;
+
+/** The commands that install Whiteboard into a CLI harness, as
+ * connect-prompts.ts tells an agent to run them. */
+function cliSteps(
+  target: Exclude<InstallTarget, "cursor" | "omp">,
+  launch: McpLaunch,
+  platform: NodeJS.Platform,
+): Step[] {
+  // The plugin install says whether it worked: the marketplace can already be
+  // known by another source, such as the repository's earlier name.
+  const marketplace = {
+    args: ["plugin", "marketplace", "add", MARKETPLACE],
+    optional: true,
+  };
+
+  // The plugins' sh launch cannot start on Windows, so there Claude and
+  // Copilot (which loads the Claude plugin) register the server directly.
+  const windowsServer = (scope: string[]) => ({
+    args: [
+      "mcp",
+      "add",
+      ...scope,
+      "whiteboard",
+      "--",
+      launch.command,
+      ...launch.args,
+    ],
+    done: ALREADY,
+  });
+
+  switch (target) {
+    case "claude":
+      return platform === "win32"
+        ? [windowsServer(["-s", "user"])]
+        : [
+            marketplace,
+            {
+              args: ["plugin", "install", PLUGIN, "--scope", "user"],
+              done: ALREADY,
+            },
+          ];
+    case "codex":
+      return [marketplace, { args: ["plugin", "add", PLUGIN], done: ALREADY }];
+    case "copilot":
+      return platform === "win32"
+        ? [windowsServer([])]
+        : [marketplace, { args: ["plugin", "install", PLUGIN], done: ALREADY }];
+    case "opencode":
+      return [
+        {
+          args: [
+            "mcp",
+            "add",
+            "--global",
+            "whiteboard",
+            "--",
+            launch.command,
+            ...launch.args,
+          ],
+          done: ALREADY,
+        },
+      ];
+    case "pi":
+      return [
+        {
+          args: [
+            "mcp",
+            "add",
+            "whiteboard",
+            "--",
+            launch.command,
+            ...launch.args,
+          ],
+          done: ALREADY,
+        },
+      ];
+  }
+}
+
+/** oh-my-pi reads its MCP servers from one JSON file; merge ours in. */
+async function connectOmp(
+  homeDir: string,
+  launch: McpLaunch,
+): Promise<ReviewConnectResult> {
+  const file = path.join(homeDir, ".omp", "agent", "mcp.json");
+
+  try {
+    const config: JsonValue = (await exists(file))
+      ? JSON.parse(await readFile(file, "utf8"))
+      : {};
+
+    if (!isJsonObject(config)) throw new Error(`${file} is not a JSON object.`);
+
+    const servers: JsonObject = isJsonObject(config.mcpServers)
+      ? { ...config.mcpServers }
+      : {};
+
+    servers.whiteboard = { command: launch.command, args: [...launch.args] };
+    const next: JsonObject = { ...config, mcpServers: servers };
+
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${JSON.stringify(next, null, 2)}\n`);
+
+    return { target: "omp", state: "connected", output: `Updated ${file}` };
+  } catch (error) {
+    return {
+      target: "omp",
+      state: "failed",
+      output: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+/** Whether Cursor's global MCP config already names Whiteboard's server. */
+async function cursorHasServer(homeDir: string): Promise<boolean> {
+  try {
+    const config: JsonValue = JSON.parse(
+      await readFile(path.join(homeDir, ".cursor", "mcp.json"), "utf8"),
+    );
+
+    return (
+      isJsonObject(config) &&
+      isJsonObject(config.mcpServers) &&
+      config.mcpServers.whiteboard !== undefined
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Cursor only installs an MCP server the user confirms, so open its link,
+ * unless it already has one: confirming again would ask for nothing new. */
+async function connectCursor(
+  homeDir: string,
+  launch: McpLaunch,
+  platform: NodeJS.Platform,
+  run: ConnectRun,
+): Promise<ReviewConnectResult> {
+  if (await cursorHasServer(homeDir))
+    return {
+      target: "cursor",
+      state: "connected",
+      output: "Cursor already has the whiteboard MCP server.",
+    };
+
+  const url = cursorInstallDeeplink(launch);
+
+  const [file, args] =
+    platform === "darwin"
+      ? // In the background, so Cursor's prompt waits behind Whiteboard.
+        ["open", ["-g", url]]
+      : platform === "win32"
+        ? ["cmd", ["/d", "/c", "start", '""', url]]
+        : ["xdg-open", [url]];
+
+  const result = await run(file, args);
+
+  return {
+    target: "cursor",
+    state: result.code === 0 ? "approve" : "failed",
+    output: result.output,
+  };
+}
+
+/** Installs Whiteboard's plugin, or its MCP server, into one harness. */
+export async function connectAgent(
+  target: InstallTarget,
+  input: ConnectEnvironment,
+): Promise<ReviewConnectResult> {
+  const homeDir = input.homeDir ?? os.homedir();
+  const env = input.env ?? process.env;
+  const platform = input.platform ?? process.platform;
+  const run = input.run ?? runProcess;
+  const launch = reviewMcpLaunch(input.hasShim, platform);
+
+  if (target === "omp") return connectOmp(homeDir, launch);
+
+  if (target === "cursor") return connectCursor(homeDir, launch, platform, run);
+
+  const executable = await findHarness(HARNESSES[target], homeDir, env);
+
+  if (!executable)
+    return {
+      target,
+      state: "failed",
+      output: `${HARNESSES[target].name} is not installed.`,
+    };
+  const outputs: string[] = [];
+
+  for (const step of cliSteps(target, launch, platform)) {
+    const result = await run(executable, step.args);
+
+    outputs.push(result.output);
+
+    if (result.code !== 0 && !step.optional && !step.done?.test(result.output))
+      return { target, state: "failed", output: outputs.join("\n").trim() };
+  }
+
+  return { target, state: "connected", output: outputs.join("\n").trim() };
+}

package/src/agent-selection.ts

@@ -35,6 +35,8 @@ export const AgentSelectionSchema = z.strictObject({
       startLine: z.number().int().positive(),
       endLine: z.number().int().positive(),
     }),
+    /** Nothing in particular: a question about the whole review. */
+    z.strictObject({ kind: z.literal("review") }),
   ]),
   title: z.string().max(500),
   detail: z.string().max(24000).optional(),
@@ -55,6 +57,8 @@ export function selectionMarkdown(
   if (selection.selectedDiff)
     return selectedDiffMarkdown(selection.selectedDiff, diffPaths);
 
+  if (target.kind === "review") return "";
+
   if (target.kind === "text")
     return target.quote
       .split(/\r?\n/)