docs(product): commit Veect product spec bundle under docs/product/

Sandcastle implementers run in git worktrees that contain only committed
files, so every PRD referencing the spec was unreadable to dispatch
agents while the bundle sat untracked in .proto/. The eight spec
documents are copied verbatim (filenames preserved) from
.proto/veect-product-docs/ and become the canonical source.

The stray veect-product-docs.zip at the repo root was already removed
before this change — that half of the task is a verified no-op.

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

docs/product/README.md

@@ -0,0 +1,120 @@
+# Veect — Product Documentation Bundle
+
+_Entry point for the development agent. Generated 2026-07-10._
+
+You are about to build **Veect**. This bundle is the complete product, design, and technical specification. Read this README first — it tells you what each document is, **which document wins when two disagree**, the invariants you must never break, and exactly where to start.
+
+---
+
+## 1. What Veect is (read this once)
+
+Veect is a **standalone design application that connects to a code repository** and turns it into a design surface. A product designer connects their team's repo (remote via GitHub/GitLab/git URL, or a local checkout); Veect discovers the repo's **real components and design tokens** and lets the designer compose screens on a canvas using _only_ that system. Every design project is a **git branch in an app-managed worktree**; the designer composes, an AI assistant helps (constrained to the repo's own components), and the result is **checkpointed as real TSX and published as an ordinary pull request** the team can review.
+
+The wedge: v0 / Lovable / Bolt / Figma Make generate _generic, throwaway_ UI. Veect emits the team's **real components** as **real code an engineer will merge** — on-brand and high-craft, not slop.
+
+**Pronounced VEEKT** (rhymes with "piqued"). Design language is a **monochrome "ink instrument"** — the tool is deliberately colorless so the customer's brand is the hero.
+
+### The three invariants — never violate these
+
+1. **One runtime.** Canvas, preview, isolation view, and exported code all render the same node tree through the same renderer. No approximations, no "roughly how it'll look."
+2. **0 unregistered elements.** AI output is whitelist-sanitized against the discovered component registry. Anything outside it is **refused, never faked** with generic markup.
+3. **Deterministic code.** Same tree → byte-identical code, every time. Export imports the customer's real library; it never inlines cloned components.
+
+---
+
+## 2. How to read these documents (authority hierarchy)
+
+Documents were written across several iterations and **deliberately supersede each other**. When two conflict, the higher-authority doc wins on its domain:
+
+| Domain                                                                                    | Authoritative doc                         | Notes                                                                                                                             |
+| ----------------------------------------------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| **How the system must behave** (architecture, connections, git, adapters, AI, milestones) | **`veect-technical-spec.md`** (rev 1.2.2) | The primary build document. Start here after this README.                                                                         |
+| **Visual & interaction language** (color, type, radius, icons, motion, components)        | **`veect-design-spec-current.md`**        | Ground truth from the built prototype. **Wins over the design brief's older art-direction section.**                              |
+| **UI/UX still to be built** (repo-connect, publish, environment, editor deltas)           | **`veect-ui-gap-spec.md`**                | Your UI work order. Everything the prototype doesn't cover yet.                                                                   |
+| **UX intent** (north star, principles, journeys, signature moments, voice, a11y)          | **`design-brief-veect.md`**               | Authoritative for _intent_; where its §11 art direction conflicts with the design spec, the design spec wins (it says so itself). |
+| **Product scope — what & why** (features, out-of-scope, personas, acceptance criteria)    | **`design-app-prd.md`**                   | Distribution details superseded by the tech spec; wedge/personas/JTBD/scope discipline still authoritative.                       |
+| **Strategy & context** (problem, positioning, market, assumptions, decisions log)         | **`company-context.md`**                  | The "why." Read for orientation; not a build doc.                                                                                 |
+| **Project status** (what's validated, what's missing, non-code work)                      | **`founder-os-audit.md`**                 | Honest state-of-the-company. Read to understand what is NOT yet proven.                                                           |
+
+**Recommended reading order for building:**
+
+1. This README
+2. `veect-technical-spec.md` (the whole thing — it's the backbone)
+3. `veect-design-spec-current.md` (the design language you'll implement in)
+4. `veect-ui-gap-spec.md` (what to build, in milestone order)
+5. Skim `design-brief-veect.md`, `design-app-prd.md`, `company-context.md` for intent/scope/why
+6. `founder-os-audit.md` last (context on what's unproven)
+
+---
+
+## 3. What already exists vs. what you're building
+
+**⚠️ Not in this bundle (request from the founder):** the **interactive prototype** (`Veect.dc.html`), the **landing page** (`Veect Landing.dc.html`), and the **React 18 / TypeScript codebase** (`veect-codebase/`). These are the founder's built artifacts. `veect-design-spec-current.md` is their specification. **The codebase seeds `packages/editor`** — do not rebuild the editor from scratch.
+
+**Already built (inherit, do not redesign):** the entire editor — canvas (React Flow substrate, zustand store), 3-pane panels, activity bar, responsive **multi-view frames** (desktop/tablet/mobile clusters), constrained-AI UX (compose ghosts, scoped edits, refusal protocol, model picker), Polish pass, history with restore cursor, token editor with live ripple, isolation mode, the **bidirectional code grammar** (TSX generates _and_ parses back), and the landing page. See `veect-ui-gap-spec.md` §1.
+
+**What you're building** is the **repo-native layer** the prototype fakes: the desktop shell (Electron, bundled Node), repository connections, worktree/git engine, discovery engine (real component/token scanning), the preview adapters (embedded Vite + managed `next dev`), SQLite persistence, publish flow, and the new UI surfaces (Connect Repository, Checkpoint/Publish, Environment). The prototype's "seams" map 1:1 onto these subsystems — the wiring table is `veect-ui-gap-spec.md` §4.
+
+---
+
+## 4. Locked decisions (do not relitigate)
+
+- **Distribution:** standalone desktop app (default) + Docker image (additional). The npm-in-repo package (Storybook-style) is a **later** distribution — build the core layered so it can be added.
+- **Repository connection:** remote-first — GitHub device-flow, any git URL (token/SSH), or local folder.
+- **Config:** `veect.config.json` (JSON, app-writable, schema-validated). `veect.preview.tsx` stays a hand-authored code file.
+- **AI:** ships in v1. Anthropic; key via app Settings (OS-encrypted) or `ANTHROPIC_API_KEY` env. Haiku default, Sonnet option.
+- **Framework support:** any React + TypeScript repo, with **full Next.js** (App Router incl. server components) as a first-class adapter via a managed `next dev`.
+- **Persistence:** local SQLite (working state/history) + canonical `design.veect.json` committed on the branch (shareable/reviewable).
+- **Name:** Veect · npm `veect` · scope `@veectjs/*`.
+
+Full decision logs live in `veect-technical-spec.md` §18 and `company-context.md`.
+
+---
+
+## 5. Build order (start at M0)
+
+From `veect-technical-spec.md` §17, cross-referenced with the UI priorities in `veect-ui-gap-spec.md` §7:
+
+| Milestone | What                                                                                                                                                                                    | Proves                                                                                              |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| **M0**    | Walking skeleton — shell boots with **no system Node**; open both fixture repos (Vite + Next) as local folders; one real component renders through **both** adapters; minimal worktree. | The bundled-runtime + dual-adapter foundation (highest technical risk — front-loaded deliberately). |
+| **M1**    | Discovery & registry — real component/token scan, props/tokens panels, watch/HMR, split lazy registries, perf-500 budgets; JSON config wizard.                                          | The repo _is_ the design system.                                                                    |
+| **M2**    | Canvas + doc + persistence — the prototype editor on real data; SQLite + JSON write-through.                                                                                            | Composing on real components, durably.                                                              |
+| **M3**    | Worktrees + codegen + checkpoint (local complete) — commit transaction, parity check, code-owned flip, committer identity, **env manager core**.                                        | Real code an engineer would merge, on a branch.                                                     |
+| **M4**    | **Remote repositories + publish** — device flow, PAT/SSH, clone/install pipeline, trust prompt, publish → PR link, failure playbooks.                                                   | The flagship remote flow + design-partner onboarding.                                               |
+| **M5**    | Next.js depth — server-component subtrees, root-layout/middleware handling, font fidelity, adapter pool/crash recovery.                                                                 | Real Next.js repos work.                                                                            |
+| **M6**    | AI compose — context assembly, constrained generation, ghost propose/accept, refusal, provenance, eval suite.                                                                           | The differentiator, wired to the real registry.                                                     |
+| **M7**    | Docker + hardening — image, doctor, Windows pass, docs.                                                                                                                                 | Self-host + shippable.                                                                              |
+
+**Your first concrete actions:** (1) request the prototype codebase from the founder; (2) read `veect-technical-spec.md` end to end; (3) stand up the pnpm monorepo per its §3; (4) build M0 against the two kitchen fixtures defined in its §15.
+
+---
+
+## 6. Known risks & unresolved items the spec flags
+
+These are called out so you don't discover them mid-build:
+
+- **Impeccable craft ruleset is unreconciled.** The Polish/craft layer (F9) cites Impeccable's _philosophy_ — the verbatim `DESIGN.md` rules couldn't be fetched. Treat exact craft thresholds as provisional; the founder can supply the real ruleset.
+- **Trust model.** Cloning a repo and running its install scripts + dev server = executing repo code inside the app. This is a stated, mitigated surface (workspace-trust prompt, `--ignore-scripts` opt-in) — implement it, don't skip it. See tech spec §6 + §16.
+- **Native-module / Electron ABI, `node` PATH shim, per-worktree installs, credential-helper mechanics, SSH-from-GUI, git-lfs** — all have specific handling in tech spec §3 + §6. These are the "fails on real machines" landmines; follow the spec precisely.
+- **Open design questions** (need founder input before the noted milestone): board↔design-doc mapping (before M2); keep the no-repo "Playground" sandbox?; checkpoint granularity; landing-page proof-strip claims are targets stated as facts (validate before public traffic). See `veect-ui-gap-spec.md` §8.
+- **Non-code, founder-owned:** name/domain/npm/trademark registration, design-partner recruiting, and Phase-1 validation are tracked in `founder-os-audit.md` — not your build work, but context for why some acceptance criteria reference "design partners."
+
+---
+
+## 7. Document manifest
+
+| File                           | One line                                                                                                                                                                                           |
+| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `README.md`                    | This entry point.                                                                                                                                                                                  |
+| `veect-technical-spec.md`      | **rev 1.2.2** — the authoritative build spec: architecture, distribution, connections, git/worktrees, adapters, AI, persistence, security, milestones, decision log.                               |
+| `veect-design-spec-current.md` | The **built** design language + prototype/codebase spec — the monochrome ink instrument, editor anatomy, node model, AI/Polish/history UX, codegen grammar, landing. **Ground truth for visuals.** |
+| `veect-ui-gap-spec.md`         | The **work order** for UI not yet built — new surfaces (connect/publish/environment), editor deltas, the seams→subsystems wiring table, per-surface state/error catalog, build order.              |
+| `design-brief-veect.md`        | UX **intent** — north star, opinionated principles, personas, journeys, the 6 signature moments, voice, accessibility, the Craft/Impeccable checklist.                                             |
+| `design-app-prd.md`            | Product **scope** — the wedge, F1–F10 features with acceptance criteria, the load-bearing out-of-scope list, success metrics, the validation gate.                                                 |
+| `company-context.md`           | **Strategy** — problem, positioning (April Dunford), competitive frame, North Star Metric, riskiest assumptions, the naming decision, all pivots.                                                  |
+| `founder-os-audit.md`          | **Status** — Founder OS phase-by-phase: what's solid (product/tech), what's missing (validation, business model), and the recommended sequence.                                                    |
+
+---
+
+_Build the invariants first and never break them; inherit the editor; follow the tech spec precisely on the "real machines" details; implement the design in the ink language. When a document disagrees with another, use the authority table in §2. Good building._

docs/product/company-context.md

@@ -0,0 +1,131 @@
+# Company Context — Veect
+
+_Living strategy doc · Founder OS · last updated 2026-07-10_
+
+## ✅ NAME DECIDED (2026-07-10): **Veect**
+
+Pronounced **VEEKT** (rhymes with _piqued_). Coined vessel — unclaimed sound, clean searches, veect.com + veect.ai confirmed available at decision time. **Brand mark (as shipped):** the lowercase `veect` wordmark closed by a **square ink terminal** ("the vector point") — no pictorial mark; design language = the monochrome ink instrument (see `veect-design-spec-current.md`). Chosen over finalists Weef, Vez, Gesso, Jig, Bezier after an 8-territory, ~150-candidate search with per-name conflict verification.
+
+- Registered/actioned by founder: veect.com, veect.ai. **Still open 🔴:** veect.dev, npm `veect` + org, GitHub org, X handle, EUIPO/USPTO knockout (classes 9/42; assess **Vectr** adjacency — vectr.com, an active vector-graphics editor), counsel pass before incorporating. Entity name suggestion: _Veect Labs d.o.o._
+
+---
+
+## ⚡ PIVOT (2026-07-10): repo-native distribution — **rev 1.2: standalone app, remote-first**
+
+Veect is a **standalone design application** (desktop, bundled runtime — no system Node needed; plus a **Docker image** for team/self-host/CI) that **connects to a repository**: GitHub (device-flow), any git URL, or a local checkout. One `veect.config.json` in the repo points at the component folders (a visual wizard writes it if absent). Each design project auto-creates a **git worktree + branch** (`veect/<slug>`, kept in app-managed workspaces — the user's repo is never touched); data lives in local **SQLite** plus a canonical `design.veect.json` committed on the branch; **Publish** pushes the branch and hands the designer a PR link. The npm-installed-in-repo package (Storybook-style) is a **later distribution** on the same core. Full spec: `veect-technical-spec.md` (rev 1.2).
+
+**Why this is stronger:**
+
+- The **mapping problem dissolves** — the canvas renders the repo's _actual_ components via the host's own toolchain, so exported code imports the real library by construction. The old red-team's #1 gap (engineer's merge bar) is solved structurally. 🟢
+- **GTM flips to a Storybook-like bottom-up dev-tool motion** — the developer installs it, then invites the designer in. This sidesteps much of A2 (designers adopting a new canvas) by making the dev the champion.
+- Purpose sharpened (founder's words): _bring designers closer to developers so they work on prototypes directly on the codebase, with the components and context the codebase actually holds._
+
+**What it changes / adds:**
+
+- **Riskiest assumption A5 — materially weakened by rev 1.2 🟡:** the standalone app bundles the Node runtime, clones the repo itself, installs dependencies itself, and manages env values in an encrypted local store — the designer no longer needs a dev environment, only **git installed + repo access + (for full-fidelity preview) env values**. Residual friction to validate: getting repo access granted, and apps whose previews need real secrets/backends. GTM note: the designer can now **self-serve** with read access — the developer's moment shifts from "install it for me" to "review my PR," which is a stronger wedge into the team.
+- **Competitor frame shifts 🟡:** nearest neighbors are now **Onlook** ("Cursor for designers", edits real local code), **Storybook (+AI)** as the incumbent in-repo component tool, and Subframe. Veect's distinction: _component-registry canvas + project-as-worktree + constrained AI + designer-grade UX_, composing **new** designs from the real system (vs. Onlook editing existing pages; vs. Storybook documenting components rather than composing with them).
+- **Business model note 🔴:** this distribution begs **open-core** (OSS/source-available tool → paid team/cloud layer: hosted previews, design sync, AI credits, dashboards — the Storybook→Chromatic analogy). Decide before launch; not blocking the build.
+- Superseded from the SaaS PRD: F1 token-file import (tokens now read from the repo), F2 component _mapping_ (components are real by construction), F8 auth/cloud projects. The design brief's UI/UX (canvas, tokens panel, AI ghost layer, refusal, polish) carries over intact.
+
+_Locked with founder: AI compose in v1 (BYO Anthropic key) · full Next.js support (managed `next dev` adapter) · SQLite + JSON-in-branch hybrid persistence._
+
+**Asset status (2026-07-10):** an **interactive editor prototype, landing page, and React 18/TS codebase exist** (`veect-design-spec-current.md` is their spec; React Flow board substrate, zustand store, two-way TSX grammar, responsive view clusters, constrained-AI UX, Polish, history — all built). The remaining product surface is the repo-native layer — connect/publish/environment — specified in `veect-ui-gap-spec.md`.
+
+---
+
+_Status: Phases 1–5 **compressed** at the founder's request to jump to Phase 6. Confidence tags: 🟢 verified · 🟡 reasoned · 🔴 assumed / needs validation._
+
+> Name is decided (see header). Trademark counsel pass remains the one open naming item. 🔴→🟡
+
+---
+
+## One-liner
+
+A **design-system-native canvas** that turns your own tokens and components into **real, production-ready React**, held to a **craft standard (Impeccable)** so output is on-brand _and_ genuinely well-designed — so what a designer composes is exactly what ships.
+
+## Problem
+
+Product designers who already have a design system still can't ship on-brand UI without waiting on engineering. Today's AI design/code tools (v0, Lovable, Bolt, Figma Make) re-invent **generic** UI instead of using the team's own components and tokens — so the output is off-brand and thrown away, and the design→code handoff stays lossy.
+
+- 🟢 92% of designers and 91% of developers say the handoff process needs improvement (Figma, _State of the Designer_).
+- 🟢 Figma Make users report it "won't use my library components" / "created new ones that just looked like mine"; v0 "treats the Figma file as a screenshot" (Figma forum; user teardowns).
+- 🟢 The market has already conceded the pain — Bolt, Lovable and Figma all bolted on "use your design system" features in 2025 because generic output was the #1 designer complaint.
+
+## Beachhead ICP
+
+Product/UI designers and design-system / design-engineer leads at startups & scale-ups (~10–200 people) that **already have a design system** (tokens + component library) and ship a **React** web product. 🟡
+
+- **User (feels pain):** product designer · design-system designer · design engineer.
+- **Champion:** Head of Design / Design Systems lead. 🟡
+- **Economic buyer:** design leadership budget; escalates to VP/Eng at team tier. 🟡
+- **Veto:** Engineering ("will the emitted code meet our repo standards?") and Security at enterprise. 🟢
+
+## Top Jobs-to-be-Done (from discovery research)
+
+1. When I finish a design, I want the built UI to match it exactly without policing every pixel, so I can stop redlining.
+2. When our design system changes, I want Figma and code components to stay in lockstep, so "the library" means one thing everywhere.
+3. When I need a screen shipped, I want to produce it myself without an eng sprint slot, so I can move at the speed of the idea.
+4. When I use AI to generate UI, I want it built from **my** components/tokens (not a generic theme), so I get on-brand output I don't throw away.
+
+## Wedge / Positioning (April Dunford frame)
+
+- **For** product designers who have a design system but can't ship on-brand code without engineering,
+- **Veect is** a design-system-native canvas that emits real, production React from your own tokens + components,
+- **unlike** v0 / Lovable / Bolt / Figma Make, which are developer/prompt-first and generate generic, throwaway UI,
+- **so that** what you design is what gets built — on-brand, high-craft, with zero translation loss.
+- **Category:** "design-system-native design-to-code" — a wedge inside the crowded AI-builder space. 🟡
+
+**Two things deepen the wedge (added after review):**
+
+- **Real-component mapping** — export emits the team's _real_ coded components (their import paths + prop names), not Veect-internal clones. Without this the output never clears the engineer's merge bar and the wedge collapses to "v0 with theming." 🟢 (this was the single biggest gap the red-team found)
+- **Craft layer (Impeccable)** — beyond "constrained to your system," a Polish pass holds output to a craft ruleset (impeccable.style — an open-source anti-"AI-slop" design language for AI harnesses). On-brand **and** high-craft is a sharper position than either alone. 🟡
+
+## Why now
+
+AI codegen is finally good enough for _constrained_ composition; design-token standardization (W3C DTCG) is maturing; "design engineering" is rising as a role; Figma Dev Mode's per-seat pricing backlash has opened a door. 🟡
+
+## Competitive frame (from existing knowledge — deep teardown deferred)
+
+| Cluster                       | Players                                                  | Why they don't own the wedge                                                                                                         |
+| ----------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Prompt/dev-first app builders | v0, Lovable, Bolt                                        | Fast but generic output; prompt-first not canvas-first; not BYO-design-system-first                                                  |
+| Visual design-to-code         | **Subframe** (closest), Builder.io Fusion, Anima, Locofy | Subframe is strong but leans "design in browser → code"; others are dev-first imports or Figma-plugin exporters with fidelity issues |
+| Site builders                 | Framer, Webflow                                          | Own proprietary runtime; you don't get _your_ React components/code                                                                  |
+| Incumbent                     | Figma (Dev Mode, Make)                                   | Enormous stickiness, but generic AI output and a handoff "tax"; not designer-owned code from your system                             |
+
+**White space (the bet):** a **designer-first** canvas where a **bring-your-own design system is the source of truth** and AI is **constrained to it**. 🟡 _(Subframe is the nearest competitor; a real teardown is still owed to harden the "unowned" claim — see 🔴 A4.)_
+
+## North Star Metric
+
+**Weekly shipped screens** — screens whose code is exported and actually used, per active designer. No repo integration yet, so **proxy** it via an explicit "mark as shipped" + design-partner check-ins. 🟡
+
+- **Activation:** first screen composed from the user's _own_ tokens + components and exported. 🟡
+- **Trust bar (primary, engineer-judged):** real PRs at design partners — merge rate + % LOC changed pre-merge. The right judge is the engineer, not the designer's self-report. 🟢
+- **Wedge-usage guardrail:** % of exported screens composed _majority_ from the user's mapped/real components (not stock base kit) — so we can't "pass" by validating a re-themed generic kit. 🟡
+
+## Business model (compressed — full Phase 5 deferred)
+
+Per-seat SaaS for designers with a usage component on AI compose; land bottom-up with individual designers, expand to design teams. Not yet modeled. 🔴
+
+---
+
+## Validation gate status (Phase 1) — **NOT formally cleared**
+
+The pain is real and well-sourced 🟢, but the core belief rests on unvalidated assumptions. Per Founder OS discipline, the MVP in the PRD is scoped as **the cheapest way to test the core bet**, not a green-lit build. Run the validation experiment (see PRD §Risks/Validation) in parallel with any build.
+
+### Riskiest assumptions to validate
+
+- 🔴 **A1 — Designers want to compose/own real code.** Many want the _outcome_ (their design shipped faithfully, fast), not to own a codebase. Evidence is genuinely mixed; some designers report AI codegen is _slower_ than just designing.
+- 🔴 **A2 — Designers will adopt a new canvas.** Figma stickiness is structural (libraries, network effects, org process); real-world switching is usually _additive / per-phase_, not a replacement.
+- 🔴 **A3 — The bottleneck is tooling, not governance.** Practitioners repeatedly say design-system drift/sync is a people-and-process problem a tool alone won't fix.
+- 🔴 **A4 — "BYO design system → real code" is genuinely unowned.** Competitive teardown was deferred this pass; Subframe is close. Harden before fundraising claims.
+
+### Validation gate (sequenced, with kill criteria — run before/at the start of build)
+
+1. **Concierge real-PRs (primary):** hand-build 5 partners' screens from their own systems and open **real PRs** against their repos. **Pass** ≥3/5 merged with <10% LOC changed; **kill/rethink** if <2/5 or reviews are structural. Tests A1 _and_ the trust bar with the correct judge, with zero product code.
+2. **Clickable-mock task test:** 5 designers complete the core task on a Figma prototype of the editor. **Pass** ≥4/5 unaided. Tests A2 (will they adopt a new canvas) before the canvas is built.
+3. **Fake-door demo** vs. a v0-style generic control: **pass** waitlist conversion ≥2× control.
+4. **Competitor teardown** (Subframe et al. — owed from Phase 2) to harden A4. No code needed.
+5. **10 problem interviews** with design-system leads probing A1 and A3.
+
+> Founder OS discipline: only the token-engine + shared-runtime spike should run concurrently with these. "Build in parallel with validation" is how the gate gets quietly bypassed — the red-team flagged exactly this.

docs/product/design-app-prd.md

@@ -0,0 +1,205 @@
+# PRD — Veect MVP · v2
+
+> **⚡ v3 PIVOT NOTE (2026-07-10, updated for spec rev 1.2) — read first.** Distribution pivoted from cloud SaaS to **repo-native**, delivered as a **standalone app + Docker image**: connect a remote repo (GitHub/git URL) or local checkout; `veect.config.json` points at component folders; git worktree per design project (app-managed, repo untouched); SQLite + JSON-in-branch persistence; **Publish** pushes `veect/<slug>` for an ordinary PR. The npm-in-repo package is a later distribution. **Prototype note:** the built editor's multi-view frames (desktop/tablet/mobile clusters) supersede F3's "desktop breakpoint only," and its two-way code grammar supersedes F5's read-only code view — see `veect-design-spec-current.md` + `veect-ui-gap-spec.md`. **`veect-technical-spec.md` is now the authoritative build document.** Superseded here: F1 (token-file import → tokens read from the repo), F2's mapping half (components are the repo's real ones by construction), F7's zip export (output = commits on a branch), F8 (auth/cloud). Still authoritative here: the wedge, personas, JTBD, F3–F6 canvas/AI/preview behavior, F9 craft layer, §8 out-of-scope discipline, §13 validation gate (V1 concierge-PR test now runs _through the tool's own output_), and all Given/When/Then that concern editor behavior.
+
+_Founder OS · Phase 6 (MVP Definition) · 2026-07-09_
+_Companion docs: `company-context.md` (strategy) · `design-brief-veect.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. Veect 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) — Veect 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: Veect 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 "Veect 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 Veect 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-veect.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** (Veect 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 Veect'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** (Veect → 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.

docs/product/design-brief-veect.md

@@ -0,0 +1,281 @@
+# Design Brief — "Veect" (working name) · v2
+
+_A hand-off for a design agent / designer. Founder OS · Phase 6._
+_Companion docs: `company-context.md` (strategy) · `design-app-prd.md` (MVP scope)._
+_v2 changes: folded in an adversarial design review (fixed art-direction contradictions, added missing screens/states, spec'd the AI interaction) **and integrated Impeccable** (impeccable.style) as Veect's craft standard._
+_**v3 (2026-07-10): the interactive prototype + codebase now exist and are ground truth** — see `veect-design-spec-current.md` (authoritative design language: the monochrome ink instrument) and `veect-ui-gap-spec.md` (the remaining work: repo-connect, publish, environment surfaces + editor deltas). This brief remains authoritative for **intent** (north star, principles, journeys, signature moments, voice, a11y) — where §11's old art direction conflicts with the design spec, **the design spec wins**._
+_Confidence: 🟢 verified · 🟡 reasoned · 🔴 assumption to validate._
+
+---
+
+## 0. On Impeccable (how it shows up in this brief)
+
+**Impeccable** (impeccable.style, by Paul Bakaus — open-source) is a _design language / "skill" for AI harnesses_ (Claude Code, Cursor) whose entire purpose is to **stop AI-generated UIs from looking like AI** — to replace generic "slop" with real craft. 🟢 It's structured as a design language (rules) plus sub-skills for **building, "polishing" (critiquing + fixing), and teaching** good design. 🟡
+
+It matters to Veect **twice**, and both are load-bearing:
+
+1. **As Veect's own craft standard** — the UI you design from this brief must itself be Impeccable-grade (see §11.5 Craft Standard + the checklist in §20). Veect dogfoods the rules it sells.
+2. **As a product capability** — Veect doesn't just constrain output to the user's _system_; it holds output to a _craft standard_ (an Impeccable-style ruleset) via a **Polish** pass, so results are **on-brand AND high-craft**. See PRD F9/F10. This is the deepening of the wedge: not just "your components," but "your components, arranged well."
+
+> ⚠️ **Fidelity note:** I could not fetch Impeccable's verbatim `DESIGN.md` this session (fetch was rate-limited). The craft rules in §11.5/§20 reflect Impeccable's documented anti-slop philosophy plus established craft; treat exact numeric values as 🟡/🔴 and reconcile them against the real Impeccable ruleset (or install the Impeccable skill) before locking. Sources listed at the end.
+
+## 1. Header / how-to
+
+- **Product:** **Veect** — decided 2026-07-10. Pronounced **VEEKT**, rhymes with _piqued_ (lock this in all voice work). Lowercase `veect` in CLI/code contexts.
+- **One-liner:** A design-system-native canvas that turns your own tokens and components into real, production-ready React — held to a craft standard so it never looks generic.
+- **Surfaces:** Desktop web app (primary). Read-only shared preview link (any device) — _fast-follow, not MVP_ (see PRD). No native mobile app.
+- **Who it's for:** Product/UI designers and design-engineer / design-system leads at startups & scale-ups that already have a design system and ship a React web product.
+- **How to use this brief:** §3–§7 = point of view + experience; §8–§9 = build map (IA + screens + states); §10–§14 + §20 = the craft bar. Recommendations are decisive defaults you may improve on, not pixel law. Everything 🔴 must be validated (see §19).
+
+## 2. Product snapshot
+
+- **What it is:** A visual canvas where a designer composes screens from **their own** components and tokens, gets **real React + Tailwind** out, and where a **craft layer (Impeccable)** keeps the result high-quality.
+- **The wedge:** v0 / Lovable / Bolt / Figma Make generate _generic_ UI and throw your design system away. Veect makes your design system the **source of truth** and constrains everything — including AI — to it, **then polishes to a craft standard**.
+- **Emotional promise:** _"My design system is alive, what I make is what ships — and it looks like we hired a great designer, not an AI."_ Relief, trust, quiet pride.
+
+## 3. Design north star
+
+> **Every screen must make the designer trust that what they see is exactly what will ship — built from their own system, arranged with real craft, with nothing lost in translation.**
+
+If a screen introduces doubt ("is this the real component? will the code match? is this on-brand? does this look generic?"), it has failed. **Trust is the product; craft is how trust is earned.**
+
+## 4. Design principles (opinionated, product-specific)
+
+1. **Your system is the hero; our chrome is stagehand.** Veect's UI is deliberately quiet, near-monochrome, recessive — a matte camera body around a bright photograph — so the user's brand dominates. _Why: the #1 complaint about competitors is off-brand output; our UI must never visually compete with the user's brand._
+2. **Real, never represented.** The canvas renders the actual coded component at actual fidelity; preview = the same runtime as export. _Why: "roughly how it'll look" is the lie that makes handoff lossy._
+3. **Show the code — trust is earned in the open.** Real code is a keystroke away, not a buried export; clean code that imports _their_ components converts skeptics. _Why: designers have been burned by screenshot-to-code; visible honest code is the proof._
+4. **AI proposes in your language; the system disposes.** AI output is always in the user's components/tokens, always shows provenance, always reversible; when it can't map, it _says so_ — it never falls open to generic markup. _Why: constrained-to-your-system is the entire differentiator._
+5. **Craft is not optional — Impeccable-grade or it doesn't ship.** Every surface (ours and the user's output) meets the craft checklist in §20: real type hierarchy, strict spacing, purposeful color, optical alignment, designed empty/error states. Generic is a bug. _Why: "on-brand but sloppy" still loses; the whole promise is that the output is genuinely good._
+6. **Flow is a latency budget, not a slogan.** The core loop is keyboard-first and sub-frame (<16ms). _Match Figma's canvas responsiveness or don't ship the canvas._ _Why: designers forgive missing features, never lag in the core loop._
+7. **Honest about fidelity.** Where something is prototype vs. production-ready, the UI says so plainly; never over-promise "shippable." _Why: over-claiming code quality loses the engineer — and the engineer is the veto._
+
+## 5. Users & context (personas condensed _for design_)
+
+|                    | **Maya — Product Designer (primary)**                                             | **Devon — Design-Systems / Design-Engineer Lead (champion + gatekeeper)** |
+| ------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| Device/env         | 27–32" display, macOS, Figma muscle memory, headphones-in flow                    | Dual monitor, VS Code + Figma, **reads the generated code**               |
+| Emotional state    | Impatient with handoff, burned by generic AI output, protective of brand          | Skeptical of design-to-code claims, allergic to messy code                |
+| Proficiency        | Expert in design tools; reads code, writes little                                 | Fluent React/Tailwind; owns the component library + the repo veto         |
+| Accessibility      | Long sessions → dark mode, low glare; keyboard-heavy                              | Scrutinizes output a11y/contrast                                          |
+| Artifact they hold | Brand/visual decisions; often **no clean token file** (it's in Figma or the repo) | The **real coded components + tokens** (Tailwind config / repo)           |
+| What wins them     | On-brand, high-craft result in minutes, no relearning                             | Code that imports _their_ components and passes review                    |
+
+> Design implication (from review): **Maya frequently does not own a DTCG/Tailwind file** — it's Devon's. Onboarding must not dead-end on "upload your tokens." See §9.2 no-file path.
+
+## 6. JTBD → top tasks
+
+| Job                                                                             | Concrete tasks the UI must make effortless                   |
+| ------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| Design finished → build matches without policing pixels → stop redlining        | Compose from real components; see live code; export exact    |
+| System changes → design & code stay in lockstep → "the library" means one thing | Re-import changed tokens; see impact/diff; apply safely      |
+| Need a screen → ship it myself → move at idea-speed                             | Prompt or drag; export runnable code                         |
+| Using AI → build from _my_ system → on-brand, not throwaway                     | Constrained AI compose with provenance; graceful "can't map" |
+| Result looks generic → make it genuinely good → look designed, not AI           | One-click **Polish** to the craft standard                   |
+
+## 7. Core user journeys (name the "aha")
+
+**A. Onboarding → first value (target <20 min, rev 1.2: repo-connect flow).**
+Open the app → **Connect a repository**: GitHub device-code sign-in → pick the repo (or paste a git URL / choose a local folder) → Veect clones + installs (honest, first-class progress — this is minutes, design it) → repo has `veect.config.json`? straight in; **no config? the wizard**: browse the repo tree, pick component folders visually, confirm detected framework/tokens → _the component library and tokens load from the repo and the canvas re-themes to their brand_ → compose a first section (drag or ✦) → **Polish** → **Checkpoint → Publish** → the PR link. **The aha: "these are _our actual components_ — and that's a real branch my team can review."**
+
+**B. The core loop (daily).**
+Open project → compose/adjust on canvas (drag, props, tokens) ⇄ glance at live code ⇄ AI compose a section ⇄ **Polish** ⇄ export. Tight, keyboard-first, low-latency — _sketching that happens to produce production code_.
+
+**C. Habit / expansion.**
+Map/save components → reuse across screens/projects → **re-import updated tokens** (System update, §9.8) → (fast-follow) share read-only prototypes; (v2) sync to repo. The user's mapped library + saved patterns is the retention flywheel.
+
+## 8. Information architecture
+
+**Surfaces:** (1) Home/Projects · (2) Editor · (3) Preview (full-screen + fast-follow shared link) · (4) **Settings** (system, mappings, account).
+
+**Editor layout (persistent 3-pane + dual companion):**
+
+```
+Top bar:  Project ▾ · breakpoint [Desktop] · ⟳ Preview · ✧ Polish · </> Code · ⇪ Export · avatar
+Left rail:  Pages/Layers · Component Library · Tokens        (switchable)
+Center:     Canvas (frames, direct manipulation)  +  ✦ AI compose bar (docked bottom)
+Right rail: Inspector (props · tokens · layout for selection)
+Companion:  Code panel (right split / bottom drawer, toggle </>)  ·  Polish panel (✧, right)
+```
+
+**Two command surfaces, reconciled (review fix):** **⌘K = commands/navigation** (find, jump, run action); **✦ AI bar = generative** (compose/modify from your system). Typing `✦` inside ⌘K routes to the AI bar. Never two overlapping "type here to make UI" fields.
+
+**Screen map:** Home → Editor → {Component editor (focused), Token manager, **System update / re-import**, Polish, Preview, Code/Export, Settings}.
+
+## 9. Key screens (purpose · primary user · key elements · **all states**)
+
+### 9.1 Home / Projects
+
+- **Purpose:** get into work fast; hold projects + systems. **Elements:** project grid (live real-render thumbnails), New project, Bring a design system, recent, search.
+- **States:** **Empty** → warm single-CTA "Bring your design system to life" + 20-sec inline demo loop. **Loading** → skeletons matching grid rhythm. **Error** → inline retry. **Populated** → real-render thumbnails.
+
+### 9.2 Onboarding — Connect your repository _(rev 1.2: replaces the file-upload flow)_
+
+- **Purpose:** get from zero to the repo's live system. **Elements:** three connect paths presented as equals — **GitHub** (device-code card: the code large and copyable, "waiting for approval" state), **git URL** (HTTPS+token / SSH-via-agent, with a plain-language access explainer), **local folder** picker; then **clone + install progress** (real stages: cloning → installing → reading components — with honest time feel, never an indeterminate spinner for minutes); then **the config wizard** if the repo has no `veect.config.json`: a repo-tree browser with visual multi-select of component folders, detected framework/tokens shown for confirmation, "we'll include this config in your first published branch."
+- **States:** **Choose source** → three calm cards. **Device-code wait** → code + "approve in browser" with retry. **Auth failed / no access** → specific, kind, actionable ("This token can't see acme/shop — ask for read access or try SSH"). **Read-only connect** → allowed, with a quiet banner ("You can design and checkpoint; Publish needs write access"). **Cloning/Installing** → staged progress, cancellable. **Wizard** → tree browser, folder multi-select, confirm chips. **Env needed** → detected `.env.example` → the Environment panel (§9.12), skippable with consequences stated. **Success** → components + tokens stream into the library and **the canvas re-themes from the repo's own system** (Signature Moment #1) + "acme/shop is live."
+
+### 9.3 Editor / Canvas (the product)
+
+- **Purpose:** compose from real components; the home of flow. **Elements:** frames, drag-drop, auto-layout stacks (direction/gap/padding = tokens), multi-select, snap/align guides, undo/redo, ⌘K, ✦ AI bar, ✧ Polish.
+- **States:** **Empty frame** → ghost placeholder + hint ("Drag a component, or ✦ describe this screen"). **Selection** → inspector + guides. **Dragging** → snap lines, live auto-layout reflow. **AI proposing** → staged **ghost layer** of _real_ components (see §10.6), provenance chips streaming in. **Polish running** → non-blocking scan with issue markers. **AI can't map** → inline first-class prompt (Signature Moment #6), not a dead error. **Save states (review fix):** autosave tick · **saving** · **offline (read-only banner)** · **reconnecting** · **conflict (two tabs)** resolution. **Latency guard:** all direct manipulation <16ms/frame.
+
+### 9.4 Component Library (manage · map · define) — _fully specified (was the weakest section)_
+
+- **Purpose:** the user's system as objects; **map** base-kit → their real coded components, and define reusable patterns. This is the retention flywheel and the wedge-critical mapping surface.
+- **Elements:**
+  - **Library list:** base kit · **mapped** components (linked to the team's real import path + prop names) · user-saved patterns; each shows usage count + a **mapping status** (mapped / unmapped / drifted).
+  - **Component detail:** a **variant matrix** (variant × state) with a **live state grid** (default / hover / focus / active / disabled / loading) rendered from the real runtime; a **token-binding panel** (which token drives which property); **prop editor**.
+  - **Mapping panel (wedge-critical):** map "Veect Button" → `@/components/ui/Button`, map props (`variant→kind`, etc.); preview the exact import the export will emit.
+  - **New component from selection** (save a composed pattern).
+- **States:** **Empty (user)** → "You've got the base kit — map it to your real components, or save your first pattern." **Mapping** → guided prop-matching with live code preview. **Editing variant** → focused mode, live state grid. **Drift flag** → quiet non-blocking marker; clicking opens **Impact review** (what changed, where used, apply/ignore). **Success** → component usable on canvas; export references the real import.
+
+### 9.5 Tokens / Design-system panel
+
+- **Purpose:** colors, type, spacing, radius, shadow as named tokens = single source of truth. **Elements:** grouped token lists, edit-in-place, **live contrast check** on color pairs, "where used" per token.
+- **States:** **Empty** → import or seed defaults. **Editing** → everything bound updates live (canvas + code) — the **token ripple** (Signature Moment #5). **Contrast fail** → inline AA warning with ratio + fix (icon+text, not color alone). **Success** → change ripples visibly.
+
+### 9.6 Prototype / Preview
+
+- **Purpose:** prove "what you see is what ships." **Elements:** full-screen live render, breakpoint switch, **real hover/focus/active states** (free from real components), device frame optional. _(Frame-to-frame click-through linking is cut from MVP — Figma-parity creep — see PRD §8.)_
+- **States:** **Loading** → fast real-render (no fake spinner). **Interactive** → cursor + keyboard, visible focus rings. **Error** → graceful "couldn't render — open editor." **(Fast-follow) Shared view** → clean, no editor chrome; link lifecycle: active / revoked / expired / 404.
+
+### 9.7 Code / Export
+
+- **Purpose:** earn trust; hand off. **Elements:** file tree, syntax-highlighted **read-only** React+Tailwind, token file, "Copy component," "Download project (.zip)." Code visibly **imports the user's mapped components** and references token vars; **fidelity badge** ("Production-grade" / "Prototype-grade").
+- **States:** **Generating** → streamed formatting. **Ready** → copy/download + honest badge. **Export success** → "Runs with `npm i && npm run dev`." **Error** → specific, retryable. **Unmapped-components warning** → "3 components aren't mapped to your repo yet — export will include Veect defaults for these. Map them?"
+
+### 9.8 System update (re-import changed tokens) — _new screen (review fix; closes JTBD #2)_
+
+- **Purpose:** keep design & code in lockstep when the system changes. **Elements:** re-import tokens → **diff** (added / changed / removed), **impact preview** ("affects 14 components across 3 screens"), one-click **apply with undo**, per-change accept/skip.
+- **States:** **No changes** → "Your system is up to date." **Diff** → grouped changes with before/after swatches. **Breaking change** → flags components that would break; safe-apply guidance. **Applied** → ripple + "System updated · undo."
+
+### 9.9 Settings — _new (was in IA, unspecified)_
+
+- **Purpose:** manage system source, component **mappings**, craft standard, account. **Elements:** design-system source, mapping table, **craft standard selector** (Veect default / Impeccable / custom), export defaults, team/billing. **States:** standard load/error; mapping health summary.
+
+### 9.10 Polish panel (Impeccable-driven) — _new product surface_
+
+- **Purpose:** critique the current screen against the craft standard and fix, in your tokens/components. **Elements:** ranked issue list (spacing off-scale, weak hierarchy, contrast fail, misalignment, orphaned state), each with a **why** (teach) and a **one-click fix**; "Polish all"; before/after.
+- **States:** **Clean** → "Impeccable. Nothing to fix." (earned, not flattering). **Issues** → grouped by severity, each fix previewable. **Applying** → animated corrections. **Can't auto-fix** → explains the manual change needed.
+
+### 9.11 Publish & branch status _(new in rev 1.2)_
+
+- **Purpose:** turn a checkpoint into a reviewable PR without the designer knowing git. **Elements:** per-project branch card (`veect/checkout-flow` · commits · behind-base indicator), **Checkpoint** and **Publish** as distinct, honest verbs; after publish, the **compare/PR deep link** as the hero action; "Update from base" with plain-language explanation.
+- **States:** **Unpublished checkpoints** → gentle nudge chip. **Publishing** → progress. **Published** → PR link + "your team can review this now." **Push rejected (no write access / protected)** → specific fix path, patch-export escape hatch. **Behind base** → staleness count + Update action. **Conflict on update** → read-only conflict view, "ask a developer" guidance — never a merge editor in v1.
+
+### 9.12 Environment & connection health _(new in rev 1.2)_
+
+- **Purpose:** the app's honest answer to "why is preview broken?" **Elements:** per-workspace env form (keys from `.env.example`, values masked, stored encrypted, never committed — say so in-UI); connection card (provider, access level, last fetch); doctor strip (git, disk, adapter health) with one-line fixes.
+- **States:** **Missing env** → adapter crash translated to a human sentence ("Preview needs `DATABASE_URL` — add it here; it stays on this machine"). **Values saved** → adapter restarts automatically. **Token expired / revoked** → re-auth flow inline. **Disk pressure** → per-workspace usage + archive suggestions.
+
+## 10. Signature moments (the award bar — craft these first)
+
+1. **"The system comes alive."** During onboarding, as tokens resolve, the neutral base kit **re-themes to the user's brand in one crafted ~700ms cascade** (colors, type, radius sweeping across components). The _"those are mine"_ moment. The single most important animation in the product.
+2. **"What you see is what ships."** Live synced split: nudge a component on canvas and the **real code updates in lockstep**, with the one reserved **live-green** indicator affirming preview = code = export.
+3. **"On-brand in one prompt."** Type _"a pricing section, three tiers"_ → it assembles from **their** Card/Button/Text in **their** tokens, with provenance chips — visibly _not_ the generic slate/Inter output expected from v0.
+4. **"The clean handoff."** Export becomes a readable file tree that **imports their real components** — a confident, almost anticlimactic _"of course it's real."_ Delight through trustworthiness.
+5. **"Change once, everywhere."** _(new)_ Edit `brand-500` in the token panel and watch a **~400ms ripple** re-theme every affected component on canvas _and_ highlight the changed code lines. The best possible demo of "system as source of truth"; the daily-use aha.
+6. **"The graceful refusal."** _(new — the differentiator, as a moment not an error)_ AI hits something your system can't express → a crafted, calm beat: _"You don't have a component for this yet. Compose one from your primitives?"_ with its own motion and copy. An error state elevated to a signature interaction is an award-grade move — and it's the exact behavior that separates Veect from tools that fake it with generic markup.
+
+## 11. Visual & art direction — **v3: SUPERSEDED by the shipped design language**
+
+> **The implemented design language wins.** The prototype resolved this section's recommendations into something sharper than what was written here — the **monochrome ink instrument**: no chromatic accent at all (the accent IS the ink, `#161513`/`#F4F4F2`), warm paper neutrals, radius **2px** everywhere in chrome, hairline separation with zero floating shadows, **Instrument Sans** (UI) + **Fragment Mono** (engraved labels) + the customer's own font for canvas content, hand-drawn 16-grid icons, **amber reserved exclusively for AI-scope affordances**, muted `--live` green for status, dark by default. **The authoritative tokens, values, and rules live in `veect-design-spec-current.md` §2 — design all new surfaces from that file, not from this section's history.**
+>
+> What survives from this section as still-binding intent: the **personality** ("a precise, calm instrument — matte body around a bright photo"); **color never the only signal** (icon + label always); the **canvas art-board theme is independent** of app chrome so light brands aren't judged on black; chrome type never competes with the customer's canvas font; and the data-viz restraint rule below.
+>
+> **Wordmark (corrected from the naming decision):** the mark is the lowercase `veect` wordmark closed by the **square ink terminal** — "the vector point" (design spec §2.1). No pictorial mark. _(The earlier ee-pair concept is retired; the pair/parity story lives on in Signature Moment #2's canvas=code lockstep, not in the logotype.)_
+
+- **Data-viz (light use — usage counts, contrast meters, polish scores):** monochrome + single accent; meters and small bars, not chart junk.
+- **Data-viz (light use — usage counts, contrast meters, polish scores):** monochrome + single accent; meters and small bars, not chart junk (follow standard restrained categorical palette if a dashboard grows).
+
+### 11.5 Craft standard — Impeccable alignment
+
+Veect's UI (and the output it generates) must pass the craft checklist in **§20**, derived from Impeccable's anti-slop philosophy: intentional type hierarchy (real size _and_ weight contrast, not just size), strict spacing scale, purposeful and restrained color, true visual hierarchy and focal point, optical alignment/correction, depth used sparingly, motion with purpose, and **every state designed** (empty/loading/error/success are where craft shows). 🟡 _Reconcile exact rules with the real Impeccable ruleset before locking (§0 note)._
+
+## 12. Motion & micro-interactions
+
+- **Character:** precise, quick, spring-based for direct manipulation; motion clarifies causality, never decorates.
+- **Params (review fix — buildable, not vibes):** drag/direct-manipulation spring ≈ **stiffness 210 / damping 24**; micro-feedback **90–160ms** ease-out; panels/drawers **180–240ms**; **re-theme reveal 600–800ms** (the one indulgent moment); **token ripple ~400ms** propagation with synced code-line highlight; **AI placement stagger ~90ms** per element.
+- **`prefers-reduced-motion`:** honor fully — re-theme cascade → crossfade; ripple → instant; disable springs/parallax. No motion is load-bearing for meaning.
+
+## 13. Voice & microcopy
+
+- **Tone:** precise, calm, designer-native; speak in **components, tokens, frames, variants** — never "divs/markup." Confident, never hypey; honest about fidelity; **explains _why_** when it fixes something (the Impeccable "teach" instinct).
+- **Do words:** compose, system, tokens, components, live, real, ships, export, on-brand, polish, craft.
+- **Don't words:** magic ✨-as-crutch, "just," "simply," "AI-powered," "pixel-perfect," "website builder," "slop."
+- **Example strings:** onboarding success → _"Your system is live."_ · export → _"Ready to ship. Runs with `npm i && npm run dev`."_ · AI can't map → _"You don't have a component for this yet. Want me to compose one from your primitives?"_ · polish clean → _"Impeccable. Nothing to fix."_ · polish fix → _"Bumped this to your 24px step and matched your heading weight — here's why."_
+
+## 14. Accessibility & responsive
+
+- **Target:** WCAG 2.2 AA for Veect's own UI (the palette in §11 is tuned to pass — a tool that _sells_ contrast checking cannot fail its own). Full keyboard operability of the canvas; visible focus rings; ARIA for panels/trees; respects reduced-motion + prefers-color-scheme.
+- **Color independence:** every status (live/warn/error, contrast/polish pass/fail) pairs icon/label with color.
+- **Output a11y:** surface **contrast checks on the user's token pairs** at import and in the token panel; the base kit ships **semantic HTML + ARIA** so exported code passes Devon's review (not just contrast).
+- **Chrome-vs-brand collision policy (review fix):** the iris selection outline and live-green dot must stay legible when the user's brand _is_ violet or green — use a **dual-tone selection outline** (light/dark stroke pair) and always pair the live indicator with an icon+label; test chrome over violet/green/black/white canvases.
+- **Responsive (the app):** desktop-first, optimized ~1280–2560px; graceful ≥1024px; below → "Veect is best on desktop." Generated **output** is responsive-ready (auto-layout), with the second breakpoint a near-term follow (PRD).
+
+## 15. Technical & platform constraints (for design awareness)
+
+- **Stack:** desktop web app; output is **React + Tailwind**, tokens as CSS vars / Tailwind theme. Canvas, preview, and export share **one component runtime** → visual parity is by construction; design assuming no divergent mock rendering.
+- **Wedge-critical:** export emits the user's **real, mapped components** (import paths + prop names), not Veect-internal clones — design the **mapping** surface (§9.4) as first-class.
+- **Constraint that shapes UX:** AI is hard-limited to the project's component/token registry → design the **"can't map / compose from primitives"** path (Moment #6) and the **Polish** loop as first-class flows.
+- **Budgets:** <16ms/frame canvas on a 50-_node_ screen (define node = one rendered element instance, incl. nested primitives); AI first paint <2s.
+
+## 16. Design success metrics
+
+- **Activation:** % of new users who compose a screen from their own system **and export** (target ≥40% 🔴).
+- **Time-to-first-value:** signup → first exported on-brand screen (<20 min median 🔴; guarded by the no-file onboarding path).
+- **Craft lift:** Polish-panel issues per screen trend down; % screens exported "clean" (no open craft issues).
+- **Task success:** compose-a-known-section success ≥90% in usability tests 🟡.
+- **Trust/delight:** SUS ≥80 🟡. _(The primary trust metric — would an engineer merge it — is measured on the eng side; see PRD §3.)_
+
+## 17. Deliverables expected (from the design agent)
+
+1. **User flows** for the 3 journeys (§7), incl. the **no-file onboarding** and the **system-update** loop.
+2. **Low→mid-fi wireframes** for all screens in §9 (9.1–9.10), each with empty/loading/error/success (+ save/offline/conflict for the editor).
+3. **Hi-fi designs:** onboarding (incl. re-theme frames), Editor, Component Library (variant matrix + mapping + drift), Tokens, System update, Polish panel, Preview, Code/Export, Settings.
+4. **Veect's own design system** (tokens, recessive-chrome components, dark+light) — dogfood the concept; ship it passing §20.
+5. **Prototypes + motion specs** for the 6 signature moments (§10).
+6. **Redlines** for the two hardest interactions: canvas↔code sync, and the constrained-AI **propose→accept / graceful-refusal** flow (§10.6).
+7. **Microcopy deck** (the voice in §13 across states) and **a11y-annotated** redlines.
+
+## 18. Inspiration / benchmarks (emulate the _quality_, do **not** clone)
+
+- **Linear** — precision, keyboard-first speed, restrained dark UI, ⌘K discipline.
+- **Figma** — canvas calm, direct-manipulation fluency, inspector clarity (the muscle memory to respect).
+- **Vercel/Geist & Raycast** — code-as-first-class-object; velocity — _but note (review):_ leaning on these too hard reproduces the 2026 default uniform; borrow the discipline, not the skin.
+- **Subframe** — nearest competitor; study its visual-builder→React flow, then out-design it on "your own system + craft is the source of truth."
+- **Impeccable (impeccable.style)** — the craft bar itself; the anti-slop standard Veect must meet and enforce.
+- **One off-cluster reference (review fix):** **Teenage Engineering / broadcast-console & camera UI** — for one ownable, tactile detail that escapes the sameness. Cash the "instrument" metaphor into form: e.g., **engraved-label token chips** and **dial-like prop steppers** for numeric tokens.
+  > Do not clone any of these. The synthesis — _a recessive, precise instrument that makes the user's brand and real, well-crafted code the hero_ — is Veect's own.
+
+## 19. Open design questions (validate before locking — carries strategy 🔴s)
+
+- 🔴 **A1 (owns-code):** How much _code surface_ do designers want? Design two framings — "export & hand to dev" (code as proof) vs. "you own/edit the code" (code as workspace) — and test which converts. Changes how prominent the code panel is.
+- 🔴 **A2 (Figma coexistence):** replacement canvas or per-phase tool alongside Figma? Recommend designing for **coexistence** first; validate with a clickable-mock task test before building the canvas.
+- 🔴 **A4 (vs Subframe):** make the "system + craft as source of truth" differentiation _visible_ in the UI before hi-fi.
+- 🟡 **Mapping vs authoring:** MVP leans on **mapping to real components**; how much in-app authoring does Devon expect? Design mapping as first-class now, authoring as a path.
+- 🔴 **Impeccable rules (fidelity):** reconcile §11.5/§20 with the verbatim Impeccable `DESIGN.md`; decide whether Veect _embeds the Impeccable skill_ or ships a compatible ruleset.
+- 🟡 **Fidelity labeling:** validate "Production-grade / Prototype-grade" language with real engineers.
+
+## 20. Appendix — Craft checklist (the "Impeccable-grade" bar)
+
+Every screen (Veect's UI _and_ generated output) should pass:
+
+- **Type:** a real hierarchy via size **and** weight (not size alone); ≤2 families; consistent scale; no default-Inter look.
+- **Spacing:** everything on the 4px scale; intentional whitespace; related things grouped, unrelated things separated; no arbitrary gaps.
+- **Color:** restrained; one purposeful accent; neutrals do the work; color never the only signal; AA contrast.
+- **Hierarchy:** one clear focal point per screen; secondary/tertiary genuinely de-emphasized; alignment optical, not just mathematical.
+- **Depth:** used sparingly and consistently (one shadow tier); borders hairline; radius on-scale.
+- **Motion:** purposeful, fast, causal; reduced-motion honored.
+- **States:** empty/loading/error/success all designed; empty and error states are craft showcases, not afterthoughts.
+- **Detail:** optical corrections, consistent icon weight, no orphaned or truncated content, real content not lorem.
+  > 🟡 Align exact thresholds with the real Impeccable ruleset (§0).
+
+---
+
+### Sources (Impeccable)
+
+- Impeccable — impeccable.style (site, docs, "Designing with Impeccable"): https://impeccable.style/ · https://impeccable.style/docs/impeccable/ · https://impeccable.style/designing/
+- GitHub — pbakaus/impeccable (incl. `DESIGN.md`, `SKILL.md`): https://github.com/pbakaus/impeccable
+- Overviews: https://abduzeedo.com/impeccable-open-source-ai-design-skill-better-ui · https://emelia.io/hub/impeccable-ai-design-skill
+
+_End of brief v2. Pair with `design-app-prd.md` for scope and acceptance criteria. Update as 🔴 items validate._

docs/product/founder-os-audit.md

@@ -0,0 +1,40 @@
+# Veect — Founder OS Full-Project Audit
+
+_Founder OS phase sweep · 2026-07-10 · requested by founder ("make sure we are not missing something")_
+_Verdict up front: **the build is ahead of the validation.** Phases 6–7 are excellent and twice red-teamed; Phase 1's exit gate has never been cleared and Phase 5 (business model) doesn't exist. Neither blocks the M0 build — both block launch and fundraising._
+
+## Phase-by-phase status
+
+| #   | Phase              | Status                    | What exists                                                                                                                                                                                                  | What's missing                                                                                                                                                                                                                                                                                  |
+| --- | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Idea Validation    | 🔴 **GATE OPEN**          | Strong secondary evidence (92% handoff pain, Figma Make complaints, market conceding the DS-fidelity gap) 🟢; assumptions mapped A1–A5                                                                       | **Zero primary validation run.** V1 concierge-PRs, V2 mock task test, V3 fake-door, V5 interviews — all designed (PRD §13, with kill criteria), none executed. A1 (designers want code) and A4 (wedge unowned) still 🔴                                                                         |
+| 2   | Market Research    | 🟡 compressed             | Competitive frame (v0/Lovable/Bolt/Figma Make/Subframe/Onlook/Storybook) from knowledge; naming hunt incidentally proved the space is being funded monthly (Legato $7M, Riff €14M — _vibe-coding adjacents_) | Deep teardown (owed for A4, esp. **Onlook + Subframe + Storybook-AI**); TAM/SAM/SOM never computed (research agents were declined) — needed for fundraising, not for building                                                                                                                   |
+| 3   | Customer Discovery | 🟡 compressed             | Personas Maya/Devon (secondary-sourced), JTBD ×4, buying committee sketch                                                                                                                                    | No primary interviews; buying committee unvalidated (esp. security veto vs. the new "app clones your repo + device-flow token" model — **rev 1.2 makes discovery MORE urgent**: will enterprises allow it?)                                                                                     |
+| 4   | Product Strategy   | 🟢 solid                  | Dunford positioning, system+craft wedge, NSM (weekly shipped screens), differentiation vs all clusters                                                                                                       | Roadmap beyond v1 (light); category narrative for launch                                                                                                                                                                                                                                        |
+| 5   | Business Model     | 🔴 **MISSING**            | One deferred note ("open-core, Storybook→Chromatic analogy")                                                                                                                                                 | **Nothing modeled.** Rev 1.2 made this load-bearing: standalone app + Docker forces the licensing/monetization decision (OSS core? free app + paid team features? Docker = paid tier?). "Build source-available" is in the spec on an assumption. Pricing, value metric, unit economics: absent |
+| 6   | MVP Definition     | 🟢 done                   | PRD v2 + pivot notes; scope discipline held through two pivots; out-of-scope list load-bearing                                                                                                               | PRD partially superseded by spec (by design); refresh after M4 reality                                                                                                                                                                                                                          |
+| 7   | Technical Planning | 🟢 done, twice red-teamed | Spec rev 1.2.1: standalone+Docker, remote-first connections, worktrees, adapters, AI, milestones M0–M7 with acceptance                                                                                       | **Impeccable ruleset still unreconciled** (F9/craft layer cites philosophy, not the verbatim DESIGN.md — fetch was blocked); fixtures to build                                                                                                                                                  |
+| 8   | Go-to-Market       | 🟡 head start             | Positioning exists (P4) **and a full landing page is BUILT** (`Veect Landing.dc.html` — hero, proof strip, wedge, refusal demo, Polish demo)                                                                 | Waitlist capture + analytics on the landing → **the V3 fake-door test is now nearly free**; launch plan, channel choice. ⚠️ The proof strip states targets (`0 unregistered / <10% LOC / <20 min`) as facts — validate or soften before public traffic                                          |
+| 9   | Growth             | ⏳ correctly idle         | NSM + activation metric defined                                                                                                                                                                              | Post-launch phase; event taxonomy worth sketching before M4 ships telemetry-free (v1 has no telemetry — deliberate; revisit)                                                                                                                                                                    |
+| 10  | Customer Success   | ⏳ correctly idle         | —                                                                                                                                                                                                            | Post-launch                                                                                                                                                                                                                                                                                     |
+| 11  | Product Evolution  | ⏳ correctly idle         | Feature-test discipline documented in Founder OS                                                                                                                                                             | Post-launch                                                                                                                                                                                                                                                                                     |
+
+## Cross-cutting open items (the loose threads)
+
+1. **Naming/legal:** veect.com + .ai secured ✅ · veect.dev / npm `veect` + org / GitHub org / X handle — **register today** · EUIPO+USPTO knockout (watch **Vectr**) · counsel pass · entity formation (Veect Labs d.o.o.) + IP assignment **before any collaborator or coding-agent-generated code ships publicly**.
+2. **Design partners:** V1 concierge-PRs and later M4 acceptance both need **~5 real teams with real repos**. Recruiting them is the longest-lead validation item — start now.
+3. **Design brief 🔴s** (carried, unresolved): A1 code-surface framing (export-proof vs. code-workspace), fidelity labels ("production-grade/prototype-grade") to validate with engineers, Impeccable reconciliation, plus **new screens** (Connect Repository, Publish, Environment) added in rev 1.2 — the design agent should get the updated brief before building those flows.
+4. **Security review posture:** rev 1.2's trust model (app executes repo code; device-flow tokens; env secrets) will face enterprise security questions — a one-page security FAQ is cheap insurance and doubles as marketing to Devon.
+5. **Prototype ↔ brief drift: RESOLVED (2026-07-10)** — the prototype's design spec is stored as ground truth (`veect-design-spec-current.md`), the brief defers to it on art direction, the tech spec (rev 1.2.2) adopts its innovations (multi-view frames, bidirectional grammar), and the remaining UI work is specified in `veect-ui-gap-spec.md`.
+
+## Recommended sequence (next ~4 weeks)
+
+1. **Today:** registrations (npm/GitHub/X/veect.dev) + trademark knockout started + entity/counsel scheduled.
+2. **This week:** hand spec rev 1.2.1 + design brief to the coding agent → **M0**. In parallel, start design-partner recruiting (5 teams).
+3. **Weeks 1–2 (parallel with build):** run the validation gate — V1 concierge-PRs (no product needed), V3 fake-door landing page (= GTM start), 10 discovery interviews probing A1/A3 **and the rev 1.2 trust question** ("would your org connect this to your repo?").
+4. **Week 2–3:** Phase 5 sprint with me — licensing/open-core decision + pricing model + unit-economics skeleton. Blocks launch posture and any fundraising narrative; does not block the build.
+5. **Week 3–4:** competitive teardown (Onlook/Subframe/Storybook-AI) to harden A4; reconcile Impeccable rules into F9; refresh design brief 🔴s with validation data.
+
+## Exit-gate summary
+
+Phase 6 ✅ · Phase 7 ✅ · Phase 4 ✅(light) · **Phase 1 ❌ — the discipline line: V1's kill criteria (≥3/5 PRs merged with <10% LOC changed) is the go/no-go for treating Veect as validated rather than believed** · Phase 5 ❌ — schedule the sprint · Phases 2–3 🟡 — upgrade opportunistically · 8 starts via the fake-door · 9–11 correctly parked.

docs/product/veect-design-spec-current.md

@@ -0,0 +1,267 @@
+# Veect — Product & Design Specification
+
+_v1.0 · July 2026 · covers `Veect.dc.html` (interactive prototype), `Veect Landing.dc.html`, and `veect-codebase/` (React 18 · TypeScript strict · Tailwind · shadcn-style)_
+_[Stored verbatim as project ground truth for the current design/prototype — founder-provided 2026-07-10. Companion: `veect-ui-gap-spec.md` for what is NOT yet in this design.]_
+
+---
+
+## 1. Product
+
+**Veect is a design-system-native canvas.** A designer brings their own tokens and
+components; Veect composes screens from _only_ that system and exports production React
+that imports their real library. The three invariants everything hangs on:
+
+1. **One runtime** — canvas, preview, isolation and export render the same tree through
+   the same renderer. No "roughly how it'll look."
+2. **0 unregistered elements** — AI output is whitelist-sanitized against the component
+   registry; anything outside it is refused, never faked.
+3. **Deterministic code** — same tree → same code, every time. Export imports the
+   customer's library (`@solstice/ui` in the demo), never inlined clones.
+   Demo fiction: the customer is **Solstice** (warm team-scheduling brand), with designer
+   Maya (owner) and design engineer Devon (reviewer, owns the merge veto).
+
+---
+
+## 2. Brand & design language
+
+### 2.1 Logo
+
+Typographic wordmark: lowercase **`veect`**, Instrument Sans 600, letter-spacing −0.035em,
+line-height 1, closed by a **square ink terminal** (the "vector point") sized ≈ 0.28 × font
+size, baseline-aligned, `currentColor`. No pictorial mark. Codebase atom: `Logo size={n}`.
+
+### 2.2 Color — chrome tokens
+
+Color belongs to the customer's canvas; the instrument is monochrome. The accent IS the ink.
+| Token | Light (default file value) | Dark |
+|---|---|---|
+| `--bg` / `--panel` | `#FCFCFB` | `#0E0E0D` |
+| `--raised` / `--chip` | `#FFFFFF` / `#F4F3F0` | `#161615` |
+| `--line` / `--line2` | `#E7E6E2` / `#CFCEC8` | `#262624` / `#3A3A37` |
+| `--t1` / `--t2` / `--t3` | `#161513` / `#63615B` / `#9A978F` | `#F4F4F2` / `#A6A6A1` / `#73736E` |
+| `--iris` (accent = ink) | `#161513` | `#F4F4F2` |
+| `--iris-dim` | `rgba(22,21,19,.06)` | `rgba(244,244,242,.09)` |
+| `--btn-ink` (text on accent) | `#FFFFFF` | `#0E0E0D` |
+| `--warn` / `--err` / `--live` | `#9A7B3F` / `#B05E5E` / `#5B7F5E` | `#C2A36B` / `#C97070` / `#8BA88E` |
+Amber (`--warn`) is reserved for AI-scope affordances (pick outline, scope chips, draw
+strokes) and the unmapped-component warning. The prototype ships **dark by default**
+(user preference); the codebase mirrors this (`index.html data-theme="dark"`).
+
+### 2.3 Surfaces & elevation
+
+Flat. Radius **2px everywhere** in chrome (customer canvas keeps its own `radius-md`
+token). No floating shadows — separation is a hairline: popovers/menus use
+`box-shadow: 0 0 0 1px var(--line2)`. Canvas frames sit on the board with a 1px
+`rgba(0,0,0,.14)` ring.
+
+### 2.4 Typography
+
+- **UI**: Instrument Sans 400/500/600 — 13px base, 11–12.5px controls.
+- **Labels**: Fragment Mono, 9–11px, uppercase, letter-spacing .06–.14em — all section
+  headers, metadata, and "engraved" captions.
+- **Customer content**: the system's own font (demo: Bricolage Grotesque) — never used
+  for chrome.
+- Scale discipline: chrome text never below 8px (activity-bar labels), canvas display
+  type responsive per view (§6).
+
+### 2.5 Iconography
+
+Hand-drawn 16-grid SVG, 1.5px stroke, round caps, `currentColor`. Set: chat (spark),
+layers, library, tokens, history, inspect (sliders), polish (spark-4), code (chevrons),
+pick (crosshair), draw (pen), eye / eye-off, mic. No icon fonts, no emoji.
+
+### 2.6 Motion
+
+120–450ms, `cubic-bezier(.2,.7,.2,1)`. Keyframes: `riseIn`, `popIn`, `fadeIn`,
+`lineFlash` (code sync), `nodePulse` (token ripple). Everything respects
+`prefers-reduced-motion`.
+
+### 2.7 Voice
+
+Plainspoken, no hype, no emoji. Refusals teach ("You don't have a component for this
+yet"), fixes explain the _why_ in the user's own tokens.
+
+---
+
+## 3. Screens
+
+| Screen            | Purpose              | Key elements                                                                                                                                                   |
+| ----------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Sign in**       | design-partner entry | email → straight through; SSO stubs; provisioning note                                                                                                         |
+| **Home**          | projects + systems   | project grid (1 live + placeholders), search, Solstice system card (ramp, open tokens, re-import), "bring a design system"                                     |
+| **Onboarding**    | the re-theme reveal  | two paths: paste tokens (parse → contrast checks) or 5-token quick path (brand, neutrals, radius, type, spacing) with live mini-kit; ends "Bring it to life →" |
+| **Editor**        | the canvas (§4–5)    |                                                                                                                                                                |
+| **Settings**      | system + governance  | token source card, component mappings ("merge bar"), craft standard picker, export defaults, plan, delete                                                      |
+| **Profile**       | account              | identity card, theme preference, workspace members (Maya/Devon), keyboard map, sign out                                                                        |
+| **System update** | US-6 re-import       | paste → diff (CHANGED/ADDED/REMOVED + swatches) → impact line → apply-with-undo → ripple                                                                       |
+| **Landing**       | marketing (§10)      |                                                                                                                                                                |
+
+Navigation: project dropdown (top-left) is the hub — all projects, new project, export,
+copy TSX, import tokens, upload component, settings, profile, onboarding demo. Escape and
+outside-click dismiss. Avatar → Profile everywhere.
+
+---
+
+## 4. Editor anatomy
+
+### 4.1 Top bar (36px)
+
+Wordmark · project dropdown · `✓ saved` · **view switcher** (centered: Desktop / Tablet /
+Mobile / ⧉ All) · Preview · **Export** (primary) · theme toggle ◐ · avatar.
+
+### 4.2 Activity bar (44px, fixed left)
+
+Toggleable icon+label buttons, grouped by dividers:
+`✦ Chat` │ `Layers · Library · Tokens · History` │ `Inspect · Polish` │ `Code`.
+Click = open that panel/tab; click again = collapse. Active = `--iris-dim` chip. At
+overlay widths (<1000px) panels are mutually exclusive and float over the board.
+
+### 4.3 Panels (resizable via edge-drag; « » collapse chevrons)
+
+- **Chat** (284px) — vertical AI thread (§7): bubbles, proposal Accept/Discard inline,
+  refusal actions, model picker (haiku/sonnet), image attachments, scope chip.
+- **Board rail** (216px) — LAYERS: collapsible tree (caret-expand, double-click reveal),
+  per-frame **variant chips** (§6); LIBRARY: 10-component base kit with mapping badges,
+  isolation ◉, add +, drag-to-canvas, patterns, custom `.tsx/.jsx` upload; TOKENS: brand
+  ramp + curated swatches + hex, radius stepper, type picker, neutrals, spacing base —
+  every change ripples live (`nodePulse`); HISTORY: labelled steps, restore cursor (§8).
+- **Inspector** (244px) — selection card, ✦ Edit-with-AI (scoped), content/variant/weight/
+  tone/size controls, gap/pad steppers (system-scale steps), Tailwind utilities
+  (collapsible; w/h/max-w/shadow/opacity selects + custom string), token bindings,
+  FRAME settings (name, width ±80, **active view** line). Polish tab: §7.3.
+- **Code** (380px, dark `#161311` always) — file segs (`{Frame}.tsx` / `tokens.css`),
+  line-numbered TSX with click-line→select-node sync and `lineFlash` on change; **edit
+  mode** (toggle → syntax-highlighted textarea → apply parses back via the generated
+  grammar, line-referenced errors); footer `prettier ✓ tsc ✓`.
+- **Isolation** (over board) — variant × state grid per component on a paper stage, real
+  runtime, Esc exits.
+
+### 4.4 Board
+
+Infinite surface: scroll pans, ⌘/ctrl-scroll zooms at cursor, two-finger pinch, drag
+empty board pans, background click deselects. Zoom cluster (− % + · fit · + frame ·
+board backdrop toggle). Frames render as **view clusters** (§6) with a draggable name
+tab (`Home · 34 nodes · one codebase`). Selection = ink ring; hover = neutral ring;
+AI-target = amber ring. Tool pill (bottom-center): **Pick (V) · Draw (D) · Overlays (O)
+· Voice (stub)** — icon buttons with key hints.
+
+### 4.5 Preview
+
+Full-screen overlay, real hover/focus states, active view's width fills the screen
+(mobile/tablet render as a centered device sheet).
+
+### 4.6 Keyboard
+
+`⌘K` commands · `✦` focus composer · `⌘Z/⇧⌘Z` undo/redo · `⌘0` fit · `⌘1` 100% ·
+`⌘±` zoom · `V/D/O` tools · `⌫` delete selection · `Esc` dismiss cascade (menu → modes →
+refusal → proposal → scope → selection).
+
+---
+
+## 5. Canvas node model
+
+`board → frame[] → (stack | card | heading | text | button | badge | input | avatar |
+image | divider | custom)*`. Layout via `dir/gap/pad/padX/padY/align/justify/maxW/bg`
+(4px scale). Content props per type; `tw` bag for curated utility classes. Frames carry
+`x/y/w/views/view`. IDs are stable; comment anchors and code-line mapping key off them.
+
+---
+
+## 6. Responsive variants — one tree, three widths
+
+- Views: **desktop** (frame's own `w`, default 1280) · **tablet 768** · **mobile 390**.
+- A frame renders every enabled view side by side (120px gap) — same children, so an
+  edit anywhere updates every view. Captions (`tablet · 768`) label each block; the
+  **active view** (drives preview, code, export width) is ink-highlighted.
+- Renderer responds to view width: row-stacks wrap ≤900, cards get flex-basis 240,
+  display type steps down (xl: 54 → 44 → 34px) ≤900/≤480.
+- Switcher semantics: Desktop/Tablet/Mobile = show only that view + make it active;
+  **⧉ All** = all three. Layer chips: label click = select frame + make active (opens
+  frame settings); eye icon = show/hide that view (min 1). Cluster growth shifts
+  right-neighbors by the width delta — clusters never collide.
+
+---
+
+## 7. AI, constrained
+
+### 7.1 Compose
+
+Prompt → system prompt embeds the registry JSON (types + allowed props) + brand voice
+rules (one primary CTA per group, 4px spacing, no lorem). Response is sanitized: unknown
+type ⇒ **refusal**, numeric props clamped to scale, strings capped. Result stages as a
+**dashed ghost** on the active frame — Accept commits (history label `AI compose —
+accepted`), Discard drops.
+
+### 7.2 Scoped edits
+
+Pick tool (V) or Inspector → "✦ Edit with AI": amber target ring + composer scope chip
+(`h1 · Scheduling…`), inline bubble at cursor, type-aware quick actions (punchier /
+shorter / demote / colorize ×n…). Edit proposals ghost beside the original and swap in
+on Accept.
+
+### 7.3 Polish (the Impeccable pass)
+
+Ranked issues (HIGH/MED/LOW): weak hierarchy (display heading at 400), competing primary
+CTAs, off-scale gaps (`gap-[18px]` drift), uneven sibling padding, AA contrast failures
+(with measured ratios). Each: title — _why it matters_ — one-click fix **in the user's
+tokens**. Fix-all; empty state "Impeccable. Nothing to fix." Craft standard selectable
+in Settings (Veect default / Impeccable / custom DESIGN.md).
+
+### 7.4 Refusal protocol
+
+Off-registry ask (3D globe, video, charts…) ⇒ "You don't have a component for this yet"
+
+- reason + **Compose from primitives** / Not now. Never generic markup. Models: Haiku 4.5
+  default, Sonnet 4.5 option; offline heuristics keep demos deterministic.
+
+---
+
+## 8. History
+
+Every mutation is a labelled step (`Add Button`, `Polish — Two primary actions`,
+`View → tablet`, `AI edit — accepted`…). History tab lists steps newest-first with age.
+Clicking restores that state and sets a **cursor**: newer steps dim (35%); the next
+meaningful edit truncates the dimmed trail. `⌘Z` walks steps; redo restores.
+
+---
+
+## 9. Code generation & round-trip
+
+| Canvas        | Export                                | Notes                                   |
+| ------------- | ------------------------------------- | --------------------------------------- |
+| heading/text  | `<h1–h4>/<p>` + Tailwind              | size/weight/tone classes, neutral ramp  |
+| button        | `<Button kind size>`                  | `variant→kind` rename shown in mappings |
+| card          | `<Card>`                              | pad/gap classes                         |
+| input         | `<TextField label placeholder />`     |                                         |
+| avatar        | `<Avatar name />`                     |                                         |
+| badge         | `@veect/base-kit` fallback + TODO     | until mapped — "map now" chip           |
+| stack         | `<div>/<nav>` flex classes            |                                         |
+| image/divider | semantic HTML                         |                                         |
+| custom upload | real `import X from "./components/…"` | props sniffed from source               |
+
+`tokens.css` generates from the live system. The **edit-mode parser** accepts exactly
+this grammar back (line-referenced errors otherwise) — the grammar runs both ways.
+Export dialog: honest file tree, `npm i && npm run dev`, copy `{Frame}.tsx`, fidelity
+badge. Guarantee line: _deterministic — same tree, same code_.
+
+---
+
+## 10. Landing page
+
+Carbon-mono flat (same language). Sections: fixed nav (scroll-spy underline, blur on
+scroll) · Hero ("Your system in. Real React out.", masked line reveal, magnetic CTAs,
+live 5-token kit demo with 3D tilt) · proof strip (0 unregistered / <10% LOC / <20 min)
+· three-pillar wedge · graceful-refusal chat (typewriter) · code panel (staggered lines)
+· Polish demo (run/undo on a Solstice card) · CTA. Left ruler tracks scroll. GSAP +
+ScrollTrigger, all reduced-motion-safe.
+
+---
+
+## 11. Codebase map & seams
+
+See `veect-codebase/README.md` for the atomic-design map (config / engine / store /
+hooks / ui / atoms / molecules / organisms / templates / pages), product invariants,
+and **Handoff notes** — the deliberate seams: model bridge (`engine/ai.ts#complete`),
+export zip, placeholder projects, auth, persistence. Board substrate: React Flow
+(`@xyflow/react`, MIT) — frames as custom nodes, zustand as single source of truth.
+Pre-flight: `npm run typecheck && npm run lint`.

docs/product/veect-technical-spec.md

@@ -0,0 +1,310 @@
+# Veect — v1 Technical Specification · rev 1.2.2
+
+_Audience: a coding agent implementing v1. Status: implementation-ready._
+_rev 1.2 (2026-07-10, founder direction): **distribution pivot** — v1 is a **standalone application** (desktop, bundled runtime) with an **additional Docker image**; repositories connect **remote-first** (GitHub / GitLab / Bitbucket / any git URL) with **local checkout** as the alternative mode; config becomes **`veect.config.json`** (machine-writable); **publishing branches to origin is now in scope**; worktrees & all Veect state move **outside the user's repo** into app-managed workspaces; the npm-installed-in-repo package (Storybook-style, rev 1.1 §1) is **deferred to a later distribution**._
+_rev 1.2.1 (same day, post adversarial review of the new layers): `node` PATH shim + Electron ABI policy (the bundled-runtime promise made real) · workspace-trust model · committer identity · config carry rule · device-flow org-wall handling · SSH BatchMode/known-hosts · exact credential-helper mechanics · LFS/submodule policy · CoW worktree installs · Docker `safe.directory` + headless secret store · env manager pulled into M3 · M0 materialization contradiction resolved._
+_rev 1.1 foundations retained: render-path invariant + parity check · split lazy `__veect__` registries, never committed · dedicated-origin adapters + Host validation · checkpoint transaction · docgen-at-scale rules · milestone discipline._
+_Companions: `design-brief-veect.md` (UI/UX) · `design-app-prd.md` (product scope) · `company-context.md` (strategy)._
+_Locked: **AI compose in v1 (Anthropic; key via app settings or env)** · **any React+TS repo, full Next.js first-class** · **SQLite locally + canonical design JSON committed in the branch** · **name: Veect / npm `veect` / scope `@veectjs/*`**._
+
+---
+
+## 1. What we are building
+
+Veect is a **standalone design application that connects to a repository** — remote or local — and turns it into a design surface:
+
+```
+1. Download Veect (macOS / Windows / Linux)         — no system Node required
+2. Connect a repository:
+     · GitHub (device-flow sign-in) → pick a repo   — the default path
+     · any git URL (HTTPS + token / SSH via agent)  — GitLab, Bitbucket, self-hosted
+     · or a local folder                            — an existing checkout
+3. Veect clones (remote) or attaches (local), installs dependencies with its
+   bundled runtime, reads veect.config.json — or walks the user through picking
+   the component folders visually and writes it
+4. The designer composes on a canvas of the repo's REAL components;
+   each design project is a git worktree + branch (veect/<slug>)
+5. Checkpoint → real TSX + design.veect.json committed → Publish pushes
+   veect/<slug> to origin → the team reviews an ordinary PR
+```
+
+A **Docker image** ships alongside: the same server, headless, for a team box, self-hosting, or CI (`docker run veect export`). The npm-in-repo package (`npm i -D veect`, Storybook-style) is a **later distribution** on the same core (§17).
+
+**Purpose (founder's words):** bring designers closer to developers so they work on prototypes directly on the codebase, with already-defined components and all the context the codebase actually holds.
+
+**What v1 must prove:** a designer with _no development environment_ connects a repo, and in one sitting produces an on-brand, real-code prototype on a branch that survives an engineer's review.
+
+### The core invariant (unchanged, stated honestly)
+
+> **Same components, same toolchain.** Every component instance on the canvas is the repo's own module compiled by the repo's own framework toolchain. Veect never re-implements or approximates a component.
+
+Enforced, not assumed: the doc renderer styles frames with **inline styles only** (never runtime-assembled Tailwind class strings); generated TSX uses Tailwind classes (Veect registers `output.dir` in the host's Tailwind content/`@source` as part of the first published branch); **checkpoint parity check** — the generated file is rendered in the adapter and perceptually diffed against the doc-rendered canvas (threshold ~1%); parity failure blocks the checkpoint with a specific error.
+
+### Non-goals for v1
+
+Multi-user realtime editing · cloud sync (Docker image is self-hosted, single-team-token) · non-React frameworks · Figma import · vector tools · editing arbitrary existing app pages (Onlook's lane) · token write-back · Storybook interop · npm-in-repo distribution (deferred, not dead) · **non-git sources** · **yarn PnP** (doctor fails with message; bun best-effort).
+
+### Prototype inheritance (rev 1.2.2 — the editor exists)
+
+The founder's interactive prototype + codebase (`veect-design-spec-current.md`; React 18 · TS strict · Tailwind · **React Flow board substrate** · **zustand** as the in-session store) **seeds `packages/editor`** and _amends this spec_ where it went further:
+
+- **Multi-view frames ship in v1** (supersedes "desktop breakpoint only"): frames carry `views/view` (desktop = frame `w` · tablet 768 · mobile 390), rendered as side-by-side **view clusters** of the same tree; the **active view** drives preview, code, and export width. Adapters render each enabled view's width; the doc model's `FrameNode` gains `views: View[]` + `view: ViewId`.
+- **Code panel edit-mode ships** (supersedes rev 1.1 "read-only"): the codegen grammar is **bidirectional** — the generated TSX parses back with line-referenced errors. The inverse parser is part of `packages/codegen` and must stay in lockstep with the emitter (golden tests run both directions).
+- **AI UX inherited:** model picker (Haiku default / Sonnet option — a per-request override of `ai.model`), image attachments in context, scoped edits (amber ring + scope chip), dashed-ghost staging, refusal protocol. The prototype's offline heuristics are retained as the **record/replay eval harness + Playground demo mode**.
+- **Vocabulary:** top-bar "Export" becomes **Checkpoint** (commit) + **Publish** (push + PR link); the export-zip dialog survives only in Playground/Docker-CI contexts.
+- **Integration seams:** the codebase's declared seams map 1:1 onto this spec's subsystems (`engine/ai.ts#complete` → §14 AI engine; export zip → §10 checkpoint/publish; placeholder projects → §2/§11 workspaces; auth stub → §6 connections; zustand-only persistence → §11 SQLite/JSON write-through). Wiring table: `veect-ui-gap-spec.md` §4; remaining UI surface: same doc §2–§3.
+
+---
+
+## 2. Architecture overview
+
+```
+Veect app (desktop shell; bundled Node runtime — ELECTRON_RUN_AS_NODE for all child processes)
+│
+├── Editor UI (the web editor, in the shell's window)
+├── Server core (Hono on 127.0.0.1) ──────────────── identical binary logic in the Docker image
+│     ├── Connections (GitHub device flow · git URL+PAT · SSH-via-agent · local folder)
+│     ├── Discovery engine (components + tokens, shared TS program, watch)
+│     ├── Doc engine (model, validation, revisions)
+│     ├── Codegen (doc → TSX, prettier, parity check)
+│     ├── Git engine (clone/fetch/worktrees/checkpoint/publish — system git, execa)
+│     └── AI engine (Anthropic, constrained to registry)
+│
+├── App data (per-OS app dir, e.g. ~/Library/Application Support/Veect)
+│   └── workspaces/github.com/acme/shop/
+│       ├── clone/                       ← managed clone (remote mode) — partial clone,
+│       │   │                              .git/info/exclude hides nothing: repo stays PRISTINE
+│       │   └── veect.config.json        ← if committed in the repo; else workspace-local (below)
+│       ├── worktrees/checkout-flow/     ← git worktree, branch veect/checkout-flow
+│       │   └── <output.dir>/checkout-page/{design.veect.json, CheckoutPage.tsx}
+│       ├── veect.db                     ← SQLite (projects, revisions, AI runs, ports)
+│       ├── config.json                  ← workspace-local config until committed to the repo
+│       └── env.enc                      ← env values, OS-encrypted (never in the clone/repo)
+│
+└── Preview adapters (dedicated port = dedicated origin each; common runtime protocol)
+      ├── vite-react: embedded Vite rooted at the worktree (cwd pinned to worktree)
+      └── nextjs: managed `next dev` of the worktree + materialized /__veect__ route
+           └── Editor canvas <iframe> — cross-origin, postMessage with pinned targetOrigin
+```
+
+**Local mode:** `workspaces/<hash-of-path>/` holds `worktrees/`, `veect.db`, `env.enc`; the user's checkout is attached read-mostly — Veect writes **nothing** into it (worktrees live in app data in **both** modes; rev 1.1's `.gitignore`/shields machinery is deleted — the repo is untouched except files the user chooses to commit on Veect branches).
+
+---
+
+## 3. Distribution & deployment
+
+**Standalone desktop app (default).** Electron shell 🟡: chosen because Electron embeds a real Node runtime — every child process (`next dev`, Vite, package managers, prettier) is spawned with `process.execPath` + `ELECTRON_RUN_AS_NODE=1`, so **the user needs no system Node**. (Tauri + node-sidecar is the documented alternative if binary size becomes a priority; the UI is plain web either way, so the shell is swappable.) Auto-update via standard channels — **draining/stopping all adapter child processes before relaunch** (an updated bundle orphans workers whose `execPath` vanished). **System git ≥ 2.38 IS required** in v1 (worktrees + partial clone; bundling git is out of scope) — the app detects it and walks the user through the one-time install (macOS xcode-select / Git for Windows) 🟡 flagged as the residual environment friction.
+
+**Runtime realities (rev 1.2.1, from adversarial review — these make the bundled-runtime promise actually hold):**
+
+- **`node` PATH shim.** npm/pnpm `.bin` wrappers and lifecycle scripts invoke a binary literally named `node` — which doesn't exist on the target machines. Veect injects a shim directory at the front of `PATH` for every child process: `node` (POSIX) and `node.exe`/`node.cmd` (Windows) exec the app binary with `ELECTRON_RUN_AS_NODE=1`. A fixture with a `node`-invoking postinstall is part of the A5 acceptance test.
+- **Native-module / ABI policy.** `ELECTRON_RUN_AS_NODE` reports a Node version but Electron's ABI differs — source builds against nodejs.org headers fail at require-time. Installs run with `npm_config_runtime=electron` + matching `disturl`/target; **doctor scans host dependencies for non-N-API native modules** (better-sqlite3-class) → playbook: prebuilt-only versions or Docker mode. N-API modules (modern sharp, @next/swc) are unaffected. `engines`/`engine-strict` mismatches are surfaced, not silently ignored.
+- **Vendored package managers.** Corepack ships shims, not binaries — first use would fetch over the network (proxy/offline failure). Veect vendors pinned pnpm/yarn in the bundle, pins `COREPACK_HOME` to app data, and prefetches at connect.
+- **`runAsNode` fuse stays ENABLED** — the architecture requires it. This deviates from Electron's default hardening guidance and makes the signed binary a general-purpose interpreter (possible EDR flags); the accepted risk is recorded in §16. Implementers must not "fix" this.
+- **Windows:** workspaces live under `%LOCALAPPDATA%` (never the roaming profile — multi-GB workspaces in Roaming is a corporate disaster); workspace dirs use short hashed names (MAX_PATH); doctor suggests a Defender exclusion for the workspaces dir.
+
+**Docker image (additional, same release).** `veect/veect` — the server core, headless, browser UI. **Token auth mandatory** (no localhost-trust in a container): boot prints/accepts `VEECT_TOKEN`; every HTTP/WS request requires it. Single-team, single-token in v1 (multi-user auth belongs to a later cloud layer — decision log). Volumes: `/data` (workspaces). Also the **CI story**: `docker run -v $PWD:/repo veect/veect export --local /repo` runs the export gate on a checked-out `veect/*` branch.
+
+**npm package `veect`** — **register the name/org now, ship later** (§17). The core is layered so the CLI/npm distribution reuses server + engines unchanged.
+
+**Monorepo layout** (rev 1.1 §3, amended): add `packages/shell/` (Electron main, auto-update, safeStorage bridge, deep links) and `packages/connections/` (providers, credential store, clone/fetch orchestration); everything else stands.
+
+---
+
+## 4. Surfaces: app UX + CLI
+
+The **GUI is primary** — connect, browse projects, design, checkpoint, publish, doctor, settings all in-app (design brief §9 incl. the new Connect Repository + Environment screens). A **`veect` CLI ships inside the app bundle** (and in the Docker image) for power users and CI:
+
+| Command                           | Behavior                                                                                                                                                                                                                                                        |
+| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `veect open [path\|url]`          | Launch/focus the app on a workspace (registers as the `veect://` deep-link handler too).                                                                                                                                                                        |
+| `veect export <project> [design]` | Regenerate TSX+JSON, prettier, full `tsc --noEmit`, parity check, checkpoint commit. **CI mode:** cwd is a plain checkout of a `veect/*` branch → operates in place, no app/workspace needed. Non-zero exit on failure.                                         |
+| `veect doctor`                    | Environment & connection report: git version, credential reachability (never prints secrets), framework/appDir detection, Tailwind content registration, adapter health, disk usage per workspace, Windows long-path check. Pass/warn/fail + one-line fix each. |
+
+`init` is gone as a user-facing requirement — connecting a repo **is** init. (The Storybook-style `npx veect init` returns with the npm distribution later.)
+
+---
+
+## 5. Configuration — `veect.config.json`
+
+JSON, not TS (founder decision): the app must be able to **read and write** it safely from the GUI (the first-run wizard writes it; the settings screen edits it), and JSON travels through the schema. A published **JSON Schema** (`https://veect.dev/schema/config.v1.json`) gives editor autocomplete; the parser accepts JSONC (comments tolerated), the writer emits canonical JSON.
+
+```jsonc
+// veect.config.json — lives at the repo root, committed like any config
+{
+  "$schema": "https://veect.dev/schema/config.v1.json",
+  "components": ["src/components/**/*.{tsx,ts}"], // REQUIRED — the design-session folders
+  "exclude": ["**/*.test.*", "**/*.stories.*"],
+  "framework": "auto", // "auto" | "nextjs" | "vite-react" | "react"
+  "appDir": ".", // monorepos: app package to run, e.g. "apps/web"
+  "preview": { "setupFile": "./veect.preview.tsx", "css": [] },
+  "tokens": { "tailwind": true, "cssVars": ["src/styles/tokens.css"] },
+  "output": {
+    "dir": "veect-designs",
+    "componentImportStyle": "alias-or-relative",
+  },
+  "git": {
+    "baseBranch": "auto", // "auto" = origin default
+    "branchPrefix": "veect/",
+    "autoCheckpoint": true, // commit on explicit Save/Export actions
+    "autoPublish": "remote-only", // push veect/<slug> after checkpoint: "remote-only" | "always" | "never"
+    "verifyHooks": false, // commit with --no-verify by default
+  },
+  "ai": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-latest",
+    "maxTokensPerRequest": 8192,
+  },
+}
+```
+
+Notes: `veect.preview.tsx` (decorators/global CSS) remains a **code** file, hand-authored — the wizard scaffolds a stub. **AI key is NOT in config** (it's a secret): sources are the app's Settings (stored via OS `safeStorage`) or `ANTHROPIC_API_KEY` env — never config, never the repo, never SQLite. **Config resolution:** committed file in the repo wins; if the repo has none, the workspace-local `config.json` (written by the wizard) applies, and the app offers to include `veect.config.json` in the project's first published branch — so the config enters the repo through an ordinary PR, and `main` is never touched by Veect directly.
+
+---
+
+## 6. Repository connections (new in rev 1.2)
+
+**Modes:** `remote` (default) | `local`.
+
+**Remote providers, v1:**
+
+- **GitHub — OAuth Device Flow** (client_id only; no secret shippable in a desktop app): user gets a code, approves in browser, app receives a token. Requested scope: `repo` (read/write to chosen repos). Fine-grained PAT paste is the equal-class fallback.
+- **Any git URL** — HTTPS with PAT/basic (GitLab, Bitbucket, Gitea, Azure DevOps, self-hosted) or **SSH via the system agent** (the app never reads or stores private keys; if no agent, instruct — a Veect-generated deploy-key flow is fast-follow).
+- Native GitLab/Bitbucket OAuth: fast-follow; the URL path covers them day one.
+
+**Credential storage:** OS keychain via Electron `safeStorage` (Docker: `VEECT_TOKEN` + provider tokens via env or the encrypted store on `/data`). Secrets never in SQLite, never in config, never logged; git operations receive credentials via an **ephemeral credential-helper** (`git -c credential.helper=...` per invocation), never embedded in remote URLs (URLs with tokens leak into `.git/config` and process lists).
+
+**Clone strategy:** partial clone `--filter=blob:none` (fast on big repos; fully compatible with worktrees), default branch checked out; `fetch` on workspace open and on a visible "refresh" action; staleness (commits behind origin/default) surfaced per project with **Update from base** (merge, never rebase; conflicts read-only with "ask a developer" guidance — rev 1.1 rules stand).
+
+**Access levels:** write access → full flow. **Read-only connect is allowed**: design, checkpoint locally; Publish disabled with an explanatory state ("ask for write access, or export a patch") — `git format-patch` export is the escape hatch.
+
+**First run in an unconfigured repo:** visual wizard — browse the repo tree, multi-select component folders, pick `appDir` (monorepo), framework/tokens autodetected and shown for confirmation → writes config per §5 resolution rules.
+
+**Dependency install:** on clone and on lockfile change, the app runs the detected package manager using the bundled runtime (npm built-in; pnpm/yarn via bundled corepack; bun = system-only best effort). Progress is first-class UI (real repos take minutes cold). **Worktrees always get their own install** (they live outside the repo dir, so ancestor `node_modules` resolution does not apply — accepted cost; pnpm's content-addressed store makes it cheap, npm/yarn are slower and show honest progress).
+
+**Environment manager (per workspace):** real apps crash without `DATABASE_URL`. The app detects env needs from **`.env.example`, `turbo.json` `globalEnv`, t3-env schemas (`src/env.ts` — pervasive in exactly this Next.js audience), and `next.config` env keys**, presents a form, stores values OS-encrypted (`env.enc`), and **injects them into adapter AND package-manager processes** (private registries: `.npmrc` with `${NPM_TOKEN}` needs it at install time; `~/.npmrc` precedence documented) — values never touch the clone, worktrees, or git. Injected process env correctly wins over Next's on-disk `.env` loading (Next does not overwrite existing vars). Local mode additionally offers one-click import from the checkout's own gitignored `.env*` files (with a staleness note when the source file changes). Doctor's crash-sniffing playbook stays. **This ships in M3** (local mode already needs it — worktrees never contain gitignored `.env.local`).
+
+**Connection realities (rev 1.2.1, from adversarial review):**
+
+- **Trust model (the one new attack surface).** Cloning a repo and running its package manager + dev server = executing that repo's code inside Veect's runtime, with injected env readable. First connect shows a **workspace-trust prompt** (VS Code-style) stating exactly this; per-repo **"install without scripts"** (`--ignore-scripts`) opt-in; threat model stated in §16. Doctor surfaces `safeStorage`'s backend — on Linux without a keyring it falls back to weak protection (`basic_text`), and the UI says so rather than implying encryption.
+- **GitHub org walls.** OAuth `repo` scope hits third-party-app restrictions and SAML SSO: auth "succeeds," then the org repo 404s until approved. Post-auth, Veect probes repo visibility and turns the 404 into the org-grant/SSO-authorize guidance flow — never a dead end. The **GitHub App** model (per-repo install, no OAuth wall; 8h tokens + refresh handled) is the fast-follow auth upgrade.
+- **Write-permission probe at connect** (provider API or `push --dry-run` to a throwaway ref) — Publish gating is known on day one, not discovered as a 403 after a week of design work.
+- **SSH from a GUI app:** `GIT_SSH_COMMAND` with `BatchMode=yes` + explicit known-hosts policy (fingerprint-confirm UI, `accept-new` thereafter — first clone must never hang on a TTY prompt). macOS GUI apps often don't inherit `SSH_AUTH_SOCK` (launchd) — doctor distinguishes "no agent reachable" from "agent has no identities" and shows the fix.
+- **Credential-helper mechanics, exactly:** every git invocation gets `-c credential.helper=` (blank — suppresses OS keychain helpers that would answer or cache) followed by `-c credential.helper=<veect-helper>`; the secret reaches the helper via fd/env, never argv. **The helper rides ALL git invocations** — partial clone lazily fetches blobs during `worktree add`/checkout/log, not just clone/fetch/push. (Repo tooling running bare `git` inside a worktree can hit an unauthenticated lazy fetch — documented limitation + doctor hint.)
+- **git-lfs:** design-adjacent repos are exactly the LFS population, and lfs isn't bundled with macOS git — Veect detects `.gitattributes` LFS filters, doctor warns with install guidance, and tests assert credential propagation into LFS transfers (`GIT_CONFIG_PARAMETERS` carries `-c` into filters).
+- **Submodules: unsupported in v1** (doctor detects and says so plainly).
+- **Install strategy (kills the tens-of-GB npm case):** the workspace clone installs once; each worktree's `node_modules` is **CoW/hardlink-cloned** from it (APFS `clonefile` / Windows ReFS / Linux reflink; fresh-install fallback on plain filesystems or lockfile drift). No redundant double-install.
+
+---
+
+## 7. Component & token discovery — unchanged from rev 1.1
+
+Scan the active project's **worktree**; zero-project state scans the clone's default branch read-only. Shared TS LanguageService per worktree; `react-docgen-typescript` + propFilter stripping node_modules-inherited props; per-file failure isolation; content-hash cache; budgets **cold < 10s / warm < 2s on `perf-500`**. `ComponentMeta`/`TokenRegistry` shapes, client/server classification with self-healing, Tailwind v3/v4 token reading, watch → `registry.updated`, HMR budget **< 500ms** for worktree-local edits — all stand. (_Live-sync covers the worktree; developer changes on `main` arrive via Update-from-base. Do not claim otherwise in product copy._)
+
+## 8. Design document model — unchanged from rev 1.1
+
+`DesignDoc v1` (one design = one folder = `design.veect.json` + generated TSX), Frame/Element/Text nodes, `lit | token | expr` prop values (`expr` renders a placeholder chip on canvas — never evaluated — and emits verbatim with a `// veect:expr` review marker), unknown-component loud error states, in-memory undo + durable revisions.
+
+## 9. Preview & rendering — framework adapters (rev 1.1 rules stand, two amendments)
+
+Dedicated-origin adapters (vite-react embedded Vite; nextjs managed `next dev` with **materialized, never-committed** `app/__veect__/**` via `.git/worktrees/<name>/info/exclude`; split lazy client/server registries with error boundaries; root-layout inheritance documented; middleware doctor check; protocol messages incl. `runtime.ready` queue-drain and `fonts.loaded`-gated measurement; LRU pool ≤ 2; crash auto-restart with backoff).
+**Amendments:** (a) all adapter child processes are spawned with the **bundled runtime** (`ELECTRON_RUN_AS_NODE`), never the system Node; (b) env injection per §6 environment manager.
+
+## 10. Git engine (rev 1.1 rules + publishing)
+
+Execa around **system git**, array-args + `--` end-of-options, slugs `^[a-z0-9][a-z0-9-]{0,40}$`.
+
+**Create project:** `git worktree add <appdata>/workspaces/<ws>/worktrees/<slug> -b veect/<slug> <base> --` → env wiring → per-worktree install → materialize `__veect__` (Next mode) → initial commit.
+
+**Checkpoint transaction (unchanged):** validate → codegen to temp → prettier → LanguageService diagnostics on generated files (<2s; full `tsc` only in `veect export`) → parity check → atomic move → `git add <explicit paths>` → `git commit --no-verify` (`veect(<slug>): <design> — <summary>` + `Veect-Design:` trailer). Any failure: nothing moves, visible dirty state, idempotent retry.
+
+**Committer identity (rev 1.2.1):** fresh designer machines have no `user.name`/`user.email` — the first commit would fail with git's "tell me who you are." Commits run with `-c user.name`/`-c user.email` sourced from the provider profile (GitHub login + noreply email) or a one-time in-app prompt; never written to the user's global gitconfig. Part of M3 acceptance on a fresh machine.
+
+**Config carry rule (rev 1.2.1):** `veect.config.json` + the Tailwind content registration ride **every project branch as byte-identical content until Veect detects them merged into base** — identical bytes make cross-branch merges resolve cleanly, and any branch's PR can be the one that lands them. (A dedicated one-time `veect/setup` PR is the documented alternative for teams that prefer it.)
+
+**Publish failure classes (rev 1.2.1, enumerated playbooks):** protected branches / rulesets restricting branch-creation patterns (`veect/*` may be disallowed — configurable `branchPrefix` is the fix) · **required signed commits** (Veect commits unsigned in v1 — documented; commit signing is a fast-follow) · pre-receive commit-message policies (conventional-commits rejects `veect(<slug>):` — `git.commitMessageTemplate` config is the escape hatch) · no write access (caught early by the connect-time probe; patch-export escape hatch).
+
+**Publish (new):** `git push -u origin veect/<slug> --` after checkpoint, per `git.autoPublish` (`remote-only` default: auto in remote mode, manual button in local mode). After publish the UI surfaces the **compare/PR deep link** (`https://<host>/<owner>/<repo>/compare/<base>...veect/<slug>?expand=1` and GitLab/Bitbucket equivalents) — zero provider API needed in v1; native "Create PR" via API is fast-follow.
+
+**Safety invariants (updated, test-enforced):** all writes inside the workspace dir (path assertion on every fs/git call) · the user's checkout (local mode) is never modified — no checkouts, stashes, index changes, not even `.gitignore` edits · **never push to the base/default branch** · never force-push · never delete remote branches · credentials only via ephemeral helper · branch collision → reattach or new slug · archive = `git worktree remove` (+ optional `push` of final state first), branch kept · hooks bypassed by default (`verifyHooks`).
+
+## 11. Persistence — unchanged from rev 1.1, relocated
+
+SQLite per workspace at `<appdata>/workspaces/<ws>/veect.db` (WAL + FS probe → TRUNCATE fallback; app-data dirs make network-FS problems rare). Tables as rev 1.1 (projects +`behind_base`, designs with `json_path/json_hash`, revisions ring-buffer, `ai_runs`, settings incl. adapter ports). Division of truth stands: SQLite = working state/history/provenance; `design.veect.json` in the branch = canonical/shareable; **file-wins reconciliation** with restore-revision safety net; no merging in v1.
+
+## 12. Code generation — unchanged from rev 1.1
+
+Deterministic TSX per design; imports via tsconfig alias-else-relative; frames → Tailwind classes when detected (content registration travels with the first published branch) else typed styles; autogenerated banner + **code-owned flip** on hand-edit (never overwrite humans); "Export as page" for Next routes; quality gates split checkpoint (fast diagnostics + parity) vs export (full `tsc` + eslint).
+
+## 13. Server & API
+
+Hono; desktop: bound to `127.0.0.1`, the shell's window is the only client. Docker: binds `0.0.0.0` with **mandatory token auth** + Host-header validation + strict CORS/WS-origin checks (rev 1.1 DNS-rebinding rules apply everywhere). REST/WS surface as rev 1.1, plus: `POST /api/connections` (provider flows), `GET /api/workspaces`, `POST /api/projects/:slug/publish`, `GET /api/env/template` · `PUT /api/env` (values write-only — the API never returns secrets), `project.staleness` + `publish.status` WS events.
+
+**Docker realities (rev 1.2.1):** the image sets `safe.directory=*` (via `GIT_CONFIG_GLOBAL`) and documents the uid/volume contract (`--user $(id -u)` or chown guidance) — otherwise git ≥2.35.2 "dubious ownership" breaks the flagship CI one-liner on bind mounts. Headless secret store: `safeStorage` doesn't exist without a desktop — env values are encrypted **AES-GCM with a key derived (scrypt) from `VEECT_SECRET`** (falls back to the boot token with a logged warning); the secret-store abstraction lives in server core, the shell merely provides the OS backend. **Multi-seat honesty:** one token = one principal — every publish authors as whoever's credentials are stored, and the env store is shared; the self-host guide says so and recommends a machine account with narrow scopes. Device flow inside a container: the code+URL are printed/displayed for approval on any browser (no in-container browser needed).
+
+## 14. AI compose — unchanged from rev 1.1, key handling amended
+
+Context assembly with deterministic lexical relevance + always-include set; **"what was sent" disclosure**; tool-forced JSON Node subtree; ≤2 repair rounds; graceful-refusal contract; ghost-layer propose/accept; provenance to `ai_runs`; CI eval via record/replay (0 unregistered elements; refusals fire). **Key sources:** app Settings (safeStorage) or env — never config/repo/DB plaintext; no key → documented setup-hint state.
+
+## 15. Testing & CI (rev 1.1 + connection layer)
+
+Fixtures unchanged (`vite-kitchen`, `next-app-kitchen` incl. middleware + redirecting root layout, `pnpm-mono`, `perf-500`, `next-pages-kitchen` M8-lite). **Added suites:** connections (device-flow mock server; PAT/SSH against a local `git daemon`/`sshd` fixture; partial-clone + worktree matrix; read-only mode; publish + collision/permission failures; credential-helper never leaks tokens into `.git/config`/argv — asserted), env manager (injection, never-on-disk-in-clone), shell smoke (app boots on macOS/Windows/Linux CI runners, spawns adapter via bundled runtime with system Node **absent** from PATH — the A5 test), Docker (token auth enforced; export-in-CI path). Windows runs the full git/worktree/connection suite.
+
+## 16. Performance, security, DX budgets
+
+| Area                                                             | Budget / rule                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| App cold start → connect screen                                  | < 3s                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| Remote connect → canvas ready (vite fixture, warm npm cache)     | < 3 min incl. clone + install (progress always visible; Next fixture bounded by `next dev`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| Canvas manipulation / server-component settle / HMR / checkpoint | rev 1.1 budgets stand (16ms · <1s · <500ms · <5s)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| Discovery                                                        | cold <10s / warm <2s on perf-500                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| Disk                                                             | per-workspace usage shown; archive/cleanup UI; warn > 5GB/workspace                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| Security                                                         | desktop server localhost-only; Docker token-auth mandatory; credentials via safeStorage/keychain + ephemeral git helper (all invocations); env values encrypted at rest, injected only into adapter/PM processes; **workspace-trust prompt before first install/run — executing repo code is the stated, accepted surface**; Linux `basic_text` keyring fallback surfaced to the user; **`runAsNode` fuse enabled by design (accepted LOLBin/EDR risk)**; AI payload = §14 disclosure; secrets never in config/DB/logs/URLs/argv; `__veect__` never committed; no telemetry v1 |
+| Failure UX                                                       | every error carries a fix; doctor playbooks add: git missing, device-flow blocked (enterprise SSO), SSH agent absent, clone auth failed, install failed (registry/proxy), env missing, disk full                                                                                                                                                                                                                                                                                                                                                                               |
+
+## 17. Milestones & acceptance (resequenced for rev 1.2)
+
+**M0 — Walking skeleton (local mode, both adapters, minimal worktree).** Shell boots on all three OSes with **no system Node** (PATH shim active); open `vite-kitchen` AND `next-app-kitchen` as local folders; **minimal worktree creation ships in M0** — the Next adapter materializes `app/__veect__/**` only ever inside a worktree, never the user's checkout (resolves the materialization/"repo untouched" contradiction); one real component renders through each adapter; protocol round-trip.
+_Accept:_ fresh machine (git present, Node absent from PATH) → open app → local fixture → rendered component < 60s; `git status` in the fixture checkout is untouched; a fixture postinstall that invokes `node` succeeds via the shim.
+
+**M1 — Discovery & registry + config.** Full scan, props/tokens panels, watch/HMR, split lazy registries, classification self-heal, perf-500 budgets; JSON config load/validate + **first-run wizard writes it** (workspace-local, offer-to-commit).
+
+**M2 — Canvas + doc + persistence.** Rev 1.1 M2 unchanged (SQLite in app data; JSON write-through + file-wins reconciliation).
+
+**M3 — Worktrees + codegen + checkpoint (local complete).** Rev 1.1 M3, with worktrees in app data + CoW-derived installs; code-owned flip; update-from-base; **committer-identity flow**; **env manager core** (local `.env*` import + injection — real Next apps need it here, not M4).
+_Accept (additions):_ first checkpoint succeeds on a fresh machine with no global gitconfig; `next-app-kitchen` with a required env var previews after env import.
+
+**M4 — Remote repositories + publish.** Device flow (incl. org-restriction guidance), PAT/SSH (BatchMode + known-hosts UI), partial clone, trust prompt, install pipeline (vendored PMs, ABI policy), env manager remote polish, read-only mode, connect-time write probe, publish + compare-link, failure-class playbooks.
+_Accept:_ on a Node-less machine, connect a **private** GitHub repo via device code → wizard → compose → checkpoint → **Publish** → the compare URL opens a reviewable PR containing the carry set per §10 (byte-identical `veect.config.json` + Tailwind registration, `design.veect.json`, generated TSX); token never appears in any file, log, argv, or `.git/config`.
+
+**M5 — Next.js depth.** Rev 1.1 M4 unchanged (server-component subtrees + refresh, root-layout/middleware handling, `next/font` fidelity, adapter pool/crash recovery).
+
+**M6 — AI compose.** Rev 1.1 M5 unchanged + key-in-Settings flow.
+
+**M7 — Docker + hardening.** Docker image (token auth, volumes, CI export path), doctor complete, Windows pass, pages-router best-effort, docs (connect-your-repo guide, env guide, self-host guide).
+_Accept:_ full matrix green; a designer following only the download-page instructions reaches first published branch on their own team's repo.
+
+## 18. Decision log
+
+| Decision                                                                                          | Status                                                                             |
+| ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| **Standalone app default + Docker additional; npm-in-repo package deferred**                      | ✅ locked (founder, 2026-07-10) — register npm `veect` now regardless              |
+| **Remote-first repo connection (GitHub device flow / git URL / SSH) with local mode**             | ✅ locked (founder, 2026-07-10)                                                    |
+| **Config = `veect.config.json`** (schema-validated, app-writable; `veect.preview.tsx` stays code) | ✅ locked (founder, 2026-07-10)                                                    |
+| Electron shell with bundled Node (`ELECTRON_RUN_AS_NODE`); Tauri+sidecar = documented alternative | 🟡 architect's call — UI is shell-agnostic web; revisit on binary-size evidence    |
+| Worktrees + all Veect state in app data, **user's repo never modified** (kills rev 1.1 shields)   | ✅ rev 1.2 — cost: per-worktree installs (pnpm cheap, npm slower, progress honest) |
+| Publish in scope: push `veect/*` only; compare-link PR; provider PR-API fast-follow               | ✅ rev 1.2 (supersedes rev 1.1 "no push")                                          |
+| System git required v1 (no bundled git; isomorphic-git can't do worktrees)                        | 🟡 residual A5 friction — guided install; revisit                                  |
+| Docker v1 = single-team token; multi-user auth = later cloud layer                                | ✅ rev 1.2                                                                         |
+| Workspace-trust prompt + per-repo `--ignore-scripts` opt-in; repo-code execution = stated surface | ✅ rev 1.2.1                                                                       |
+| `node` PATH shim + `npm_config_runtime=electron` ABI policy + vendored PMs                        | ✅ rev 1.2.1                                                                       |
+| Worktree installs derived via CoW/hardlink from the workspace clone                               | ✅ rev 1.2.1                                                                       |
+| GitHub App auth (per-repo install, refresh tokens)                                                | fast-follow — device flow + PAT/SSH ship v1                                        |
+| Commit signing; provider PR-API; GitLab/Bitbucket native OAuth                                    | fast-follow                                                                        |
+| AI in v1 (key via Settings/env) · full Next adapter · SQLite+JSON-in-branch · name Veect          | ✅ carried forward                                                                 |
+| License / open-core split                                                                         | strategy, not blocking 🔴 — build source-available                                 |
+| Design-doc concurrent merge                                                                       | v1 = file-wins + revision net; deferred                                            |
+
+---
+
+_End of spec (rev 1.2). The editor's visual/interaction contract is `design-brief-veect.md` (see its Connect Repository and Environment screens); the founder's React prototype seeds `packages/editor`; this document is authoritative for everything behind it._

docs/product/veect-ui-gap-spec.md

@@ -0,0 +1,144 @@
+# Veect — UI & Design Gap Specification
+
+_The work order for what the current design does NOT yet cover. 2026-07-10._
+_Ground truth for what exists: `veect-design-spec-current.md` (v1.0 — prototype, landing, codebase). Target: `veect-technical-spec.md` rev 1.2.1. Design language for everything below: the **ink instrument** (§2 of the design spec) — do not invent new colors or radii; the only new pattern this gap requires is specified in §6._
+_Audience: the design agent (screens, states, motion) and the coding agent (behavior, integration seams). Every item carries its spec reference and milestone._
+
+---
+
+## 0. The headline shift the UI hasn't made
+
+The prototype is a beautiful **SaaS-canvas fiction**: tokens arrive by _paste_, components are a demo kit + `.tsx` upload, output leaves by _export zip_. The shipped product (spec rev 1.2.1) is **repo-native**: tokens and components are _discovered from a connected repository_, projects _are_ git branches in app-managed worktrees, and output leaves by _Checkpoint → Publish → PR link_. Almost everything in this document derives from that one shift. The editor itself — canvas, panels, AI, Polish, history, view clusters, code panel — is largely **done and ahead of spec**; what's missing is the shell around it and the truth underneath it.
+
+**Vocabulary changes that ripple through all chrome:** "Export" → **Checkpoint** (commit to the branch) and **Publish** (push + PR link) · "project" = a branch (`veect/<slug>`) in a **workspace** (a connected repo) · "import tokens / upload component" → "connect repository / rescan". The export-zip dialog survives only inside Docker/CI contexts.
+
+---
+
+## 1. Already done — do not redesign
+
+Editor anatomy (top bar, activity bar, panels, board, tool pill, keyboard cascade) · view clusters & responsive variants · constrained AI (compose ghosts, scoped edits, refusal protocol, model picker, attachments) · Polish with craft-standard picker · history with restore cursor · code panel incl. **edit-mode round-trip grammar** · isolation mode · token editor with live ripple · System-update diff screen · Settings/Profile shells · Sign-in shell · Landing page. These are inherited into the product as-is; the technical spec has been amended to adopt the prototype's innovations (multi-view frames, bidirectional grammar) rather than the reverse.
+
+---
+
+## 2. New surfaces to design & build
+
+### 2.1 Connect Repository — replaces token-paste onboarding as the primary path · **M4** · spec §6
+
+The single most important missing flow; it carries first-run trust.
+
+- **Source chooser:** three calm cards — **GitHub** · **Git URL** · **Local folder**. Fragment-mono captions; no provider logos larger than 16-grid icons.
+- **GitHub device flow:** large copyable code, "approve in browser" link, waiting state (subtle pulse, no spinner), retry; **org-wall state** — auth succeeded but repo 404s → guidance card ("your org must authorize Veect — here's the link / ask an admin"), never a dead end.
+- **Git URL path:** URL field + auth method (token / SSH-agent); SSH first-connect shows a **host-fingerprint confirm** (mono, ink, Accept/Reject); "no agent reachable" vs "agent has no identities" are distinct states with distinct fixes.
+- **Local folder:** native picker; instant attach.
+- **Workspace-trust prompt (required, before first install):** plain-language card — "Veect will run this repository's install scripts and dev server on your machine. Only connect repositories you trust." Options: Trust & continue · **Install without scripts** (per-repo toggle, persisted) · Cancel. Voice: factual, not scary.
+- **Clone + install progress:** staged, honest, minutes-long (see §6 pattern): `cloning → installing (pnpm) → reading components → starting preview`. Each stage with elapsed time; cancellable; failure surfaces the doctor playbook string inline.
+- **Config wizard (repo has no `veect.config.json`):** repo file-tree browser (mono, indent guides), multi-select component folders, `appDir` picker for monorepos, detected framework + tokens shown as confirm chips; footer note: "This config will ride your first published branch." Writes workspace-local config until merged.
+- **Read-only connect:** allowed; persistent quiet banner "Design and checkpoint freely — Publish needs write access" + patch-export escape hatch in the project menu.
+- **States:** choose / device-wait / org-wall / auth-fail (specific) / fingerprint / trust / cloning / installing / scanning / wizard / env-needed (→ §2.3) / success — success is the **re-theme reveal recast**: components and tokens stream in FROM the repo and the mini-kit re-themes (Signature Moment #1, now earned from a clone instead of a paste).
+
+### 2.2 Publish & branch status · **M3–M4** · spec §10
+
+- **Top bar:** `Export` primary button becomes two verbs: **Checkpoint** (secondary) · **Publish** (primary). `✓ saved` stays (autosave ≠ checkpoint — the distinction needs a hover explainer).
+- **Branch card** (project dropdown + a status strip in the board's empty corner): `veect/checkout-flow · 4 checkpoints · 2 behind base` — mono, engraved.
+- **Publish flow:** progress → success = **PR deep-link as the hero action** ("Open pull request →"), copyable branch name; this is Signature Moment #4 (the clean handoff) relocated from the zip dialog.
+- **Failure states (each with its playbook string):** no write access (pre-detected at connect; button pre-disabled with reason) · branch-name policy rejected (offer prefix change) · signed-commits required (explain, link out) · commit-message policy (offer template config).
+- **Update from base:** staleness chip → one-click merge; **conflict state is read-only** — file list + "ask a developer" guidance card; never a merge editor.
+- **Unpublished-work nudge:** quiet chip after N checkpoints without publish; never a modal.
+
+### 2.3 Environment & connection health · **M3 (local import) / M4 (full)** · spec §6
+
+- **Env panel** (Settings section + first-run interstitial when detected): key list from `.env.example`/turbo/t3-env/next.config; masked value fields; "stays on this machine, encrypted" caption (Fragment Mono); per-key source badge. Local mode: "Import from your checkout's .env.local" one-click + staleness note.
+- **Adapter-crash translation:** the board's preview error state gets a human sentence ("Preview needs `DATABASE_URL` — add it in Environment") with a jump link — never a raw stack.
+- **Connection card:** provider, access level (read/write chip), last fetch, re-auth inline when token expires.
+- **Doctor strip:** git version, disk per workspace, adapter health — pass/warn/fail glyphs (ink/warn/err), one-line fixes; lives in Settings, surfaces as a toast only on failure.
+
+### 2.4 Home, reworked: workspaces → projects → designs · **M4** · spec §2
+
+- Hierarchy: **Workspace** (repo card: host icon, `owner/name`, branch count, disk, last fetch) → **Projects** (branch cards with checkpoint/publish status) → open editor.
+- "Bring a design system" card → **"Connect a repository"**; the Solstice system card pattern becomes the workspace card.
+- Keep a **Playground** entry (the current 5-token demo path, clearly labeled "no repo — sandbox") — it's the landing-page demo funnel and the only place token-paste onboarding survives. 🟡 founder-confirm.
+
+### 2.5 Desktop shell surfaces · **M0–M7** · spec §3
+
+- **First-run:** git-missing walk-through (per-OS instructions, re-check button); theme choice honored from OS.
+- **Settings additions:** AI key entry (masked, safeStorage caption, "test key" action) · vendored-PM info line · workspace disk usage + archive/cleanup actions · update channel + "restart to update" (adapters drain first — show "stopping previews…" toast).
+- **Deep links:** `veect://` open-workspace/project handling.
+- **Menu/tray:** minimal native menu (About, Check for updates, Quit) — everything else stays in-app.
+
+### 2.6 Docker / headless sign-in · **M7** · spec §13
+
+One page: token field (from `VEECT_TOKEN`), ink wordmark, no marketing. Session cookie after success. Device-flow codes render in-browser for container use. A "you're on a shared instance — publishes author as the stored identity" caption (multi-seat honesty).
+
+---
+
+## 3. Existing surfaces that must evolve
+
+| Surface                         | Change                                                                                                                                                                                                                                                                                                                                                                                   | Milestone · spec ref |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- |
+| **Library panel**               | Demo kit + upload → **discovered components from the repo**: scan progress skeletons; per-file failure badges (⚠ + tooltip, never abort); `client / server / universal` environment badges (mono chips); `@deprecated` + `@veect-ignore` states; mapping badges retire ("map now" survives only for base-kit fallbacks in Playground). Custom `.tsx` upload survives only in Playground. | M1 · §7              |
+| **Server components on canvas** | Selectable/movable, **internals non-editable** — quiet engraved badge "server component — edits its props, not its insides"; settle shimmer (≤1s) on prop change instead of instant re-render.                                                                                                                                                                                           | M5 · §9              |
+| **Adapter status**              | Board-level states: `starting preview…` (staged), `preview crashed — restarting (2/5)` with log-tail drawer, `restart failed` → doctor playbook. Never a blank board.                                                                                                                                                                                                                    | M1 · §9              |
+| **AI panel**                    | Add **provenance chips** on proposals ("built from Card ×3, Button — your library"); **"what was sent" disclosure** (collapsible mono block — privacy trust); **key-missing state** (setup hint + Settings link); model picker stays.                                                                                                                                                    | M6 · §14             |
+| **Checkpoint parity failure**   | New blocking state on Checkpoint: "Canvas and generated code differ (parity 97.2%) — this is a bug on our side; nothing was committed" + diff thumbnail + report action. Honest, self-blaming voice.                                                                                                                                                                                     | M3 · §1              |
+| **Code panel**                  | `prettier ✓ tsc ✓` footer joins **commit context** (`last checkpoint a3f21c9 · 2m`); **code-owned flip**: if the real file was hand-edited outside Veect, panel banner "This design is code-owned now — Veect won't regenerate it" + read-only lock + un-own action. Edit-mode grammar stays (adopted into spec).                                                                        | M3 · §12             |
+| **History panel**               | Steps that became git checkpoints get a **commit tick + short SHA** (mono); restore-cursor semantics unchanged; caption clarifies "history is local; checkpoints are shared."                                                                                                                                                                                                            | M3 · §11             |
+| **System-update screen**        | Keep the diff/impact/apply-with-undo UI as-is — **rewire the source** from "paste tokens" to **Update-from-base** (repo diff of tokens/components after merge). The screen you built is exactly right; only its input changes.                                                                                                                                                           | M4 · §6              |
+| **Isolation mode**              | Variant × state grid derives from **discovered prop types** (literal unions) instead of the demo kit's hardcoded variants.                                                                                                                                                                                                                                                               | M1 · §7              |
+| **Sign-in**                     | Becomes app first-run (no SaaS account in v1) — identity = provider connection; the screen's shell survives as the Docker token page (§2.6).                                                                                                                                                                                                                                             | M4/M7                |
+| **Export dialog**               | Retires from the top bar (→ Checkpoint/Publish). Its file-tree/`npm run dev` content survives inside Playground export + Docker/CI docs.                                                                                                                                                                                                                                                 | M3                   |
+
+---
+
+## 4. Integration seams — where the prototype meets the spec
+
+The codebase's deliberate seams (its README "Handoff notes") map 1:1 onto spec subsystems — this is the coding agent's wiring diagram:
+
+| Prototype seam             | Becomes                                                                                           | Spec ref |
+| -------------------------- | ------------------------------------------------------------------------------------------------- | -------- |
+| `engine/ai.ts#complete`    | Server AI engine (Anthropic, registry-constrained, repair loop, refusal)                          | §14      |
+| Export zip                 | Git engine: checkpoint transaction + publish                                                      | §10      |
+| Placeholder projects       | Workspaces/projects from SQLite + worktrees                                                       | §2, §11  |
+| Auth stub                  | Connections (device flow / PAT / SSH) + safeStorage                                               | §6       |
+| Persistence (zustand only) | SQLite autosave/revisions + `design.veect.json` write-through; zustand stays the in-session store | §11      |
+| Demo registry JSON         | Discovery engine output (`ComponentMeta`/`TokenRegistry`)                                         | §7       |
+| Offline heuristics         | Retained as the record/replay eval harness + demo mode                                            | §14/§15  |
+
+---
+
+## 5. Design-language extensions (the only new rules)
+
+1. **Long-running staged progress** — the one pattern the ink language lacks (clone/install take minutes). Spec: left-aligned stage list, Fragment Mono labels, current stage in `--t1` with elapsed time, done stages get an ink tick, pending in `--t3`; a single 1px progress hairline under the list (no bars, no spinners >600ms); always cancellable; failures replace the stage line with the playbook string in `--err`.
+2. **Semantic assignments for new states:** connection/live health = `--live` (unchanged) · **AI-anything stays amber** (`--warn`) — publish/PR/checkpoint actions are **ink**, never green (success = ink tick + label, per the existing language) · destructive/conflict = `--err`.
+3. **Trust & security captions** are Fragment Mono engraved (same as metadata) — security posture is presented as instrument fact, not marketing.
+4. **The wordmark's square ink terminal** is the only brand mark on new surfaces (Docker page, first-run, PR-success card). No new marks.
+
+---
+
+## 6. State & playbook string catalog (per new surface)
+
+Write these in the §2.7 voice — each error names the cause and the next action, ≤2 sentences:
+git missing · device-code expired · org not authorized · token expired/revoked · no write access · SSH no-agent vs no-identities · host-fingerprint changed (⚠ stern) · clone failed (auth vs network) · install failed (registry/proxy/native-module → "this dependency needs tools this machine doesn't have — use Docker mode") · scripts blocked by trust choice · env missing (named key) · adapter crash/restart/gave-up · parity failure · publish rejected (×4 classes) · behind base · merge conflict · disk pressure · update ready (adapters will restart).
+
+---
+
+## 7. Build order (tied to spec milestones)
+
+| Priority          | Items                                                                                                                                                                                     | Unblocks                                            |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| **P0 (M0–M3)**    | Checkpoint/Publish verbs in top bar · history↔checkpoint ticks · code-owned flip · parity-fail state · env local import + crash translation · adapter status states · first-run git check | Local-mode complete product                         |
+| **P1 (M4)**       | Connect Repository (full §2.1) · trust prompt · Home rework · Publish flow + failure playbooks · System-update rewire · read-only mode                                                    | The flagship remote flow; design-partner onboarding |
+| **P2 (M1/M5/M6)** | Library discovery states · isolation from real props · server-component affordances · AI provenance + disclosure + key settings                                                           | Real-repo depth                                     |
+| **P3 (M7)**       | Docker sign-in · disk/cleanup · deep links · update-drain toast                                                                                                                           | Self-host + polish                                  |
+
+---
+
+## 8. Open design questions (founder or validation, not the design agent)
+
+1. **Board ↔ design mapping:** prototype = one board of frames per project; spec = multiple named designs (folders) per project. **Recommendation:** one board _is_ one design doc (frames within it = its screens); the project dropdown gains a design switcher. Decide before M2 persistence lands. 🟡
+2. **Playground mode** — keep the no-repo sandbox as a permanent funnel? (Recommended yes; it's the landing demo and the only home for token-paste + base kit.) 🟡
+3. **Checkpoint granularity** — every explicit Save = commit (current spec) vs. designer-chosen "milestones"? Validate with design partners in V1 interviews. 🔴
+4. **Landing page claims** — the proof strip (`0 unregistered / <10% LOC / <20 min`) states our _targets_ as facts; before public launch, either validate them (Phase 1 gate) or soften copy. 🔴 (flagged in `founder-os-audit.md`)
+
+---
+
+_End of gap spec. Pair with `veect-design-spec-current.md` (what exists) and `veect-technical-spec.md` rev 1.2.1 (how it must behave). The design agent should deliver §2 screens with full state sets in the ink language; the coding agent wires §4 seams in milestone order._