agentic-dev/docs/product

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.