diffing 0.16.1 → 0.18.0

package/dist/{mcp-BgrRjzn3.mjs → mcp-H7ytYScV.mjs}

@@ -1,6 +1,6 @@
-import { i as buildGitDiffArgs, s as parseDiffOptions, t as startServer } from "./server-Ct9QuV1l.mjs";
-import { t as formatComments } from "./comment-format-B85NHZnG.mjs";
-import { n as formatPlanReview } from "./plan-format-BwJh5JSE.mjs";
+import { i as buildGitDiffArgs, s as parseDiffOptions, t as startServer } from "./server-CiE24vh-.mjs";
+import { r as formatPlanReview, t as formatMockupReview } from "./mockup-format-CM3ivHHX.mjs";
+import { t as formatComments } from "./comment-format-D4mCqr7T.mjs";
 import { _ as generateSessionToken, c as removeServerLockIfOwned, i as isLockAlive, p as writeServerLock, r as diffScopeKey, s as removeServerLock, t as acquireServerStartupLease, u as resolveActiveServerLock, x as SESSION_TOKEN_HEADER, y as isLoopbackHost } from "./server-lock-CdaUNZyX.mjs";
 import { i as reviewSessionUrl, n as joinSessionApiUrl, r as reviewSessionBaseUrl, t as appendSessionToken } from "./session-url-B9FOnF3F.mjs";
 import { n as AWAIT_REVIEW_TIMEOUT_NEXT_ACTION, r as AWAIT_TOOL_DESCRIPTION_SUFFIX, s as PLAN_SUBMIT_NEXT_ACTION, t as AWAIT_PLAN_TIMEOUT_NEXT_ACTION } from "./handoff-DcShCxWJ.mjs";
@@ -16,7 +16,12 @@ import { z } from "zod";
 const moduleDirectory = dirname(fileURLToPath(import.meta.url));
 function readPackageVersion() {
 	const packagePath = resolve(moduleDirectory, "..", "package.json");
-	const pkg = JSON.parse(readFileSync(packagePath, "utf-8"));
+	let pkg;
+	try {
+		pkg = JSON.parse(readFileSync(packagePath, "utf-8"));
+	} catch {
+		throw new Error(`Invalid package.json at ${packagePath}`);
+	}
 	if (typeof pkg.version !== "string" || !pkg.version) throw new Error(`Invalid package version in ${packagePath}`);
 	return pkg.version;
 }
@@ -340,13 +345,14 @@ function createMcpServer(options) {
 	const ownerId = options.ownerId ?? randomUUID();
 	const defaultClientDir = existsSync(resolve(moduleDirectory, "client")) ? resolve(moduleDirectory, "client") : resolve(repoRoot, "dist/client");
 	const clientDir = options.clientDir ?? defaultClientDir;
-	const instructions = `diffing is bound to ${repoRoot} for this connection. First call review_session_status. If no web session is running, call start_review_session; it is safe to retry and never replaces a user session. For code review, prefer diff_summary then paged diff_files/diff_hunks/diff_slice over get_diff; create_comment as needed. Handoff: default is async — share the UI URL and end your turn; use await_review only when the human is reviewing now or asked you to wait. For a GitHub PR session, call gh_overview and bounded diff tools; use gh_list_threads/reviews for discussion, and mutate GitHub only with explicit user authorization. For plan review, call submit_plan, share the plan URL, and park unless asked to wait; then await_plan_review when sync waiting. A changes-requested verdict means revise and resubmit the same planId; rejected means stop; approved means proceed. Wait tools return released or timeout with disposition/nextAction; timeout means park (do not silent-loop). MCP connects only to the loopback diffing server; explicitly authorized GitHub tools may make the server call GitHub.`;
+	const instructions = `diffing is bound to ${repoRoot} for this connection. First call review_session_status. If no web session is running, call start_review_session; it is safe to retry and never replaces a user session. For code review, prefer diff_summary then paged diff_files/diff_hunks/diff_slice over get_diff; create_comment as needed. Handoff: default is async — share the UI URL and end your turn; use await_review only when the human is reviewing now or asked you to wait. For a GitHub PR session, call gh_overview and bounded diff tools; use gh_list_threads/reviews for discussion, and mutate GitHub only with explicit user authorization. For plan review, call submit_plan, share the plan URL, and park unless asked to wait; then await_plan_review when sync waiting. For HTML mockup review, call submit_mockup, share the mockup URL, and park unless asked to wait; then await_mockup_review when sync waiting. A changes-requested verdict means revise and resubmit the same planId; rejected means stop; approved means proceed. Wait tools return released or timeout with disposition/nextAction; timeout means park (do not silent-loop). MCP connects only to the loopback diffing server; explicitly authorized GitHub tools may make the server call GitHub.`;
 	const server = new McpServer({
 		name: "diffing",
 		version: MCP_VERSION
 	}, { instructions });
 	let reviewCursor = null;
 	let planCursor = null;
+	let mockupCursor = null;
 	let selectedLock = null;
 	function liveLock() {
 		if (selectedLock && lockIsAlive(selectedLock, repoRoot)) return selectedLock;
@@ -416,6 +422,15 @@ function createMcpServer(options) {
 		};
 		return planCursor.round;
 	}
+	async function seedMockupCursor(session, signal, force = false) {
+		if (!force && mockupCursor?.identity === session.identity) return mockupCursor.round;
+		const status = await requestSessionJson(session, "/api/mockup-review/status", { signal });
+		mockupCursor = {
+			identity: session.identity,
+			round: force ? status.round ?? 0 : Math.max(0, (status.round ?? 0) - 1)
+		};
+		return mockupCursor.round;
+	}
 	function sessionStatus() {
 		const lock = liveLock();
 		if (!lock) return {
@@ -618,54 +633,67 @@ function createMcpServer(options) {
 	});
 	server.registerTool("diff_summary", {
 		title: "Summarize the active diff (bounded)",
-		description: "Return bounded totals and change-kind counts without transferring the patch. Works for web, TUI, and GitHub PR sessions. Prefer this over get_diff.",
-		inputSchema: {},
+		description: "Return bounded totals, top-level directory buckets, and change-kind counts without transferring the patch. Optional exclude=[\"lockfiles\"] drops lock/generated basenames from counts only. Works for web, TUI, and GitHub PR sessions. Prefer this over get_diff.",
+		inputSchema: { exclude: z.array(z.enum(["lockfiles"])).optional() },
 		outputSchema: { result: z.unknown() },
 		annotations: READ_ONLY
-	}, async () => {
-		const result = await requestSessionJson(requireInspectSession(), "/api/diff/summary");
+	}, async ({ exclude } = { exclude: void 0 }) => {
+		const session = requireInspectSession();
+		const query = new URLSearchParams();
+		if (exclude?.length) query.set("exclude", exclude.join(","));
+		const result = await requestSessionJson(session, `/api/diff/summary${query.size ? `?${query}` : ""}`);
 		return textResult(JSON.stringify(result), { result });
 	});
 	server.registerTool("diff_files", {
 		title: "Page changed files (bounded)",
-		description: "Return a bounded page of changed-file metadata with an opaque numeric continuation cursor. Works for web, TUI, and GitHub PR sessions.",
+		description: "Return a bounded page of changed-file metadata. Optional path is a git pathspec-ish glob (src/lib/**, **/foo.ts). cursor/nextCursor index the filtered list; each row still has the global file index. Works for web, TUI, and GitHub PR sessions.",
 		inputSchema: {
 			cursor: z.number().int().nonnegative().optional(),
-			limit: z.number().int().positive().max(1e3).optional()
+			limit: z.number().int().positive().max(1e3).optional(),
+			path: z.string().min(1).optional()
 		},
 		outputSchema: { result: z.unknown() },
 		annotations: READ_ONLY
-	}, async ({ cursor = 0, limit = 100 }) => {
-		const result = await requestSessionJson(requireInspectSession(), `/api/diff/files?cursor=${cursor}&limit=${limit}`);
+	}, async ({ cursor = 0, limit = 100, path }) => {
+		const session = requireInspectSession();
+		const query = new URLSearchParams({
+			cursor: String(cursor),
+			limit: String(limit)
+		});
+		if (path) query.set("path", path);
+		const result = await requestSessionJson(session, `/api/diff/files?${query}`);
 		return textResult(JSON.stringify(result), { result });
 	});
 	server.registerTool("diff_hunks", {
 		title: "Page hunk metadata (bounded)",
-		description: "Return bounded hunk metadata for one file index. Pass generation from diff_summary to reject stale navigation. Works for web, TUI, and GitHub PR sessions.",
+		description: "Return bounded hunk metadata for one file. Pass path (glob resolving to exactly one file) or file (global index), not both. Pass generation from diff_summary to reject stale navigation. Works for web, TUI, and GitHub PR sessions.",
 		inputSchema: {
-			file: z.number().int().nonnegative(),
+			file: z.number().int().nonnegative().optional(),
+			path: z.string().min(1).optional(),
 			generation: z.number().int().nonnegative().optional(),
 			cursor: z.number().int().nonnegative().optional(),
 			limit: z.number().int().positive().max(1e3).optional()
 		},
 		outputSchema: { result: z.unknown() },
 		annotations: READ_ONLY
-	}, async ({ file, generation, cursor = 0, limit = 100 }) => {
+	}, async ({ file, path, generation, cursor = 0, limit = 100 }) => {
 		const session = requireInspectSession();
 		const query = new URLSearchParams({
-			file: String(file),
 			cursor: String(cursor),
 			limit: String(limit)
 		});
+		if (file !== void 0) query.set("file", String(file));
+		if (path) query.set("path", path);
 		if (generation !== void 0) query.set("generation", String(generation));
 		const result = await requestSessionJson(session, `/api/diff/hunks?${query}`);
 		return textResult(JSON.stringify(result), { result });
 	});
 	server.registerTool("diff_slice", {
 		title: "Read a bounded diff slice",
-		description: "Read exact logical rows for one file with strict line and byte budgets; use nextRow to continue. Works for web, TUI, and GitHub PR sessions. Prefer this over get_diff.",
+		description: "Read exact logical rows for one file with strict line and byte budgets; use nextRow to continue. Pass path (glob resolving to exactly one file) or file (global index), not both. Works for web, TUI, and GitHub PR sessions. Prefer this over get_diff.",
 		inputSchema: {
-			file: z.number().int().nonnegative(),
+			file: z.number().int().nonnegative().optional(),
+			path: z.string().min(1).optional(),
 			start: z.number().int().nonnegative().optional(),
 			generation: z.number().int().nonnegative().optional(),
 			maxLines: z.number().int().positive().max(1e3).optional(),
@@ -673,23 +701,25 @@ function createMcpServer(options) {
 		},
 		outputSchema: { result: z.unknown() },
 		annotations: READ_ONLY
-	}, async ({ file, start = 0, generation, maxLines = 120, maxBytes = 256 * 1024 }) => {
+	}, async ({ file, path, start = 0, generation, maxLines = 120, maxBytes = 256 * 1024 }) => {
 		const session = requireInspectSession();
 		const query = new URLSearchParams({
-			file: String(file),
 			start: String(start),
 			maxLines: String(maxLines),
 			maxBytes: String(maxBytes)
 		});
+		if (file !== void 0) query.set("file", String(file));
+		if (path) query.set("path", path);
 		if (generation !== void 0) query.set("generation", String(generation));
 		const result = await requestSessionJson(session, `/api/diff/slice?${query}`);
 		return textResult(JSON.stringify(result), { result });
 	});
 	server.registerTool("diff_search", {
 		title: "Search the active diff (bounded)",
-		description: "Search changed paths and content with bounded hits/bytes and generation-safe continuation coordinates. Works for web, TUI, and GitHub PR sessions.",
+		description: "Search changed paths and content with bounded hits/bytes and generation-safe continuation coordinates. Optional path glob limits hits to matching files (in addition to file+row continuation). Works for web, TUI, and GitHub PR sessions.",
 		inputSchema: {
 			query: z.string().min(1),
+			path: z.string().min(1).optional(),
 			generation: z.number().int().nonnegative().optional(),
 			file: z.number().int().nonnegative().optional(),
 			row: z.number().int().nonnegative().optional(),
@@ -698,7 +728,7 @@ function createMcpServer(options) {
 		},
 		outputSchema: { result: z.unknown() },
 		annotations: READ_ONLY
-	}, async ({ query, generation, file = 0, row = 0, limit = 100, maxBytes = 256 * 1024 }) => {
+	}, async ({ query, path, generation, file = 0, row = 0, limit = 100, maxBytes = 256 * 1024 }) => {
 		const session = requireInspectSession();
 		const params = new URLSearchParams({
 			q: query,
@@ -707,6 +737,7 @@ function createMcpServer(options) {
 			limit: String(limit),
 			maxBytes: String(maxBytes)
 		});
+		if (path) params.set("path", path);
 		if (generation !== void 0) params.set("generation", String(generation));
 		const result = await requestSessionJson(session, `/api/diff/search?${params}`);
 		return textResult(JSON.stringify(result), { result });
@@ -1476,6 +1507,375 @@ function createMcpServer(options) {
 			planId: plan.id
 		});
 	});
+	const MOCKUP_SUBMIT_NEXT_ACTION = "Share the mockup URL and park unless the human is reviewing now or asked you to wait. Then call await_mockup_review.";
+	server.registerTool("submit_mockup", {
+		title: "Submit HTML mockup for review",
+		description: "Submit HTML mockup screen(s) for visual review. Pass html or screens[].html inline — do NOT write mockup files into the consumer git tree. Share the URL and park unless asked to wait. Resubmit with mockupId to bump version.",
+		inputSchema: {
+			title: z.string().optional(),
+			html: z.string().optional(),
+			screens: z.array(z.object({
+				id: z.string().optional(),
+				label: z.string().optional(),
+				html: z.string()
+			})).optional(),
+			mockupId: z.string().optional(),
+			source: z.string().optional(),
+			model: z.string().optional()
+		},
+		outputSchema: {
+			mockupId: z.string(),
+			version: z.number(),
+			url: z.string(),
+			nextAction: z.string()
+		},
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		}
+	}, async ({ title, html, screens, mockupId, source, model }) => {
+		const session = requireWebSession();
+		await seedMockupCursor(session, void 0, true);
+		const mockup = await requestSessionJson(session, "/api/mockups", {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				id: mockupId,
+				title,
+				html,
+				screens,
+				source,
+				model
+			})
+		});
+		const url = appendSessionToken(`${session.apiOrigin}/mockup/${mockup.id}`, session.lock.authToken);
+		return textResult(`Submitted mockup ${mockup.id} (v${mockup.version}) at ${url}. ${MOCKUP_SUBMIT_NEXT_ACTION}`, {
+			mockupId: mockup.id,
+			version: mockup.version,
+			url,
+			nextAction: MOCKUP_SUBMIT_NEXT_ACTION
+		});
+	});
+	server.registerTool("await_mockup_review", {
+		title: "Wait for mockup review verdict",
+		description: "Sync wait for a mockup verdict. Prefer async handoff after submit_mockup unless asked to wait.",
+		inputSchema: { timeoutSeconds: z.number().optional() },
+		outputSchema: {
+			status: z.enum(["released", "timeout"]),
+			disposition: z.enum(["continue", "park"]).optional(),
+			decision: z.string().optional(),
+			reviewXml: z.string().optional(),
+			mockup: z.unknown().optional(),
+			round: z.number().optional()
+		},
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false
+		}
+	}, async ({ timeoutSeconds }, extra) => {
+		const session = requireWebSession();
+		const deadline = Date.now() + Math.max(1, timeoutSeconds ?? 25) * 1e3;
+		let sinceRound = await seedMockupCursor(session, extra?.signal);
+		while (Date.now() < deadline) {
+			const remaining = Math.max(deadline - Date.now(), 0);
+			const result = await requestSessionJson(session, `/api/mockup-review/await?timeoutMs=${Math.min(25e3, remaining)}&sinceRound=${sinceRound}`, { signal: extra?.signal });
+			if (result.status === "released" && result.payload) {
+				mockupCursor = {
+					identity: session.identity,
+					round: result.payload.round ?? sinceRound
+				};
+				return textResult(result.payload.reviewXml ?? `decision=${result.payload.decision}`, {
+					status: "released",
+					disposition: "continue",
+					decision: result.payload.decision,
+					reviewXml: result.payload.reviewXml,
+					mockup: result.payload.mockup,
+					round: result.payload.round
+				});
+			}
+			sinceRound = result.round ?? sinceRound;
+			mockupCursor = {
+				identity: session.identity,
+				round: sinceRound
+			};
+		}
+		return textResult("Timeout waiting for mockup review. Park and retry await_mockup_review when the human is ready.", {
+			status: "timeout",
+			disposition: "park",
+			round: sinceRound
+		});
+	});
+	server.registerTool("list_mockups", {
+		title: "List mockups",
+		description: "List submitted HTML mockups for this repository.",
+		inputSchema: {},
+		outputSchema: { mockups: z.array(z.unknown()) },
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, async () => {
+		const all = await requestBaseJson("/api/mockups");
+		return textResult(`${all.length} mockup(s)`, { mockups: all });
+	});
+	server.registerTool("get_mockup", {
+		title: "Get a mockup",
+		description: "Fetch one mockup by id, including comments and screens.",
+		inputSchema: { mockupId: z.string().min(1) },
+		outputSchema: { mockup: z.unknown() },
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, async ({ mockupId }) => {
+		const mockup = await requestBaseJson(`/api/mockups/${encodeURIComponent(mockupId)}`);
+		return textResult(formatMockupReview(mockup), { mockup });
+	});
+	server.registerTool("get_mockup_versions", {
+		title: "List mockup versions",
+		description: "List version snapshots for a mockup.",
+		inputSchema: { mockupId: z.string().min(1) },
+		outputSchema: { versions: z.array(z.unknown()) },
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, async ({ mockupId }) => {
+		const versions = await requestBaseJson(`/api/mockups/${encodeURIComponent(mockupId)}/versions`);
+		return textResult(`${versions.length} version(s)`, { versions });
+	});
+	server.registerTool("get_mockup_version", {
+		title: "Get a mockup version",
+		description: "Fetch one historical mockup version.",
+		inputSchema: {
+			mockupId: z.string().min(1),
+			version: z.number().int().positive()
+		},
+		outputSchema: {
+			version: z.unknown(),
+			mockup: z.unknown()
+		},
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: true
+		}
+	}, async ({ mockupId, version }) => {
+		const data = await requestBaseJson(`/api/mockups/${encodeURIComponent(mockupId)}/versions/${version}`);
+		return textResult(`v${version}`, data);
+	});
+	async function findMockupForComment(commentId) {
+		const mockup = (await requestBaseJson("/api/mockups?include=comments")).find((m) => (m.comments ?? []).some((c) => c.id === commentId));
+		if (!mockup) throw new Error(`Mockup comment ${commentId} was not found.`);
+		return mockup;
+	}
+	server.registerTool("reply_to_mockup_comment", {
+		title: "Reply to a mockup comment",
+		description: "Post an agent reply on a mockup comment thread.",
+		inputSchema: {
+			commentId: z.string().min(1),
+			body: z.string().min(1),
+			model: z.string().optional()
+		},
+		outputSchema: { ok: z.boolean() },
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		}
+	}, async ({ commentId, body, model }) => {
+		const mockup = await findMockupForComment(commentId);
+		await requestBaseJson(`/api/mockups/${encodeURIComponent(mockup.id)}/comments/${encodeURIComponent(commentId)}/replies`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({
+				body,
+				model,
+				role: "agent"
+			})
+		});
+		return textResult(`Replied to ${commentId}`, { ok: true });
+	});
+	server.registerTool("resolve_mockup_comment", {
+		title: "Resolve a mockup comment",
+		description: "Mark a mockup comment thread resolved.",
+		inputSchema: { commentId: z.string().min(1) },
+		outputSchema: { ok: z.boolean() },
+		annotations: {
+			readOnlyHint: false,
+			idempotentHint: false
+		}
+	}, async ({ commentId }) => {
+		const mockup = await findMockupForComment(commentId);
+		await requestBaseJson(`/api/mockups/${encodeURIComponent(mockup.id)}/comments/${encodeURIComponent(commentId)}`, {
+			method: "PUT",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ status: "resolved" })
+		});
+		return textResult(`Resolved ${commentId}`, { ok: true });
+	});
+	server.registerTool("inspect_mockup", {
+		title: "Inspect a mockup (bounded)",
+		description: "Read compact, bounded mockup data. view=summary (headline stats), comments (paged comment list), comment (one thread), screen (screen list). Filter by comment scope: status, screenId, viewport (desktop|tablet|mobile), version. Page with cursor/limit; context=none|anchor|source controls how much anchor data is included. Prefer this over get_mockup, which returns every screen's full HTML.",
+		inputSchema: {
+			mockupId: z.string().min(1),
+			view: z.enum([
+				"summary",
+				"comments",
+				"comment",
+				"screen"
+			]).default("summary"),
+			status: z.enum(["open", "resolved"]).optional(),
+			screenId: z.string().optional(),
+			viewport: z.enum([
+				"desktop",
+				"tablet",
+				"mobile"
+			]).optional(),
+			version: z.number().int().positive().optional(),
+			commentId: z.string().optional(),
+			cursor: z.number().int().nonnegative().optional(),
+			limit: z.number().int().positive().max(200).optional(),
+			context: z.enum([
+				"none",
+				"anchor",
+				"source"
+			]).default("anchor")
+		},
+		outputSchema: { data: z.unknown() },
+		annotations: READ_ONLY
+	}, async ({ mockupId, view, status, screenId, viewport, version, commentId, cursor, limit, context }) => {
+		const params = new URLSearchParams();
+		params.set("view", view);
+		if (status) params.set("status", status);
+		if (screenId) params.set("screen", screenId);
+		if (viewport) params.set("viewport", viewport);
+		if (version !== void 0) params.set("version", String(version));
+		if (commentId) params.set("id", commentId);
+		if (cursor !== void 0) params.set("cursor", String(cursor));
+		if (limit !== void 0) params.set("limit", String(limit));
+		params.set("context", context);
+		const data = await requestBaseJson(`/api/mockups/${encodeURIComponent(mockupId)}/inspect?${params.toString()}`);
+		return textResult(`inspect_mockup ${view} for ${mockupId}`, { data });
+	});
+	server.registerTool("revise_mockup", {
+		title: "Revise a mockup screen",
+		description: "One-screen revision of an HTML mockup. op=upsert adds/replaces a screen (html inline, never files on disk), op=remove deletes a screen, op=patch replaces the first exact occurrence of expectedText with replacement. Every success bumps the mockup version; pass expectedVersion to guard against racing edits (409 version-mismatch on conflict, nothing applied). For revisions touching many screens, resubmit via submit_mockup with the same mockupId instead.",
+		inputSchema: {
+			mockupId: z.string().min(1),
+			op: z.enum([
+				"upsert",
+				"remove",
+				"patch"
+			]),
+			screenId: z.string().min(1),
+			html: z.string().optional(),
+			label: z.string().optional(),
+			expectedText: z.string().optional(),
+			replacement: z.string().optional(),
+			expectedVersion: z.number().int().positive().optional()
+		},
+		outputSchema: {
+			mockupId: z.string(),
+			version: z.number(),
+			screenIds: z.array(z.string()),
+			occurrences: z.number().optional()
+		},
+		annotations: MUTATING
+	}, async ({ mockupId, op, screenId, html, label, expectedText, replacement, expectedVersion }) => {
+		const headers = { "Content-Type": "application/json" };
+		const base = `/api/mockups/${encodeURIComponent(mockupId)}/screens/${encodeURIComponent(screenId)}`;
+		if (op === "upsert") {
+			if (!html) throw new Error("revise_mockup op=upsert requires html");
+			const mockup = await requestBaseJson(base, {
+				method: "PUT",
+				headers,
+				body: JSON.stringify({
+					html,
+					label,
+					expectedVersion
+				})
+			});
+			return textResult(`Upserted screen ${screenId} on ${mockupId} → v${mockup.version}`, {
+				mockupId,
+				version: mockup.version,
+				screenIds: mockup.screens.map((s) => s.id)
+			});
+		}
+		if (op === "remove") {
+			const mockup = await requestBaseJson(`${base}${expectedVersion !== void 0 ? `?expectedVersion=${expectedVersion}` : ""}`, { method: "DELETE" });
+			return textResult(`Removed screen ${screenId} from ${mockupId} → v${mockup.version}`, {
+				mockupId,
+				version: mockup.version,
+				screenIds: mockup.screens.map((s) => s.id)
+			});
+		}
+		if (expectedText === void 0 || replacement === void 0) throw new Error("revise_mockup op=patch requires expectedText and replacement");
+		const data = await requestBaseJson(base, {
+			method: "PATCH",
+			headers,
+			body: JSON.stringify({
+				expectedText,
+				replacement,
+				expectedVersion
+			})
+		});
+		return textResult(`Patched ${screenId} on ${mockupId} (${data.occurrences} exact match(es)) → v${data.mockup.version}`, {
+			mockupId,
+			version: data.mockup.version,
+			screenIds: data.mockup.screens.map((s) => s.id),
+			occurrences: data.occurrences
+		});
+	});
+	const threadOpSchema = z.discriminatedUnion("op", [
+		z.object({
+			op: z.literal("reply"),
+			commentId: z.string().min(1),
+			body: z.string().min(1),
+			role: z.string().optional(),
+			model: z.string().optional()
+		}),
+		z.object({
+			op: z.literal("edit"),
+			commentId: z.string().min(1),
+			replyId: z.string().optional(),
+			body: z.string().min(1)
+		}),
+		z.object({
+			op: z.literal("delete"),
+			commentId: z.string().min(1),
+			replyId: z.string().optional()
+		}),
+		z.object({
+			op: z.literal("resolve"),
+			commentId: z.string().min(1)
+		}),
+		z.object({
+			op: z.literal("unresolve"),
+			commentId: z.string().min(1)
+		})
+	]);
+	server.registerTool("update_mockup_threads", {
+		title: "Update mockup threads (atomic batch)",
+		description: "Atomically apply mockup thread operations: reply (agent answer), edit/delete replies, delete comments, resolve/unresolve. Every operation is validated against the mockup before any is applied — one invalid op aborts the whole batch with no changes. Thread ops never bump the mockup version. Prefer this over single-op reply_to_mockup_comment / resolve_mockup_comment when doing several edits.",
+		inputSchema: {
+			mockupId: z.string().min(1),
+			operations: z.array(threadOpSchema).min(1)
+		},
+		outputSchema: {
+			applied: z.number(),
+			results: z.array(z.unknown())
+		},
+		annotations: MUTATING
+	}, async ({ mockupId, operations }) => {
+		const data = await requestBaseJson(`/api/mockups/${encodeURIComponent(mockupId)}/threads/batch`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body: JSON.stringify({ operations })
+		});
+		return textResult(`Applied ${data.applied} thread op(s) to ${mockupId}`, {
+			applied: data.applied,
+			results: data.results
+		});
+	});
 	server.registerResource("agent-guide", "diffing://agent-guide", {
 		title: "diffing agent guide",
 		description: "Portable quick reference for the native code-review and plan-review workflows.",
@@ -1506,6 +1906,13 @@ This MCP connection is immutably bound to \`${repoRoot}\`.
 4. On \`changes-requested\`, revise and resubmit with the same \`planId\`.
 5. On \`approved\`, proceed; on \`rejected\`, stop.
 
+## Mockup review
+1. Call \`submit_mockup\`, share the URL, and park unless asked to wait; resubmit with the same \`mockupId\` to bump the version.
+2. On resume or sync wait, call \`await_mockup_review\` (or \`list_mockups\` / \`get_mockup\`).
+3. For bounded reads prefer \`inspect_mockup\` (view=summary/comments/comment/screen, filters by status/screenId/viewport/version).
+4. To revise one screen use \`revise_mockup\` (upsert/remove/patch with \`expectedVersion\` guard); thread ops go through atomic \`update_mockup_threads\`.
+5. On \`approved\`, implement; on \`changes-requested\`, revise and resubmit; on \`rejected\`, stop.
+
 ## GitHub PR
 1. In \`gh-pr\` mode call \`gh_overview\`, then the bounded diff tools.
 2. Fetch published discussion with \`gh_list_threads\` (prefer unresolved) and \`gh_list_reviews\`.