proto-plugin 0.1.0

package/AGENTS.md

@@ -0,0 +1,350 @@
+# AGENTS.md
+
+Instructions for AI agents working with `prototype` and host-app prototypes.
+
+## Scope in host repos
+
+Unless `DEVELOPER=true` is set in `.env.local`, agent work scope in a **host app** (e.g. `your-host-app`) is `**src/prototypes/<slug>/` only**. Do not modify prototype package code (`packages/prototype/`), app routing, or shared UI unless explicitly developing the prototype package.
+
+---
+
+## Architecture
+
+
+| Layer                  | Location                                                                | Notes                                                            |
+| ---------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| **Prototype**   | `packages/prototype/`                                            | Shell, comments, variant explorer, gallery client, verify script |
+| **Host prototypes**    | `src/prototypes/<slug>/`                                                | Feature UI, mock data, `component-ids.ts`                        |
+| **Host manifest**      | `prototype.config.ts`                                                   | Registers all prototypes                                         |
+| **Host design system** | `src/app/globals.css`, `@/components/ui`                                | Synced from source; host prototypes only                         |
+| **Tool design system** | Host `globals.css`, `src/components/ui/`, `src/components/platform-ui/` | Uses host tokens; shadcn primitives + tool chrome composites     |
+
+
+Host prototypes import framework from `prototype` and UI from `@/components/ui`.
+
+**Prototype package code must never import `@/components/ui` or `@/lib/utils` from the host.** Use `@prototype/components/ui`, `@prototype/components/platform-ui`, and `@prototype/lib/utils` only.
+
+---
+
+## Relationship to source app (host apps)
+
+Host apps replicate product UI from the **source application** (linked read-only via `SOURCE_PATH` and `pnpm link-source`) **exactly** — standalone code, no runtime imports from the source monorepo.
+
+### What is synced vs replicated
+
+
+| Layer                   | Source                                                   | Runtime import from source? |
+| ----------------------- | -------------------------------------------------------- | --------------------------- |
+| Design tokens + base UI | Synced → `@/components/ui`, `globals.css`                | No                          |
+| Feature/page UI         | Replicated → `src/prototypes/<slug>/_components/`        | No                          |
+| Data / auth / routing   | Mock constants + local state                             | No                          |
+| Source reference        | `source/` symlink (`SOURCE_PATH` + `pnpm link-source`) | Read-only                   |
+
+
+**Synced** via `pnpm sync-from-source`: `globals.css` (host only), fonts, `src/components/ui/`, shared utils.
+
+**Replicated per prototype**: page components, layout shells, form/section layout, mock data.
+
+### Source sync config (`prototype.sync.config.sh`)
+
+The sync/link scripts are host-agnostic — package code names nothing host-specific. The host declares everything in a `prototype.sync.config.sh` at its repo root (the scripts error until it exists). Create it from the template at `scripts/lib/host-config.example.sh`. It declares:
+
+- `SYNC_FILES`, `SYNC_DIRS`, `SYNC_GLOBS` — paths to copy from source (mirrored 1:1).
+- `SYNC_LOCAL_EXTENSIONS` — components this host customizes beyond source; printed as a re-apply reminder since the sync overwrites them.
+- `SOURCE_DB_ENV_VARS`, `SOURCE_DB_CONSOLE_URL` — env vars `link-source-db` copies from the source app's `.env.local`, and the console URL to print.
+
+### How to build a prototype from source
+
+1. Link source: `SOURCE_PATH` in `.env.local`, run `pnpm link-source`. (First-time setup: create `prototype.sync.config.sh` from `scripts/lib/host-config.example.sh`.)
+2. Find the real page in source and read it fully.
+3. Trace imports; classify as base UI (`@/components/ui`), shared util, context-bound (mock), or layout chrome (`Mock`*).
+4. Copy render logic, not infrastructure — preserve class names, layout, semantic tokens.
+5. Mock data as typed constants matching screenshots/source fixtures.
+6. Look up dimensions from source — do not guess.
+7. Wire prototype infrastructure (checklist below).
+8. Run `pnpm verify:prototype-ids`.
+
+Default to **mock data only**.
+
+Reference prototype: `example-feature` — `src/prototypes/example-feature/` (or any registered slug in your host app).
+
+---
+
+## Prototypes (`src/prototypes/`)
+
+Shareable UI at `/prototypes/[slug]`. Registered in `prototype.config.ts`.
+
+**Every UI component must be comment-anchorable** — enforced by `pnpm verify:prototype-ids`.
+
+### Rules (mandatory)
+
+1. **Register** the slug in `prototype.config.ts` and add a screenshot under `public/prototypes/screenshots/`.
+2. **Create** `src/prototypes/<slug>/component-ids.ts` — every component target id (see `example-feature/component-ids.ts`).
+3. **Wire comments** with `usePrototypeComments` on the page (see `example-feature/index.tsx`).
+4. **Wrap the root JSX of every React component** in `PrototypeComponent` from `prototype`.
+5. **On-page prototype controls** (state pickers, variant tabs, preview toggles) must use `PrototypeControl` or `PrototypeControlGroup`, not plain `PrototypeComponent`.
+6. **Use ids from the registry only** — dev mode logs an error for unregistered ids.
+7. **Id naming:**
+  - File's main export: kebab-case filename (`settings-section.tsx` → `settings-section`; `index.tsx` → `page`).
+  - Other functions in the same file: `{filename}.{function-kebab}`.
+  - Dynamic list items: add a prefix to `dynamicPrefixes` in `component-ids.ts`.
+8. **Scroll container:** `PrototypeComponent` with `id="scroll-container"` on the main `overflow-y-auto` wrapper.
+9. **Do not** use `data-testid` for comment anchoring.
+
+### Examples
+
+```tsx
+import { PrototypeComponent } from "prototype";
+
+export function SettingsSection(props: SettingsSectionProps) {
+  return (
+    <PrototypeComponent id="settings-section" className="...">
+      ...
+    </PrototypeComponent>
+  );
+}
+```
+
+```tsx
+import { PrototypeControl } from "prototype";
+
+export function PrototypePreviewStateSelect(...) {
+  return (
+    <PrototypeControl id="prototype-preview-state-select" className="flex items-center gap-2">
+      ...
+    </PrototypeControl>
+  );
+}
+```
+
+### New prototype checklist
+
+1. Identify the source page/feature and confirm visual parity.
+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. Call `usePrototypeComments(liveState, onRestore)` on the page.
+7. Run `pnpm verify:prototype-ids`.
+8. Capture screenshot; share via `pnpm share-prototype <slug>`.
+
+---
+
+## Preview states & state map
+
+Prototypes with preview modes use `definePreviewStateRegistry` in `*-preview-states.ts`. One registry drives the state picker, map nodes, `edges`, and sections.
+
+### State map layout
+
+Edge paths draw directly between node anchors (straight or elbow segments). They **do not route around** other states.
+
+When two states are connected by an `edges` entry, arrange `canvasLayout.rows` so **no unrelated state sits on the path between them**. Otherwise the connector passes through the intervening card — arrows only render at path endpoints, so the middle segment looks directionless and the link reads ambiguously.
+
+Prefer adjacent columns on the same row, or use `{ id, column }` / `startColumn` to offset nodes so vertical edges do not cut through unrelated cards in the same column.
+
+Reference: `src/prototypes/example-feature/_components/list-preview-states.ts`.
+
+---
+
+## Design exploration
+
+Use when comparing **2+ UI directions** for the same user problem.
+
+
+| Layer         | Location                                               | Owns                                                                                         |
+| ------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| **Tool**      | `prototype` (`PrototypeVariantExplorer`, etc.) | Modal chrome, variant tabs, rationale popover, Mobbin gallery, localStorage for brief fields |
+| **Prototype** | `src/prototypes/<slug>/_components/`                   | Variant renderers, copy, rationale, context JSON, Mobbin references, `component-ids.ts`      |
+
+
+Reference: `example-feature/_components/no-data-design-exploration-config.tsx` + `no-data-variant-toggle.tsx`.
+
+### Config shape
+
+```ts
+{
+  componentIdPrefix: string;
+  variantTabsIdPrefix: string;
+  storageKeyPrefix: string;
+  variant, onVariantChange,
+  options: { value, label, hint? }[];
+  rationale: Record<TVariant, { good, bad }>;
+  renderers: Record<TVariant, ComponentType>;
+  brief: { titleDefault, descriptionDefault };
+  context?: { label, data: unknown, render?, defaultExpanded?, panelId? };
+  mobbin?: { references, title?, description?, imagePathForReference? };
+  variantsSection?: { title?, description? };
+}
+```
+
+### Iterating on variants
+
+When asked to **modify an existing option**, add a **new variant** (do not replace in place), register ids, and update `DEFAULT_*_VARIANT`.
+
+**Variant list order:** prepend each new entry to the top of `*_VARIANT_OPTIONS` (first item in the array). That order drives the design-brief sidebar/modal scroll view and variant tabs — newest explorations appear at the top.
+
+
+| Prompt intent         | Action                                          |
+| --------------------- | ----------------------------------------------- |
+| Targeted modification | One new derivative variant; keep prior variants |
+| Broad regeneration    | New full set of variants                        |
+
+
+---
+
+## PR split specs (implementation plan)
+
+Use when a prototype ships as a **sequence of small source PRs** rather than one monolith. The review sidebar **Spec** panel lists each PR, previews its slice, and generates agent prompts.
+
+
+| Layer         | Location                             | Owns                                                                                                                                             |
+| ------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Tool**      | `prototype`                  | `PrototypeSpecPanelContent`, `buildPrSplitPrototypeUrl`, `buildPrAgentPrompt`, Vercel preview fetch (`/api/pr-vercel-preview`), highlight tokens |
+| **Prototype** | `src/prototypes/<slug>/_components/` | `PR_SPLIT_ENTRIES` data, `PR_SPLIT_CONFIG`, wireframe renderers, live-state URL wiring                                                           |
+
+
+Reference: `example-feature/_components/pr-split-config.ts` + `pr-split-wireframes.tsx`.
+
+### Host setup
+
+1. Re-export the preview API route:
+
+```ts
+// src/app/api/pr-vercel-preview/route.ts
+export { getPrVercelPreview as GET } from "prototype/server";
+```
+
+1. Set `GITHUB_TOKEN` (or rely on local `gh` CLI) so PR cards can resolve Vercel preview URLs.
+
+### Prototype data (`pr-split-config.ts`)
+
+Keep **only** prototype-specific config and entries in the host prototype:
+
+```ts
+import type { PrSplitConfig, PrSplitEntry as PrSplitEntryBase } from "prototype";
+
+export type MyWireframeId = "sidebar" | "invite-form" | "member-list" | /* … */;
+
+export type MyPrSplitEntry = PrSplitEntryBase<MyWireframeId, MyLiveState>;
+
+export const PR_SPLIT_CONFIG: PrSplitConfig<MyLiveState> = {
+  slug: "my-slug",
+  seriesLabel: "My feature FE",
+  sourceRepo: "your-org/your-repo",
+  sourceWorkPath: "apps/web",
+  configFilePath: "src/prototypes/my-slug/_components/pr-split-config.ts",
+  branchName: (entry) => `feature/my-feature-fe-${entry.order}-…`,
+  writeEntryToSearchParams: (searchParams, entry) => {
+    // Write liveState into URL params (plus tool adds `prSplit=<order>`)
+  },
+  defaultPreviewPath: "/settings/team",
+  vercelProjectName: "source-app",
+  scopeNote: "Do not bundle unrelated work.",
+};
+
+export const PR_SPLIT_ENTRIES: MyPrSplitEntry[] = [
+  {
+    order: 1,
+    title: "…",
+    description: "…",
+    size: "Small" | "Medium" | "Large",
+    targetId: "my-slug.settings-section", // registered in component-ids.ts
+    liveState: { /* restores prototype when card is clicked */ },
+    wireframeId: "invite-form",
+    prUrl: "https://github.com/your-org/your-repo/pull/…", // after PR opens
+    branch: "…",
+    analyticsNotes: ["Event name"],
+    approved: true,
+  },
+];
+```
+
+**Entry fields:**
+
+
+| Field                          | Required       | Purpose                                                                        |
+| ------------------------------ | -------------- | ------------------------------------------------------------------------------ |
+| `order`                        | yes            | Merge sequence (1, 2, 3…)                                                      |
+| `title`, `description`, `size` | yes            | Card copy + agent prompt                                                       |
+| `targetId`                     | yes            | Component to highlight (`focusShareTarget`) — must exist in `component-ids.ts` |
+| `liveState`                    | yes            | Prototype state restored when the card is selected                             |
+| `wireframeId`                  | yes            | Key into prototype wireframe registry                                          |
+| `prUrl`, `branch`              | after PR opens | Sidebar links + dependency chain in prompts                                    |
+| `linearUrl`                    | optional       | Linear issue link shown in the PR split sidebar                                  |
+| `previewPath`                  | optional       | Path on Vercel preview host (default from config)                              |
+| `vercelPreviewHost`            | optional       | Fallback when GitHub comment lookup fails                                      |
+| `analyticsNotes`               | optional       | Product analytics events for the agent prompt                                  |
+| `approved`                     | optional       | Shows approved vs in-review badge                                              |
+
+
+### Wireframes (`pr-split-wireframes.tsx`)
+
+Prototype-specific schematic thumbnails for each `wireframeId`. Pattern:
+
+1. Define a `PageShell` (or layout scaffold) matching the prototype page structure.
+2. Use low-fidelity `Wire` blocks — neutral grays for chrome, **highlighted** regions for the PR target.
+3. Import highlight tokens from the tool: `PR_TARGET_HIGHLIGHT_BORDER`, `PR_TARGET_HIGHLIGHT_FILL`.
+4. Register one renderer per `wireframeId` in a `Record<WireframeId, () => ReactNode>`.
+5. Export `PrSplitWireframe` wrapped in `PrototypeComponent` (register id in `component-ids.ts`).
+
+Highlighted areas must match what `targetId` points to on the real prototype.
+
+### Page wiring (`index.tsx`)
+
+1. Parse `?prSplit=<order>` on load; restore matching entry's `liveState`.
+2. Sync `prSplit` param when selection changes.
+3. Mount spec panel via review context:
+
+```tsx
+import {
+  PrototypeSpecPanelContent,
+  buildPrAgentPrompt,
+} from "prototype";
+
+setSpecContent(
+  <PrototypeSpecPanelContent
+    entries={PR_SPLIT_ENTRIES}
+    renderWireframe={(id) => <PrSplitWireframe id={id} embedded />}
+    buildAgentPrompt={(entry, origin) =>
+      buildPrAgentPrompt(entry, PR_SPLIT_ENTRIES, PR_SPLIT_CONFIG, origin)
+    }
+    onPrNavigate={handlePrNavigate}
+    selectedPrOrder={selectedPrOrder}
+  />,
+);
+```
+
+1. `handlePrNavigate` applies `entry.liveState` and calls `review.focusShareTarget(entry.targetId)`.
+2. Register `"spec-panel-content"` in `component-ids.ts`.
+
+### Agent workflow
+
+1. Copy prompt from an unopened PR card (copy icon).
+2. Implement in source app per prompt instructions.
+3. Open PR → set `prUrl` and `branch` on the matching `PR_SPLIT_ENTRIES` item.
+4. Later PR prompts automatically list prior PRs as dependencies.
+
+---
+
+## Comment system
+
+- Storage: Upstash Redis key `prototype-comments:<slug>`
+- Resolution: `targetId` → `querySelector` inside `[data-prototype-screenshot]`
+- Library: `packages/prototype/src/lib/prototype-comments/`
+
+---
+
+## Fidelity checklist
+
+Before finishing, confirm side-by-side with source or a screenshot:
+
+- Layout, spacing, typography, badge variants, empty/loading/error states
+- All semantic tokens from `globals.css` — no hardcoded hex
+- Interactive states behave like source where in scope
+
+### Anti-patterns
+
+- Importing from `source/` at runtime
+- Reimplementing synced `@/components/ui` primitives
+- Approximating layout dimensions or colors
+

package/README.md

@@ -0,0 +1,279 @@
+# prototype
+
+Shared framework for building shareable UI prototypes in Next.js — review shell, comment anchoring, variant exploration, and the prototype home gallery.
+
+Host apps keep **project-specific** code: prototypes under `src/prototypes/`, design tokens in `globals.css`, synced `@/components/ui`, and styleguide pages. The `prototype` package owns everything reusable across projects.
+
+## Install
+
+From npm (public):
+
+```bash
+pnpm add proto-plugin
+# or
+npm install proto-plugin
+```
+
+## Host setup
+
+1. **Register prototypes** in `prototype.config.ts` at the repo root:
+
+```ts
+import { definePrototypeConfig } from "proto-plugin";
+import MyPrototype from "./src/prototypes/my-slug";
+import { myComponentRegistry } from "./src/prototypes/my-slug/component-ids";
+
+export default definePrototypeConfig({
+  prototypes: [
+    {
+      slug: "my-slug",
+      title: "My prototype",
+      screenshot: "/prototypes/screenshots/my-slug.png",
+      component: MyPrototype,
+      componentRegistry: myComponentRegistry,
+    },
+  ],
+});
+```
+
+2. **Gallery home** — `src/app/(platform-gallery)/page.tsx`:
+
+```tsx
+import { createPrototypeGalleryPage } from "proto-plugin";
+import prototypeConfig from "../../../prototype.config";
+
+export default createPrototypeGalleryPage(prototypeConfig);
+```
+
+3. **Prototype route** — `src/app/(source-prototype)/prototypes/[slug]/page.tsx`:
+
+```tsx
+import { createPrototypePage } from "proto-plugin";
+import prototypeConfig from "../../../../../prototype.config";
+
+const page = createPrototypePage(prototypeConfig);
+export default page.default;
+export const generateStaticParams = page.generateStaticParams;
+```
+
+4. **Next.js config** — transpile the package (use a relative import so CSS is not loaded during config evaluation):
+
+```ts
+import { withPrototype } from "./packages/prototype/src/config/with-prototype";
+
+export default withPrototype({ nextConfig: { /* … */ } });
+```
+
+5. **Tailwind** — scan prototype package components from the host `globals.css`:
+
+```css
+@import "tailwindcss";
+@source "../../packages/prototype/src/**/*.{js,ts,jsx,tsx}";
+```
+
+6. **tsconfig paths** (optional, for tool internal `@prototype/*` alias when developing the package):
+
+```json
+{
+  "compilerOptions": {
+    "paths": {
+      "proto-plugin": ["./packages/prototype/src/index.ts"],
+      "proto-plugin/server": ["./packages/prototype/src/server.ts"]
+    }
+  }
+}
+```
+
+## Public API
+
+| Export | Use |
+| --- | --- |
+| `definePrototypeConfig` | Register prototypes (sets global config as a side effect) |
+| `createPrototypePage` | Factory for `/prototypes/[slug]` page + `generateStaticParams` |
+| `createPrototypeRegistry` | Server helpers: `getAllPrototypes`, `getPrototype`, … |
+| `PrototypeComponent`, `PrototypeControl` | Comment-anchorable UI wrappers |
+| `PrototypeShell` | Review chrome (comments sidebar, screenshot capture) |
+| `PrototypeVariantExplorer` | Multi-variant design exploration |
+| `usePrototypeComments` | Live state + comment restore |
+| `PrototypeGalleryClient` | Card grid for prototype home |
+| `PrototypeGalleryShell`, `PrototypeGalleryHeader`, `PrototypeGalleryPage` | Tool-styled gallery layout (wrap in host route at `/`) |
+| `definePrototypeComponentRegistry` | Per-prototype component id registry |
+
+**Server-only** (import from `proto-plugin/server`):
+
+- `readScreenshotManifest`
+- `touchScreenshotManifest`
+
+## Styles
+
+The `prototype` package uses the **host design system** — same tokens and Tailwind utilities as prototype pages.
+
+| Layer | Path |
+| --- | --- |
+| Host tokens + Tailwind | Host `src/app/globals.css` |
+| shadcn primitives | `src/components/ui/` |
+| Tool composites (sidebar, panel, toolbar, menus) | `src/components/platform-ui/` |
+
+Host `globals.css` must `@source` prototype package TSX for Tailwind utilities.
+
+## Publish
+
+From `packages/prototype/`:
+
+```bash
+npm login
+pnpm publish-package
+```
+
+Uses the public npm registry (`registry.npmjs.org`).
+
+## Verify component ids
+
+From the host repo root (forwards to the `prototype` package):
+
+```bash
+pnpm verify:prototype-ids
+```
+
+Or run directly in the package:
+
+```bash
+pnpm --filter prototype verify:prototype-ids
+```
+
+Runs `scripts/verify-prototype-component-ids.mjs` against the host's `src/prototypes/*/`.
+
+## Source app sync
+
+Scripts live in `scripts/` and resolve the host root via `prototype.config.ts`.
+
+The scripts are host-agnostic: which files to sync, which components the host
+has customized, and which source-app env vars to link are all declared by the
+host in a `prototype.sync.config.sh` at its repo root (template:
+`scripts/lib/host-config.example.sh`).
+
+From the host repo root:
+
+```bash
+pnpm link-source          # symlink source/ in editor
+pnpm sync-from-source     # sync files declared in prototype.sync.config.sh
+pnpm link-source-db       # copy configured env vars from source .env.local
+```
+
+Or run directly in the package:
+
+```bash
+pnpm --filter prototype link-source
+pnpm --filter prototype sync-from-source
+pnpm --filter prototype link-source-db
+pnpm --filter prototype share-prototype <slug>
+pnpm --filter prototype download-mobbin-references
+```
+
+Set `SOURCE_PATH` in the host `.env.local` (see host `.env.example`).
+
+### Share a prototype preview
+
+```bash
+pnpm share-prototype example-feature
+pnpm share-prototype --no-push example-feature
+```
+
+Uses `VERCEL_PROJECT` when set, otherwise the host `package.json` name. Override with `--project <name>`.
+
+### Mobbin reference images
+
+```bash
+pnpm download-mobbin-references
+pnpm download-mobbin-references -- --ids=uuid1,uuid2
+```
+
+## Starter prompt (for AI agents)
+
+Copy the block below into a new agent chat to scaffold a host app from scratch. The agent should ask you for a few values up front, then handle the rest (including inferring what to sync from source).
+
+````markdown
+Set up a new Next.js host app for `proto-plugin` — a framework for shareable UI prototypes.
+
+## Before you start — ask me for these
+
+Do not scaffold or run commands until I answer. Ask in one message:
+
+1. **Host app name** — directory name for the new Next.js project.
+2. **Where to create it** — parent directory (absolute path), or confirm the current workspace.
+3. **Source app path** — absolute path to the real product repo whose UI we will prototype (used for `source/` symlink and sync).
+4. **Optional env** — whether I want comment/screenshot persistence configured now (`KV_REST_API_URL`, `KV_REST_API_TOKEN`, `BLOB_READ_WRITE_TOKEN`) or to skip for later.
+
+Wait for my answers, then do all setup yourself.
+
+## 1. Scaffold the app
+
+Create a new directory and initialize a vanilla Next.js app using the host app name and parent path I gave you:
+
+- App Router, TypeScript, Tailwind CSS v4, ESLint, pnpm
+- No src-dir alias tricks beyond what Next generates (`src/app/…`)
+- React 19 + Next.js 15+
+
+Run `pnpm create next-app@latest` with the host app name I provided (`--typescript --tailwind --eslint --app --src-dir --use-pnpm`), in the parent directory I specified, then `cd` into the new project.
+
+Install the package:
+
+```bash
+pnpm add proto-plugin
+```
+
+## 2. Wire the host app
+
+Follow the package README (`node_modules/proto-plugin/README.md`) and implement every host step:
+
+1. **`prototype.config.ts`** at the repo root — start with an empty `prototypes: []` array using `definePrototypeConfig` from `proto-plugin`.
+2. **Gallery home** — `src/app/page.tsx` via `createPrototypeGalleryPage(prototypeConfig)`.
+3. **Prototype route** — `src/app/prototypes/[slug]/page.tsx` via `createPrototypePage(prototypeConfig)` (export `default` + `generateStaticParams`).
+4. **Root layout** — wrap children with `createPrototypeSiteLayout()` from `proto-plugin` in `src/app/layout.tsx`.
+5. **API catch-all** — `src/app/api/[...path]/route.ts` using `createPrototypeApiRoute(prototypeConfig)` from `proto-plugin/server`; export `GET`, `POST`, and `PUT` handlers that call `dispatch`.
+6. **`next.config.ts`** — wrap with `withPrototype` from `proto-plugin/with-prototype` and ensure `proto-plugin` is transpiled.
+7. **`src/app/globals.css`** — keep Tailwind v4 setup and add:
+
+   ```css
+   @source "../../node_modules/proto-plugin/src/**/*.{js,ts,jsx,tsx}";
+   ```
+
+8. **`package.json` scripts** — forward CLI commands to the installed package:
+
+   ```json
+   {
+     "link-source": "pnpm --dir node_modules/proto-plugin link-source",
+     "sync-from-source": "pnpm --dir node_modules/proto-plugin sync-from-source",
+     "link-source-db": "pnpm --dir node_modules/proto-plugin link-source-db",
+     "verify:prototype-ids": "pnpm --dir node_modules/proto-plugin verify:prototype-ids",
+     "share-prototype": "pnpm --dir node_modules/proto-plugin share-prototype"
+   }
+   ```
+
+9. **`.env.example` and `.env.local`** — document and set `SOURCE_PATH` to the source app path I provided. Add comment/screenshot storage vars only if I asked for them in step 5 — the app should run without them, but comments won't persist.
+
+Run `pnpm dev` and confirm `/` shows the empty gallery and the app builds cleanly before continuing.
+
+## 3. Link the source app
+
+The host reads the real product codebase through a read-only `source/` symlink — never import from it at runtime.
+
+1. Copy `node_modules/proto-plugin/scripts/lib/host-config.example.sh` to **`prototype.sync.config.sh`** at the host repo root.
+2. Inspect the linked source app and fill in `SYNC_FILES`, `SYNC_DIRS`, and `SYNC_GLOBS` yourself — start with design tokens and base UI (`src/app/globals.css`, `src/components/ui/`, fonts, shared utils) and add anything else the source clearly depends on. Do not ask me to confirm the list.
+3. Set `SOURCE_PATH` in `.env.local` to the source app path I provided.
+4. Run `pnpm link-source` — creates `source/` → source app symlink.
+5. Run `pnpm sync-from-source` — copies declared paths from source into the host.
+6. If I asked for local DB/API env vars, configure `SOURCE_DB_ENV_VARS` in `prototype.sync.config.sh` and run `pnpm link-source-db`.
+
+After sync, re-check `globals.css` still includes the `@source` line for `proto-plugin`.
+
+## 4. Ready for prototypes
+
+When setup is done, tell me the host is ready and summarize what was synced. For building individual prototypes, read and follow **`node_modules/proto-plugin/AGENTS.md`** — that is the ground truth for prototype structure, `PrototypeComponent` ids, source fidelity, and verification (`pnpm verify:prototype-ids`).
+
+Do not modify files inside `node_modules/proto-plugin/`. All host-specific work stays in the host repo (`prototype.config.ts`, `prototype.sync.config.sh`, `src/prototypes/`, synced design system files).
+````
+
+## Agent instructions
+
+See [`AGENTS.md`](./AGENTS.md) — ground truth for building prototypes with this tool.

package/components.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles/globals.css",
+    "baseColor": "zinc",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@prototype/components",
+    "ui": "@prototype/components/ui",
+    "utils": "@prototype/lib/utils"
+  }
+}