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

docs/decisions/adr-029-designdoc-v1-and-editor-rebuild.md

@@ -0,0 +1,45 @@
+# ADR-029 — DesignDoc v1 as the committed schema; editor rebuilt to conventions
+
+**Status:** Accepted
+
+**Date:** 2026-07-12
+
+## Context
+
+Two related inheritance questions from the `.proto` bundle needed resolution before PRDs could be written.
+
+**The schema schism.** The bundle contains two different design-document models: the tech spec's **DesignDoc v1** (§8 — Frame/Element/Text nodes; `lit | token | expr` prop values where `expr` renders as a chip and emits verbatim with a review marker; Element nodes referencing *arbitrary discovered components*; unknown-component error states) and the prototype's **VeectNode** (13 hardcoded demo-kit types with one flat props bag). This choice is contract-level: `design.veect.json` is committed on the project's branch and reviewed by engineers in every Veect PR — the single hardest artifact to migrate later.
+
+**The inheritance question.** The bundle loudly locks "inherit the editor, do not rebuild — the codebase seeds `packages/editor`". But analysis showed the bundle holds *three generations* of the editor (React codebase < written design spec < `Veect.dc.html` interactive prototype), with the codebase missing table-stakes surfaces (history panel, preview overlay, tool pill, ⌘K, toasts, AI ghost rendering, node deletion). The lock's premises also predate the 2026-07-12 decisions: the iframe canvas (ADR-028) retires NodeRenderer — the codebase's biggest organism — from the board path; DesignDoc v1 replaces the store's node model; and the hosted topology (ADR-027) moves the editor into `apps/web-next` on React 19, ending its Vite standalone-ness. What the lock protected has mostly been invalidated by newer decisions.
+
+## Decision
+
+**1. DesignDoc v1 (tech spec §8) is the canonical schema for `design.veect.json`.** Zod schemas live in the `design-doc` feature (entities layer). Element nodes reference discovered components by registry id; prop values are `lit | token | expr`; `expr` is never evaluated — it renders as a chip and emits verbatim with a `// veect:expr` review marker. The Playground's base kit is just another registry, so Playground documents use the same schema.
+
+**2. The editor's in-memory model is a view-model with an explicit mapping layer.** Whatever shape the editor store needs for interaction performance, it maps to/from DesignDoc v1 at the persistence and codegen boundaries. The prototype's `VeectNode` shape is at most an internal detail of the Playground — never the committed contract.
+
+**3. Code-panel edit mode ships honestly.** The bidirectional grammar is proven for the generated shape of registry components; it is *not* proven for arbitrary hand-written TSX. Edit mode is therefore enabled exactly where the grammar provably round-trips (golden tests emit → parse → emit byte-identical, per spec §12), and the panel downgrades to read-only with an explanatory banner elsewhere (server-component subtrees, `expr`-bearing nodes, code-owned files). Honesty over false parity — the same voice as the parity-failure state.
+
+**4. The editor UI is rebuilt under template conventions, not vendored.** This deliberately reverses the bundle's "do not rebuild" lock, for the reasons in Context. The rebuild is conformance-native from day one: components in `packages/editor` (+ the ink design language in `core-ui`) with stories and tests as the ESLint rules expect, React 19, store designed around DesignDoc v1 and the iframe canvas.
+
+**5. What "inherit the editor" still means — the engine logic and the design.** The prototype's pure logic ports as tested libraries: the codegen/parser grammar (generalized per §12), the view-cluster math (`views.ts`), the Polish rule engine, the AI whitelist sanitizer, color/token math. The interaction design, copy, and visual language port from the design artifacts with this **ground-truth order: `Veect.dc.html` (newest — interaction + copy) > `veect-design-spec-current.md` > prototype codebase (reference only, never vendored).** This amends the bundle's authority table, which had no row for the HTML.
+
+## Alternatives considered
+
+- **VeectNode as the committed schema, extended with a `custom` type.** Fastest vendoring, no mapping layer. Rejected: bakes demo-kit assumptions into the reviewed contract; migrating design partners' committed JSON later is the migration you never want.
+- **Vendor the codebase + "editor completion" epic to HTML parity.** The pre-grill recommendation. Rejected by the founder in light of ADR-027/028: the completion epic would rebuild the canvas, store, and React version anyway while dragging along un-storied, un-tested vendored files behind a lint-exemption zone.
+- **Adopt DesignDoc v1 but cut edit mode from v1.** Safest. Rejected: the bidirectional grammar is one of the prototype's two headline innovations and the tech spec explicitly adopted it; the honest-downgrade rule contains the risk without cutting the feature.
+
+## Consequences
+
+- An **editor-foundation PRD** (board shell, panels, store on DesignDoc v1, keyboard model, canvas protocol client) precedes the subsystem PRDs that add panels; there is no "editor completion" epic.
+- `component-must-have-story` / `component-must-have-test` apply to the editor from the first commit — no exemption zone, no tightening debt.
+- The grammar's generalization to arbitrary registry components (imports via registry metadata, prop serialization rules, escaping — the prototype never escaped text content) is in scope for the codegen PRD, with the round-trip golden suite as its gate.
+- The prototype codebase and `.dc.html` files are committed as reference material (location decided in the platform-retrofit PRD) so dispatch agents can read them; `packages/editor` starts empty.
+- Node identity across code edits (the prototype minted fresh ids on parse-back, breaking anchor claims) must be solved in the design-doc PRD — stable-id preservation is a schema-level concern.
+
+## Related
+
+- ADR-027 (hosted topology — React 19 / web-next placement), ADR-028 (iframe canvas — what the rebuilt board targets)
+- Tech spec §8 (DesignDoc v1), §12 (codegen + golden tests); design spec §5 (prototype node model), §9 (grammar)
+- Glossary: **Design doc**, **Registry**, **Iframe canvas**, **Playground**