docs(product): commit design references under docs/product/reference/

Copy the founder's design handoff bundle (.proto/design/) into
docs/product/reference/ byte-for-byte so dispatch agents running in git
worktrees can read the HTML prototypes, veect-codebase/ prototype,
upload PNGs, and remaining bundle files (ADR-029: reference only, never
vendored into packages/). Ignore-list entries so whole-codebase auditors
and formatters skip reference material: .prettierignore (byte
preservation through lint-staged), .fallowrc.json ignorePatterns, root
ESLint ignores, and the coverage:diff allowlist in
scripts/coverage/diff.mjs (+ unit test). .DS_Store files skipped.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK

docs/product/reference/project/uploads/design-app-prd.md

@@ -0,0 +1,177 @@
+# PRD — "Weave" MVP (working name) · v2
+
+_Founder OS · Phase 6 (MVP Definition) · 2026-07-09_
+_Companion docs: `company-context.md` (strategy) · `design-brief-weave.md` (UI/UX)_
+_v2 changes (from adversarial product review + Impeccable integration): **real-component mapping pulled into MVP** (the wedge depended on it); **Impeccable craft/Polish layer added** (F9); validation gate **sequenced with kill criteria**; trust metric moved to **engineer-observed merge behavior**; scope trims (share link, frame-linking, full authoring → deferred)._
+_Tags: 🟢 verified · 🟡 reasoned · 🔴 assumed / needs validation_
+
+---
+
+## 1. Problem & why now
+Product designers with an existing design system can't ship on-brand UI without engineering, and AI tools (v0, Lovable, Bolt, Figma Make) generate **generic, throwaway** code that ignores their tokens and components. Weave makes the design system the source of truth — a canvas where everything you compose is **real React built from your own components** — and holds output to a **craft standard (Impeccable)** so it's on-brand *and* genuinely good, not slop. (Evidence in `company-context.md`.)
+
+## 2. Goals & non-goals
+**Goals (MVP)**
+- Prove the core bet: **your design system in → on-brand, high-craft, production React out, from a visual canvas.**
+- Get a designer from "bring my system" to "export a screen's real code" in **one sitting (<20 min)** 🟡.
+- Clear the trust bar: an engineer would **merge** the output (import their real components, pass review), not rewrite it 🟢. *This is the bar the whole wedge rests on.*
+
+**Non-goals (MVP)**
+- Not a full-app/backend builder (Lovable/Bolt's lane) — Weave is **UI + prototypes**.
+- Not a Figma replacement or vector-illustration tool.
+- Not multi-framework, not real-time multiplayer, not repo round-trip, not a component-authoring studio (all deferred; §8).
+
+## 3. Success metrics
+| Metric | Definition | MVP target |
+|---|---|---|
+| **North Star** | Weekly shipped screens (code exported & used), proxied by an explicit **"mark as shipped"** + design-partner check-ins (no repo integration yet) | trend up 🟡 |
+| **Trust bar (primary, engineer-judged)** | Real PRs opened at design partners: **merge rate**, **% LOC changed pre-merge**, structural-vs-nit review comments | ≥60% merged with <10% LOC changed 🔴 |
+| **Wedge-usage** | % of exported screens composed *majority* from the user's **mapped/real** components (not stock base kit) | ≥50% floor 🔴 |
+| **Activation** | First screen composed from own system **and exported** | ≥40% of signups 🔴 |
+| **Time-to-first-value** | Signup → first exported on-brand screen | <20 min median 🔴 |
+| **Craft** | Open Polish issues per exported screen | trend →0 🟡 |
+| **Guardrail** | Canvas interaction latency | <16 ms/frame on a 50-node screen (node = one rendered element instance) 🟡 |
+
+## 4. Target users
+- **P1 — "Maya," product designer** (primary): has a design system, ships React, blocked on eng, burned by generic AI output. Often does **not** own a clean token file (it lives in Figma/repo).
+- **P2 — "Devon," design-systems / design-engineer lead** (champion + gatekeeper): owns the **real coded component library**; cares that output imports *their* components and passes review. Holds the merge veto.
+
+## 5. Core value & the "aha"
+*"I typed a screen, it came out in MY components and MY tokens, it's genuinely well-designed, and the code imports our real library."* Four trust beats: my system re-themes the tool → the canvas renders the **real** component → **Polish** makes it craft-grade → export imports our **real** components.
+
+## 6. MVP — the core loop
+```
+1. Bring your system  →  2. Map to your real components  →  3. Compose on canvas
+   tokens·fonts·assets     (Devon; optional if no coded lib)      real components
+   (file OR 5-token path)                                              ↓
+        ↑                                                    4. AI compose (constrained)
+        └──────────── 7. Export (imports your real code) ← 6. Polish (craft) ← 5. Preview
+```
+
+## 7. In scope (MVP) — each traced to the wedge
+| # | Capability | MVP boundary | Traces to |
+|---|---|---|---|
+| F1 | **Design-system import** | Tailwind config **or** paste CSS variables **or** Figma Variables (if available); **no-file path: set 5 core tokens** over the base kit. Upload fonts (woff2) + assets. One source of truth. | Whole wedge; Maya's real input path |
+| F2 | **Component library + mapping** | Tokenized **base kit** (~15 components, **semantic HTML + ARIA**). **Map base-kit components → the team's real components** (import path + prop names) so export references their library. Save composed **patterns**. *(Full variant/prop authoring deferred.)* | Wedge-critical: clears the merge bar; JTBD #2 |
+| F3 | **Canvas / composer** | Frames, drag/drop, **auto-layout** stacks (dir/gap/padding = tokens), props, token binding, undo/redo, keyboard-first. **Desktop breakpoint**; layout model responsive-ready. | Figma-like half; flow |
+| F4 | **AI compose (constrained)** | Prompt → assembles **only** from mapped/base components + tokens; **propose→accept** (staged ghost layer); shows provenance; **graceful refusal** (offers to compose from primitives w/ token binding + save) — never emits non-system markup. | The differentiator; JTBD #4 |
+| F5 | **Real code output** | Clean **React + Tailwind**; **imports the user's mapped components** (not inlined clones); tokens as CSS vars/Tailwind theme; Prettier; deterministic (same tree → same code). | The trust bar; JTBD #1 |
+| F6 | **Live preview** | Same runtime as canvas/export renders the **real** components; breakpoint switch; **real hover/focus/active states**. *(No frame-to-frame linking — see §8.)* | Kills "dead document"; JTBD #1 |
+| F7 | **Export / handoff** | Copy component code; **download runnable project (.zip)** wired to tokens + real component imports. *(Share link deferred.)* | Activation; North Star |
+| F8 | **Auth / projects** | Projects, autosave, single-player. **Manual provisioning acceptable** for a ~10-team design-partner MVP. | Table stakes |
+| **F9** | **Craft / Polish layer (Impeccable)** | Generated & composed output adheres to a **craft ruleset**; a **Polish** action critiques the screen (spacing, hierarchy, type, contrast, alignment, states), proposes **one-click fixes in your tokens/components**, and **explains why** (teach). | On-brand **and** high-craft = anti-slop; new user ask |
+| F10 | *(fast-follow)* **Pluggable standard** | Choose craft standard: Weave default / **Impeccable** / custom. | Extends F9; deepens moat |
+
+## 8. Explicitly OUT of scope (the load-bearing section) — deferred
+> Rule: *"Does the core value — on-brand, high-craft real code from a visual canvas — survive without it?"* If yes → cut.
+
+- **Full component-authoring studio** (variant/prop/slot editor). MVP = base kit + **mapping** + pattern-save; authoring recreates Subframe and risks a third source of truth. → fast-follow
+- **Real-time multiplayer.** Single-player + (later) share link. → v2
+- **Repo round-trip / two-way Git sync.** The dream; not needed to prove value. Export-only. → v2
+- **Share/read-only preview link.** Copy+zip is the activation event; link is virality, not the bet. → fast-follow
+- **Frame-to-frame prototyping / interaction linking.** Figma-parity creep; conflicts with "not a Figma replacement." Real component states come free. → v2
+- **Figma file (layout) import.** Fidelity rabbit hole (v0/Anima's failure). Tokens/Variables yes; layouts no. → v2
+- **Multiple frameworks** (Vue/Svelte/SwiftUI/HTML). React+Tailwind only. → later
+- **Full vector/illustration tools.** Composer, not illustrator. → out of lane
+- **Backend / data / auth-in-app / business logic.** Out of Lovable/Bolt's lane. → out of lane
+- **Second breakpoint (mobile).** Desktop MVP; model responsive-ready. → near-term follow
+- **Design-token governance/versioning, multi-brand; plugins/marketplace; comments/redline.** → v2
+
+## 9. User stories & acceptance criteria (Given/When/Then)
+
+**US-1 — Bring my system (incl. no-file path)**
+- **Given** a Tailwind config / pasted CSS vars / Figma Variables, **when** I import, **then** tokens parse and the base kit re-themes within ~3s.
+- **Given** I have no token file, **when** I choose the 5-token path, **then** I set brand/neutral/radius/font/spacing and the kit re-themes live — **no dead end**.
+- **Given** an invalid file, **when** I import, **then** I get a line-referenced error with manual mapping.
+
+**US-2 — Map to my real components**
+- **Given** a coded component library, **when** I map "Weave Button" → `@/components/ui/Button` and its props, **then** the code preview shows the exact real import, and canvas instances render as that mapped component.
+- **Given** unmapped components on a screen, **when** I export, **then** I'm warned which will fall back to Weave defaults, and offered to map them.
+
+**US-3 — AI compose, constrained**
+- **Given** an imported system, **when** I prompt "pricing, three tiers," **then** the result uses **only** my mapped/base components + tokens, staged as a ghost layer to **accept/discard**, listing components used.
+- **Given** the AI can't map a need, **when** it hits it, **then** it **says so** and offers to compose from primitives (with token binding + save) — **it does not inject generic markup**. **AC:** across a 100-prompt eval, **0 unregistered elements** in output. 🟢 (differentiator integrity)
+
+**US-4 — Trust the code (engineer-judged)**
+- **Given** a composed screen, **when** Devon opens the code, **then** it **imports our real components** (not re-declared inline), references token vars, is Prettier-clean, `tsc`+`eslint` clean.
+- **Given** an exported zip, **when** run (`npm i && npm run dev`), **then** it renders identically to preview (shared runtime).
+
+**US-5 — Prototype**
+- **Given** a screen, **when** I preview, **then** real hover/focus/active states work at the desktop breakpoint. *(No click-through linking in MVP.)*
+
+**US-6 — Keep system in lockstep** *(new)*
+- **Given** updated tokens, **when** I re-import, **then** I see a **diff + impact** ("affects 14 components / 3 screens") and can **apply with undo**; bindings are preserved; nothing silently breaks.
+
+**US-7 — Polish to craft standard** *(new — Impeccable)*
+- **Given** a composed screen, **when** I run **Polish**, **then** I get a ranked list of craft issues (off-scale spacing, weak hierarchy, contrast fail, misalignment, missing state), each with a **why** and a **one-click fix expressed in my tokens/components**.
+- **Given** a clean screen, **when** I Polish, **then** it says "Impeccable. Nothing to fix." (earned, not flattery).
+
+## 10. Low-fi wireframes
+_See `design-brief-weave.md` §9 for full screens + states. Editor spine:_
+```
+Top: Project ▾ · [Desktop] · ⟳Preview · ✧Polish · </>Code · ⇪Export
+Left: Pages/Layers · Library(map/patterns) · Tokens
+Center: Canvas + ✦ AI bar        Right: Inspector (props·tokens·layout) / Polish issues
+Companion: Code panel — imports { Button, Card } from "@/components/ui"
+```
+
+## 11. Functional requirements
+- FR-1 Parse Tailwind + CSS-vars + Figma Variables tokens; 5-token quick path; font/asset upload+storage; contrast check at import.
+- FR-2 Base kit (~15, semantic + ARIA) bound to tokens; **component-mapping registry** (Weave component → real import path + prop map); pattern save.
+- FR-3 Canvas engine: frames, drag/drop, auto-layout, token-bound props, desktop breakpoint (responsive-ready model), undo/redo, shortcuts, autosave+offline/conflict handling.
+- FR-4 AI compose constrained to the project registry; propose→accept staging; provenance; graceful-refusal path; 0-unregistered-elements guarantee.
+- FR-5 Codegen: tree → React+Tailwind, **imports mapped components**, tokens as vars, Prettier, deterministic; export = runnable zip.
+- FR-6 Single shared component runtime for canvas/preview/export; breakpoint switch; real interaction states.
+- FR-7 **Polish engine (F9):** evaluate a screen against the craft ruleset; produce ranked, explained, auto-fixable issues expressed in tokens/components.
+- FR-8 Token re-import: diff, impact analysis, safe apply+undo.
+- FR-9 Auth/projects/autosave (manual provisioning acceptable for partner MVP).
+
+## 12. Non-functional requirements
+- **Performance:** <16ms/frame canvas on a 50-node screen; AI first paint <2s; Polish scan <2s on a typical screen. 🟡
+- **Fidelity (corrected):** state the **shared-runtime invariant** (preview == export by construction) as the guarantee; **golden-file visual tests on real user-composed screens** with **pinned browser + fonts** (not base-kit-only). Target ≥98% match. 🟡
+- **Code quality:** exported project passes `tsc`+`eslint`; imports resolve against the mapped library; **semantic HTML/ARIA** in base kit.
+- **Security/privacy:** per-project isolation; assets/fonts scoped to project; **no training on user systems (absolute for MVP)**; SOC2 path noted (not MVP). 🟢 (eng/security veto)
+- **Accessibility (tool):** WCAG 2.2 AA for Weave's UI; keyboard-operable canvas.
+- **Browsers:** latest Chrome/Edge/Safari/Firefox; desktop-first.
+- **Reliability:** autosave ≤5s; no lost work on refresh; offline read-only + reconnect.
+
+## 13. Validation plan & gate (sequenced — review fix)
+> The MVP is a **bet to validate**, not a green light. Run these **before/at the start of build**, with pre-registered kill criteria. Only the token-engine + shared-runtime spike may run concurrently.
+
+| # | Experiment | Tests | Pass / Kill threshold |
+|---|---|---|---|
+| V1 | **Concierge real-PRs:** hand-build 5 partners' screens from their systems, open **real PRs** against their repos | A1 + the trust bar (right judge) | **Pass** ≥3/5 merged with <10% LOC changed; **Kill/rethink** if <2/5 or reviews are structural |
+| V2 | **Clickable-mock task test** (Figma prototype of the editor), 5 designers | A2 (will they work in a new canvas) | **Pass** ≥4/5 complete the core task unaided |
+| V3 | **Fake-door demo** ("your system → on-brand screen → real code") vs. a v0-style generic control | Desirability / positioning | **Pass** waitlist conversion ≥2× control |
+| V4 | **Subframe/competitor teardown** (owed from Phase 2) | A4 (is the wedge unowned) | Decision input; no code needed |
+| V5 | **10 problem interviews** with design-system leads | A1 + A3 (tooling vs governance) | Qualitative gate |
+
+## 14. Key risks & mitigations
+| Risk | L/I | Mitigation |
+|---|---|---|
+| 🔴 Designers want the *outcome*, not to own code (A1) | M/High | V1 + V3 before heavy build; position as "export & hand to dev," code as proof |
+| Output doesn't clear the merge bar (imports/clean) | M/High | Mapping in MVP; shared runtime; golden-file tests; V1 is the direct test |
+| AI "fails open" to generic markup | M/High | Registry-only codegen; explicit refusal path; 0-unregistered eval |
+| Won't displace Figma (A2) | H/Med | Position per-phase (coexist); V2 before canvas build |
+| Subframe/incumbents own it first (A4) | M/Med | V4 teardown; sharpen system+craft wedge; Impeccable moat |
+| Scope creep to "app builder" | H/Med | §8 is load-bearing; guard it |
+| Impeccable rules not literally matched | L/Med | Reconcile with real ruleset / embed the Impeccable skill (F10) |
+
+## 15. Open questions
+- Import a **coded** library at MVP (mapping assumes one exists) vs. base-kit-only for library-less teams? (Support both; mapping is first-class.) 🟡
+- Token source of truth first: Tailwind vs Figma Variables vs CSS vars? (Recommend Tailwind + CSS-vars, Figma Variables if API allows.) 🟡
+- **Embed the Impeccable skill directly, or ship a compatible ruleset?** (F10 decision.) 🔴
+- Promise "shippable" or "starting-point" code? (Fidelity labeling.) 🔴
+
+## 16. Build sequence (trust path first)
+0. **Validation gate (§13)** — V1/V4 need no product code; start immediately.
+1. **Component runtime + token engine** (base kit re-themes from tokens) — the spine.
+2. **Component mapping registry** (Weave → real imports) — the merge bar.
+3. **Canvas compose + inspector** on that runtime.
+4. **Codegen + export** (make the trust bar real early).
+5. **AI compose, constrained** (propose→accept, refusal).
+6. **Polish engine (Impeccable)** + **token re-import**.
+7. **Preview + auth/projects** hardening.
+
+## Exit gate (Phase 6)
+Scope is defensibly minimal — every §7 item traces to the wedge/North Star, §8 removes the rest, and the wedge-critical **mapping** and **craft** capabilities are now in. **Phase 1's gate remains uncleared (🔴 A1–A4):** treat this as the spec for a bet, and run §13 with its kill criteria before committing the full build.