---
id: 01-commit-product-docs
epic: platform-retrofit
title: Commit the product spec and design references under docs/product/
type: technical-story
status: in-progress
feature: docs
depends-on: []
blocks: [08-rewrite-agent-docs]
created: 2026-07-12T10:22:00Z
updated: 2026-07-12T11:16:19.512Z
---

## Goal

The full Veect specification bundle is committed and authoritative under `docs/product/`: spec docs at top level (filenames preserved from the `.proto/veect-product-docs/` bundle), design references (`Veect.dc.html`, `Veect Landing.dc.html`, the Weave backup, the `veect-codebase/` prototype, upload PNGs) under `docs/product/reference/`, the product README amended with the ADR-027/028/029 supersessions and the `Veect.dc.html` ground-truth authority row (ADR-029 §5). `veect-product-docs.zip` and the emptied `.proto/` are gone.

## Why

Sandcastle implementers run in git worktrees, which contain only committed files — every PRD referencing the spec would be unreadable to the agents implementing it while the bundle sits untracked in `.proto/`. Committing the spec makes it the canonical source dispatch agents can read (PRD user stories 1 and 7).

## Done when

- `git ls-files docs/product/` shows the full committed spec bundle; `.proto/` and `veect-product-docs.zip` no longer exist.
- Design references live under `docs/product/reference/`; the prototype codebase is NOT vendored into `packages/` (ADR-029) and its `package.json` stays outside the pnpm workspace globs (`packages/*`, `apps/*`) by construction.
- Fallow/lint ignore lists skip `docs/product/reference/` so whole-codebase auditors don't flag reference material.
- `docs/product/README.md` opens with a short "Repo supersessions" section linking ADR-027/028/029, and its authority table includes the `Veect.dc.html` ground-truth row.
- HTML prototypes committed as-is (no LFS — PRD Q1).
- `pnpm typecheck && pnpm lint && pnpm test && pnpm conformance && pnpm fallow:audit && pnpm coverage:diff` pass on every commit.

## In scope

- Moving `.proto/veect-product-docs/*` → `docs/product/` (top level, filenames preserved).
- Moving the design references from `.proto/design/` → `docs/product/reference/`.
- Deleting `veect-product-docs.zip` (repo root) and the emptied `.proto/` directory.
- Fallow/lint ignore-list entries for `docs/product/reference/`.
- The "Repo supersessions" + authority-table amendment to `docs/product/README.md`.

## Out of scope

- Vendoring the prototype codebase into `packages/` (never — ADR-029).
- CLAUDE.md/AGENTS.md updates that point at `docs/product/` (story 08).
- Any edits to the spec documents' content beyond the README amendment.

## Tasks

- [x] Migrate the spec bundle `.proto/veect-product-docs/` → `docs/product/` (top level, filenames preserved) and delete the stray `veect-product-docs.zip` at the repo root — spec docs committed and greppable; all gates pass on this commit. _(landed 4d1d534, reviewer-approved; zip was already absent — verified no-op; gates green under the epic's baseline waiver)_
- [ ] Migrate the design references from `.proto/design/` → `docs/product/reference/` (HTML prototypes as-is, `veect-codebase/` prototype, upload PNGs and remaining bundle files), add `docs/product/reference/` to the fallow/lint ignore lists so whole-codebase auditors skip reference material, and delete the emptied `.proto/` — one commit, all gates pass.
- [ ] Amend `docs/product/README.md`: prepend a short "Repo supersessions" section linking ADR-027/028/029 and add the `Veect.dc.html` ground-truth row to the authority table (ADR-029 §5) — one commit, all gates pass.
