docs: full implementation plan (PRD decisions locked + specs 1-4 + impl plan)

- PRD: 20 locked decisions, open items cleared, fence fixed
- docs/TECH-SPEC-PIPELINE.md: deterministic math + 9 test vectors (deliverable #1)
- docs/ARCHITECTURE.md, DATA-MODEL.md, OPENAPI.md (deliverable #2),
  CONTENT-WOO.md, DEPLOYMENT.md (deliverable #4), IMPL-PLAN.md
- README rewritten; .gitignore added

AGENTS.md pending Ty's approval (protected file write was blocked).

.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+*.egg-info/
+
+# Node
+node_modules/
+frontend/build/
+frontend/.svelte-kit/
+frontend/dist/
+
+# Env / secrets (NEVER commit)
+.env
+.env.local
+.env.*.local
+deploy/.env
+*.pem
+*.key
+
+# Data / images
+*.db
+*.sqlite3
+data/
+images/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/
+
+# Logs
+*.log

README.md

@@ -1,2 +1,43 @@
 # SlabUploader
-this is a woocommerce uploader tool
+
+Mobile-first, self-hosted app for publishing one-of-a-one wood slabs to WooCommerce.
+Field capture (offline) → deterministic measurement/pricing/normalization → publish a
+single slab to the store as a pending product.
+
+Owner: Ty (Whidbey). Store: www.whidbeywoodstore.com. Deploy: .201 (Caddy, Docker).
+
+## Status
+**Planning complete — ready for implementation.** All 20 product decisions locked
+(PRD "Decisions log", 2026-08-24). Build plan in `docs/IMPL-PLAN.md` (phases 0–6).
+
+## Documentation
+| File | What |
+|---|---|
+| `Slab capture app PRD.txt` | Requirements + locked decisions (source of truth for "what") |
+| `docs/ARCHITECTURE.md` | Services, client/server split, offline PWA, data flow |
+| `docs/TECH-SPEC-PIPELINE.md` | Deterministic math + image pipeline, constants, 9 test vectors |
+| `docs/DATA-MODEL.md` | SQLite schema + status state machine |
+| `docs/OPENAPI.md` | Client↔server API contract (deliverable #2) |
+| `docs/CONTENT-WOO.md` | Content templates + WooCommerce payload/integration |
+| `docs/DEPLOYMENT.md` | Compose, Caddy, backup/restore, key rotation (deliverable #4) |
+| `docs/IMPL-PLAN.md` | Phased build plan with acceptance criteria + exit gates |
+| `AGENTS.md` | Working contract + hard rules for anyone implementing |
+
+## Quick orientation
+- **Deterministic core** (measurements, pricing, normalization, Woo sync) is pure,
+  network-free, and unit-tested. Inference (species/character + optional content) is
+  the *only* scoped-LLM surface, and it's toggleable — the app fully works without it.
+- **Offline-first PWA**: capture works with no network; drafts + photos persist in
+  IndexedDB and sync when online.
+- **Two containers** (`frontend`, `fastapi`) + Caddy. Single SQLite + image volumes.
+- **v1 non-goals**: no versioning, no staff/roles, no bulk publish, no analytics,
+  no update path (create-only, SKU-deduped).
+
+## Repo remotes
+- Canonical: `github.com/TyTech99/SlabUploader`
+- Mirror: Gitea `TyTech_Internal/SlabUploader` (truenas.local:30008)
+
+## Getting started (implementer)
+1. Read `AGENTS.md` (hard rules) and `docs/IMPL-PLAN.md` (phases).
+2. Start at Phase 0 — scaffold + the tested deterministic pipeline.
+3. Don't skip the exit gates; Ty signs each phase.

Slab capture app PRD.txt

@@ -10,6 +10,36 @@ Build a mobile‑first, self‑hosted web app that streamlines publishing one‑
 - No bulk publishing; slab‑by‑slab submission only.  
 - Measurements must be accurate; manual length entry is authoritative and used to extrapolate widths and bdft.  
 - No analytics in v1.
+- No pricing tiers in v1 — flat price-per-bdft per species/character.
+- No app-level auth in v1 — no JWT/login; app relies on HTTPS + trusted network.
+- Single SKU per slab; duplicate SKU publish is blocked.
+- Images are purged after successful publish (retained only while draft/retry).
+- Deploy target: .201, Docker Compose + Caddy.
+
+## Decisions log (2026-08-24, Ty)
+1. Widths: sample 3–5 widths at peaks/troughs of the slab edge (see Open items for the bdft formula).
+2. Fallback chain: ruler shot if readable → manual length entry; from manual length + a top-down photo, derive pixel scale and extrapolate widths.
+3. Ruler is always in inches.
+4. Species/character list = synced from WooCommerce categories (FR25); user sets price-per-bdft per value.
+5. No tiers — price = bdft × price_per_bdft, user override before Woo submission.
+6. All inference models must support vision (species/character detection operates on slab photos).
+7. v1 target store: www.whidbeywoodstore.com.
+8. Aspect ratio: 1:1 (Woo best practice), ≥1000×1000 px, slab centered at ~80% fill.
+9. Same SKU = blocked (simple dedupe).
+10. No app-level auth; Woo API auth = username (consumer key) + app password.
+11. Single FastAPI backend (Node service dropped — Python handles WooCommerce REST).
+12. Images not needed after WooCommerce submission; purged on successful publish.
+13. Deploy on .201; Docker + Caddy preferred.
+14. UATs built after the prototype.
+15. The schema in the Security section is the pricing-rule shape — confirmed.
+16. (Orphan ```md fence fixed.)
+17. Bolt.dev deliverable disregarded — this is a Hermes project.
+18. bdft formula: average of sampled widths → bdft = L × w_avg × t / 12 (accepted 2026-08-24).
+19. No usable top-down photo → manual width entry (accepted 2026-08-24).
+20. Normalized image size: 1600×1600 preferred output, 1000×1000 minimum (accepted 2026-08-24).
+
+## Open items
+- (none — all resolved 2026-08-24; see Decisions log items 18–20)
 
 ## Goals and success metrics
 **Goals**
@@ -45,7 +75,7 @@ Build a mobile‑first, self‑hosted web app that streamlines publishing one‑
 - Fallbacks: If SKU or ruler unreadable, allow manual entry (SKU or length). Manual length is authoritative and used to extrapolate widths and sqft.  
 - Enrich: Species detection (optional inference) or manual selection; character selection (manual or optional inference); thickness manual entry.  
 - Pricing: Apply bdft pricing rules (species + character) to compute price recommendation; allow override.  
-- Photo normalization: Background removal, auto‑crop to ~80% frame fill, enforce theme aspect ratios, optional merchandising filter.  
+- Photo normalization: Background removal, auto‑crop to ~80% frame fill, enforce 1:1 aspect ratio, optional merchandising filter.  
 - Review & publish: Final review screen with full override capability; publish single slab to WooCommerce using App Passwords.  
 - Configuration: Configure OpenAI endpoint, WooCommerce credentials, pricing rules, brand voice, and GEO context.
 
@@ -76,7 +106,7 @@ Build a mobile‑first, self‑hosted web app that streamlines publishing one‑
 - **FR12:** User can override species/character at any time prior to publish.
 
 ### Pricing engine
-- **FR13:** UI to define bdft pricing rules by species and character (price per bdft, optional tiers).  
+- **FR13:** UI to define bdft pricing rules by species and character (flat price per bdft; no tiers in v1). Species/character values come from the synced WooCommerce category list (FR25).  
 - **FR14:** Deterministic bdft calculation and application of pricing rules to produce a price recommendation.  
 - **FR15:** Price recommendation editable by user; final price stored as authoritative.
 
@@ -87,13 +117,14 @@ Build a mobile‑first, self‑hosted web app that streamlines publishing one‑
 
 ### Photo normalization and merchandising
 - **FR19:** Remove green‑sheet background deterministically (RemBG/U²Net or equivalent).  
-- **FR20:** Detect slab boundaries and auto‑crop so slab fills ~80% of frame; enforce theme aspect ratios.  
+- **FR20:** Detect slab boundaries and auto‑crop so slab fills ~80% of frame; enforce 1:1 aspect ratio, slab centered; output 1600×1600 px preferred (1000×1000 minimum).  
 - **FR21:** Store both original and normalized images.  
 - **FR22:** Optional merchandising filter (contrast, warmth, grain enhancement) applied deterministically; toggleable per slab.  
 - **FR23:** Provide photo review UI to reorder, delete, or retake images.
 
 ### WooCommerce sync and taxonomy
-- **FR24:** Authenticate to WooCommerce using App Passwords.  
+- **FR24:** Authenticate to WooCommerce using consumer key (username) + consumer secret (App Password) against www.whidbeywoodstore.com.  
+- **FR24a:** Publish is blocked if the slab SKU already exists in WooCommerce (simple dedupe, no update path in v1).  
 - **FR25:** Sync categories, tags, and attributes from WooCommerce and cache locally.  
 - **FR26:** Auto‑assign taxonomy based on species/character mapping; allow manual override.  
 - **FR27:** Create/update single WooCommerce product per slab with SKU, titles, description, price, categories, attributes, and normalized images.  
@@ -106,7 +137,7 @@ Build a mobile‑first, self‑hosted web app that streamlines publishing one‑
 
 ### Configuration and hosting
 - **FR32:** Settings UI for OpenAI base URL, OpenAI API key, model name, WooCommerce URL, WooCommerce App Password, pricing rules, brand voice, GEO context.  
-- **FR33:** App must be deployable via Docker Compose on Ty’s servers; support HTTPS via Caddy/Traefik.  
+- **FR33:** App deploys via Docker Compose on .201 with Caddy for HTTPS (single domain, reverse proxy to frontend + fastapi).  
 - **FR34:** All secrets stored encrypted at rest; all client‑server traffic over HTTPS.
 
 ## Non‑functional requirements
@@ -127,23 +158,23 @@ Build a mobile‑first, self‑hosted web app that streamlines publishing one‑
 - Camera API for capture and immediate preview
 
 **Server (self‑hosted, containerized)**  
-- FastAPI (Python) for deterministic image pipeline, advanced ruler detection, bdft math, RemBG/U²Net background removal, species/character inference endpoint (optional), and content generation wrapper that calls Ty’s OpenAI endpoint.  
+- FastAPI (Python) for deterministic image pipeline, advanced ruler detection, bdft math, RemBG/U²Net background removal, species/character inference endpoint (optional), content generation wrapper that calls Ty’s OpenAI endpoint, and WooCommerce REST integration (taxonomy sync, product creation, sync logging) — the Node.js service from the original draft was folded in (see Decision 11).  
-- Node.js service for WooCommerce REST API integration, taxonomy sync, product creation/update, and logging.  
 - SQLite for v1 (slab records, pricing rules, taxonomy cache, sync history). Optional Postgres later.
 
 **Inference**  
-- Configurable OpenAI‑compatible endpoint (user supplies base URL and key). Inference limited to species/character detection and optional content refinement. All inference calls logged and include confidence scores.
+- Configurable OpenAI‑compatible endpoint (user supplies base URL and key). **The endpoint/model must support vision** — species/character detection operates on slab photos. Inference limited to species/character detection and optional content refinement. All inference calls logged and include confidence scores.
 
 **Deployment**  
-- Docker Compose with `frontend`, `fastapi`, and `node` services.  
+- Docker Compose with `frontend` and `fastapi` services on .201.  
-- Caddy or Traefik for HTTPS and reverse proxy.  
+- Caddy for HTTPS and reverse proxy.  
-- Systemd or container supervisor for service management.
+- Docker compose as the service supervisor.
 
 **Security**  
 - AES encryption for stored secrets.  
-- JWT for session management (single owner account).  
+- No app-level auth in v1 (single owner; app protected by HTTPS + network trust).  
 - HTTPS enforced.
 
+### Pricing rule schema (confirmed as the pricing-rule shape — Decision 15)
 id: uuid
 species: string
 character: string
@@ -152,7 +183,6 @@ created_at: timestamp
 updated_at: timestamp
 
 
-```md
 ## Key flows and acceptance criteria
 
 ### Capture → Enrich → Publish flow
@@ -162,7 +192,7 @@ updated_at: timestamp
 4. Upload: client uploads draft to server for advanced processing.  
 5. Server processing: advanced ruler detection → pixel→inch scaling → widths inference → bdft calc → species/character inference (optional) → pricing engine → photo normalization → content generation (optional via configured OpenAI endpoint).  
 6. Review: client receives enriched draft; user edits/overrides any field.  
-7. Publish: user triggers publish; Node service syncs taxonomy and creates/updates WooCommerce product with normalized images. Status updated and logged.
+7. Publish: user triggers publish; FastAPI syncs taxonomy and creates the WooCommerce product with normalized images (SKU-deduped per FR24a). Status updated and logged.
 
 ### Acceptance criteria
 - End‑to‑end slab capture to published product works on modern iPhone and Android browsers.  
@@ -172,7 +202,7 @@ updated_at: timestamp
 - Deterministic functions covered by unit tests; inference calls logged and stored for audit.
 
 ## Operational and debugging notes
-- Local dev: Docker Compose with `frontend`, `fastapi`, `node`. Use ngrok for mobile testing.  
+- Local dev: Docker Compose with `frontend` and `fastapi`. Mobile testing over LAN/Tailscale against the Caddy-served domain (no public tunnel needed).  
 - Logging: centralized logs per service; store inference request/response payloads for audit.  
 - Testing: unit tests for deterministic math and image processing; integration tests for WooCommerce sync against a staging store.  
 - Secrets: store App Passwords and OpenAI keys encrypted; rotate keys periodically.  
@@ -180,8 +210,8 @@ updated_at: timestamp
 
 ## Next recommended deliverables
 1. Technical spec for the deterministic image pipeline and ruler→inch math (algorithms and test vectors).  
-2. OpenAPI contract between SvelteKit client and FastAPI/Node services.  
+2. OpenAPI contract between SvelteKit client and FastAPI.  
-3. Bolt.dev project skeleton (optional) for UI prototype, with explicit notes on which endpoints must be replaced with deterministic implementations.  
+3. (Disregarded — this is a Hermes project, not bolt.diy.)  
 4. Deployment playbook (Docker Compose, Caddy, backup, key rotation).
 
 

docs/ARCHITECTURE.md

@@ -0,0 +1,174 @@
+# Architecture
+
+Status: SPEC · 2026-08-24 · SlabUploader
+Companion to: PRD (root), TECH-SPEC-PIPELINE.md, DATA-MODEL.md, OPENAPI.md, DEPLOYMENT.md.
+
+## 1. Service topology (2 containers + 1 reverse proxy)
+
+Per Decision 11 the original Node service is folded into FastAPI. Final v1 topology:
+
+```
+                        ┌──────────────────────────────────────────┐
+  mobile (PWA)          │              .201 host                    │
+ ┌──────────────┐ HTTPS │  ┌─────────┐        ┌──────────────────┐  │
+ │  SvelteKit   │───────┼─▶│  Caddy  │───────▶│  frontend (nginx │  │
+ │  browser     │       │  │  :443   │  :5173 │  static + /api   │  │
+ │  IndexedDB   │       │  │  slab.* │  ─────▶│  proxy)         │  │
+ │  camera API  │       │  └─────────┘        └──────────────────┘  │
+ └──────────────┘       │                          │ /api → :8000  │
+        │  (offline:    │                          ▼               │
+         all local)     │                   ┌──────────────────┐   │
+                        │                   │  fastapi         │   │
+                        │                   │  :8000           │   │
+                        │                   │  ┌────────────┐  │   │
+                        │                   │  │ pipeline   │  │   │
+                        │                   │  │ (determin. │  │   │
+                        │                   │  └────────────┘  │   │
+                        │                   │  ┌────────────┐  │   │
+                        │                   │  │ woo client │  │   │
+                        │                   │  └────────────┘  │   │
+                        │                   │  ┌────────────┐  │   │
+                        │                   │  │ inference  │  │   │
+                        │                   │  └────────────┘  │   │
+                        │                   └───────┬──────────┘   │
+                        │                           │              │
+                        │        SQLite + image vols (named volumes)│
+                        └──────────────────────────────────────────┘
+                                          │ (configurable OpenAI-compat
+                                          ▼  vision endpoint, e.g. .202)
+```
+
+- **frontend** — SvelteKit (SSG/SPA mode) + Tailwind. Built to static, served by an
+  nginx container. Pure client app; talks to `/api` on the same origin. No build-time
+  secrets. This is the PWA (SW + IndexedDB).
+- **fastapi** — one Python service owning: deterministic image pipeline, bdft math,
+  pricing engine, WooCommerce REST client, taxonomy sync, inference wrapper,
+  content generation. SQLite + image storage in named volumes.
+- **caddy** — reverse proxy + automatic HTTPS. Fronts `frontend` and routes `/api`
+  to `fastapi`. No separate Traefik/systemd — compose is the supervisor (Decision 13).
+
+No message broker in v1. Long jobs (normalization, publish) run in-process via a
+small background worker (FastAPI `BackgroundTasks` + a lightweight in-process queue,
+or `arq` on SQLite/Redis only if needed). See §6.
+
+## 2. Client/server split (authoritative vs hint)
+
+Per TECH-SPEC §1.5: the client runs a *light* pass for instant feedback; the server
+runs the *authoritative* pass. Stored and published values are always the server's.
+
+| Capability | Client (hint) | Server (authoritative) |
+|---|---|---|
+| SKU OCR | Tesseract.js (accept/manual) | re-run; on mismatch surface both, user picks |
+| Ruler scale | OpenCV.js quick check | full tick detection + cross-check |
+| Widths / bdft | none (needs server geometry) | full pipeline |
+| Green removal / crop | preview only | full normalization |
+| Species/character | none | inference (vision) + manual |
+| Pricing | none | pricing engine |
+| Content (title/desc) | none | templates + optional LLM |
+
+The client never publishes. Only the server writes to WooCommerce (FR24/FR27).
+
+## 3. Offline-first PWA (Decision: full offline per PRD)
+
+### 3.1 What lives on the client (IndexedDB)
+- **Draft slabs**: full metadata (all review-screen fields) + photo blobs
+  (originals). Calibration photos included. IndexedDB object stores:
+  `slabs`, `photos` (blob), `syncQueue`.
+- **Service Worker**: precache app shell (SvelteKit build). API is *not* cached —
+  network-first for API, but the capture flow itself needs no network.
+
+### 3.2 Capture → queue → sync flow
+1. Capture is fully offline: photos → IndexedDB, OCR/ruler hints run locally.
+2. Draft persists to IndexedDB after every step (no "save" button — always saved).
+3. **Upload queue**: when online, the PWA pushes pending drafts (metadata + photo
+   blobs) to `POST /api/slabs/{id}/upload`. Server runs the authoritative pipeline,
+   returns the enriched draft. Client merges enriched values, marks synced.
+4. **Publish** is always an online action (needs Woo). If offline, the slab stays
+   `ready`; publish is enabled when connectivity returns.
+5. Reconciliation: each draft carries a `client_rev` (monotonic int). Server rejects
+   an upload whose `client_rev` < the stored rev for that slab (stale). Conflict
+   surfaces in UI for the user to resolve. v1 has a single owner, so conflicts are
+   rare; the mechanism is there for correctness.
+
+### 3.3 Connectivity detection
+`navigator.onLine` + a lightweight `GET /api/health` probe. UI shows offline banner
+and disables publish. No hard dependency on either — capture works regardless.
+
+## 4. Data flow (happy path)
+
+```
+[client] capture (offline)
+   → OCR SKU (hint) / ruler (hint) / 1–5 photos → IndexedDB draft (rev=1)
+[online] PWA → POST /api/slabs            {draft, rev=1}
+        POST /api/slabs/{id}/upload       {photo blobs}
+[server] authoritative pipeline:
+   ruler→scale → geometry → widths → bdft → species/char (inference, opt)
+   → pricing → normalization → content (opt LLM)
+   → store enriched draft (status=review, rev=2), store original+normalized images
+[client] GET /api/slabs/{id} → review screen (all fields editable)
+[client] PUT /api/slabs/{id}             {overrides, rev=2}
+[client] POST /api/slabs/{id}/publish
+[server] taxonomy sync (if needed) → Woo create (draft/pending) → store woo_product_id
+   → status=published → purge images (Decision 12)
+```
+
+## 5. Determinism boundary
+
+Everything left of the "inference" and "content" boxes is deterministic and unit-
+tested (PRD "Deterministic core"). The two inference-touching paths are:
+- species/character detection (vision) — toggleable, returns confidence
+- optional content refinement (text LLM) — toggleable
+
+Both are wrapped so that toggling them OFF leaves a fully functional deterministic
+app. The app must pass its entire test suite with inference disabled.
+
+## 6. Concurrency & jobs
+
+- v1 is single-owner, single-slab workflow (no bulk). Concurrency is minimal.
+- Long ops (normalization ~3–5s, publish with image upload) use FastAPI
+  `BackgroundTasks` + a per-slab status field (`processing`/`ready`/`publishing`/
+  `published`/`failed`). Client polls `GET /api/slabs/{id}` (short, exponential backoff).
+- If a job dies, the slab is `failed` with a reason; re-publish is idempotent by
+  SKU-dedupe (FR24a) — but v1 has no update path, so a failed publish that already
+  created the Woo product is surfaced for manual handling (see IMPL-PLAN risk).
+- No external broker (Redis) in v1. If the in-process queue proves insufficient,
+  add `arq` + a single Redis container — a documented, reversible extension.
+
+## 7. Security (Decision 10, PRD Security)
+
+- No app-level auth. App is reachable only on the trusted LAN/Tailscale
+  (domain `slab.tyubumini.local`). HTTPS enforced by Caddy.
+- Secrets (Woo consumer key/secret, inference key, AES master key) stored encrypted
+  at rest (AES-GCM) in SQLite; the AES key itself is an env var injected by compose,
+  never in the DB. Config is editable via the Settings UI (FR32) but values are
+  re-encrypted on save.
+- Client stores no persistent secrets. The PWA needs none — all secrets server-side.
+- All client↔server traffic HTTPS.
+
+## 8. Deployment target
+
+- Host: **.201** (no inference there; inference is a remote configurable endpoint).
+- Stack: Docker Compose (`frontend`, `fastapi`) + Caddy (container or host-managed —
+  see DEPLOYMENT.md). Domain: `slab.tyubumini.local` (Decision: LAN/Tailscale only).
+- Named volumes: `slab_db` (SQLite), `slab_images` (original+normalized). Backed up
+  per DEPLOYMENT.md.
+
+## 9. Extensibility (documented, not built)
+
+- Postgres swap for SQLite (DATA-MODEL keeps the schema portable).
+- Redis/arq if job volume grows.
+- Update path for existing Woo products (v2; v1 is create-only by SKU dedupe).
+- Multi-slab bulk (explicit non-goal v1).
+- Staff accounts/roles (explicit non-goal v1).
+
+## 10. Tech stack (pinned intent — exact versions at scaffold)
+
+| Layer | Choice |
+|---|---|
+| Client | SvelteKit, TailwindCSS, Tesseract.js, OpenCV.js, IndexedDB, Camera API, Workbox/SW |
+| Server | Python 3.12, FastAPI, Pydantic v2, OpenCV (cv2), numpy, Pillow, RemBG/U²Net (onnx), httpx |
+| Woo | WooCommerce REST v3 via httpx (consumer key/secret, Basic auth) |
+| DB | SQLite (stdlib `sqlite3` or SQLAlchemy; see DATA-MODEL) |
+| Inference | OpenAI-compatible client (configurable base_url/key/model; must be vision-capable) |
+| Proxy/HTTPS | Caddy |
+| Packaging | Docker Compose |

docs/CONTENT-WOO.md

@@ -0,0 +1,151 @@
+# Content Generation & WooCommerce Integration
+
+Status: SPEC · 2026-08-24 · SlabUploader
+Covers: FR16 (deterministic content templates + optional LLM refinement), FR17
+(brand voice / GEO), FR18 (editable, never auto-published), FR25–28 (taxonomy sync,
+product create, sync log), and the exact WooCommerce REST v3 payload.
+
+## 1. Content generation (FR16–18)
+
+### 1.1 Deterministic templates (always on)
+Templates are configured in Settings (`content_templates`, editable per FR32).
+Defaults below. Placeholders use `{field}`.
+
+**title** (default):
+```
+{species} {length_ft}ft {length_in_remainder}in × {width_avg_in}in Wood Slab — {character}
+```
+Example: `Black Walnut 16ft 0in × 18.2in Wood Slab — Cathedral`
+- `length_ft` = floor(length_in / 12), `length_in_remainder` = length_in mod 12 (1 dp).
+
+**short_title** (default):
+```
+{species} Slab — {character}
+```
+Example: `Black Walnut Slab — Cathedral`
+
+**description** (default, multi-paragraph):
+```
+A one-of-a-one {character} {species} slab, {length_ft}ft {length_in_remainder}in long with an
+average width of {width_avg_in}in and {thickness_in}in thickness ({bdft} bdft).
+
+Each slab is naturally shaped — width varies along the length at {width_min_in}in to
+{width_max_in}in. Sold by the slab; dimensions as measured. {geo_sentence}
+```
+`geo_sentence` = GEO context sentence from Settings (FR17), e.g.
+`"Locally milled and shipped from the Pacific Northwest."` (default if unset: none).
+
+All template math fields come from the deterministic pipeline (never from the LLM).
+
+### 1.2 Optional LLM refinement (FR17, toggleable)
+- Triggered only if `content_llm_enabled` is true AND the user taps "Refine with AI"
+  on the review screen (never automatic — FR18).
+- Prompt (server-side, assembled): system = brand voice + GEO context; user = the
+  template-generated title/description + slab facts; task = "improve the title and
+  description for a premium one-of-a-one wood slab listing. Keep all measurements
+  exact. Do not invent features. Return JSON: {title, short_title, description}."
+- **Guardrail (deterministic)**: after the LLM returns, the server re-checks that every
+  numeric dimension in the LLM text still matches the pipeline values (regex on
+  numbers). Mismatch → reject the LLM output, keep the template version, log the
+  rejection. This keeps measurement accuracy deterministic even when the LLM is on.
+- Output is always editable (FR18); `content_source` = `llm` when used.
+- If the inference endpoint is text-only or unreachable → the button is disabled,
+  templates still work. No failure mode blocks publish.
+
+### 1.3 Audit
+Every content generation (template or LLM) is logged with inputs (template version,
+slab facts), the LLM request/response payload when used (PRD "inference calls logged"),
+and the final stored content.
+
+## 2. WooCommerce integration (FR24–28)
+
+### 2.1 Auth & client
+- REST v3: `GET/POST/PATCH/DELETE {woo_base_url}/wp-json/wc/v3/…`
+- Basic auth: `woo_consumer_key:woo_consumer_secret` (Decision 10; the "username" is
+  the consumer key, the "app password" is the consumer secret).
+- Client: `httpx` with timeouts (connect 10s, read 60s for image-heavy create).
+- `woo_base_url` default: `https://www.whidbeywoodstore.com`.
+
+### 2.2 Taxonomy sync (FR25)
+`POST /api/admin/taxonomy/sync` pulls, in order:
+1. `GET /products/categories?per_page=100` (paginate) → `woo_taxonomy(kind=category)`
+2. `GET /products/tags?per_page=100` → `kind=tag`
+3. `GET /products/attributes` → `kind=attribute`
+Rebuilds the cache table (delete + insert, single transaction). Returns counts.
+Failure → `502 woo_error`; previous cache retained (never delete-then-fail).
+
+### 2.3 Auto-assign taxonomy (FR26)
+- **Category**: species value is matched to a Woo category by name (case-insensitive,
+  trimmed). Match → that category id. No match → the slab's `category_override`
+  (user picks in review) or empty (Woo required-field validation will surface it).
+- **Tags**: `[character]` plus optional `[species]` if present as a tag.
+- **Attributes**: species/character/length/thickness as product attributes if the
+  corresponding Woo attributes exist in the cache (by name). Missing attributes are
+  skipped, not created (v1: no attribute creation).
+- Every assignment is overridable in the review screen (FR26).
+
+### 2.4 Product create payload (FR27)
+`POST /products` — body (only non-null fields sent):
+```jsonc
+{
+  "name": "{title}",
+  "type": "simple",
+  "status": "pending",            // test-target decision: NEVER "publish" automatically
+  "sku": "{sku}",
+  "regular_price": "{price}",     // 2 dp string, e.g. "2730.00"
+  "description": "{description}",
+  "short_description": "{short_title}",
+  "categories": [ { "id": <species category id> } ],
+  "tags": [ { "id": <char tag id> }, … ],
+  "images": [
+    { "src": "<data URL or pre-uploaded attachment URL>", "alt": "{species} {character} slab" }
+  ],
+  "attributes": [ … if present … ],
+  "virtual": false,
+  "downloadable": false,
+  "catalog_visibility": "visible"
+}
+```
+**Image upload strategy** (Woo v3): `images[].src` accepts a URL or a data URL.
+For reliability the server:
+1. For each customer-facing (inventory, normalized) photo in `seq` order:
+   `POST /media` with the JPEG bytes → get attachment `source_url`.
+2. Reference those `source_url` values in `images` (≤5, per PRD 1–5 inventory photos).
+3. Calibration photos are excluded (FR2).
+
+**Status = `pending`** by default (test-target decision: test products must never go
+live without human action). The Settings key `woo_publish_status` (default `pending`)
+controls this; Ty flips it to `publish` only when intentionally going live.
+
+### 2.5 Dedupe & idempotency (FR24a)
+Before create: `GET /products?sku={sku}`.
+- Found → `409 duplicate_sku` (v1 has no update path; human resolves).
+- Not found → proceed. (Single-owner, slab-by-slab, so no TOCTOU concern in practice;
+  the check is still done for correctness.)
+
+### 2.6 Sync result & logging (FR28)
+- On success: set `slabs.woo_product_id`, `status=published`, `published_at`, write
+  `sync_log(status=success, woo_product_id, payload_hash)`.
+- On Woo HTTP error: `status=failed`, `sync_log(status=failed, http_status, error,
+  detail=<Woo error body>)`. Surface in UI + poll response.
+- **Partial-failure note** (risk, see IMPL-PLAN): if media uploads succeed but the
+  final product POST fails, orphaned Woo attachments may exist. v1: log it; a manual
+  cleanup note is surfaced. Not auto-deleted (could delete a real image).
+
+## 3. End-to-end publish sequence (server side)
+```
+1. validate slab publishable (length,width,thickness,price,species,char,≥1 photo)
+2. dedupe by SKU (GET /products?sku=)            → 409 duplicate_sku if exists
+3. (re)sync taxonomy if cache older than 1h       → best-effort; use existing cache on fail
+4. resolve category/tags/attributes (auto-assign + overrides)
+5. upload normalized inventory images → media     → source_urls
+6. POST /products (status=pending)                → woo_product_id
+7. write sync_log(success), set slab published, purge images
+   on any failure at 2–6: write sync_log(failed), slab=failed, (images retained for retry)
+```
+
+## 4. What is deterministic vs scoped-inference here
+- Deterministic: templates, all dimension text, category/tag/attribute resolution,
+  payload assembly, dedupe, logging.
+- Scoped inference: optional LLM title/description refinement only, with the
+  numeric-accuracy guardrail (§1.2).

docs/DATA-MODEL.md

@@ -0,0 +1,166 @@
+# Data Model (SQLite, v1)
+
+Status: SPEC · 2026-08-24 · SlabUploader
+Storage: single SQLite file (volume `slab_db`). Schema kept portable to Postgres
+(DATETIME→TIMESTAMPTZ, TEXT blobs→bytea/objects). All math values stored full
+precision (float64); display rounding is a presentation concern (TECH-SPEC §2).
+
+## Conventions
+- IDs: `TEXT` UUIDv4 (client-generated for slabs so the PWA can reference a slab
+  before it exists server-side).
+- Timestamps: UTC ISO-8601 `TEXT` (`YYYY-MM-DDTHH:MM:SSZ`).
+- Soft state via `status` column; no hard deletes for slabs (audit). Images purged
+  on publish (Decision 12) but the slab row + metadata retained.
+- Money stored as float64 USD, rounded half-up to cents at write (TECH-SPEC §2).
+- `client_rev` / `server_rev`: monotonic ints for optimistic concurrency (ARCH §3.2).
+
+## ERD (text)
+```
+slabs 1─N slab_photos
+slabs 1─0..1 sync_log (latest)   [sync_log is an append-only history; 1 per publish attempt]
+pricing_rules  N─1 (species, character)  [unique pair]
+woo_taxonomy (cache)  categories / tags / attributes
+settings 1 row (key→encrypted value)
+```
+
+## Tables
+
+### slabs
+| col | type | notes |
+|---|---|---|
+| id | TEXT PK | client-generated UUID |
+| sku | TEXT UNIQUE NOT NULL | from OCR or manual; dedupe key (FR24a) |
+| status | TEXT NOT NULL | `draft` `processing` `ready` `review` `publishing` `published` `failed` |
+| species | TEXT | controlled value (from woo_taxonomy categories) or free until confirmed |
+| species_confidence | REAL NULL | from inference, if used |
+| species_source | TEXT | `inference` `manual` |
+| character | TEXT | controlled value |
+| character_confidence | REAL NULL | |
+| character_source | TEXT | `inference` `manual` |
+| length_in | REAL NOT NULL | authoritative (ruler-derived or manual) |
+| length_source | TEXT | `ruler` `manual` |
+| width_avg_in | REAL | average of sampled widths (TECH-SPEC §5.2) |
+| width_source | TEXT | `sampled` `manual` |
+| thickness_in | REAL NOT NULL | always manual (FR8) |
+| sqft | REAL | (L×w_avg)/144 |
+| bdft | REAL | (L×w_avg×t)/12 (Decision 18) |
+| price_per_bdft | REAL NULL | copied from pricing rule at compute time (snapshot) |
+| price | REAL NOT NULL | final authoritative price (override or recommendation) |
+| price_source | TEXT | `recommendation` `override` |
+| title | TEXT | generated/edited |
+| short_title | TEXT | |
+| description | TEXT | |
+| content_source | TEXT | `template` `llm` `manual` |
+| normalized_fill_ok | INTEGER | 0/1 — met ~80% fill target (TECH-SPEC TV-6) |
+| woo_product_id | INTEGER NULL | set on successful publish (FR28) |
+| published_at | TEXT NULL | |
+| client_rev | INTEGER NOT NULL DEFAULT 1 | |
+| server_rev | INTEGER NOT NULL DEFAULT 1 | |
+| created_at | TEXT NOT NULL | |
+| updated_at | TEXT NOT NULL | |
+
+Index: `sku` (unique), `status`, `updated_at`.
+
+### slab_photos
+| col | type | notes |
+|---|---|---|
+| id | TEXT PK | |
+| slab_id | TEXT FK→slabs.id ON DELETE CASCADE | |
+| kind | TEXT NOT NULL | `calibration_sku` `calibration_ruler` `inventory` |
+| role | TEXT | for inventory: `topdown` (the width-sampling photo) or `extra` |
+| seq | INTEGER | display order (FR23 reorder) |
+| original_path | TEXT | relative to images volume |
+| normalized_path | TEXT NULL | set after normalization |
+| is_customer_facing | INTEGER | calibration=0, inventory=1 (FR2: calibration never uploaded) |
+| created_at | TEXT | |
+
+Rule: only `kind=inventory` photos are uploaded to WooCommerce. Calibration photos
+are internal-only (FR2).
+
+### pricing_rules
+| col | type | notes |
+|---|---|---|
+| id | TEXT PK | uuid (PRD pricing schema) |
+| species | TEXT NOT NULL | |
+| character | TEXT NOT NULL | |
+| price_per_bdft | REAL NOT NULL | flat (Decision 5; no tiers) |
+| created_at | TEXT | |
+| updated_at | TEXT | |
+
+`UNIQUE (species, character)`. Seeded from synced Woo categories (Decision 4);
+user sets `price_per_bdft` per value in Settings (FR13).
+
+### woo_taxonomy (cache)
+| col | type | notes |
+|---|---|---|
+| kind | TEXT | `category` `tag` `attribute` |
+| woo_id | INTEGER | Woo term id |
+| name | TEXT | |
+| parent_id | INTEGER NULL | categories |
+| slug | TEXT | |
+| synced_at | TEXT | |
+
+`UNIQUE (kind, woo_id)`. Rebuilt by `POST /api/admin/taxonomy/sync` (FR25). This is
+the controlled list for species (Decision 4 — species drawn from categories) and
+the taxonomy auto-assign source (FR26).
+
+### sync_log (append-only history)
+| col | type | notes |
+|---|---|---|
+| id | INTEGER PK AUTOINCREMENT | |
+| slab_id | TEXT FK | |
+| attempt | INTEGER | 1,2,… per slab |
+| action | TEXT | `create` |
+| woo_product_id | INTEGER NULL | |
+| status | TEXT | `success` `failed` `blocked_duplicate_sku` |
+| http_status | INTEGER NULL | |
+| error | TEXT NULL | machine-readable code |
+| detail | TEXT NULL | human-readable message / Woo error body |
+| payload_hash | TEXT | sha256 of the Woo product payload sent (audit, FR28) |
+| created_at | TEXT | |
+
+FR28: log sync results, surface errors, store Woo product ID on success.
+
+### settings (key/value, encrypted values)
+| col | type | notes |
+|---|---|---|
+| key | TEXT PK | |
+| value_enc | BLOB | AES-GCM ciphertext (see Security) |
+| updated_at | TEXT | |
+
+Keys:
+- `woo_base_url` (plaintext-OK, but encrypted for uniformity)
+- `woo_consumer_key`, `woo_consumer_secret` (secret)
+- `inference_base_url`, `inference_api_key` (secret), `inference_model`
+- `inference_enabled` (bool), `content_llm_enabled` (bool)
+- `brand_voice` (text), `geo_context` (text)
+- `content_templates` (JSON: title/short_title/description templates, FR16)
+- `aspect_ratio` = `1:1`, `output_px` = 1600, `output_px_min` = 1000 (Decision 20)
+- `fill_target` = 0.80
+
+The AES-GCM master key is an env var (`SLAB_AES_KEY`, 32 bytes base64) injected by
+compose — never stored in the DB. Each `value_enc` = `nonce(12) || ciphertext`.
+
+## Status state machine
+```
+draft → processing → ready → review → publishing → published
+                     │                                ↑ (woo_product_id set)
+                     └→ failed (retry → publishing)
+any → failed (with error)
+```
+- `processing`: server pipeline running.
+- `ready`: enriched, awaiting user review.
+- `review`: user has opened/edited the review screen.
+- `publishing`: Woo create in flight.
+- `published`: Woo product created (draft/pending on the store — never live without
+  human action, per test-target decision).
+- `failed`: pipeline or publish error; `sync_log.detail` has the reason.
+
+## Concurrency
+- Single owner. Optimistic locking via `server_rev`: an update must send the `server_rev`
+  it last read; server rejects on mismatch (409) → client re-fetches. This is the
+  server-side counterpart to the client `client_rev` (ARCH §3.2).
+
+## Backup
+- SQLite file + images volume are the only durable state. Backup = `sqlite3 .backup`
+  of the DB file (WAL-safe) + `tar` of the images volume. See DEPLOYMENT.md.

docs/DEPLOYMENT.md

@@ -0,0 +1,156 @@
+# Deployment Playbook (.201, Docker Compose + Caddy)
+
+Status: SPEC (deliverable #4) · 2026-08-24 · SlabUploader
+Target: TyUBUMini at 192.168.1.201. Domain: `slab.tyubumini.local` (LAN/Tailscale
+only — Decision). Inference is NOT on .201; it's a remote configurable endpoint
+(.202 or elsewhere).
+
+> Note: exact Caddyfile/ports to be verified against the live .201 Caddy setup at
+> implementation time (bolt.diy already runs Caddy TLS on tyubumini.local:8443).
+> This playbook is the plan; the first implementation task is a .201 inventory pass.
+
+## 1. Host inventory (do first — do not assume)
+
+Before deploying, record the current state (HARD RULE: inventory before execute):
+1. `docker ps` — existing containers, published ports (avoid collisions; bolt.diy
+   owns 8443/8444-class ports).
+2. Caddy config location (host file or container) and existing `tyubumini.local`
+   site blocks.
+3. Free port choice for the compose stack (proposal: `18080` http, `18443` https —
+   verify free).
+4. Docker volume dir convention on the host.
+5. Tailscale: confirm `slab.tyubumini.local` is reachable from the phone's network
+   (same LAN or Tailscale). If the domain isn't in DNS yet, add it (Pi-hole/AdGuard
+   or Tailscale MagicDNS) — one record, A → 192.168.1.201 (LAN) + Tailscale name.
+
+## 2. Repository layout (at scaffold)
+
+```
+SlabUploader/
+├── AGENTS.md
+├── README.md
+├── docs/                          # this plan set
+├── deploy/
+│   ├── docker-compose.yml
+│   ├── Caddyfile.fragment         # slab site block (merged into host Caddy)
+│   ├── .env.example               # SLAB_AES_KEY, port vars (no real secrets)
+│   └── backup.sh                  # sqlite .backup + images tar, with retention
+├── frontend/                      # SvelteKit app (Phase 1)
+└── backend/                       # FastAPI app (Phase 0)
+    ├── app/
+    │   ├── main.py
+    │   ├── pipeline/              # deterministic core (constants.py, ruler, geometry, widths, pricing, normalize)
+    │   ├── woo/                   # Woo client, taxonomy, publish
+    │   ├── inference/             # vision + content wrappers (toggleable)
+    │   ├── api/                   # routers (slabs, photos, pricing, taxonomy, settings)
+    │   ├── db/                    # schema.sql, models, migrations (alembic)
+    │   └── security/              # AES-GCM settings encryption
+    ├── tests/                     # pytest — unit (deterministic) + integration (woo)
+    └── Dockerfile
+```
+
+## 3. docker-compose.yml (target shape)
+
+```yaml
+services:
+  frontend:
+    build: ./frontend
+    ports: ["127.0.0.1:${FRONTEND_PORT:-18080}:80"]   # Caddy-only; not public
+    depends_on: [fastapi]
+    restart: unless-stopped
+
+  fastapi:
+    build: ./backend
+    environment:
+      SLAB_AES_KEY: ${SLAB_AES_KEY}        # from .env (32-byte base64)
+      # no Woo/inference keys here — they live encrypted in SQLite (Settings UI)
+    volumes:
+      - slab_db:/data
+      - slab_images:/images
+    ports: ["127.0.0.1:${FASTAPI_PORT:-18081}:8000"]  # Caddy-only
+    mem_limit: 2g                            # env convention: mem_limit preferred
+    restart: unless-stopped
+
+volumes:
+  slab_db:
+  slab_images:
+```
+
+Conventions (house rules):
+- `mem_limit` on services (not host-level tuning).
+- Services bind to 127.0.0.1 only; Caddy is the only public surface.
+- No `latest` tags on base images — pin versions.
+- `restart: unless-stopped`; compose is the supervisor (no systemd units).
+
+## 4. Caddy (fragment)
+
+```caddyfile
+slab.tyubumini.local {
+    tls internal            # Caddy internal CA (matches bolt.diy pattern)
+    reverse_proxy frontend:80 {
+        header_up X-Real-IP {remote_host}
+    }
+    handle /api/* {
+        reverse_proxy fastapi:8000
+    }
+}
+```
+- HTTPS enforced (http→https redirect automatic).
+- If the host Caddy already serves `*.tyubumini.local`, add this as a site block;
+  verify the internal CA cert is trusted on the phone (same flow as bolt.diy).
+- LAN/Tailscale only — no public exposure.
+
+## 5. Secrets
+
+| Secret | Where | Notes |
+|---|---|---|
+| `SLAB_AES_KEY` | `.env` on host (mode 600) → compose env | 32-byte base64; NEVER in the repo |
+| Woo consumer key/secret | SQLite `settings` (AES-GCM) via Settings UI | rotate in Woo → re-enter in UI |
+| Inference API key | SQLite `settings` (AES-GCM) via Settings UI | usually empty for local llama.cpp |
+| `.env.example` | repo | placeholders only, committed |
+
+Key rotation (AES): `SLAB_AES_KEY` change requires re-encrypting settings —
+provide `python -m app.security.rekey NEW_KEY` (reads old key from env
+`SLAB_AES_KEY_OLD`, decrypts, re-encrypts, updates). Documented in playbook §7.
+
+## 6. Backup & restore
+
+`deploy/backup.sh` (run via cron on .201, e.g. daily 03:00):
+```
+1. sqlite3 /data/slab.db ".backup /backups/slab-YYYYMMDD.db"   # WAL-safe
+2. tar czf /backups/slab-images-YYYYMMDD.tgz -C /images .
+3. retain: 7 daily + 4 weekly; prune older
+4. log result to /var/log/slab-backup.log; alert (Hermes) on failure
+```
+- Backup target: local dir first; mirror to TrueNAS SMB share
+  (`\\truenas.local\…\backups\slab`) for off-box safety (same pattern as other stacks).
+- **Restore**: stop compose → restore DB file + untar images → start compose.
+  Tested at least once during Phase 6 (UAT) before declaring backup done.
+
+## 7. Operations runbook
+
+| Task | Command / how |
+|---|---|
+| Deploy (first) | inventory §1 → `docker compose -f deploy/docker-compose.yml build` → `up -d` → Caddy reload → smoke §8 |
+| Update | `git pull` → `docker compose build fastapi frontend` → `up -d` (DB migrations run on start via alembic) |
+| Logs | `docker compose logs -f fastapi` / `frontend` |
+| Health | `curl -k https://slab.tyubumini.local/api/health` |
+| Rekey AES | §5 |
+| Rotate Woo creds | Woo UI → new consumer key/secret → Settings UI → `POST /api/settings/test-woo` |
+| Rotate inference key | Settings UI (if external) |
+| Rollback image | `git checkout <tag>` → rebuild → up -d; DB down-migrations provided for schema changes |
+| Reset one slab | delete its photos dir + `UPDATE slabs SET status='draft'` (admin script) |
+
+## 8. Smoke test (after every deploy)
+1. `GET /api/health` → ok
+2. Settings: Woo creds configured + `test-woo` ok
+3. Create a slab → upload test photos (fixture set) → poll to `ready`
+4. Verify bdft/price match the fixture's expected values (golden test)
+5. Publish test slab → `published`, Woo product visible as **pending** in store admin
+6. Delete/leave the pending test product as a staging artifact (never published)
+
+## 9. Scaling path (not v1)
+- Postgres when SQLite write contention appears (schema already portable).
+- Redis+arq when in-process queue shows lag.
+- GPU on .201 only if RemBG latency becomes a bottleneck — otherwise keep it CPU
+  (normalization budget is 3–5s per PRD; U²Net on modern CPU meets that).

docs/IMPL-PLAN.md

@@ -0,0 +1,179 @@
+# Implementation Plan
+
+Status: SPEC · 2026-08-24 · SlabUploader
+The build plan a professional (or a fresh Hermes session) executes against. Each
+phase has: goal, deliverables, acceptance criteria (testable), and exit gate.
+Ordering is by dependency — do not skip ahead. Definition of done for EVERY phase:
+code + tests + real execution output in the PR/commit message + docs updated.
+
+Ground rules (from AGENTS.md):
+- Deterministic core is unit-tested before any UI consumes it.
+- No feature without a passing test and shown output.
+- Inference stays toggleable; the full suite must pass with it disabled.
+- One phase = a reviewable, shippable increment.
+
+---
+
+## Phase 0 — Skeleton & deterministic core (server)
+Goal: repo scaffold + the tested deterministic pipeline, no UI, no Woo.
+
+Deliverables:
+- `backend/` FastAPI skeleton: app factory, health endpoint, config, logging.
+- `pipeline/` implementing TECH-SPEC: constants.py, ruler→scale, geometry, width
+  sampler, bdft math, pricing, green-removal, crop/normalize, merch filter.
+- `db/`: schema.sql + alembic migration for all tables (DATA-MODEL).
+- `tests/`: port every TECH-SPEC test vector (TV-1…TV-9) to pytest; add property
+  tests (bdft monotonic in inputs; width sampler returns 3–5 points; crop fill ∈
+  [0.75,0.85]).
+- Dockerfile for backend; runs `pytest` in CI/local.
+
+Acceptance:
+- `pytest` green, covering all 9 TVs + property tests; coverage of `pipeline/` ≥ 95%.
+- `GET /api/health` works on the dev container.
+- A fixture photo set (3–5 real slab photos) runs end-to-end through the pipeline
+  CLI (`python -m app.pipeline.run <dir>`) and prints bdft/widths/normalized outputs
+  matching hand-computed expectations.
+
+Exit gate: Ty reviews the pipeline CLI output on real photos; math confirmed.
+
+## Phase 1 — API surface (no Woo, no inference)
+Goal: full slab CRUD + photo upload + settings, backed by the Phase-0 core.
+
+Deliverables:
+- Routers per OPENAPI: slabs (CRUD + upload + poll), photos (serve), pricing-rules,
+  settings (with AES-GCM encryption + test stubs), taxonomy (cache read/write).
+- Optimistic concurrency (client_rev/server_rev, 409 paths).
+- Status state machine + in-process job queue (processing→ready).
+- Integration tests (httpx TestClient): create→upload→poll→ready; revision conflict;
+  duplicate SKU; settings encryption round-trip (secret never returned).
+
+Acceptance:
+- OPENAPI.md endpoints implemented; a generated `openapi.yaml` matches the doc.
+- Integration tests green; secrets never leak into any GET response (asserted).
+- `docker compose up` (backend + a throwaway frontend stub) serves the API.
+
+Exit gate: Ty drives the API with curl through a full draft→ready cycle.
+
+## Phase 2 — Frontend: capture & offline PWA
+Goal: mobile-first capture flow, fully offline, with the local light pass.
+
+Deliverables:
+- SvelteKit + Tailwind app (SPA/SSG), Workbox service worker, IndexedDB stores.
+- Capture flow: SKU close-up (Tesseract.js OCR + manual fallback), ruler shot
+  (OpenCV.js hint + manual length fallback), 1–5 inventory photos, thickness entry.
+- Draft autosave to IndexedDB (rev management), offline banner, upload queue.
+- Photo review UI (reorder/delete/retake; mark top-down photo).
+
+Acceptance:
+- On a real phone (LAN/Tailscale), the entire capture flow works with airplane mode
+  on (photos + OCR + draft persist offline).
+- On reconnect, queued draft uploads and the enriched draft merges.
+- Lighthouse mobile ≥ 90 on the capture screens; one-hand usable (manual check).
+- SW precache verified (reload with network off after first load).
+
+Exit gate: Ty captures a real slab fully offline on his phone; draft survives a
+browser restart.
+
+## Phase 3 — Frontend: enrich, review, publish UI
+Goal: the enriched review screen and publish action, wired to Phase-1 API.
+
+Deliverables:
+- Review screen: all fields editable (dimensions, species/character with confidence
+  + manual override, price with recommendation, content with "Refine with AI" toggle,
+  normalized photos).
+- Species/character inference UI (calls server; shows confidence; manual confirm below
+  threshold).
+- Publish button (online-only), status polling, success/failure states, error detail.
+- Settings UI (FR32): Woo creds + test, inference endpoint + test (vision check),
+  pricing rules editor, brand voice/GEO, templates.
+
+Acceptance:
+- Full round-trip in browser: capture→upload→review→edit→publish→published (against
+  a Woo sandbox/mock in tests; against real store in Phase 6).
+- Inference disabled → review screen fully functional with manual species/character.
+- Every field is editable and the override persists (asserted in a test).
+
+Exit gate: Ty publishes a test slab to the real store as a **pending** product.
+
+## Phase 4 — WooCommerce integration (real)
+Goal: production Woo sync, taxonomy, dedupe, logging (FR24–28).
+
+Deliverables:
+- Woo client (httpx, Basic auth, timeouts), taxonomy sync, auto-assign, media upload,
+  product create (status=pending default), dedupe, sync_log.
+- `POST /api/admin/taxonomy/sync` against the real store.
+- Integration tests against a Woo mock (respx) for success + error + duplicate paths.
+- Partial-failure handling (orphaned media noted, per CONTENT-WOO §2.6).
+
+Acceptance:
+- Real publish: product appears in store admin as pending, correct SKU/price/images/
+  category/tags; `woo_product_id` stored; `sync_log` written with payload_hash.
+- Duplicate SKU publish → 409, no second product created.
+- Woo error (bad creds / 500) → slab `failed` with detail; retry path works.
+- All Woo integration tests green (mock + one live smoke).
+
+Exit gate: Ty verifies a real pending product in the store is correct.
+
+## Phase 5 — Inference (vision + optional content)
+Goal: scoped, toggleable inference with guardrails.
+
+Deliverables:
+- Vision wrapper: species/character detection from the top-down photo via the
+  configurable OpenAI-compatible endpoint; returns confidence; logs request/response.
+- Content refinement (optional LLM) with the numeric-accuracy guardrail (CONTENT-WOO
+  §1.2).
+- `test-inference` endpoint (vision capability check).
+- All inference code behind feature flags; suite passes with everything OFF.
+
+Acceptance:
+- With a local vision model configured: species/character suggestion appears with
+  confidence; low confidence → manual confirm required.
+- With inference OFF: full app works, tests green (explicit test asserts no network
+  calls to the inference endpoint).
+- LLM refinement rejects output that alters a measurement (guardrail test).
+- Inference payloads stored for audit (asserted present after a call).
+
+Exit gate: Ty runs species detection on 3 real slabs; results acceptable or manually
+corrected (that's the design).
+
+## Phase 6 — Deployment, UAT, hardening
+Goal: production on .201 + user acceptance tests (PRD deliverable: UATs after prototype).
+
+Deliverables:
+- .201 inventory pass (DEPLOYMENT §1) → final compose + Caddyfile.
+- Deploy to `slab.tyubumini.local`; backup/restore runbook executed once (restore tested).
+- **UAT suite** built from PRD acceptance criteria: a scripted set of real slabs
+  (≥3 species, ≥1 cathedral, ≥1 manual-width fallback, ≥1 offline capture, ≥1
+  duplicate-SKU attempt) with expected bdft/price/image-fill asserted.
+- Performance check: capture OCR 1–2s, server normalization 3–5s per slab (PRD NFR).
+- Docs: README, runbook, key-rotation verified.
+
+Acceptance (PRD success metrics, measured):
+- E2E capture→publish on iPhone AND Android browsers works.
+- Manual length override recalculates widths/sqft/bdft correctly (UAT asserts).
+- Normalization: slab ~80% frame in ≥95% of UAT photos.
+- Woo product created with normalized images + correct taxonomy.
+- Deterministic functions unit-tested; inference calls logged for audit.
+- Backup restore demonstrated once.
+
+Exit gate: Ty signs off on UAT results; v1 declared done.
+
+---
+
+## Risks & mitigations
+| Risk | Impact | Mitigation |
+|---|---|---|
+| Ruler detection unreliable in field lighting | bad scale → bad widths | manual length is authoritative fallback (always available); ruler confidence surfaced; UAT gates it |
+| Green-sheet color varies / U²Net CPU latency > budget | slow/failed normalization | chroma-key primary (fast); U²Net fallback; `output_px` can drop to 1000 min; GPU path documented |
+| No vision model available at deploy | species inference off | inference is toggleable; manual species/character fully functional — v1 not blocked |
+| Woo partial publish (media up, product POST fails) | orphaned images, confusing state | sync_log + retained images for retry; manual cleanup note; no auto-delete |
+| Local llama.cpp vision endpoint not up on .202 | inference off | configurable endpoint; deploy-time config; app works without it |
+| SQLite contention under concurrent polls | slowdown | single owner, low volume; Postgres path documented |
+| .201 port/Caddy collision with bolt.diy | deploy conflict | Phase-0/6 inventory pass before any port bind |
+
+## Definition of Done (v1, project-level)
+- All 6 phases exit-gated by Ty.
+- PRD acceptance criteria met (measured in Phase 6 UAT).
+- `pytest` + integration + UAT green; inference-off path green.
+- Deployed on .201, HTTPS, backed up, restore tested, runbook + key-rotation verified.
+- Repo mirrored to Gitea (GitHub canonical); docs current.

docs/OPENAPI.md

@@ -0,0 +1,186 @@
+# OpenAPI Contract — SvelteKit Client ↔ FastAPI
+
+Status: SPEC (deliverable #2) · 2026-08-24 · SlabUploader
+This is the binding API contract. The machine-readable `openapi.yaml` is generated
+from the FastAPI app at implementation time and must match this doc. Base path:
+`/api`. All requests/responses JSON unless noted. All timestamps UTC ISO-8601.
+
+## Conventions
+- **Auth**: none (ARCH §7). Trusted LAN/Tailscale + HTTPS.
+- **Errors** — uniform envelope:
+  ```json
+  { "error": { "code": "string", "message": "string", "detail": "object|null" } }
+  ```
+  - `400` `validation` — payload failed validation (Pydantic).
+  - `404` `not_found` — unknown slab/setting.
+  - `409` `revision_conflict` — `client_rev`/`server_rev` mismatch (send `detail.current_server_rev`).
+  - `409` `duplicate_sku` — SKU already exists (FR24a).
+  - `422` `unpublishable` — slab not in a publishable state / missing required field.
+  - `502` `woo_error` — WooCommerce rejected the request (`detail` carries Woo body).
+  - `500` `internal` — unexpected.
+- **Revisions**: create/update carry `client_rev`; server echoes `server_rev`. Client
+  stores `server_rev` and sends it back on the next update. Mismatch → `409 revision_conflict`.
+- **Pagination**: v1 lists are small (single owner, slab-by-slab); lists return full
+  arrays. If volume grows, add `?limit&cursor` (documented, not built).
+
+## Schemas (Pydantic v2)
+
+### SlabCreate
+```jsonc
+{
+  "id": "uuid (client-generated)",
+  "sku": "string 3..24 [A-Z0-9-]",
+  "length_in": 0,          // optional at create; required before publish
+  "length_source": "manual|ruler|null",
+  "thickness_in": 0,       // optional at create; required before publish
+  "species": "string|null",
+  "character": "string|null",
+  "title": "string|null", "short_title": "string|null", "description": "string|null",
+  "price": 0, "price_source": "recommendation|override|null",
+  "client_rev": 1
+}
+```
+
+### Slab (read model)
+All of `SlabCreate` fields (resolved) plus:
+`status`, `width_avg_in`, `width_source`, `sqft`, `bdft`, `price_per_bdft`,
+`species_confidence`, `character_confidence`, `normalized_fill_ok`,
+`woo_product_id`, `published_at`, `server_rev`, `created_at`, `updated_at`,
+`photos: [PhotoRead]`.
+
+### PhotoRead
+```jsonc
+{ "id":"uuid","kind":"calibration_sku|calibration_ruler|inventory",
+  "role":"topdown|extra|null","seq":1,
+  "original_url":"/api/slabs/{id}/photos/{pid}/original",
+  "normalized_url":"/api/slabs/{id}/photos/{pid}/normalized|null",
+  "is_customer_facing":0|1 }
+```
+
+### PriceRule
+`{ id, species, character, price_per_bdft, created_at, updated_at }`
+
+### SettingsView (read; secrets masked)
+```jsonc
+{ "woo_base_url":"https://www.whidbeywoodstore.com",
+  "woo_credentials_configured": true,
+  "inference_base_url":"http://192.168.1.202:8080",
+  "inference_model":"<model>", "inference_enabled": true,
+  "content_llm_enabled": false,
+  "brand_voice":"…", "geo_context":"…",
+  "aspect_ratio":"1:1","output_px":1600,"output_px_min":1000,"fill_target":0.80 }
+```
+Secrets (keys) are never returned; only a `*_configured` boolean.
+
+---
+
+## Endpoints
+
+### Health & meta
+- `GET /api/health` → `{ "status":"ok","version":"…","woo_reachable":bool }`
+  (light probe; used by PWA connectivity check, ARCH §3.3)
+- `GET /api/meta` → `{ "version":"…","templates_configured":bool }`
+
+### Slabs
+- `POST /api/slabs`  body `SlabCreate` → `201` `Slab` (status `draft`).
+  - `409 duplicate_sku` if SKU exists.
+- `GET /api/slabs` → `200` `[Slab]` (all, most-recent first).
+- `GET /api/slabs/{id}` → `200` `Slab` / `404`.
+- `PUT /api/slabs/{id}`  body `SlabUpdate` (any subset of editable fields + `client_rev`)
+  → `200` `Slab`. Re-runs derived math (sqft/bdft/price recommendation) server-side when
+  inputs change. `409 revision_conflict`, `409 duplicate_sku`.
+- `DELETE /api/slabs/{id}` → `204` (soft: only allowed while unpublished; published
+  slabs are retained for audit).
+
+### Photo upload (offline queue, ARCH §3.2)
+- `POST /api/slabs/{id}/upload`  body: JSON manifest
+  ```jsonc
+  { "client_rev":2,
+    "photos":[ { "id":"uuid","kind":"inventory","role":"topdown","seq":1,
+                 "blob":"<base64>" , "filename":"slab1_topdown.jpg" } ] }
+  ```
+  (Photos are base64 in v1 for transport simplicity; total request cap 40 MB.
+  If that proves heavy, switch to multipart — documented extension.)
+  → `202` `{ "status":"processing" }`. Server runs the authoritative pipeline
+  (ruler→scale→geometry→widths→bdft→species/char→pricing→normalization→content)
+  asynchronously. Client polls `GET /api/slabs/{id}`.
+  - `409 revision_conflict` on stale `client_rev`.
+  - Pipeline failure → slab `failed` (poll returns the error).
+
+### Publish
+- `POST /api/slabs/{id}/publish` → `202` `{ "status":"publishing" }`.
+  Pre-conditions (else `422 unpublishable`): status in `ready`/`review`, length+width+
+  thickness present, price present, ≥1 inventory photo, species/character confirmed.
+  - Dedupe: if SKU already has a published slab → `409 duplicate_sku` (FR24a).
+  - Woo failure → slab `failed`, `sync_log` written, poll returns `502 woo_error`.
+  - Success → slab `published`, `woo_product_id` set, images purged (Decision 12).
+
+### Status poll
+- `GET /api/slabs/{id}` (same as above) is the poll endpoint. Long-running ops set
+  `status` to `processing`/`publishing`; client backs off (1s,2s,4s… cap 10s).
+
+### Photos (serve)
+- `GET /api/slabs/{id}/photos/{pid}/original` → `image/*` (original, while retained)
+- `GET /api/slabs/{id}/photos/{pid}/normalized` → `image/*` (normalized, while retained)
+  - After publish, both → `410 Gone` (images purged, Decision 12).
+
+### Taxonomy (FR25/FR26)
+- `POST /api/admin/taxonomy/sync` → `200` `{ "categories":n,"tags":n,"attributes":n,"synced_at":"…" }`
+  Pulls from Woo, rebuilds `woo_taxonomy` cache. `502 woo_error` on failure.
+- `GET /api/admin/taxonomy` → `200` the cached taxonomy (grouped by kind).
+  This is the controlled list for species (Decision 4) and auto-assign (FR26).
+
+### Pricing rules (FR13/14/15)
+- `GET /api/pricing-rules` → `[PriceRule]`
+- `POST /api/pricing-rules` body `{ species, character, price_per_bdft }` → `201` `PriceRule`
+  (`409` if pair exists → use PUT).
+- `PUT /api/pricing-rules/{id}` body `{ price_per_bdft }` → `200` `PriceRule`
+- `DELETE /api/pricing-rules/{id}` → `204`
+- `GET /api/pricing-rules/recommend`?species=…&character=…&bdft=… → `200`
+  `{ "price_per_bdft":n|null, "recommendation":n|null }` (FR14; null if no rule).
+
+### Settings (FR32)
+- `GET /api/settings` → `200` `SettingsView`
+- `PUT /api/settings` body: partial `{ key: value }` for non-secret fields, and
+  secret fields by name (values re-encrypted server-side, ARCH §7).
+  → `200` `SettingsView`.
+- `POST /api/settings/test-woo` → `200` `{ "ok":bool,"detail":"…" }` (validates Woo creds).
+- `POST /api/settings/test-inference` → `200` `{ "ok":bool,"vision_capable":bool,"detail":"…" }`
+  (sends a tiny image; `vision_capable` false → UI warns, species inference disabled).
+
+---
+
+## Request/response examples
+
+### Create a slab
+```
+POST /api/slabs
+{ "id":"9f1c…","sku":"BW-0042","length_source":null,"client_rev":1 }
+→ 201
+{ "id":"9f1c…","sku":"BW-0042","status":"draft","server_rev":1, "photos":[], … }
+```
+
+### Upload photos (triggers pipeline)
+```
+POST /api/slabs/9f1c…/upload
+{ "client_rev":1, "photos":[ …base64… ] }
+→ 202 { "status":"processing" }
+GET /api/slabs/9f1c…   (poll)
+→ 200 { "status":"ready","bdft":218.4,"width_avg_in":18.2,"price":2730.0,
+        "species":"Black Walnut","character":"Cathedral","server_rev":2, … }
+```
+
+### Publish
+```
+POST /api/slabs/9f1c…/publish
+→ 202 { "status":"publishing" }
+GET /api/slabs/9f1c…   (poll)
+→ 200 { "status":"published","woo_product_id":1042,"published_at":"…", … }
+```
+
+## Versioning
+URL is `/api/v1` at implementation (this doc omits the prefix for brevity). Breaking
+changes bump to `/api/v2`; the PWA pins the version it was built against.
+
+## Out of contract (v1)
+- Bulk endpoints, staff/role endpoints, webhook push (client polls), analytics.

docs/TECH-SPEC-PIPELINE.md

@@ -0,0 +1,271 @@
+# Technical Spec: Deterministic Image Pipeline & Ruler→Inch Math
+
+Status: SPEC (pre-implementation) · 2026-08-24 · TyTech / SlabUploader
+Scope: PRD deliverable #1 — algorithms and test vectors for the deterministic core.
+No inference, no LLM. Everything here is pure functions of (pixels, inputs) → outputs.
+Every threshold/constant lives in §8 (single source of truth) and is unit-tested.
+
+---
+
+## 1. Invariants
+
+1. **Determinism** — same inputs → bit-identical outputs. No randomness, no timestamps in math, no network calls.
+2. **Manual entry is authoritative** — a user-entered value (length, width, thickness, SKU, price) always wins over any computed value.
+3. **Fallback chain is explicit** — every computed value has a defined fallback; the system never silently guesses.
+4. **All math in inches and board feet** — stored as float64; display rounding per §2.
+5. **Client vs server split** — client runs the *light* pass (preview, OCR, quick ruler check) for feedback; server runs the *authoritative* pass. Server values are what get stored and published. Client results are hints only.
+
+## 2. Units & rounding
+
+| Quantity | Internal | Display | Stored |
+|---|---|---|---|
+| Length, widths | float64 inches | 1 decimal | full precision |
+| Thickness | float64 inches (manual) | 2 decimals (eighths OK in UI) | full precision |
+| sqft | float64 | 1 decimal | full precision |
+| bdft | float64 | 1 decimal | full precision |
+| Price | float64 USD | 2 decimals | 2 decimals (round half-up) |
+
+- bdft is **never rounded up to whole units** (ASSUMPTION — flag to Ty: lumber-trade practice sometimes rounds up; v1 does not).
+- Price computed from unrounded bdft, then rounded half-up to cents.
+- Pixel→inch scale is float64 px/inch, never pre-rounded.
+
+## 3. Ruler → inch scale
+
+### 3.1 Inputs
+- `ruler.png` — calibration photo: a standard **12-inch ruler** (Decision 3: always inches), placed flat and parallel to the slab's long axis on the green sheet.
+- Known: `RULER_INCHES = 12.0` (§8).
+
+### 3.2 Server algorithm (authoritative)
+```
+1. Grayscale, GaussianBlur (k=5, σ=1.0)
+2. Detect the ruler:
+   a. Canny (40, 120) → contours → candidate quads (4 corners, area > 5% of frame)
+   b. Score candidates: high straight-line edge density (Hough, minLineLength=10% of ruler width),
+      regular tick spacing (see 3.3), aspect ratio within 12:0.5..12:2 band
+   c. Take highest score; none above TICK_SPACING_TOL → RULER_FAIL
+3. Perspective-correct the ruler to a top-down rect using its 4 corners
+   → rect of W_r × H_r px, long axis horizontal
+4. Tick detection on the corrected rect:
+   a. Column-wise dark-pixel projection over the central 60% band of the rect
+   b. Local minima with prominence > MIN_TICK_PROMINENCE → tick x-positions
+   c. Cluster ticks; compute gaps; identify the modal gap g_mode
+   d. Tick labels: integer inches where cumulative distance from the first
+      labeled tick ≈ k × g_mode for k = 1..12
+   e. Scale candidate: s = (x_{12th tick} − x_{1st tick}) / 11.0   [px per inch]
+      (11 gaps between tick 1 and tick 12)
+   f. Validation: |g_mode − (s/1)| < TICK_SPACING_TOL and tick count ≥ 12
+5. Cross-check with the ruler rect edges: s_edge = (W_r − 2·margin) / 12.0
+   where margin is the detected pre-"1" and post-"12" padding (mode tick gap).
+   If |s − s_edge| / s < RULER_CROSS_CHECK_TOL → use s.
+   Else → prefer s (tick-based), log warning.
+6. Emit: scale_px_per_inch = s, ruler_confidence = f(tick_count, tol residuals)
+```
+`RULER_FAIL` → the pipeline proceeds via the manual-length path (§5.3).
+
+### 3.3 Client light pass (OpenCV.js, preview only)
+Canny + largest 4-point contour + tick projection. Emits a *hint* scale for live
+feedback ("~201 px/in — looks right"). Never stored. If it fails, UI says
+"ruler unclear — you can enter length manually."
+
+### 3.4 SKU OCR (client, Tesseract.js)
+- Preprocess: grayscale → contrast stretch → upscale ×2 if ruler-width < 800 px → binarize (Otsu)
+- PSM: 7 (single line), character whitelist: `ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-`
+- Accept if: confidence ≥ OCR_CONF_MIN AND regex `^[A-Z0-9-]{3,24}$`
+- Else → manual SKU entry (FR3). Server re-runs OCR on upload as a secondary check; mismatch → surface both, user picks.
+
+## 4. Top-down photo → pixel geometry
+
+The inventory photo used for width sampling must be **top-down** (slab flat on the
+green sheet, camera above). Selection rule: the first inventory photo whose slab
+contour aspect ratio matches (L_px : w_px ≈ reported L : expected w) — else the
+user picks which photo is top-down in the review UI (FR23).
+
+```
+1. Green-sheet removal (see §7.1) → slab mask M
+2. Contour of M → C (largest contour)
+3. Rotate C so its principal axis is horizontal (PCA)
+4. Length in px: L_px = max extent along the axis
+5. If ruler scale available: L_in = L_px / s.  Cross-check vs any user-entered
+   length (manual is authoritative; if |L_in − L_manual| / L_manual > LEN_MISMATCH_TOL
+   → warn in UI, use manual).
+6. Edge profiles: for x ∈ [0, L_px], y_top(x), y_bot(x) from C.
+   Width profile: w(x) = y_bot(x) − y_top(x)
+```
+
+## 5. Dimensions → sqft → bdft
+
+### 5.1 Width sampling at peaks & troughs (Decision 1)
+```
+1. Smooth w(x) with a moving average (window = L_px / 50)
+2. Find local maxima (peaks) and minima (troughs) of w(x) with
+   prominence > WIDTH_FEATURE_PROM
+3. Candidate sample x-positions:
+   - x = 0.05·L_px  and  x = 0.95·L_px  (near both ends, always)
+   - all peak/trough x-positions (trimmed to interior)
+4. Select 3–5 points (WIDTH_SAMPLES_MIN..MAX):
+   always keep the two end points; add interior points ranked by prominence
+   until 5, or stop at 3 if fewer interior features exist.
+5. w_i = w(x_i) in px → inches via scale (or via manual length, §5.3)
+6. w_avg = (Σ w_i) / n        (Decision 18)
+```
+
+### 5.2 Core math
+```
+sqft = (L_in × w_avg_in) / 144
+bdft = (L_in × w_avg_in × t_in) / 12        (Decision 18)
+```
+
+### 5.3 Fallbacks (Decisions 2, 19)
+| Available | Scale source | Length | Widths |
+|---|---|---|---|
+| Ruler OK | ruler px/in | computed (cross-checked vs manual) | sampled from top-down photo |
+| Ruler FAIL, manual L, top-down photo OK | L_manual / L_px | manual (authoritative) | sampled from photo via derived scale |
+| Ruler FAIL, manual L, NO usable top-down photo | — | manual | **manual width entry** (Decision 19; single width = w_avg) |
+| No length at all (no ruler, user declines) | — | BLOCK publish — length is required | — |
+
+## 6. Pricing (Decisions 4, 5, 13)
+```
+rule = pricing_rules[species, character]        (seeded from synced Woo categories)
+recommendation = bdft × rule.price_per_bdft     (unrounded bdft)
+final_price = user override if edited, else recommendation
+stored_price = round_half_up(final_price, 2)
+```
+- No rule for (species, character) → recommendation = null, UI shows "no pricing rule — set price manually". Publish still allowed with a manual price.
+
+## 7. Photo normalization (Decisions 8, 20)
+
+### 7.1 Green-sheet background removal (deterministic first)
+The sheet is a uniform green; chroma-key beats a general matting model here:
+```
+1. Convert to HSV (OpenCV 8-bit: H 0–179)
+2. Sheet mask: H ∈ [GREEN_HUE_LO, GREEN_HUE_HI] AND S ≥ GREEN_SAT_MIN AND V ≥ GREEN_VAL_MIN
+3. Border flood-fill: keep only sheet pixels connected to the image border
+   (protects greenish wood tones inside the slab)
+4. Morphological close (kernel 9) then 1–2px feather on the alpha edge
+5. Fallback: if sheet coverage < SHEET_COV_MIN of frame (wrong background),
+   escalate to U²Net matting for that photo and flag it in the log
+```
+
+### 7.2 Boundary detection & 1:1 crop (FR20)
+```
+1. Slab bbox from mask M (after removal)
+2. Target: slab occupies FILL_TARGET of the final 1:1 frame
+   → frame side (px) = min(bbox_w, bbox_h) / FILL_TARGET
+3. Crop window: square of that side, centered on the bbox center
+   (clamped to source bounds; if clamped, re-center on the clamp-constrained side)
+4. Upscale/crop to 1600×1600 (Decision 20; 1000×1000 is the hard minimum —
+   if source can't supply 1000 px of slab in the short dimension, keep source
+   resolution, flag "low-res" in the review UI)
+5. Output: 1600×1600 PNG (transparency preserved), plus a JPEG (q=85) copy
+   for the WooCommerce upload
+```
+
+### 7.3 Merchandising filter (FR22, optional, per-slab toggle)
+Deterministic LUT: contrast +12% (linear stretch), warmth +8 (R/B channel shift
+toward warm), grain = unsharp mask (radius 2, amount 0.4). Fixed constants in §8 —
+no per-photo tuning. Applied after §7.2, before encode.
+
+### 7.4 What gets stored (Decision 12)
+- While draft / retry: original + normalized, both on disk (Docker volume)
+- After successful publish: both purged (SQLite rows keep metadata only)
+
+## 8. Deterministic constants (single source of truth)
+
+```python
+RULER_INCHES          = 12.0     # known physical ruler length
+CANNY_LO, CANNY_HI    = 40, 120
+MIN_TICK_PROMINENCE   = 0.15     # of projection peak amplitude
+TICK_SPACING_TOL      = 0.05     # 5%
+RULER_CROSS_CHECK_TOL = 0.03     # 3%
+OCR_CONF_MIN          = 70       # Tesseract 0–100
+LEN_MISMATCH_TOL      = 0.05     # 5%
+WIDTH_FEATURE_PROM    = 0.02     # 2% of L_px, in width-profile prominence
+WIDTH_SAMPLES_MIN, WIDTH_SAMPLES_MAX = 3, 5
+END_TRIM              = 0.05     # sample at 5% and 95% of length
+GREEN_HUE_LO, GREEN_HUE_HI = 35, 85
+GREEN_SAT_MIN         = 40
+GREEN_VAL_MIN         = 40
+SHEET_COV_MIN         = 0.25     # sheet must cover ≥25% of frame
+FILL_TARGET           = 0.80     # slab fill of final frame
+OUTPUT_PX             = 1600     # 1:1 output size (Decision 20)
+OUTPUT_PX_MIN         = 1000     # hard minimum
+JPEG_QUALITY          = 85
+FILTER_CONTRAST       = 0.12
+FILTER_WARMTH         = 8
+FILTER_GRAIN_RADIUS   = 2
+FILTER_GRAIN_AMOUNT   = 0.4
+```
+All of these are importable module-level constants (`pipeline/constants.py` when
+implemented) and each test vector in §9 pins at least one of them.
+
+## 9. Test vectors
+
+### TV-1: Ruler scale (pure math)
+Ruler rect corrected; ticks detected at px [100, 300, 500, …, 2300] (12 ticks, 200 px apart).
+- scale = (2300 − 100) / 11 = **200.0 px/in**
+- s_edge with margin 100 px each side, W_r = 2500: (2500 − 200) / 12 = 191.67 → Δ = 4.2% > 3% → use tick scale, log warning. ✔ expected branch.
+
+### TV-2: Full happy path
+- scale = 200 px/in (from TV-1)
+- L_px = 19,200 → L = 96.0 in
+- widths (px) at x = 960, 4800, 9600, 14400, 18240: [3500, 3640, 3800, 3560, 3700]
+  → inches: [17.5, 18.2, 19.0, 17.8, 18.5] → w_avg = **18.2 in**
+- t = 1.5 in (manual)
+- sqft = (96 × 18.2) / 144 = **12.13**
+- bdft = (96 × 18.2 × 1.5) / 12 = **218.40**
+- rule: (Black Walnut, Cathedral) = $12.50/bdft
+- recommendation = 218.40 × 12.50 = **$2,730.00**
+
+### TV-3: Manual length, derived scale
+- RULER_FAIL; manual L = 96.0 in; L_px = 19,200 → scale = 200.0 px/in (derived)
+- Same width px as TV-2 → identical downstream results (18.2 in avg, 218.40 bdft).
+- Asserts the fallback chain is value-equivalent when inputs match.
+
+### TV-4: No top-down photo (Decision 19)
+- Manual L = 96.0, manual width = 18.0, t = 1.5
+- w_avg = 18.0 → bdft = (96 × 18 × 1.5) / 12 = **216.00**
+- No photo used in math; publish allowed.
+
+### TV-5: Pricing edge cases
+- bdft = 218.4, rule $12.34 → rec = 2695.056 → stored **$2,695.06** (half-up)
+- bdft = 0 (degenerate) → rec = $0.00, UI blocks publish (slab must have positive dims)
+- No rule → rec = null; manual price $999.99 stored as-is.
+
+### TV-6: Normalization geometry
+- Source 4000×3000; slab bbox (px): x 400..3600, y 600..2400 → w=3200, h=1800
+- frame side = 1800 / 0.80 = 2250
+- crop: 2250×2250 centered on (2000, 1500) → x 875..3125, y 275..2525 (in bounds ✔)
+- slab fill check: 1800 / 2250 = **0.80** ✔
+- Output: 1600×1600. Slab in output: 1800·(1600/2250) = 1280 px → 80% of 1600 ✔
+- Clamp case: bbox center (1000, 1000), side 2250 → clamp x to 0..2250, y to 0..2250; re-center rule applies; expected crop x 0..2250, y 0..2250 with slab offset left/up — fill still 0.80.
+
+### TV-7: Green-sheet key
+- Synthetic: 1000×1000, H=60 S=120 V=120 background; center 400×200 rect H=20 S=60 V=80 (wood)
+- Expected: mask covers background minus the wood rect; border-flood removes any
+  interior sheet-colored islands; sheet coverage = 60% ≥ 25% ✔ (no U²Net escalation)
+- Wood rect with a green-ish tone (H=45 S=50 V=100) touching no border → NOT removed (border flood) ✔
+
+### TV-8: Width sampler selection
+- w(x) profile: ends 100, peak 140 at x=0.3L, trough 90 at x=0.6L, end 105
+  (prominences: peak 40 ≥ 2% of L_px-scale ✔, trough 50 ✔)
+- Expected sample points: {0.05L, 0.95L, 0.3L(peak), 0.6L(trough)} = 4 points (≤5 ✔)
+- n=4 → w_avg = (100+105+140+90)/4 = 108.75 (px) → inches via scale.
+
+### TV-9: OCR acceptance
+- "BW-0042" conf 85, regex ✔ → accept
+- "BW-004?" conf 78 → regex ✘ → manual entry
+- "BW-0042" conf 65 → conf < 70 → manual entry
+
+## 10. Assumptions (flagged for Ty)
+
+1. **bdft not rounded up** to whole units (§2). Say the word and it's a one-line change.
+2. **12-inch ruler** with inch ticks is the standard calibration tool (Decision 3 implies; spec assumes a 1-ft rule with ticks at every inch).
+3. **Top-down photo selection** = best aspect-ratio match, user-overridable (FR23). No inference used for this.
+4. **Ruler parallel to long axis** — if the user places it diagonally, tick scale is still valid (it's a linear scale), only the cross-check margin logic degrades; acceptable for v1.
+5. Green sheet is the standard bright craft green. A different sheet color → U²Net fallback path (§7.1 step 5), not a config item in v1.
+
+## 11. Out of scope for this spec (next: OpenAPI contract, deliverable #2)
+- Endpoint shapes, request/response schemas, error taxonomy
+- SQLite schema beyond the pricing-rule shape (PRD)
+- WooCommerce product payload mapping
+- Content generation templates (FR16) — deterministic template design is a separate short doc