docs(m3): lock Create requirements on m3-ds

Add docs/CREATE.md as M3 SoT from Ty conversation (Woo attributes sync,
ready-set use, create, OpenAI Settings dependency). Point AGENTS/PRODUCT
here; mark main milestone splits obsolete for this branch.

AGENTS.md

@@ -2,31 +2,37 @@
 
 ## Agent context
 
-Read this file, `docs/CAPTURE.md`, and `docs/PHOTOS.md`.
+Read this file, `docs/CAPTURE.md`, `docs/PHOTOS.md`, and `docs/CREATE.md`.
-Implement Milestone 2 only. Specification: `docs/PHOTOS.md`.
+Implement **Milestone 3** only. Specification: `docs/CREATE.md`.
-PRD: `docs/PRODUCT.md` for destination and field names. Do not implement Milestone 3 or 4.
+PRD overview: `docs/PRODUCT.md` for destination and field names.
-Do not widen Milestone 2 into Complete-listing taxonomy, SKU, price, copy, or Woo create.
 
-## Milestone 2
+**M3 scope SoT is `docs/CREATE.md` and the Ty conversations that produced it.**
+Milestone / task breakdowns on `main` are obsolete for M3. Do not cross-reference `main` for scope once coding on this branch.
 
-Photos.
+Do not implement work outside `docs/CREATE.md` unless Ty expands scope in chat.
-Acceptance: on a phone, batch of 1–N photos, user-picked calibration photo through Milestone 1 mask/axis/measure, every successful shot as a 3:4 transparent inventory PNG lined up, Milestone 1 numbers on screen, dimension-overlay copy of the calibration PNG present.
+Do not touch deploy port `:10880`. UAT redeploy target is overnight Docker on ubudual5060 `:10881`.
 
-Milestone 2 is inference-free. Batch mask/crop reuse and dimension overlays run in the browser as ordinary code. There is no inference URL and no model call in this milestone.
+## Milestone 3
 
-## Milestone 1 (historical)
+Create — Woo attributes sync (WordPress application password), proper use of the synced taxonomy for the ready set and product create, plus OpenAI-compatible inference endpoint dependency in Settings.
+Acceptance: see Done when in `docs/CREATE.md`. Practice SKU `SLAB-UAT-*` exists in the store as draft; create works with inference off.
 
-Capture. Spec: `docs/CAPTURE.md`. Remains the calibration math and PNG contract Milestone 2 reuses.
+## Milestone 1–2 (shipped inputs)
+
+- Capture: `docs/CAPTURE.md` — calibration math and PNG contract.
+- Photos: `docs/PHOTOS.md` — batch inventory PNGs + dimension overlay. Base tip for this branch: shipped M2 on `:10881`.
 
 ## Invariants
 
 - Quantity per listing is one.
 - User enters length, thickness, and SKU.
-- App proposes remaining listing fields. User reviews before create.
+- App may propose remaining listing fields. User reviews before create.
 - Non-math fields remain editable until create.
 - `bdft = sqft × thickness_in`
 - Price proposal is `bdft × species $/bdft`. User may replace it. Missing rate leaves price empty.
 - User-entered length, thickness, SKU, price, and taxonomy override computed or inferred values.
+- **Woo attributes** = synced species + wood categories; Edge / Figure / Grade / Thickness / Moisture; `fig-*` / `feat-*`. Store is source of truth.
+- Woo auth is WordPress application password (server-side). `WOO_BASE_URL` is compose/env; inference URL is Settings.
 - SKUs matching `SLAB-UAT-*` create as Woo draft.
 - Create works with inference off.
 - Source below the PNG size floor requires a new photo.

docs/CREATE.md

@@ -0,0 +1,112 @@
+# Milestone 3 — Create
+
+Builds on Milestones 1–2 (`docs/CAPTURE.md`, `docs/PHOTOS.md`).
+Destination and field names also live in `docs/PRODUCT.md`.
+
+**Scope source of truth:** this file and the Ty conversations that wrote it.
+Task and milestone breakdowns on `main` (including older PRODUCT / IMPL-PLAN / CONTENT-WOO splits) are **obsolete for M3**. Do not cross-reference `main` for what M3 includes once this branch is the working set.
+
+## Goal
+
+Phone path from Photos-ready device draft → store-synced **Woo attributes** filled and reviewed → WooCommerce product create (practice SKUs as draft) → clear device draft.
+
+M3 also wires the **OpenAI-compatible inference endpoint** as a server dependency so inference ops can run when enabled. Create must still work with inference off.
+
+## Woo attributes
+
+Locked name for the synced taxonomy package. WooCommerce is the source of truth; the app caches ids and never invents the lists.
+
+### Categories (product categories, leaf-only)
+
+| Field | Cardinality | Notes |
+|---|---|---|
+| Species | exactly 1 required | Synced species leaves only; no hardcoded / fallback set |
+| Wood category | 1+ required | Parents are grouping only; picks are leaves |
+
+### Attributes (exactly five locked Woo attributes)
+
+| Attribute | Cardinality | Notes |
+|---|---|---|
+| Edge Type | 1 required | Term id from sync |
+| Figure | 1+ required | Term ids from sync |
+| Grade | 1+ required | Term ids from sync |
+| Thickness | 1 required | Measured thickness rounded **up** into the store band |
+| Moisture | 1 required | Default kiln-dried; user sets/keeps; **never inferred** |
+
+v1: missing attributes are skipped, not created. Species, character, length, and free-text thickness are **not** product attributes.
+
+### Tags
+
+| Tag prefix | Cardinality | Notes |
+|---|---|---|
+| `fig-*` | 1+ required | Other Woo tags ignored |
+| `feat-*` | 0+ optional | Character / inclusions / voids / checks map onto existing feat tags only |
+
+### Listing facts beside taxonomy
+
+- User: SKU, length, thickness (and app-computed widths / sqft / bdft from M1/M2)
+- Price: propose `bdft × species $/bdft` from pricing rules; user may override; missing rate → empty price
+- Copy: title / short title / description from templates (optional Generate text when inference is on; not required for ready)
+
+## Sync (Woo)
+
+- FastAPI is the sole Woo client. Credentials never in the browser.
+- Auth: WordPress **application password** for a dedicated low-privilege WP user (not Woo `ck_`/`cs_` consumer keys).
+- Store URL: `WOO_BASE_URL` from `deploy/.env` / compose (`https://` only). Settings shows it read-only. Not a SQLite settings row.
+- Woo username + application password: Settings UI → AES-GCM in SQLite (`SLAB_AES_KEY` env).
+- Taxonomy sync pulls, in order: categories → tags (`fig-*` / `feat-*` only) → attributes + terms (five locked).
+- Sync failure keeps the previous cache (never delete-then-fail). Stale picks show “no longer valid”; never silently swap.
+
+## Inference dependency
+
+- OpenAI-compatible endpoint: `inference_base_url`, API key, model in **Settings** (encrypted), not compose env.
+- Server proxies all inference calls.
+- Feature-flagged. **Create / ready path must pass with inference off** (manual taxonomy + deterministic numbers + Woo draft).
+- Vision may prefill taxonomy at ≥0.7 confidence when on; typed values always win; below threshold → leave empty.
+
+## Ready set (submission ready)
+
+Review does not continue until the full ready set is filled. Species + one figure is not enough.
+
+Required:
+
+- ≥1 inventory PNG (from M2)
+- SKU, length, thickness; widths / sqft / bdft present
+- Species, ≥1 wood category, edge type, ≥1 figure, ≥1 grade, thickness band, moisture, ≥1 `fig-*`, price
+- `feat-*` optional (0+)
+
+## Create
+
+- `POST` product to Woo with categories, attributes, tags, price, copy, inventory PNG images.
+- Duplicate SKU (any store status) blocks create; no update path in this version.
+- `SLAB-UAT-*` always creates as Woo **draft**, even if Settings say publish.
+- Device draft ≠ Woo draft. After successful create, clear the device draft.
+- Default create status from Settings `woo_create_status` (`draft` \| `publish`, default `draft`), subject to the UAT force-draft rule.
+
+## Acceptance (done when)
+
+Product state induced: overnight UAT app on ubudual5060 `http://100.64.0.9:10881` (or the current M3 deploy of this branch), with Woo credentials and `WOO_BASE_URL` pointed at the intended store.
+
+Evidence from that state:
+
+1. Taxonomy sync via application password retrieves Woo attributes into the app cache; pickers offer only synced ids.
+2. A Photos-ready slab can be filled to the full ready set using those synced lists (inference off is a required path).
+3. Create with `SLAB-UAT-*` yields a WooCommerce **draft** product whose categories / attributes / tags / price / images match the reviewed ready set.
+4. Duplicate SKU is blocked; device draft clears after success.
+5. Inference Settings accept an OpenAI-compatible base URL / key / model; create still succeeds with inference disabled.
+
+## Dishonest proxies (do not count as pass)
+
+- Hardcoded or fixture taxonomy lists treated as “synced”
+- Mock Woo client or in-process fake that never hit the real store
+- Claiming ready / create green from unit tests alone without a real draft in the store
+- Consumer-key auth instead of application password
+- Inference “wired” only as dead config with no server proxy path, or create that requires inference on
+- Touching `:10880` (Ty Node/SvelteKit) or dumping work onto `m2-ds` / doc-simplification branches
+
+## Out of scope (unless Ty expands M3 in chat)
+
+- Full Assist UX beyond the OpenAI endpoint dependency and optional prefill rules above
+- Creating new Woo attributes / terms / tags from the app
+- Update-in-place of an existing store SKU
+- Bulk create

docs/PRODUCT.md

@@ -39,39 +39,32 @@ Milestone 3 uses FastAPI as the Woo client. Store credentials stay on the server
 
 ## Create
 
+Spec: `docs/CREATE.md` (Milestone 3 SoT on this branch).
+
 `SLAB-UAT-*` creates as a WooCommerce draft (store status).
 Duplicate SKU blocks create.
 A listing can be created with inference off.
 A device draft in the app is separate from a WooCommerce draft.
+Woo attributes (synced taxonomy) and the OpenAI-compatible inference Settings dependency are defined in `docs/CREATE.md`.
 
 ## Milestones
 
-Work is split into four milestones. Each milestone is done when its acceptance can be demonstrated.
+M1 and M2 are shipped inputs. **M3 scope is defined in `docs/CREATE.md` and Ty conversations — not by older splits on `main`.**
 
 ### Milestone 1 — Capture
 
-Spec: `docs/CAPTURE.md`. Done historically; handoff into Milestone 2.
+Spec: `docs/CAPTURE.md`. Shipped; handoff into Milestone 2.
-
-User stories:
-- Photograph a slab on a green or black sheet and remove the background.
-- Set length from the bounding rectangle and get widths, sqft, and bdft.
-- Leave and later Continue or Start fresh.
-
-Acceptance: inventory PNG and measurements visible on a phone. No Woo create.
 
 ### Milestone 2 — Photos
 
-Spec: `docs/PHOTOS.md`. Current work.
+Spec: `docs/PHOTOS.md`. Shipped on UAT `:10881`. No Woo create. No Complete-listing taxonomy in this milestone.
-
-Batch photos of one slab, pick calibration, run Milestone 1 on that reference, apply the same mask params and crop to the rest, preview all inventory PNGs lined up, plus a dimension-overlay copy of the calibration PNG.
-Acceptance: on a phone, 1–N store-ready inventory PNGs for the slab (including dimension overlay on the calibration copy) with Milestone 1 measures visible. No Woo create. No Complete-listing taxonomy in this milestone.
 
 ### Milestone 3 — Create
 
-WooCommerce draft for a practice SKU. Then clear the device draft.
+Spec: `docs/CREATE.md`. Current work on branch `m3-ds`.
-Acceptance: `SLAB-UAT-*` exists in the store as draft.
+Woo attributes sync via application password, ready-set use of that taxonomy, product create, inference endpoint dependency.
+Acceptance: see Done when in `docs/CREATE.md`.
 
-### Milestone 4 — Assist
+### Later work
 
-Optional vision and generated copy on the manual path from Milestones 1–3.
+Anything beyond `docs/CREATE.md` (including fuller Assist UX) is out of M3 unless Ty expands scope in chat.
-Acceptance: create still works with inference off.

docs/archive/README.md

@@ -15,3 +15,7 @@ Live spec on this branch:
 - `docs/PRODUCT.md`
 - `docs/CAPTURE.md`
 - `deploy/` for hosting only
+
+## M3 note (2026-09-16)
+
+For Milestone 3 on branch `m3-ds`, do **not** treat docs frozen on `main` as scope SoT. Use `docs/CREATE.md` on `m3-ds` (conversation-locked). Archive / `main` files remain historical reference only.