Danijel Martinek
ae86501c12
The bundle was authored 2026-07-10 for the Electron/local-first plan; ADR-027/028/029 (2026-07-12) supersede it where they conflict. Prepend a Repo supersessions section, add the Veect.dc.html ground-truth row to the authority table (ADR-029 $5), and mark $3's 'codebase seeds packages/editor' instruction as superseded. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
130 lines
16 KiB
Markdown
130 lines
16 KiB
Markdown
# 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.
|
||
|
||
## Repo supersessions (2026-07-12)
|
||
|
||
This bundle was authored 2026-07-10 for the Electron/local-first plan. On 2026-07-12 the repo's ADRs superseded it where the two conflict — when anything below disagrees with an ADR, the ADR wins:
|
||
|
||
- **[ADR-027 — hosted SaaS + control-plane/runner split](../decisions/adr-027-hosted-saas-and-runner-split.md).** Veect v1 is a hosted cloud SaaS, not an Electron desktop app. Retires the tech spec §3 runtime machinery (bundled Node, PATH shim, ABI policy, `safeStorage`), the GitHub device flow, per-workspace SQLite, and the self-host Docker image for v1.
|
||
- **[ADR-028 — iframe canvas](../decisions/adr-028-iframe-canvas.md).** The board renders real repo components through runner-served iframes; NodeRenderer retires to the Playground only.
|
||
- **[ADR-029 — DesignDoc v1 + editor rebuild](../decisions/adr-029-designdoc-v1-and-editor-rebuild.md).** DesignDoc v1 is the canonical committed schema, and the editor is **rebuilt** under template conventions — this supersedes this README's §3 "the codebase seeds `packages/editor` — do not rebuild" instruction. The prototype codebase is reference material only, at `docs/product/reference/`.
|
||
|
||
---
|
||
|
||
## 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.** |
|
||
| **Editor interaction & copy ground truth** (where newer than the design spec) | **`reference/project/Veect.dc.html`** | Per ADR-029 §5, the ground-truth order is `Veect.dc.html` > `veect-design-spec-current.md` > prototype codebase (reference only). |
|
||
| **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. _Superseded by ADR-029: the editor is rebuilt under template conventions; the prototype codebase is reference-only._
|
||
|
||
**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._
|