# 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._
