docs(work): add Veect ADRs 027-029, glossary terms, first two PRDs

Records the 2026-07-12 grill-session decisions repurposing this repo
for Veect v1 as a hosted SaaS: ADR-027 (hosted distribution +
control-plane/runner split), ADR-028 (iframe canvas), ADR-029
(DesignDoc v1 canonical + editor rebuild). Seeds the work pipeline
with the platform-retrofit and walking-skeleton PRDs (approved) and
adds the Veect product-domain section to the glossary. These
consciously supersede the .proto bundle's Electron/local-first
distribution decisions.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
This commit is contained in:
2026-07-12 12:17:35 +02:00
parent ee0fec0691
commit 442b70476c
6 changed files with 415 additions and 0 deletions

View File

@@ -406,6 +406,60 @@ The Renovate-triggered re-walk of `evaluate-library` when a runtime dep's major
**Dev-seed mode**:
`USE_DEV_SEED=true` (or default fallback when not in production) → `bindAll()` wires populated mocks + `InMemoryEventBus` + `InMemoryJobQueue`. Developer default so `pnpm dev` boots without Payload running.
## Veect product domain
Terms for the Veect product being built in this repo (hosted design-to-code SaaS; source bundle in `.proto/veect-product-docs/`, superseded on distribution by the 2026-07-12 founder decisions). Vocabulary here wins over the `.proto` docs where they disagree.
**Control plane**:
The hosted multi-tenant Veect service — auth, tenancy, project metadata, design-doc persistence, AI proxying, and orchestration of workspace runners. The part of Veect that Veect operates.
**Workspace** (Veect domain):
A connected repository plus its Veect-side state — credentials, env values, trust settings, runner, discovered registry. One workspace = one repo. Owned by the `workspaces` feature.
_Avoid:_ pnpm workspace (build tooling sense) — qualify when ambiguous.
**Project** (Veect domain):
A design project inside a workspace — a git branch (`veect/<slug>`) backed by a managed worktree, carrying checkpoints and publish state. Owned by the `projects` feature.
_Avoid:_ "project" in the generic repo/monorepo sense.
**Workspace runner** (a.k.a. **runner**):
The process boundary that executes a connected repo's own code — clone, worktrees, dependency installs, discovery scans, preview adapters (dev servers), and git operations. Talks to the control plane over the **runner protocol**. Two implementations: **cloud runner** and **local runner**.
**Cloud runner**:
The Veect-operated runner implementation — one isolated container per workspace (CPU/mem limits, egress allowlist, no cross-tenant network) on Veect-managed infrastructure. Founder decision 2026-07-12.
**Local runner** (a.k.a. **CLI agent**):
The user-operated runner implementation — a CLI the developer runs against a local checkout; the browser editor reaches it directly (127.0.0.1) after pairing with the hosted session. Ships in v1 (founder decision 2026-07-12). The successor of the spec's "local folder" connection mode.
**Runner protocol**:
The single contract between control plane/editor and any runner implementation — the generalization of the tech spec §9 "common runtime protocol". One protocol, N runners (cloud, local, later Tauri-embedded).
**Preview adapter**:
The runner-side process that serves a workspace's frames through the repo's own toolchain (embedded Vite or managed `next dev`), one dedicated origin per adapter. The canvas's iframes and the parity check both render through it.
**Canvas agent** (and **canvas protocol**):
The Veect-authored script the preview adapter injects into every frame host page — hit-testing, selection reporting, geometry measurement (`fonts.loaded`-gated), drop-target resolution — speaking a pinned-`targetOrigin` postMessage contract (the canvas protocol, part of the runner-protocol family). Never sourced from the customer repo. See ADR-028.
**Iframe canvas**:
The canvas rendering model (founder decision 2026-07-12): React Flow frames host cross-origin iframes served by the preview adapter; selection/hover/hit-testing/measurement run through an injected agent script over postMessage. Honors the one-runtime invariant — the canvas is the repo's compiled output, never an approximation.
**Playground**:
The no-repo sandbox mode — token-paste/5-token onboarding, base kit, NodeRenderer rendering. The only place the inherited NodeRenderer remains the canvas; also the landing-page demo funnel.
**Design doc** (`design.veect.json`):
The canonical, committed, PR-reviewable design document on a project's branch — DesignDoc v1 schema (tech spec §8): Frame/Element/Text nodes, `lit | token | expr` prop values, Element nodes referencing discovered components by registry id. The editor's in-memory model maps to it; it is the contract engineers review.
_Avoid:_ the prototype's 13-type `VeectNode` shape — that is a Playground-internal view-model, never the committed schema.
**Registry** (Veect domain):
The discovered component + token inventory of a workspace (`ComponentMeta` + `TokenRegistry`), produced by the discovery feature from the repo's own source. The AI whitelist, the library panel, and codegen all consume it. "0 unregistered elements" is measured against it.
**Checkpoint** (Veect verb):
Committing a project's current state to its branch — codegen → prettier → diagnostics → parity check → atomic commit, executed as one transaction inside the runner. Distinct from autosave (control-plane persistence).
**Publish** (Veect verb):
Pushing a project's branch to origin and surfacing the compare/PR link. Never touches the base branch.
_Avoid:_ "export" for this action — export survives only as the Playground/CI artifact path (`veect export`).
_Avoid:_ confusing the Veect **workspace** (a connected repo + its state) with a pnpm workspace, and Veect **worktree** (git worktree backing a design project) with the dispatch loop's agent-isolation worktrees.
## Relationships
- A **PRD** decomposes into one or more **Epics**.