gentle-pi 4.2.0 → 4.4.0

package/lib/gentle-design.ts

@@ -0,0 +1,513 @@
+import { join } from "node:path";
+import { designCommentBatchContent, designCommentContent, hasSystemTokens, listDesignEntries, readDesignManifest, resolveSystemBoard, startDesignCanvasServer, type DesignArtboard, type DesignCanvasServer, type DesignCanvasServerOptions, type DesignSessionContent } from "./design-canvas-server.ts";
+import { createDesignCommentStore, DesignCommentsError, type StoredDesignComment } from "./design-comments.ts";
+import { createDesignHandoffStore, DesignHandoffsError, sendDesignHandoff, type DesignHandoff, type DesignHandoffDelivery, type DesignHandoffStatus } from "./design-handoffs.ts";
+import { openInBrowser, type OpenInBrowserResult } from "./design-open-browser.ts";
+import { detectDesignSources, staleDesignSources } from "./design-sources.ts";
+
+// Gentle Design helpers: argument parsing, the designs already written under
+// design/<slug>/design.json, the usage text, the per-session canvas that
+// open/stop drive, and the comments tool. The extension stays a thin wrapper.
+
+export const DESIGN_SKILL_NAME = "gentle-design";
+
+export const DESIGN_SUBCOMMANDS = ["open", "stop", "sync", "implement"] as const;
+export type DesignSubcommand = (typeof DESIGN_SUBCOMMANDS)[number];
+
+export type DesignArgs =
+	| { kind: "usage" }
+	| { kind: "subcommand"; name: DesignSubcommand; rest: string }
+	| { kind: "brief"; brief: string };
+
+export function parseDesignArgs(args: string): DesignArgs {
+	const text = args.trim();
+	if (!text) return { kind: "usage" };
+	const [head = "", ...rest] = text.split(/\s+/);
+	const name = DESIGN_SUBCOMMANDS.find((subcommand) => subcommand === head);
+	return name ? { kind: "subcommand", name, rest: rest.join(" ") } : { kind: "brief", brief: text };
+}
+
+export interface DesignSummary {
+	slug: string;
+	title: string;
+	/** design.json modification time in milliseconds. */
+	mtime: number;
+}
+
+/** Designs under <cwd>/design, through the listing the canvas server uses (same containment rule). */
+export function listDesigns(cwd: string): DesignSummary[] {
+	return listDesignEntries(join(cwd, "design")).map(({ slug, title, mtime }) => ({ slug, title, mtime }));
+}
+
+/** Whether design/system.html exists, so the canvas can open on the system board alone. */
+export function hasSystemBoard(cwd: string): boolean {
+	return resolveSystemBoard(join(cwd, "design")) !== undefined;
+}
+
+export const DESIGN_HELP =
+	"Design HTML artboards with any model: /gentle:design <brief> starts a design run; no arguments open the latest design (or the system board alone) on the local canvas. Subcommands: open [slug], stop, sync (write design/system.md and design/system.html from the project's design sources; the canvas shows that system board first), implement <slug>/<artboard> (hand an artboard off to the project's real stack, also from the canvas Implement button).";
+
+/** What /gentle:design sync asks the skill to do; it rides designRunMessage like a brief. */
+export const DESIGN_SYNC_REQUEST =
+	'sync the project design system: follow "Design system sync" to read the project\'s design sources and write design/system.md and design/system.html.';
+
+export function designUsage(designs: readonly DesignSummary[]): string {
+	const lines = ["Usage: /gentle:design <brief>", "Describe the goal, layout, content, and audience. Directions are written to design/<slug>/."];
+	if (designs.length > 0) {
+		lines.push("", "Designs in this project:");
+		for (const design of designs) lines.push(`  ${design.title} (${design.slug})`);
+	}
+	return lines.join("\n");
+}
+
+/** The message that runs the skill: a skill command when Pi has it loaded, otherwise a pointer to the bundled file. */
+export function designRunMessage(brief: string, skill: { loaded: boolean; path: string }): string {
+	if (skill.loaded) return `/skill:${DESIGN_SKILL_NAME} ${brief}`;
+	return `Read the ${DESIGN_SKILL_NAME} skill at ${skill.path} and follow it for this design brief:\n\n${brief}`;
+}
+
+export type DesignNotice = { message: string; level: "info" | "warning" | "error" };
+
+export type DesignImplementInput = {
+	slug: string;
+	artboard: Pick<DesignArtboard, "file" | "title" | "tradeoff">;
+	/** The design's valid ODD feature document, when design.json links one. */
+	feature?: string;
+	/** Whether design/system.md exists. */
+	systemTokens: boolean;
+	/** The open comments on this artboard. */
+	comments: ReadonlyArray<Pick<StoredDesignComment, "id" | "selector" | "excerpt" | "comment">>;
+};
+
+/** The handoff message for one artboard (S8); the command and the canvas button both send exactly this. */
+export function designImplementMessage(input: DesignImplementInput): string {
+	const path = `design/${input.slug}/${input.artboard.file}`;
+	const lines = [
+		`Implement the design artboard ${path}`,
+		"",
+		`Artboard: ${path}`,
+		`Title: ${input.artboard.title}`,
+	];
+	if (input.artboard.tradeoff) lines.push(`Tradeoff: ${input.artboard.tradeoff}`);
+	lines.push(
+		"",
+		"Implement it in the project's real stack. Use the artboard as the visual spec: map its parts to the project's existing components and styles, and do not copy the artboard HTML verbatim.",
+	);
+	if (input.systemTokens) lines.push("Take colors, typography, spacing, radius and shadows from design/system.md, the project's token source.");
+	if (input.comments.length > 0) {
+		lines.push("", `Open comments on this artboard (${input.comments.length}); apply each one in the implementation:`);
+		input.comments.forEach((comment, index) => {
+			lines.push(
+				`${index + 1}. Comment id: ${comment.id}`,
+				`   Element: ${comment.selector}`,
+				`   Excerpt: ${comment.excerpt ? JSON.stringify(comment.excerpt) : "(none)"}`,
+				"   Comment:",
+				...comment.comment.split("\n").map((line) => `   ${line}`),
+			);
+		});
+		const ids = input.comments.map((comment) => JSON.stringify(comment.id)).join(", ");
+		lines.push(`When they are applied, resolve them with the ${DESIGN_COMMENTS_TOOL_NAME} tool (action "resolve", slug "${input.slug}", ids [${ids}]).`);
+	}
+	lines.push(
+		"",
+		`Report progress with the ${DESIGN_TOOL_NAME} tool: action "handoff", target "${input.slug}/${input.artboard.file}", status "in_progress" when you start; status "implemented" when it is done, with previewUrl set to the running app's loopback URL (localhost, 127.0.0.1 or [::1]) when one is running, so the canvas can compare it with the artboard.`,
+		input.feature
+			? `This design belongs to an ODD feature: track this implementation in ${input.feature} (add or reopen its task there and log this handoff).`
+			: "This design is not linked to an ODD feature document: size it under the project's ODD rules as usual.",
+		"This handoff itself commits nothing.",
+	);
+	return lines.join("\n");
+}
+
+/** The artboard a handoff records in handoffs.json (S15). */
+export type DesignHandoffTarget = { slug: string; file: string; feature?: string };
+
+/** `warnings` name what design.json dropped (an invalid feature link), so the command can report it. */
+export type DesignImplementPlan = { kind: "send"; message: string; warnings: string[]; handoff: DesignHandoffTarget } | { kind: "refuse"; notice: DesignNotice };
+
+function implementTargets(cwd: string): string[] {
+	const targets: string[] = [];
+	for (const design of listDesigns(cwd)) {
+		try {
+			for (const artboard of readDesignManifest(join(cwd, "design"), design.slug).artboards) targets.push(`${design.slug}/${artboard.file}`);
+		} catch {
+			// An unreadable design has no artboard to hand off.
+		}
+	}
+	return targets;
+}
+
+type DesignRefusal = Extract<DesignImplementPlan, { kind: "refuse" }>;
+
+function unknownTarget(cwd: string, reason: string): DesignRefusal {
+	const targets = implementTargets(cwd);
+	if (targets.length === 0) return { kind: "refuse", notice: { message: `${reason}\nNo designs in design/ yet.\n${designUsage([])}`, level: "warning" } };
+	const shown = targets.length > 30 ? [...targets.slice(0, 30), `… ${targets.length - 30} more`] : targets;
+	return { kind: "refuse", notice: { message: `${reason}\nUsage: /gentle:design implement <slug>/<artboard>. Available: ${shown.join(", ")}.`, level: "warning" } };
+}
+
+type ResolvedTarget = { kind: "artboard"; slug: string; artboard: DesignArtboard; feature?: string; warnings: string[] };
+
+/** `<slug>/<file>` checked against the design's manifest; `what` names the action in the refusal. */
+function resolveDesignTarget(cwd: string, target: string, what: string): ResolvedTarget | DesignRefusal {
+	const text = target.trim();
+	const slash = text.indexOf("/");
+	const slug = slash === -1 ? text : text.slice(0, slash);
+	const file = slash === -1 ? "" : text.slice(slash + 1);
+	if (!slug || !file) return unknownTarget(cwd, `Name the artboard to ${what} as <slug>/<artboard>.`);
+	if (!listDesigns(cwd).some((design) => design.slug === slug)) return unknownTarget(cwd, `No design "${slug}" in design/.`);
+	let manifest;
+	try {
+		manifest = readDesignManifest(join(cwd, "design"), slug);
+	} catch (error) {
+		return { kind: "refuse", notice: { message: error instanceof Error ? error.message : String(error), level: "warning" } };
+	}
+	const artboard = manifest.artboards.find((candidate) => candidate.file === file);
+	if (!artboard) return unknownTarget(cwd, `No artboard "${file}" in design/${slug}/design.json.`);
+	const warnings = (manifest.warnings ?? []).map((warning) => `design/${slug}/design.json: ${warning}`);
+	return { kind: "artboard", slug, artboard, feature: manifest.feature, warnings };
+}
+
+/** Validates `<slug>/<file>` against the design's manifest and builds its handoff message. */
+export async function planDesignImplement(cwd: string, target: string): Promise<DesignImplementPlan> {
+	const resolved = resolveDesignTarget(cwd, target, "implement");
+	if (resolved.kind === "refuse") return resolved;
+	const { slug, artboard, feature, warnings } = resolved;
+	const designRoot = join(cwd, "design");
+	let comments: StoredDesignComment[];
+	try {
+		comments = await createDesignCommentStore(designRoot).listOpen(slug, artboard.file);
+	} catch (error) {
+		const reason = error instanceof DesignCommentsError && error.code === "invalid-file"
+			? `design/${slug}/comments.json cannot be read: ${error.message}. Fix the file by hand; it is never overwritten.`
+			: error instanceof Error ? error.message : String(error);
+		return { kind: "refuse", notice: { message: reason, level: "warning" } };
+	}
+	return { kind: "send", message: designImplementMessage({ slug, artboard, feature, systemTokens: hasSystemTokens(designRoot), comments }), warnings, handoff: { slug, file: artboard.file, feature } };
+}
+
+/** A handoffs.json problem as the reason the user or the model reads; a broken file is never overwritten. */
+function handoffsProblem(slug: string, error: unknown): Error {
+	if (error instanceof DesignHandoffsError && error.code === "invalid-file") {
+		return new Error(`design/${slug}/handoffs.json cannot be read: ${error.message}. Fix the file by hand; it is never overwritten.`);
+	}
+	return error instanceof Error ? error : new Error(String(error));
+}
+
+/**
+ * Sends a planned handoff (the command): recorded in handoffs.json as sent and
+ * chosen before `deliver` runs, then marked queued when the delivery says so.
+ */
+export async function sendDesignImplement(cwd: string, plan: Extract<DesignImplementPlan, { kind: "send" }>, deliver: (message: string) => DesignHandoffDelivery | Promise<DesignHandoffDelivery>): Promise<{ queued: boolean }> {
+	const store = createDesignHandoffStore(join(cwd, "design"));
+	return sendDesignHandoff(store, plan.handoff, () => deliver(plan.message)).catch((error: unknown) => {
+		throw error instanceof DesignHandoffsError ? handoffsProblem(plan.handoff.slug, error) : error;
+	});
+}
+
+export interface DesignCanvasDeps {
+	startServer?: (options: DesignCanvasServerOptions) => Promise<DesignCanvasServer>;
+	openBrowser?: (url: string) => Promise<OpenInBrowserResult>;
+}
+
+/**
+ * `url` is set once the canvas shows something; `opened` says whether a browser tab shows it.
+ * `refreshed` is true when an already connected canvas page was told to show and reload it,
+ * so no new tab was opened (S14).
+ */
+export type DesignOpenNotice = DesignNotice & { url?: string; opened?: boolean; refreshed?: boolean };
+
+export interface DesignCanvas {
+	/**
+	 * Shows `slug`, or the most recent design, on the session's canvas server, starting it when needed.
+	 * A running server with a connected canvas page refreshes that page instead of opening the browser.
+	 */
+	open(cwd: string, slug?: string): Promise<DesignOpenNotice>;
+	/** Closes the running server; false when none was running. */
+	stop(): Promise<boolean>;
+	/** The URL the running canvas last showed; undefined when none is running. */
+	url(): string | undefined;
+}
+
+/** The canvas of `slug`, or the root canvas (system board only) when slug is null. */
+function canvasUrl(server: DesignCanvasServer, slug: string | null): string {
+	return new URL(slug === null ? `/${server.token}/` : `/${server.token}/d/${slug}/`, server.url).href;
+}
+
+/**
+ * One canvas server per session; comment messages go to `deliver`, whose failure the server reports as HTTP 500.
+ * For a handoff, `deliver` also answers whether the message was queued behind a busy agent.
+ * A comment with a readable screenshot arrives as text followed by the attached image.
+ */
+export function createDesignCanvas(deliver: (message: DesignSessionContent) => DesignHandoffDelivery | Promise<DesignHandoffDelivery>, deps: DesignCanvasDeps = {}): DesignCanvas {
+	const startServer = deps.startServer ?? startDesignCanvasServer;
+	const openBrowser = deps.openBrowser ?? ((url: string) => openInBrowser(url));
+	let running: { root: string; server: Promise<DesignCanvasServer>; url?: string } | undefined;
+
+	async function stop(): Promise<boolean> {
+		const current = running;
+		running = undefined;
+		if (!current) return false;
+		const server = await current.server.catch(() => undefined);
+		await server?.close();
+		return server !== undefined;
+	}
+
+	async function serverFor(cwd: string): Promise<DesignCanvasServer> {
+		const root = join(cwd, "design");
+		// A new session cwd means a different design root, so the old server goes.
+		if (running && running.root !== root) await stop();
+		if (!running) {
+			const server = startServer({
+				designRoot: root,
+				onComment: async (comment) => { await deliver(designCommentContent(comment)); },
+				onComments: async (batch) => { await deliver(designCommentBatchContent(batch)); },
+				// The same plan as /gentle:design implement, so both send identical text; the server
+				// has already recorded the handoff, and this answers whether it was queued.
+				onImplement: async ({ slug, file }) => {
+					const plan = await planDesignImplement(cwd, `${slug}/${file}`);
+					if (plan.kind === "refuse") throw new Error(plan.notice.message);
+					return deliver(plan.message);
+				},
+			});
+			running = { root, server };
+			server.catch(() => { if (running?.server === server) running = undefined; });
+		}
+		return running.server;
+	}
+
+	async function open(cwd: string, requested?: string): Promise<DesignOpenNotice> {
+		const designs = listDesigns(cwd);
+		// With only design/system.html, the canvas opens on the system board alone (L14).
+		const systemOnly = designs.length === 0 && requested === undefined && hasSystemBoard(cwd);
+		if (designs.length === 0 && !systemOnly) {
+			return { message: `No designs in design/ yet.\n${designUsage([])}`, level: "warning" };
+		}
+		const slug = systemOnly ? null : requested ?? designs[0].slug;
+		if (slug !== null && !designs.some((design) => design.slug === slug)) {
+			return { message: `No design "${slug}" in design/. Available: ${designs.map((design) => design.slug).join(", ")}.`, level: "warning" };
+		}
+		// Only a server that was already running can have a canvas page of its own connected.
+		const reused = running?.root === join(cwd, "design");
+		let server: DesignCanvasServer;
+		try {
+			server = await serverFor(cwd);
+		} catch (error) {
+			return { message: `The design canvas could not start: ${error instanceof Error ? error.message : String(error)}`, level: "error" };
+		}
+		const url = canvasUrl(server, slug);
+		if (running) running.url = url;
+		if (reused && server.connectedClients() > 0 && server.show(slug) > 0) {
+			return { message: `Design canvas refreshed: ${url}`, level: "info", url, opened: true, refreshed: true };
+		}
+		const result = await openBrowser(url);
+		if (result.opened) return { message: `Design canvas: ${url}`, level: "info", url, opened: true };
+		const reason = result.error ? ` (${result.error})` : "";
+		return { message: `Design canvas: ${url}\nThe browser could not be opened${reason}. Open the URL manually.`, level: "warning", url, opened: false };
+	}
+
+	return { open, stop, url: () => running?.url };
+}
+
+export const DESIGN_COMMENTS_TOOL_NAME = "gentle_design_comments";
+
+export type DesignCommentsToolParams = { action: "list" | "resolve"; slug?: string; file?: string; ids?: string[] };
+export type DesignCommentsToolResult = { text: string; details: { comments: Array<StoredDesignComment & { slug: string }> } | { slug: string; resolved: string[]; unknown: string[] } };
+
+function describeComment(slug: string, comment: StoredDesignComment): string[] {
+	return [
+		`- [${comment.id}] design/${slug}/${comment.file}`,
+		`  Element: ${comment.selector}`,
+		`  Excerpt: ${comment.excerpt ? JSON.stringify(comment.excerpt) : "(none)"}`,
+		`  Comment: ${comment.comment.split("\n").join("\n           ")}`,
+		...(comment.screenshot ? [`  Screenshot: design/${slug}/${comment.screenshot} (open it with the read tool)`] : []),
+	];
+}
+
+/** list: open comments (all designs, or one design and artboard); resolve: mark ids of one design resolved. */
+export async function runDesignCommentsTool(cwd: string, params: DesignCommentsToolParams): Promise<DesignCommentsToolResult> {
+	const store = createDesignCommentStore(join(cwd, "design"));
+	const failure = (slug: string, error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-file"
+		? new Error(`design/${slug}/comments.json cannot be read: ${error.message}. Fix the file by hand; it is never overwritten.`)
+		: error;
+	if (params.action === "resolve") {
+		if (typeof params.slug !== "string" || !params.slug) throw new Error("resolve needs the design slug.");
+		const ids = params.ids ?? [];
+		if (ids.length === 0) throw new Error("resolve needs at least one comment id in ids.");
+		const { updated, unknown } = await store.setStatus(params.slug, ids, "resolved").catch((error: unknown) => { throw failure(params.slug!, error); });
+		const resolved = updated.map((comment) => comment.id);
+		const lines = [`Resolved ${resolved.length} comment${resolved.length === 1 ? "" : "s"} in design/${params.slug}${resolved.length ? `: ${resolved.join(", ")}` : ""}.`];
+		if (unknown.length) lines.push(`Unknown ids: ${unknown.join(", ")}.`);
+		return { text: lines.join("\n"), details: { slug: params.slug, resolved, unknown } };
+	}
+	const slugs = params.slug ? [params.slug] : listDesigns(cwd).map((design) => design.slug);
+	const found: Array<StoredDesignComment & { slug: string }> = [];
+	const problems: string[] = [];
+	for (const slug of slugs) {
+		try {
+			for (const comment of await store.listOpen(slug, params.file)) found.push({ slug, ...comment });
+		} catch (error) {
+			// One design's broken file must not hide the others, unless it was asked for by name.
+			if (params.slug) throw failure(slug, error);
+			problems.push(`design/${slug}/comments.json: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	const scope = params.slug ? `design/${params.slug}${params.file ? `/${params.file}` : ""}` : "design/";
+	const lines = found.length === 0
+		? [`No open comments in ${scope}.`]
+		: [`Open design comments in ${scope} (${found.length}):`, ...found.flatMap((comment) => describeComment(comment.slug, comment)), "", `After applying a comment, resolve it with ${DESIGN_COMMENTS_TOOL_NAME} (action "resolve", slug, ids).`];
+	if (problems.length) lines.push("", "Unreadable comment files:", ...problems.map((problem) => `- ${problem}`));
+	return { text: lines.join("\n"), details: { comments: found } };
+}
+
+export const DESIGN_TOOL_NAME = "gentle_design";
+
+/** Appended to the system prompt while the gentle-design skill is available (S11). */
+export const DESIGN_PROMPT_HINT = [
+	`Gentle Design: any request for a UI design, mockup, screen, landing page or visual directions uses the ${DESIGN_SKILL_NAME} skill by default; read the skill first when it is not loaded.`,
+	`Before designing, call the ${DESIGN_TOOL_NAME} tool (action "list"); when the project has design sources but no design/system.md, run the skill's design system sync first.`,
+	`After writing or changing a design, open or refresh it on the canvas with the ${DESIGN_TOOL_NAME} tool (action "open" with the slug), unless the user said not to.`,
+	"Designs stay under design/<slug>/.",
+].join("\n");
+
+export type DesignToolParams = {
+	action: "list" | "open" | "stop" | "implement" | "handoff";
+	slug?: string;
+	target?: string;
+	/** handoff only. */
+	status?: string;
+	note?: string;
+	previewUrl?: string;
+};
+/** How many design source paths list names; `total` still counts them all. */
+const LISTED_DESIGN_SOURCES = 20;
+
+export type DesignSystemState = { exists: boolean; file: "design/system.md"; staleSources: string[] };
+export type DesignToolDetails =
+	| {
+		designs: Array<{ slug: string; title: string; artboards: Array<{ file: string; title: string }>; error?: string }>;
+		systemBoard: boolean;
+		designSources: { paths: string[]; total: number };
+		system: DesignSystemState;
+		canvas: { running: boolean; url?: string };
+	}
+	| { url: string; opened: boolean; refreshed?: true }
+	| { stopped: boolean }
+	| { target: string; warnings: string[] }
+	| { target: string; chosen: string | null; handoff: DesignHandoff };
+/** `texts` become the tool's content parts; a refusal throws, so Pi flags the result as an error. */
+export type DesignToolResult = { texts: string[]; details: DesignToolDetails };
+
+function handoffState(entry: DesignHandoff): string {
+	const status = entry.status === "in_progress" ? "in progress" : entry.status;
+	const parts = [`handoff ${status}${entry.status === "sent" && entry.queued ? ", queued" : ""}`];
+	if (entry.previewUrl) parts.push(`preview ${entry.previewUrl}`);
+	return parts.join("; ");
+}
+
+type ListedDesign = {
+	slug: string;
+	title: string;
+	artboards: Array<{ file: string; title: string }>;
+	error?: string;
+	/** Present only when the design has handoff records (S15). */
+	chosen?: string | null;
+	handoffs?: Record<string, DesignHandoff>;
+	handoffsError?: string;
+};
+
+async function listDesignTool(cwd: string, canvas: DesignCanvas): Promise<DesignToolResult> {
+	const designRoot = join(cwd, "design");
+	const handoffStore = createDesignHandoffStore(designRoot);
+	const designs: ListedDesign[] = [];
+	for (const { slug, title } of listDesigns(cwd)) {
+		let design: ListedDesign;
+		try {
+			const artboards = readDesignManifest(designRoot, slug).artboards.map(({ file, title }) => ({ file, title }));
+			design = { slug, title, artboards };
+		} catch (error) {
+			design = { slug, title, artboards: [], error: error instanceof Error ? error.message : String(error) };
+		}
+		try {
+			const document = await handoffStore.read(slug);
+			if (document.chosen !== null || Object.keys(document.handoffs).length > 0) {
+				design.chosen = document.chosen;
+				design.handoffs = document.handoffs;
+			}
+		} catch (error) {
+			design.handoffsError = error instanceof Error ? error.message : String(error);
+		}
+		designs.push(design);
+	}
+	const systemBoard = hasSystemBoard(cwd);
+	const url = canvas.url();
+	const lines = designs.length === 0 ? ["No designs in design/ yet."] : [`Designs in design/ (${designs.length}):`];
+	for (const design of designs) {
+		lines.push(`- ${design.slug}: ${design.title}${design.error ? ` (design.json cannot be read: ${design.error})` : ""}`);
+		if (design.chosen) lines.push(`  Chosen: ${design.chosen} (the other artboards are alternatives)`);
+		if (design.handoffsError) lines.push(`  handoffs.json cannot be read: ${design.handoffsError}`);
+		for (const artboard of design.artboards) {
+			const entry = design.handoffs && Object.hasOwn(design.handoffs, artboard.file) ? design.handoffs[artboard.file] : undefined;
+			lines.push(`  - ${artboard.file}: ${artboard.title}${entry ? ` (${handoffState(entry)})` : ""}`);
+		}
+	}
+	lines.push(systemBoard ? "System board: design/system.html (shown first on the canvas)." : "No system board (design/system.html).");
+	const sources = detectDesignSources(cwd);
+	const exists = hasSystemTokens(designRoot);
+	const system: DesignSystemState = { exists, file: "design/system.md", staleSources: exists ? staleDesignSources(cwd, sources) : [] };
+	lines.push(sources.length === 0 ? "Design sources: none detected." : `Design sources (${sources.length}): ${capped(sources)}`);
+	if (!system.exists) lines.push(`Design system: no design/system.md.${sources.length > 0 ? " Run the skill's Design system sync before designing." : ""}`);
+	else if (system.staleSources.length === 0) lines.push("Design system: design/system.md is up to date.");
+	else {
+		const count = system.staleSources.length;
+		lines.push(`Design system: design/system.md is older than ${count} source${count === 1 ? "" : "s"} changed after it: ${capped(system.staleSources)}. Say its tokens may be outdated and offer to sync again before designing.`);
+	}
+	lines.push(url ? `Canvas: running at ${url}` : "Canvas: not running.");
+	const designSources = { paths: sources.slice(0, LISTED_DESIGN_SOURCES), total: sources.length };
+	return { texts: [lines.join("\n")], details: { designs, systemBoard, designSources, system, canvas: url ? { running: true, url } : { running: false } } };
+}
+
+function capped(paths: readonly string[]): string {
+	const shown = paths.slice(0, LISTED_DESIGN_SOURCES);
+	if (paths.length > shown.length) shown.push(`… ${paths.length - shown.length} more`);
+	return shown.join(", ");
+}
+
+/** The handoff action: the agent's progress on one artboard, validated by the manifest and the store. */
+async function handoffTool(cwd: string, params: DesignToolParams): Promise<DesignToolResult> {
+	if (params.status !== "in_progress" && params.status !== "implemented") throw new Error('handoff needs status "in_progress" or "implemented".');
+	const status: Exclude<DesignHandoffStatus, "sent"> = params.status;
+	const resolved = resolveDesignTarget(cwd, params.target ?? "", "report on");
+	if (resolved.kind === "refuse") throw new Error(resolved.notice.message);
+	const { slug, artboard } = resolved;
+	const store = createDesignHandoffStore(join(cwd, "design"));
+	const handoff = await store.setStatus(slug, artboard.file, status, { note: params.note, previewUrl: params.previewUrl }).catch((error: unknown) => { throw handoffsProblem(slug, error); });
+	const { chosen } = await store.read(slug).catch((error: unknown) => { throw handoffsProblem(slug, error); });
+	const path = `design/${slug}/${artboard.file}`;
+	const lines = [`Handoff of ${path}: ${status === "in_progress" ? "in progress" : "implemented"}.${chosen === artboard.file ? ` It is the chosen artboard of design/${slug}.` : ""}`];
+	if (handoff.previewUrl) lines.push(`Preview: ${handoff.previewUrl}${status === "implemented" ? " (the canvas offers Compare)" : ""}.`);
+	return { texts: [lines.join("\n")], details: { target: `${slug}/${artboard.file}`, chosen, handoff } };
+}
+
+/** The gentle_design tool: the /gentle:design actions on the session's canvas, without sending a user message. */
+export async function runDesignTool(cwd: string, params: DesignToolParams, canvas: DesignCanvas): Promise<DesignToolResult> {
+	if (params.action === "handoff") return handoffTool(cwd, params);
+	if (params.action === "list") return listDesignTool(cwd, canvas);
+	if (params.action === "stop") {
+		const stopped = await canvas.stop();
+		return { texts: [stopped ? "Design canvas stopped." : "No design canvas is running."], details: { stopped } };
+	}
+	if (params.action === "open") {
+		const notice = await canvas.open(cwd, params.slug || undefined);
+		if (notice.url === undefined) throw new Error(notice.message);
+		const details = notice.refreshed ? { url: notice.url, opened: true, refreshed: true as const } : { url: notice.url, opened: notice.opened === true };
+		return { texts: [notice.message], details };
+	}
+	const target = params.target ?? "";
+	const plan = await planDesignImplement(cwd, target);
+	if (plan.kind === "refuse") throw new Error(plan.notice.message);
+	// The model follows this handoff in its current run, so it is never queued.
+	await createDesignHandoffStore(join(cwd, "design")).markSent(plan.handoff.slug, plan.handoff.file, { queued: false, feature: plan.handoff.feature })
+		.catch((error: unknown) => { throw handoffsProblem(plan.handoff.slug, error); });
+	return { texts: [plan.message, ...plan.warnings.map((warning) => `Warning: ${warning}`)], details: { target: target.trim(), warnings: plan.warnings } };
+}