docs: label Phase 0 scaffold targets on docs-only main

TEST-SPEC harness paths and compose Dockerfiles are deliverables until code
lands. Cases stay not run. Stops agents inventing alternate test trees.

README.md

@@ -16,22 +16,22 @@ Build order is in `docs/IMPL-PLAN.md`. Empty app on the real host first, then th
 
 ## Documentation
 
+Ownership detail lives in `AGENTS.md` §0. Short map:
+
 | File | What |
 |---|---|
 | `AGENTS.md` | Hard rules. Read first. |
-| `docs/ARCHITECTURE.md` | Hybrid topology, what runs where, secrets, status machine |
+| `docs/IMPL-PLAN.md` | What to build next (phases, Gates A/B/C, exit gates) |
-| `docs/TECH-SPEC-PIPELINE.md` | Math, image pipeline, constants, test vectors TV-1–TV-10 |
+| `docs/TECH-SPEC-PIPELINE.md` | Math, image pipeline, TV-1–TV-10 |
-| `docs/DATA-MODEL.md` | SQLite tables, slab statuses, settings |
+| `docs/ARCHITECTURE.md` | Hybrid topology, secrets why, status machine |
-| `docs/OPENAPI.md` | Browser to server API |
+| `docs/UX.md` | Signed mill-owner presentation (phone and PC) |
-| `docs/CONTENT-WOO.md` | Titles, descriptions, WooCommerce payload |
+| `docs/TEST-SPEC.md` | Engineer test bar (cases stay `not run` until code exists) |
-| `docs/PROMPTS.md` | Call 1 / Call 2 prompt files (server text files) |
-| `docs/DEPLOYMENT.md` | Compose, Caddy, secrets placement, ops |
-| `docs/UX.md` | Presentation: what the mill owner sees and does |
 | `docs/UAT-PRACTICE.md` | Walkable practice UAT for `SLAB-UAT-*` |
-| `docs/IMPL-PLAN.md` | Phases 0–6, exit gates, deferred stub (Phase 2) |
 | `deploy/INVENTORY.md` | Host worksheet before binding ports |
 | `docs/archive/PRD-2026-08.txt` | Frozen history, not a source for new work |
 
+`docs/UX-DESIGN.md` is non-normative wireframes. `docs/UX.md` wins on conflict.
+
 ## Short map
 
 - Client (SvelteKit) owns the happy path: mask knobs, sqft, bdft, 3:4 PNG. Server (FastAPI) stores drafts, talks to WooCommerce, and proxies vision. Server matting ("Try harder") is deferred from POC; POC mask tuning is client-side only.
@@ -50,7 +50,7 @@ Source of truth: Gitea `Ty_Tech/SlabUploader` on gitea-atd
 
 ## Getting started
 
-1. Read `AGENTS.md` and Phase 0 in `docs/IMPL-PLAN.md`.
+1. Read `AGENTS.md` (locks) and `docs/IMPL-PLAN.md` Phase 0 (build next).
-2. Build the client math modules and a thin FastAPI health/settings app. Measuring lives in the browser.
+2. Run `docs/checks/check-structure.sh` if you change doc ownership or calendar homes.
-3. Ty signs each phase.
+3. Scaffold `frontend/` and `backend/` per Phase 0. Measuring lives in the browser. Compose paths are already pinned.
-4. Live docs on `main` are the source of truth. The archive PRD is frozen history only.
+4. Ty signs each phase. Live docs on `main` are the source of truth. The archive PRD is frozen history only.

deploy/docker-compose.yml

@@ -1,5 +1,8 @@
-# Implementable compose for SlabUploader (docs/refactor-v2).
+# Implementable compose for SlabUploader.
-# From repo root:
+# Phase 0 deliverable targets: frontend/Dockerfile, backend/Dockerfile,
+# backend/app/prompts/, and deploy/.env.example are not yet in the tree on
+# docs-only main. This file pins their paths so scaffolding does not invent them.
+# From repo root (after those scaffolds exist):
 #   cp deploy/.env.example deploy/.env && chmod 600 deploy/.env
 #   docker compose -f deploy/docker-compose.yml --env-file deploy/.env up -d
 # Bind loopback only. Caddy is the TLS edge. Services on the compose network

docs/DEPLOYMENT.md

@@ -38,13 +38,13 @@ SlabUploader/
 ├── README.md
 ├── docs/                          # this plan set
 ├── deploy/
-│   ├── docker-compose.yml
+│   ├── docker-compose.yml         # checked in; build contexts point at Phase 0 deliverables
 │   ├── Caddyfile.fragment         # slab site block (merged into host Caddy)
 │   ├── INVENTORY.md               # filled at Gate B on the designated host
-│   ├── .env.example               # SLAB_AES_KEY, APP_*, WOO_BASE_URL (https only)
+│   ├── .env.example               # Phase 0 deliverable (SLAB_AES_KEY, APP_*, WOO_BASE_URL)
-│   └── backup.sh                  # sqlite .backup + images tar, with retention
+│   └── backup.sh                  # Phase 0/6 deliverable (sqlite .backup + images tar)
-├── frontend/                      # SvelteKit app
+├── frontend/                      # Phase 0 deliverable — SvelteKit app (not yet in tree on docs-only main)
-└── backend/                       # FastAPI app
+└── backend/                       # Phase 0 deliverable — FastAPI app (not yet in tree on docs-only main)
     ├── app/
     │   ├── main.py
     │   ├── (no happy-path pipeline SoT here)  # hybrid: TECH-SPEC modules live in frontend/ or shared pure TS; backend = store/Woo/inference/U2Net stub
@@ -58,10 +58,13 @@ SlabUploader/
     └── Dockerfile
 ```
 
+The layout above is the **scaffold target**. On docs-only `main`, `frontend/`, `backend/`, `deploy/.env.example`, and `deploy/backup.sh` are not yet in the tree. Compose still names those build contexts so Phase 0 does not invent paths.
+
 ## 3. docker-compose.yml (checked in)
 
-Canonical file: `deploy/docker-compose.yml`. Placeholders: `deploy/.env.example`.
+Canonical file: `deploy/docker-compose.yml`. Placeholders: `deploy/.env.example` (Phase 0 deliverable).
-From **repo root**:
+Compose `build.dockerfile` paths are **Phase 0 deliverable targets**, not proof the Dockerfiles exist yet.
+From **repo root** (after Phase 0 scaffolds exist):
 
 ```
 cp deploy/.env.example deploy/.env && chmod 600 deploy/.env

docs/TEST-SPEC.md

@@ -53,15 +53,19 @@ Other abbreviations used in this document:
 
 ## 2. How cases are executed
 
-Test automation lives in the repo under `backend/tests/` and `frontend/e2e/`. The harness uses:
+This file is the engineer bar. It is not proof that the harness tree exists yet.
+
+On docs-only `main`, `frontend/` and `backend/` are **not yet on this branch**. Paths below are **Phase 0 deliverable targets** until the code lands. Until then every Phase 0 (and earlier) case stays `not run`. Do not treat `frontend/e2e/` or `backend/tests/` as present. Do not invent a different test layout (for example `frontend/test/bvt/`) to satisfy this bar.
+
+When code lands, automation lives under:
 
 - **Unit tests**: `backend/tests/unit/` (pytest) and `frontend/src/__tests__/` (Vitest). These run against pure modules with no network calls.
 - **API contract tests**: `backend/tests/contract/` (pytest + `httpx` TestClient). These hit the FastAPI app through its test client, asserting request/response shape, status codes, and revision handling.
 - **Integration tests**: `backend/tests/integration/` (pytest + `httpx` TestClient + `respx` WooCommerce mock). These verify Woo create, duplicate SKU, taxonomy sync, stale-field recovery, and settings encryption round-trips without touching a real store.
 - **UI end-to-end tests**: `frontend/e2e/` (Playwright). These exercise the full browser flow: capture, mask knobs, axis confirm, numbers entry, review, and publish. They run against a started Docker Compose stack with the FastAPI test server and mocked Woo endpoints.
-- **Ops / deployment tests**: `deploy/tests/` (shell scripts). These verify compose health, backup/restore, and Caddy routing.
+- **Ops / deployment tests**: `deploy/tests/` (shell scripts). These verify compose health, backup/restore, and Caddy routing. `docs/checks/check-structure.sh` is a docs-structure pin and may run before app code exists.
 
-Test dependencies are pinned in `backend/tests/requirements-test.txt` and `frontend/package.json` (devDependencies). CI runs the full suite before any merge; the suite must pass with inference disabled.
+Test dependencies are pinned in `backend/tests/requirements-test.txt` and `frontend/package.json` (devDependencies) when those packages exist. CI runs the full suite before any merge once the tree has code; the suite must pass with inference disabled.
 
 ---