proto-plugin 0.1.1 → 0.1.3

package/src/lib/prototypes/comment-storage-setup-prompt.ts

@@ -0,0 +1,124 @@
+export const COMMENT_STORAGE_NOT_CONFIGURED_MESSAGE =
+  "Comment storage is not configured. Set Upstash Redis and Vercel Blob env vars.";
+
+export function isCommentStorageSetupError(message: string | null | undefined): boolean {
+  if (!message) return false;
+  return (
+    message.includes("not configured") ||
+    message.includes("Upstash Redis") ||
+    message.includes("Vercel Blob") ||
+    message.includes("KV_REST") ||
+    message.includes("BLOB_")
+  );
+}
+
+export type CommentStorageSetupPromptOptions = {
+  vercelProjectName?: string;
+  vercelTeamSlug?: string;
+};
+
+export function buildCommentStorageSetupPrompt({
+  vercelProjectName = "proto-plugin",
+  vercelTeamSlug = "maayan-alberts-projects",
+}: CommentStorageSetupPromptOptions = {}): string {
+  const upstashTermsUrl = `https://vercel.com/${vercelTeamSlug}/~/integrations/accept-terms/upstash?source=cli`;
+
+  return [
+    "Set up prototype storage (Upstash Redis + Vercel Blob) for this host app. **Do every step yourself** — the user should not run commands manually.",
+    "",
+    "## Your job",
+    "Provision both stores on Vercel, pull env vars locally, restart dev, and confirm Comments + gallery storage work. Only stop to ask the user when a browser step is unavoidable (marketplace terms).",
+    "",
+    "## Vercel project",
+    `- Project: \`${vercelProjectName}\``,
+    `- Team: \`${vercelTeamSlug}\``,
+    "",
+    "## Step 1 — Link the repo (skip if \`.vercel/project.json\` exists)",
+    "```bash",
+    `npx vercel link --yes --project ${vercelProjectName} --scope ${vercelTeamSlug}`,
+    "```",
+    "",
+    "## Step 2 — Accept Upstash marketplace terms (browser — ask user once)",
+    "If `vercel integration add` returns `integration_terms_acceptance_required`, send the user this URL and wait for confirmation before retrying:",
+    upstashTermsUrl,
+    "",
+    "## Step 3 — Install Upstash Redis",
+    "```bash",
+    "npx vercel integration add upstash/upstash-kv -m primaryRegion=sfo1 -p free -n proto-plugin-redis",
+    "```",
+    "",
+    "Connect to **development**, **preview**, and **production** (default when prompted with `--yes`).",
+    "",
+    "## Step 4 — Create Vercel Blob store (required)",
+    "Gallery screenshots need Blob — not optional.",
+    "",
+    "```bash",
+    "npx vercel blob create-store proto-plugin-blob --access public -y -e development -e preview -e production",
+    "```",
+    "",
+    "If a store already exists, connect it to this project from Vercel → Storage, or use `vercel blob list-stores` and ensure `BLOB_READ_WRITE_TOKEN` is on the project.",
+    "",
+    "## Step 5 — Verify env vars exist on Vercel",
+    "```bash",
+    "npx vercel env ls",
+    "npx vercel integration list",
+    "```",
+    "",
+    "Required before continuing:",
+    "- `KV_REST_API_URL`",
+    "- `KV_REST_API_TOKEN`",
+    "- `BLOB_READ_WRITE_TOKEN`",
+    "",
+    "If `vercel env pull` previously only gave `VERCEL_OIDC_TOKEN`, that is CLI auth — not storage. Storage vars appear only after steps 3–4 succeed.",
+    "",
+    "## Step 6 — Pull env vars locally (required — do not skip)",
+    "`.env.local` holds host-only values like `SOURCE_PATH`. **Never** pull into `.env.local` — it overwrites that file.",
+    "",
+    "Pull development env vars into a separate file:",
+    "",
+    "```bash",
+    "npx vercel env pull .env.development.local -y",
+    "```",
+    "",
+    "Next.js loads both `.env.local` and `.env.development.local` in development.",
+    "",
+    "After pull, confirm `.env.development.local` contains `KV_REST_*` and `BLOB_READ_WRITE_TOKEN`. Leave `SOURCE_PATH` in `.env.local` untouched.",
+    "",
+    "## Step 7 — Restart dev and verify",
+    "```bash",
+    "pnpm dev",
+    "```",
+    "",
+    "Then confirm storage is configured:",
+    "",
+    "```bash",
+    "curl -s http://localhost:1985/api/prototypes/storage-status",
+    "```",
+    "",
+    "Expect:",
+    "- `comments.configured: true`",
+    "- `gallery.storageConfigured: true`",
+    "",
+    "Open a prototype → Comments sidebar should load with no setup prompt (empty list is fine).",
+    "",
+    "## Required env vars (all three)",
+    "| Var | Purpose |",
+    "| --- | --- |",
+    "| `KV_REST_API_URL` | Upstash Redis — comments, change log, gallery metadata |",
+    "| `KV_REST_API_TOKEN` | Upstash Redis token |",
+    "| `BLOB_READ_WRITE_TOKEN` | Vercel Blob — gallery screenshot uploads |",
+    "",
+    "Either `KV_*` or `UPSTASH_REDIS_REST_*` works — the app normalizes both.",
+    "",
+    "## Reference",
+    "- Env template: `.env.example`",
+    "- Storage status: `packages/prototype/src/server/prototype-storage-status-route.ts`",
+    "- Redis client: `packages/prototype/src/server/redis/client.ts`",
+  ].join("\n");
+}
+
+export function buildCommentStorageSetupCopyText(
+  options: CommentStorageSetupPromptOptions = {},
+): string {
+  return buildCommentStorageSetupPrompt(options);
+}

package/src/lib/prototypes/create-prototype-prompt.ts

@@ -0,0 +1,96 @@
+export function suggestPrototypeSlug(title: string): string {
+  return title
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export function buildCreatePrototypePrompt({
+  title,
+  description,
+  origin = "http://localhost:3003",
+}: {
+  title: string;
+  description: string;
+  origin?: string;
+}): string {
+  const trimmedTitle = title.trim();
+  const trimmedDescription = description.trim();
+  const suggestedSlug = suggestPrototypeSlug(trimmedTitle);
+  const galleryUrl = `${origin}/`;
+
+  const lines = [
+    `Create a new prototype: "${trimmedTitle}".`,
+    "",
+    "## Brief",
+    `- Title: ${trimmedTitle}`,
+    `- Description: ${trimmedDescription}`,
+    `- Suggested slug: \`${suggestedSlug || "my-prototype"}\` (pick a unique kebab-case slug if taken)`,
+    "",
+    "## Source app",
+    "Draw from the **source application** (linked via `SOURCE_PATH` / `pnpm link-source`) — not from other prototypes in this gallery. Replicate the page or feature named in the brief **exactly**: layout, spacing, typography, components, empty/loading/error states, and interactions. Match the source side-by-side; do not approximate or invent alternate UI.",
+    "",
+    "## Gallery",
+    galleryUrl,
+  ];
+
+  lines.push(
+    "",
+    "## Preview states (required — do not skip)",
+    "Before building UI, list every distinct mode reviewers must open directly from the State picker and `/prototypes/<slug>/states` map. Include modes implied by the brief and source page, for example:",
+    "- Primary tabs, steps, or wizard stages",
+    "- Empty, loading, and error branches",
+    "- Filter bars, preset filters, active filter chips, and add-filter popovers",
+    "- Modals, drawers, and overlay branches",
+    "- View toggles (list vs calendar, grid vs table, etc.)",
+    "",
+    "Each mode gets one registry entry in `*-preview-states.ts` with matching `liveState` in `createLiveStateForPreview`. Wire the full stack in the same pass as the UI — not as a follow-up.",
+    "",
+    "## Instructions",
+    "Follow AGENTS.md → New prototype checklist and **Live state & preview states (mandatory)**.",
+    "",
+    "1. Find the source page/feature in the linked source app, read it fully, and confirm side-by-side visual parity before finishing.",
+    "2. Create `src/prototypes/<slug>/` with a default export page component.",
+    "3. Add `component-ids.ts` — exhaustive static id list + `dynamicPrefixes`.",
+    "4. Register in `prototype.config.ts` with `componentRegistry`.",
+    "5. Wrap every UI component in `PrototypeComponent` / `PrototypeControl`.",
+    "6. Define typed `liveState`, wire `usePrototypeComments(liveState, onRestore)`, and derive all preview-relevant UI from `liveState`.",
+    "7. Add preview states in the same change (mandatory for feature pages — see **Preview states** above):",
+    "   - `src/prototypes/<slug>/_components/<slug>-preview-states.ts` — `definePreviewStateRegistry`, `createLiveStateForPreview`, one entry per mode",
+    "   - `src/prototypes/<slug>/_components/<slug>-preview-state-select.tsx` — wire `ControlsPanelSelect` with `appearance=\"menuList\"` into the review toolbar via `setTweaksContent` (no floating mini-pill on the page)",
+    "   - `src/prototypes/<slug>/_components/<slug>-state-canvas-config.tsx` — wireframes from the same registry",
+    "   - `src/prototypes/<slug>/state-map-page.tsx` — full-page state map at `/prototypes/<slug>/states`",
+    "   - `stateMapComponent` on the prototype entry in `prototype.config.ts`",
+    "   - In `index.tsx`: `review.setStateCanvasConfig(build…StateCanvasConfig(onStateSelect))` in an effect — pass only the select handler, not `liveState` or the current preview mode (state map is stateless; always light mode)",
+    "8. Run `pnpm verify:prototype-ids` and `pnpm verify:prototype-preview-states`.",
+    "9. Capture a screenshot under `public/prototypes/screenshots/`; share via `pnpm share-prototype <slug>`.",
+    "",
+    "Reference: `src/prototypes/booking-flow/` (`index.tsx`, `*-preview-states.ts`, `*-preview-state-select.tsx`, `*-state-canvas-config.tsx`, `state-map-page.tsx`, `prototype.config.ts` → `stateMapComponent`).",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildCreatePrototypeCopyText({
+  title,
+  description,
+  origin = "http://localhost:3003",
+}: {
+  title: string;
+  description: string;
+  origin?: string;
+}): string {
+  const trimmedTitle = title.trim();
+  const trimmedDescription = description.trim();
+  const brief = [`Title: ${trimmedTitle}`, `Description: ${trimmedDescription}`].join(
+    "\n",
+  );
+  const prompt = buildCreatePrototypePrompt({
+    title: trimmedTitle,
+    description: trimmedDescription,
+    origin,
+  });
+
+  return `${brief}\n\n---\n\n${prompt}`;
+}

package/src/lib/prototypes/create-prototype-registry.ts

@@ -40,6 +40,11 @@ export function createPrototypeRegistry(config: PrototypeConfig) {
         ?.component;
     },
 
+    getPrototypeStateMapComponent(slug: string) {
+      return requireConfig().prototypes.find((prototype) => prototype.slug === slug)
+        ?.stateMapComponent;
+    },
+
     getPrototypeComponentRegistryForSlug(
       slug: string,
     ): PrototypeComponentRegistry | undefined {

package/src/lib/prototypes/design-exploration-types.ts

@@ -1,14 +1,16 @@
 import type { ReactNode } from "react";
 
+export type DesignExplorationRationale = {
+  good: string;
+  bad: string;
+};
+
 export type DesignExplorationVariantOption<TVariant extends string> = {
   value: TVariant;
   label: string;
   hint?: string;
-};
-
-export type DesignExplorationRationale = {
-  good: string;
-  bad: string;
+  /** One-line pros/cons shown under the variant title in the design brief. */
+  rationale?: DesignExplorationRationale;
 };
 
 export type DesignExplorationBrief = {
@@ -47,26 +49,82 @@ export type DesignExplorationVariantsSection = {
   description?: string;
 };
 
-/** Persists to KV via `storageKeyPrefix` — use `useDesignExplorationDefault`. */
+/** Pre-exploration UI — always pinned at the bottom of the variant list. */
+export type DesignExplorationBaselineOption<TVariant extends string> = {
+  value: TVariant;
+  /** Shown in the brief and tabs. Default: "Original". */
+  label?: string;
+  hint?: string;
+  rationale?: DesignExplorationRationale;
+};
+
 export type DesignExplorationConfig<TVariant extends string> = {
   componentIdPrefix: string;
   variantTabsIdPrefix: string;
   storageKeyPrefix: string;
   variant: TVariant;
   onVariantChange: (variant: TVariant) => void;
+  /** Layout directions being explored — newest first. Excludes baseline. */
   options: DesignExplorationVariantOption<TVariant>[];
-  rationale: Record<TVariant, DesignExplorationRationale>;
   renderers: Record<TVariant, () => ReactNode>;
   brief: DesignExplorationBrief;
   context?: DesignExplorationContext;
   mobbin?: DesignExplorationMobbin;
   variantsSection?: DesignExplorationVariantsSection;
+  /**
+   * UI state before this exploration was added. Rendered last in the brief
+   * and tabs; deduped from `options` when the same value appears there.
+   */
+  baseline: DesignExplorationBaselineOption<TVariant>;
+  /**
+   * Default variant stored in the codebase (e.g. `DEFAULT_*_VARIANT`). Marks
+   * the "Default" option in the design brief. Falls back to the first option.
+   */
+  defaultVariant?: TVariant;
   /** Label for prev/next variant tab buttons. Default: "variant". */
   variantTabAriaLabel?: string;
-  /** Path to design exploration config — included in reset-brief copy prompt. */
+  /** Path to design exploration config — included in copy prompts. */
   briefConfigFilePath?: string;
 };
 
+export const DESIGN_EXPLORATION_BASELINE_LABEL = "Original";
+
+export function resolveDesignExplorationBaselineOption<
+  TVariant extends string,
+>(
+  baseline: DesignExplorationBaselineOption<TVariant>,
+): DesignExplorationVariantOption<TVariant> {
+  return {
+    value: baseline.value,
+    label: baseline.label ?? DESIGN_EXPLORATION_BASELINE_LABEL,
+    hint: baseline.hint,
+    rationale: baseline.rationale,
+  };
+}
+
+/** Exploration options only — baseline value removed when duplicated. */
+export function getDesignExplorationVariantOptions<
+  TVariant extends string,
+>(
+  options: DesignExplorationVariantOption<TVariant>[],
+  baseline: DesignExplorationBaselineOption<TVariant>,
+): DesignExplorationVariantOption<TVariant>[] {
+  return options.filter((option) => option.value !== baseline.value);
+}
+
+/** Exploration options plus baseline pinned at the bottom (for tabs / cycling). */
+export function getDesignExplorationDisplayOptions<
+  TVariant extends string,
+>(
+  options: DesignExplorationVariantOption<TVariant>[],
+  baseline: DesignExplorationBaselineOption<TVariant>,
+): DesignExplorationVariantOption<TVariant>[] {
+  return [
+    ...getDesignExplorationVariantOptions(options, baseline),
+    resolveDesignExplorationBaselineOption(baseline),
+  ];
+}
+
 /** Plain-text copy of the overview fields as shown in the design brief modal. */
 export function buildBriefOverviewCopyText(
   title: string,
@@ -84,11 +142,13 @@ export function buildCreateDesignExplorationPrompt({
   existingExplorations = [],
   origin = "http://localhost:3003",
   briefText,
+  includeMobbin = true,
 }: {
   slug: string;
   existingExplorations?: Array<{ id: string; label: string }>;
   origin?: string;
   briefText?: string;
+  includeMobbin?: boolean;
 }): string {
   const prototypeUrl = `${origin}/prototypes/${slug}`;
   const variantSetsRegistrar = `src/prototypes/${slug}/_components/*-variant-sets.tsx`;
@@ -122,6 +182,27 @@ export function buildCreateDesignExplorationPrompt({
     "## Prototype",
     `- Slug: \`${slug}\``,
     `- Preview: ${prototypeUrl}`,
+  );
+
+  if (includeMobbin) {
+    lines.push(
+      "",
+      "## Mobbin references",
+      "Before building variants, pull real-world reference screens from Mobbin. Use the Mobbin MCP `search_screens` tool when available; otherwise search on mobbin.com.",
+      "",
+      "1. Search for **3–5 screens** that match the brief and the distinct layout directions you plan to explore. Prefer specific UI descriptions (e.g. \"settings page with profile photo and bio field\") over vague style words.",
+      "2. Pick references that clarify layout, hierarchy, and copy patterns — not just visual polish.",
+      "3. In `*-design-exploration-config.tsx`, add a `mobbin` block:",
+      "   - `references`: `{ id, appName, imageUrl, mobbinUrl, relevance, variantHint? }[]` — use each screen UUID as `id`",
+      "   - `imagePathForReference`: `(id) => \\`/prototypes/mobbin-references/${id}.webp\\``",
+      "4. Register `mobbin-inspiration-gallery` and `mobbin-inspiration-gallery.` in `component-ids.ts` (or pass a custom `mobbinGalleryId` to `PrototypeVariantExplorer`).",
+      "5. Download local assets: `pnpm download-mobbin-references -- --ids=<comma-separated-ids>`",
+      "",
+      "Reference: `src/prototypes/proto-partner-page/_components/invite-copy-design-exploration-config.tsx`.",
+    );
+  }
+
+  lines.push(
     "",
     "## Instructions",
     "Follow AGENTS.md → Design exploration. Do not register a new prototype slug — add a design exploration variant set on this page.",
@@ -129,7 +210,12 @@ export function buildCreateDesignExplorationPrompt({
     "1. Add `{ id, label, previewMode? }` to the variant sets registrar (e.g. `" +
       variantSetsRegistrar +
       "`).",
-    "2. Create `*-design-exploration-config.tsx` with options, rationale, renderers, and brief defaults.",
+    "   - Give this exploration a **distinct Lucide icon** in the review sidebar: add a `{ test, icon }` rule to `packages/prototype/src/lib/prototypes/variant-set-lucide-icon.tsx` that matches its id or label. Place the rule **before** broad matchers (e.g. `/mobile/i`) so it wins. Pick an icon that fits the topic and avoid reusing icons already assigned to other explorations on this prototype — do not leave new explorations on the default `LayoutGrid` fallback or the generic `Smartphone` icon shared by unrelated mobile explorations.",
+    `2. Create \`*-design-exploration-config.tsx\` with options, renderers, brief defaults, baseline,${includeMobbin ? " and the Mobbin references above" : ""}.`,
+    "   - `baseline`: the UI before this exploration existed — `{ value, label?, hint? }`, pinned at the bottom of the variant list.",
+    "   - `options`: layout directions to compare — exclude the baseline value when possible.",
+    "   - Build renderers with `buildDesignExplorationRenderers(options, (variant) => …, baseline)` — one preview per option plus baseline.",
+    "   - Wrap overlay-style variants in `DesignExplorationVariantPreviewShell` with `layout=\"overlay\"` for sidebar previews.",
     "3. Create `*-variant-toggle.tsx` mounting `PrototypeVariantExplorer` with matching `variantSet={{ id, label }}`.",
     "4. Register static ids + any `dynamicPrefixes` in `src/prototypes/" +
       slug +
@@ -149,11 +235,13 @@ export function buildCreateDesignExplorationCopyText({
   existingExplorations = [],
   origin = "http://localhost:3003",
   briefText,
+  includeMobbin = true,
 }: {
   slug: string;
   existingExplorations?: Array<{ id: string; label: string }>;
   origin?: string;
   briefText: string;
+  includeMobbin?: boolean;
 }): string {
   const trimmedBrief = briefText.trim();
   const prompt = buildCreateDesignExplorationPrompt({
@@ -161,6 +249,141 @@ export function buildCreateDesignExplorationCopyText({
     existingExplorations,
     origin,
     briefText: trimmedBrief,
+    includeMobbin,
+  });
+
+  return `${trimmedBrief}\n\n---\n\n${prompt}`;
+}
+
+export function buildMoreDesignExplorationVariantsPrompt({
+  slug,
+  explorationLabel,
+  explorationId,
+  options,
+  brief,
+  configFilePath,
+  origin = "http://localhost:3003",
+  briefText,
+  multipleVersions = true,
+}: {
+  slug: string;
+  explorationLabel: string;
+  explorationId?: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  brief: DesignExplorationBrief;
+  configFilePath?: string;
+  origin?: string;
+  briefText?: string;
+  /** When false, prompt asks for one targeted derivative variant. */
+  multipleVersions?: boolean;
+}): string {
+  const prototypeUrl = `${origin}/prototypes/${slug}`;
+  const configTarget = configFilePath ?? "the design exploration config file";
+  const trimmedBrief = briefText?.trim() ?? "";
+
+  const lines = [
+    `Add new layout variants to the "${explorationLabel}" design exploration on the "${slug}" prototype.`,
+    "",
+    "## Brief",
+  ];
+
+  if (trimmedBrief) {
+    lines.push(trimmedBrief);
+  } else if (multipleVersions) {
+    lines.push(
+      "Describe the new directions to explore:",
+      "- What to try:",
+      "- Target count: 3–5 new variants",
+    );
+  } else {
+    lines.push(
+      "Describe the variation to explore:",
+      "- What to try:",
+      "- Target count: 1 new variant",
+    );
+  }
+
+  lines.push(
+    "",
+    "## Exploration context",
+    `- Label: ${explorationLabel}`,
+  );
+
+  if (explorationId) {
+    lines.push(`- Variant set id: \`${explorationId}\``);
+  }
+
+  lines.push(
+    `- Overview title: ${brief.titleDefault}`,
+    `- Overview description: ${brief.descriptionDefault}`,
+    "",
+    "## Existing variants",
+  );
+
+  for (const option of options) {
+    const hint = option.hint ? ` — ${option.hint}` : "";
+    lines.push(`- ${option.label} (\`${option.value}\`)${hint}`);
+  }
+
+  lines.push(
+    "",
+    "## Prototype",
+    `- Slug: \`${slug}\``,
+    `- Config: \`${configTarget}\``,
+    `- Preview: ${prototypeUrl}`,
+    "",
+    "## Instructions",
+    "Follow AGENTS.md → Design exploration → Iterating on variants.",
+    "",
+    multipleVersions
+      ? "Supply **3–5 new variant options** unless the brief specifies a different count."
+      : "Add **one new derivative variant** unless the brief specifies otherwise.",
+    "",
+    multipleVersions
+      ? "When modifying an existing option, add **new variants** (do not replace in place)."
+      : "When modifying an existing option, add a **single new variant** (do not replace in place). Keep all existing variants.",
+    "",
+    "1. Prepend new entries to the top of `*_VARIANT_OPTIONS` so newest explorations appear first.",
+    "2. Add matching renderers via `buildDesignExplorationRenderers` and any new component ids.",
+    "3. Keep existing variants unless the brief explicitly asks to remove one.",
+    "4. Run `pnpm verify:prototype-ids`.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildMoreDesignExplorationVariantsCopyText({
+  slug,
+  explorationLabel,
+  explorationId,
+  options,
+  brief,
+  configFilePath,
+  origin = "http://localhost:3003",
+  briefText,
+  multipleVersions = true,
+}: {
+  slug: string;
+  explorationLabel: string;
+  explorationId?: string;
+  options: Array<{ value: string; label: string; hint?: string }>;
+  brief: DesignExplorationBrief;
+  configFilePath?: string;
+  origin?: string;
+  briefText: string;
+  multipleVersions?: boolean;
+}): string {
+  const trimmedBrief = briefText.trim();
+  const prompt = buildMoreDesignExplorationVariantsPrompt({
+    slug,
+    explorationLabel,
+    explorationId,
+    options,
+    brief,
+    configFilePath,
+    origin,
+    briefText: trimmedBrief,
+    multipleVersions,
   });
 
   return `${trimmedBrief}\n\n---\n\n${prompt}`;
@@ -187,9 +410,37 @@ export function buildResetBriefDefaultsPrompt({
   ].join("\n");
 }
 
+/**
+ * Prompt that asks an agent to set the codebase-stored default variant. Copied
+ * by the "Make default" control in the design brief — the default lives in the
+ * config file (e.g. `DEFAULT_*_VARIANT`), not in KV storage.
+ */
+export function buildSetDefaultVariantPrompt({
+  variantLabel,
+  variantValue,
+  configFilePath,
+}: {
+  variantLabel: string;
+  variantValue: string;
+  configFilePath?: string;
+}): string {
+  const target = configFilePath ?? "the design exploration config file";
+
+  return [
+    `Make "${variantLabel}" the default design exploration variant.`,
+    "",
+    `In ${target}, update the exported default variant constant (e.g. \`DEFAULT_*_VARIANT\`) so it equals:`,
+    "",
+    variantValue,
+    "",
+    'This constant is the codebase-stored default the prototype renders first, and the option marked "Default" in the design brief. Keep it as one of the values in the variant options list.',
+  ].join("\n");
+}
+
 /**
  * Prepend new entries to the top of *_VARIANT_OPTIONS so they appear first in the
- * design-brief scroll view (see AGENTS.md). Default variant is stored in KV.
+ * design-brief scroll view (see AGENTS.md). The default variant is stored in the
+ * codebase config (`defaultVariant`), not KV.
  */
 export function getAdjacentDesignExplorationVariant<TVariant extends string>(
   options: DesignExplorationVariantOption<TVariant>[],

package/src/lib/prototypes/link-source-prompt.ts

@@ -0,0 +1,93 @@
+export function buildLinkSourcePrompt({
+  sourceInput,
+  description,
+  currentSourcePath,
+  referencePaths = [],
+}: {
+  sourceInput?: string;
+  description?: string;
+  currentSourcePath?: string;
+  referencePaths?: string[];
+} = {}): string {
+  const trimmedInput = sourceInput?.trim();
+  const trimmedDescription = description?.trim();
+  const trimmedCurrent = currentSourcePath?.trim();
+  const isUpdate = Boolean(trimmedCurrent);
+
+  const lines = [
+    isUpdate
+      ? "Update the linked source application for this prototype host app."
+      : "Link the source application for this prototype host app.",
+    "",
+    "## Goal",
+    "Set `SOURCE_PATH` in `.env.local` and run `pnpm link-source` so the `source/` symlink points at the real product repo.",
+  ];
+
+  if (trimmedCurrent) {
+    lines.push("", "## Current source", `- \`SOURCE_PATH\`: \`${trimmedCurrent}\``);
+  }
+
+  lines.push("", "## Desired source");
+
+  if (trimmedInput) {
+    lines.push(`- ${trimmedInput}`);
+    lines.push(
+      "",
+      "Resolve this to a filesystem path (folder name, relative path like `../cal.diy`, or absolute path) before writing `.env.local`.",
+    );
+  } else {
+    lines.push("- (Specify folder name, path, or description above before copying.)");
+  }
+
+  lines.push(
+    "",
+    "## Clarification",
+    "If the input is vague, matches multiple folders on disk, or you cannot confidently identify the correct repo from the description and filesystem, ask the user a clarifying question before changing anything. Do not guess — confirm the exact path first.",
+  );
+
+  if (trimmedDescription) {
+    lines.push("", "## Notes", trimmedDescription);
+  }
+
+  if (referencePaths.length > 0) {
+    lines.push(
+      "",
+      "## Reference screenshots",
+      "Use these files for additional context:",
+    );
+    for (const referencePath of referencePaths) {
+      lines.push(`- \`${referencePath}\``);
+    }
+  }
+
+  lines.push(
+    "",
+    "## Steps",
+    "1. Confirm the correct source path. If it is still unclear after checking the description and filesystem, ask the user before proceeding.",
+    "2. Set or update `SOURCE_PATH` in `.env.local` at the host repo root (see `.env.example`).",
+    "3. Run `pnpm link-source` from the host repo to create or refresh the `source/` symlink.",
+    "4. Restart the dev server if it is already running so env changes are picked up.",
+    "5. Confirm the gallery sidebar footer shows the correct source directory name.",
+  );
+
+  return lines.join("\n");
+}
+
+export function buildLinkSourceCopyText({
+  sourcePath,
+  description,
+  currentSourcePath,
+  referencePaths = [],
+}: {
+  sourcePath?: string;
+  description?: string;
+  currentSourcePath?: string;
+  referencePaths?: string[];
+} = {}): string {
+  return buildLinkSourcePrompt({
+    sourceInput: sourcePath,
+    description,
+    currentSourcePath,
+    referencePaths,
+  });
+}