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:
@@ -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**.
|
||||
|
||||
Reference in New Issue
Block a user