docs(m2): lock Photos milestone — batch, calibrate, overlays

Record Ty's narrowed M2 scope on m2-ds: multi-photo batch, pick
calibration, reuse M1 mask/crop, lined-up inventory PNGs, and
axis-oriented dimension overlay copy. Not taxonomy or Woo create.

AGENTS.md

@@ -2,16 +2,21 @@
 
 ## Agent context
 
-Read this file and `docs/CAPTURE.md`.
+Read this file, `docs/CAPTURE.md`, and `docs/PHOTOS.md`.
-Implement Milestone 1 only. Specification: `docs/CAPTURE.md`.
+Implement Milestone 2 only. Specification: `docs/PHOTOS.md`.
-PRD: `docs/PRODUCT.md` for destination and field names. Do not implement Milestone 2, 3, or 4.
+PRD: `docs/PRODUCT.md` for destination and field names. Do not implement Milestone 3 or 4.
+Do not widen Milestone 2 into Complete-listing taxonomy, SKU, price, copy, or Woo create.
 
-## Milestone 1
+## Milestone 2
 
-Capture.
+Photos.
-Acceptance: on a phone, one real slab, approved mask, approved length-axis rectangle, user length and thickness, inventory PNG on screen, widths and board feet on screen.
+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.
 
-Milestone 1 is inference-free. Background removal, rectangle, measurements, and PNG encode run in the browser as ordinary code. There is no inference URL and no model call in this milestone.
+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 1 (historical)
+
+Capture. Spec: `docs/CAPTURE.md`. Remains the calibration math and PNG contract Milestone 2 reuses.
 
 ## Invariants
 
@@ -26,3 +31,4 @@ Milestone 1 is inference-free. Background removal, rectangle, measurements, and
 - Create works with inference off.
 - Source below the PNG size floor requires a new photo.
 - Existing store SKU blocks create.
+- Dimension overlay orientation follows the user-approved length axis from Milestone 1.

README.md

@@ -7,6 +7,7 @@ Lists one-of-a-kind wood slabs on Whidbey Wood Store.
 | PRD | `docs/PRODUCT.md` |
 | Invariants and agent context | `AGENTS.md` |
 | Milestone 1 | `docs/CAPTURE.md` |
+| Milestone 2 | `docs/PHOTOS.md` |
 | Hosting | `deploy/` |
 
 Owner: Ty. Store: https://www.whidbeywoodstore.com/

docs/PHOTOS.md

@@ -0,0 +1,67 @@
+# Milestone 2 — Photos
+
+Builds on Milestone 1. Spec for calibration math and inventory PNG properties: `docs/CAPTURE.md`.
+This milestone gets every photo of one slab background-removed and cropped store-ready.
+It does not fill Complete-listing taxonomy, SKU, price, or copy. It does not create a WooCommerce product.
+No inference URL. No model. Mask and crop for non-calibration shots reuse the approved calibration params as ordinary client code.
+
+## Goal
+
+Phone capture of one slab → a lined-up set of Woo-compatible inventory PNGs, plus Milestone 1 calibration numbers on the reference shot, plus one annotated copy of the calibration PNG with dimension overlays.
+
+## Use case
+
+1. User adds a batch of one or more photos of the same slab (Setup rules from Milestone 1: green or black sheet, top-down reference expectations still apply to the calibration choice).
+2. User selects which photo in the batch is the calibration photo.
+3. App runs the Milestone 1 workflow on that calibration photo only: Mask → Length axis → Measure (length `L`, thickness, Calculate).
+4. After Calculate, the app applies the approved mask sheet and sensitivity, and the same crop rules (3:4 portrait, 80% fill, transparent PNG, shorter-side floor), to every other photo in the batch.
+5. App adds a second copy of the calibration inventory PNG with dimension overlays burned in (see Dimension overlay).
+6. User sees: all formatted inventory PNGs lined up for preview, and the Milestone 1 calibration details (widths, sqft, bdft, scale, clean calibration PNG) presented as in Measure.
+
+A batch of one photo still works: that photo is the calibration photo; the end set is the clean PNG plus the dimension-overlay copy.
+
+## States (additions over Milestone 1)
+
+1. Batch — add one or more photos; continue when the batch has at least one.
+2. Pick calibration — user chooses which batch photo is the reference.
+3. Mask / Length axis / Measure — Milestone 1 states on the calibration photo only.
+4. Photos ready — lined-up inventory PNGs for every batch photo, plus the dimension-overlay copy of the calibration PNG, plus Milestone 1 numbers.
+
+Device draft restores the last approved state, including the batch and which photo was calibration when those exist.
+
+## Apply to non-calibration photos
+
+For each non-calibration photo:
+
+- Reuse the approved Mask sheet (Auto / Green / Black) and sensitivity from the calibration photo. Do not re-open Mask controls for that photo in this milestone.
+- Run background removal with those params; compose inventory PNG with the same crop rules as Milestone 1 Calculate.
+- If a photo yields an empty mask or fails the PNG size floor, keep it out of the ready set and show a clear per-photo error; other photos still proceed.
+
+Scale, widths, sqft, and bdft stay tied to the calibration photo and user `L` / thickness. Non-calibration photos are visual inventory only.
+
+## Dimension overlay
+
+A second copy of the **calibration** inventory PNG is added to the collection. Overlays are black, large enough to read on phone and storefront.
+
+Orientation follows the **user-approved length axis** from Milestone 1 (not the upright edges of the photo).
+
+- **Length:** dimension graphic beside the wood on the right in axis-space (outside the slab edge along the length direction).
+- **Widths:** stations every 12 in along the approved length axis, starting 6 in from one end of the slab span, continuing while the station is not within 6 in of the other end (stations at 6, 18, 30, … in inches along the axis while ≤ `L − 6`). Each width is drawn across the wood perpendicular to the length axis, with arrow tips on the left and right slab edges and the measurement text on that line.
+
+The clean calibration PNG remains in the set. The annotated copy is extra.
+
+## Acceptance
+
+On a phone UAT build:
+
+- User can capture 1–N photos, pick calibration, complete Milestone 1 on that shot, and see every successful batch photo as a 3:4 transparent inventory PNG lined up.
+- Calibration measures match Milestone 1 presentation.
+- Dimension-overlay copy of the calibration PNG is present with black length and width graphics oriented to the approved axis.
+- No Woo create. No inference URL.
+
+## Out of scope
+
+- Complete-listing fields (SKU, species, category, edge, figure, grade, thickness band, moisture, `fig-*` / `feat-*`, title, short title, description, price)
+- WooCommerce create (Milestone 3)
+- Inference / Assist (Milestone 4)
+- Changing Milestone 1 mask/axis/measure math except to reuse its outputs for batch apply and overlays

docs/PRODUCT.md

@@ -32,8 +32,9 @@ Store categories, attributes, and `fig-*` / `feat-*` tags are the filters. Measu
 
 ## System seams
 
-Milestone 1 runs in the browser. No backend and no inference URL.
+Milestones 1 and 2 run in the browser. No backend and no inference URL.
-Handoff is the device draft: source photo, approved mask, inventory PNG, length, thickness, widths, sqft, bdft.
+Milestone 1 handoff is the device draft: source photo, approved mask, inventory PNG, length, thickness, widths, sqft, bdft.
+Milestone 2 extends the draft with the photo batch, calibration choice, per-photo inventory PNGs, and the dimension-overlay calibration copy.
 Milestone 3 uses FastAPI as the Woo client. Store credentials stay on the server.
 
 ## Create
@@ -49,7 +50,7 @@ Work is split into four milestones. Each milestone is done when its acceptance c
 
 ### Milestone 1 — Capture
 
-Spec: `docs/CAPTURE.md`. Current work.
+Spec: `docs/CAPTURE.md`. Done historically; handoff into Milestone 2.
 
 User stories:
 - Photograph a slab on a green or black sheet and remove the background.
@@ -58,10 +59,12 @@ User stories:
 
 Acceptance: inventory PNG and measurements visible on a phone. No Woo create.
 
-### Milestone 2 — Review
+### Milestone 2 — Photos
 
-Remaining listing fields in the app.
+Spec: `docs/PHOTOS.md`. Current work.
-Acceptance: every field in Complete listing is filled or proposed and editable.
+
+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