From 0c5ee36a7aa30885ceb90a56cf4ce58137e65882 Mon Sep 17 00:00:00 2001 From: grokbot_ty Date: Wed, 2 Sep 2026 02:40:28 +0000 Subject: [PATCH] docs: split list-ready into capture, submit, and confidence-gate Name every DATA-MODEL submit field in mill-owner English. Issue #9 empty-below-0.7 stays a subset; species plus one figure is not enough to list. --- AGENTS.md | 4 +-- docs/ARCHITECTURE.md | 14 ++++++---- docs/CONTENT-WOO.md | 9 ++++-- docs/DATA-MODEL.md | 2 +- docs/OPENAPI.md | 2 +- docs/UX.md | 66 ++++++++++++++++++++++++++++++++++++++++---- 6 files changed, 78 insertions(+), 19 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a8d37e5..c62ba08 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -158,7 +158,7 @@ Payload and publish sequence depth: `docs/CONTENT-WOO.md` (cites this section fo - **Call 1 (vision) / Call 2 (text) only after Gate C is green, still inside overall POC** before “done” — not post-POC. - Call 1 auto only if `inference_enabled`; Call 2 never auto-fires (user taps Generate text). - Call 1 body: all inventory photos @1024 (not top-down-only). Taxonomy lists sent to Call 1 are **exactly the Woo-synced species / attribute / tag sets**. No hardcoded or invented species. -- **Confidence 0.7 (default):** ≥ 0.7 → pre-populate species, wood categories, edge, figure, grade, and feat-* from Call 1 (**mutable**). < 0.7 → those fields stay **empty**; user is gated before ready. Mandatory floor: species + ≥1 figure (product also requires ≥1 wood category). Presentation: `docs/UX.md`. Inference never auto-publishes. +- **Confidence 0.7 (default):** ≥ 0.7 → pre-populate species, wood categories, edge, figure, grade, and feat-* from Call 1 (**mutable**). < 0.7 → those fields stay **empty**. That empty-start subset is not the submit list. Ready still requires the full named set in §7 (species + one figure is not enough). Presentation: `docs/UX.md`. Inference never auto-publishes. - **Taxonomy cache:** `taxonomy_last_sync_at` vs `taxonomy_anchor` (bump only on stored-subset hash change, including deletions). Client re-pulls iff the anchor advanced. `test-woo` always syncs; publish if last_sync >1h. No per-nav sync. No Woo taxonomy timestamp. - Call 2 portable context: default full resend; never require `previous_response_id`. `test-inference` two-turn probe `stateful|stateless|fail`. Fail blocks **Call 2 enablement only**. - LoRA deferred. No numeric/dimension invention by LLM; templates inject deterministic numbers. @@ -172,7 +172,7 @@ Prompt file mechanics: `docs/PROMPTS.md`. `draft → calibrated → ready → publishing → published` (or `failed` with detail). - **calibrated:** mask + axis confirmed; length/thickness/SKU entered; client computed sqft/bdft/widths; draft uploaded. -- **ready:** SKU, length, thickness, client sqft/bdft/widths, at least one inventory PNG, exactly one species, ≥1 wood category, edge type, ≥1 figure and matching fig tags, grade, thickness store band, moisture (default kiln-dried), price, title, short title, description. Feature tags optional. Vision may prefill taxonomy only when confidence ≥ 0.7. +- **ready:** SKU, length, thickness, client sqft/bdft/widths, ≥1 inventory PNG, exactly one species, ≥1 wood category, 1 edge type, ≥1 figure term, ≥1 fig-* tag, ≥1 grade, thickness store band (round-up), 1 moisture (default kiln-dried; not inferred), price. feat-* 0+. Title/description may be typed, generated, or templated at publish. Vision may prefill the taxonomy subset only when confidence ≥ 0.7. - Inference does not gate publish. Below-threshold Call 1 does not prefill; empty mandatory fields block ready (see UX spec). - Never confuse slab `draft` with **Woo draft** (`woo_create_status`). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index be73001..2aafbc1 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -156,13 +156,15 @@ any → failed (with error) 1. **draft** — user took photos, no mask confirmed yet. 2. **calibrated** — user confirmed the BG edge, confirmed length axis, entered length/thickness/SKU. Client computed sqft/bdft/widths. Draft uploaded to server. -3. **ready** — all mandatory fields populated (species, wood category, edge type, - figure, grade, thickness, price, title/desc/short desc, at least one photo). +3. **ready** — SKU, length, thickness, client sqft/bdft/widths, ≥1 inventory PNG, + exactly one species, ≥1 wood category, 1 edge type, ≥1 figure term, ≥1 fig-* tag, + ≥1 grade, thickness store band (round-up), 1 moisture (default kiln-dried), price. + feat-* 0+. Title/description may be typed, generated, or templated at publish. Values can come from Call 1 (≥ 0.7 pre-fill the user kept), manual entry, or a mix. - **Review gate:** below-threshold Call 1 leaves that field empty. Mandatory before - ready: **exactly one species, ≥1 wood category, ≥1 figure**. Inline nudges, not - submit-only (`docs/UX.md`). Inference is optional; with inference OFF the user - fills everything by hand. + **Review gate:** below-threshold Call 1 leaves species, wood category, figure, + edge, grade, and feat-* empty. That subset is not the submit list. Inline nudges + on every still-required control, not submit-only (`docs/UX.md`). Inference is + optional; with inference OFF the user fills everything by hand. 4. **publishing** — Woo create in flight. Poll for result. 5. **published** — Woo product created, woo_product_id stored. Images purged. 6. **failed** — pipeline, inference, or publish error. Error detail stored. Retry available. diff --git a/docs/CONTENT-WOO.md b/docs/CONTENT-WOO.md index bbfe9fc..412960b 100644 --- a/docs/CONTENT-WOO.md +++ b/docs/CONTENT-WOO.md @@ -99,9 +99,12 @@ edge, figure, grade, and feature tags (character, inclusions, voids, checks map to existing `feat-*` tags only). The mill owner can change every filled value. Typed values always win. -If it is less sure, those fields stay empty. Review will not continue until they -pick exactly one species, at least one wood category, and at least one figure. -How that looks on the phone: `docs/UX.md`. Do not fill a low-confidence guess. +If it is less sure, those fields stay empty. That empty-start subset is not +the submit list. Review will not continue until the full ready set is filled: +SKU, length, thickness, price, species, wood category, edge type, figure, +grade, thickness band, moisture, fig-* tags, and inventory PNG(s). Species +plus one figure is not enough. How that looks on the phone: `docs/UX.md`. +Do not fill a low-confidence guess. Names from vision or from typing match store ids case-insensitive, trimmed. No match leaves the field empty so they can pick from the list. The store will still diff --git a/docs/DATA-MODEL.md b/docs/DATA-MODEL.md index 9837cec..f81e1cb 100644 --- a/docs/DATA-MODEL.md +++ b/docs/DATA-MODEL.md @@ -65,7 +65,7 @@ any → failed (with error) 1. **draft** — photos taken, no mask confirmed. 2. **calibrated** — BG edge confirmed, length axis confirmed, length/thickness/SKU entered. Client computed sqft/bdft/widths. Draft uploaded to server. -3. **ready** — SKU, length, thickness, client sqft/bdft/widths, ≥1 inventory PNG, one species, ≥1 wood category, edge type, ≥1 figure and fig tags, grade, thickness store band, moisture (default kiln-dried), price, title, short title, description. Feature tags optional. Vision may prefill taxonomy only when confidence ≥ 0.7. +3. **ready** — SKU, length_in, thickness_in, client sqft/bdft/widths, ≥1 inventory PNG, exactly one species, ≥1 wood category, 1 edge type, ≥1 figure term, ≥1 fig-* tag, ≥1 grade, thickness_term_id (round-up from measured thickness), 1 moisture (default kiln-dried; user override; not inferred), price. feat-* 0+. Title/short_title/description may be typed, generated, or written by templates at publish. Call 1 may prefill only the vision subset when confidence ≥ 0.7. Inference optional. Publishable. 4. **publishing** — Woo create in flight. Poll for result. 5. **published** — Woo product created. This row + all photos deleted. sync_log retained. 6. **failed** — pipeline, inference, or publish error. Error detail stored. Retry available. diff --git a/docs/OPENAPI.md b/docs/OPENAPI.md index db8ff82..7be9037 100644 --- a/docs/OPENAPI.md +++ b/docs/OPENAPI.md @@ -188,7 +188,7 @@ Sheet/slider prefs are client localStorage only in POC (not in SettingsView). ### Publish - `POST /api/v1/slabs/{id}/publish` — Publish to WooCommerce. - - Pre-conditions: status `ready` with the DATA-MODEL ready set (SKU, measures, PNG, species, wood category, edge, figure+fig tags, grade, thickness band, moisture, price, title, short title, description). Else `422 unpublishable` with field keys. UI maps, no raw code. + - Pre-conditions: status `ready` with SKU, length_in, thickness_in, client sqft/bdft/widths, ≥1 inventory PNG, exactly one species, ≥1 wood category, 1 edge type, ≥1 figure term, ≥1 fig-* tag, ≥1 grade, thickness_term_id, 1 moisture, price. Else `422 unpublishable` with field keys. UI maps, no raw code. - Dedupe: if SKU already exists in Woo under any status → `409 duplicate_sku` (same payload as PUT). - Stale Woo value → `422 stale_field` as above. Draft stays on the phone. - Returns `202` `{ "status": "publishing" }`. Client polls. diff --git a/docs/UX.md b/docs/UX.md index 8be943d..69a3ccd 100644 --- a/docs/UX.md +++ b/docs/UX.md @@ -6,13 +6,51 @@ A suggestion from the vision model never beats a typed value. Empty is better th ## Before you can list -A listing is ready when the store row is complete, not when species and figure are filled. +A listing is ready when the store row is complete. Species plus one figure is not enough. -Capture already gave you photos (cut and length axis confirmed), the listing PNG, SKU, length, thickness, and the computed square feet, board feet, and widths. +### Capture (calibrated) -Review still needs the rest of the store fields: one species, at least one wood category, edge type, at least one figure (the figure attribute and the matching fig tag), grade, the store thickness band taken from the thickness you typed, moisture (kiln-dried unless you change it), a price, and a title, short title, and description. Feature tags are optional. +These are already done before review. You cannot list without them. -If vision is on and sure enough, it may fill some of those store fields. If it is not sure, species, wood category, edge, figure, grade, and feature tags stay empty for you to pick. That empty-vs-fill rule is only those fields. It is not the whole listing. SKU and measurements do not wait on the model. +- Cut around the wood confirmed by eye (the overlay sits on the photo; no checker banner) +- Length axis confirmed by eye +- Length in inches +- Thickness in inches +- SKU +- Square feet, board feet, and min / max / average width (computed from the cut and the length you typed; shown, not guessed) +- At least one listing PNG (the cropped inventory photo) + +### Review / submit + +These are required to mark the slab ready and send it to the store. Mill-owner names; the column names live in `docs/DATA-MODEL.md`. + +- SKU (already typed in capture; still required) +- Length and thickness in inches (already typed; still required) +- Price +- Species — exactly one, from the store list +- Wood category — at least one +- Edge type +- Figure — at least one from the store figure list (the figure attribute) +- Grade — at least one +- Thickness class — the store thickness band, rounded up from the thickness you typed +- Moisture — required. Starts as kiln-dried. You can change it. Vision does not pick this. +- Figure tags (`fig-*`) — at least one +- Feature tags (`feat-*`) — optional (zero or more) +- Listing photos — the inventory PNG(s) from capture + +The store product also needs a name (title), categories, tags, images, SKU, and price. Categories, tags, images, SKU, and price are the fields above. Title can be typed or written with Generate text. If it is still empty when you list, the templates write the name. Generate text never runs on its own. + +Continue stays off until every required field in this list is set. Feature tags may stay empty. + +### When vision is unsure + +The 0.7 bar is only about whether the model may fill a guess. It is not a shorter submit list. + +If vision is off, or on but under 0.7, these start empty: species, wood category, figure, edge, grade, and feature tags. You pick them. Empty is better than a confident-looking wrong species. + +Moisture still starts kiln-dried. Thickness class still comes from the thickness you typed. SKU, length, thickness, photos, and price do not wait on the model. + +You still cannot list until the full review / submit list is filled — not only species and figure. Any required field that is still empty is marked on that control. You should not have to tap continue to find out which one. @@ -88,7 +126,23 @@ Title and description start empty until you type or tap Generate text. Generate ### Nudges on the field -Every required field that is empty gets a line under that control when the screen opens. Species: "Pick the species from the store list." Wood category: "Pick at least one wood category." Figure: "Pick at least one figure." Edge, grade, moisture, price, title, short title, and description use the same pattern on their own controls if they are empty. The line goes away when that field is valid. Continue stays off while any required field is empty. +Every required control that is empty gets a line under it when the screen opens — not only species, wood category, and figure. The line goes away when that field is valid. Continue stays off while any required field is empty. + +- SKU: "Enter a SKU." +- Length: "Enter the length in inches." +- Thickness: "Enter the thickness in inches." +- Price: "Enter a price." +- Species: "Pick the species from the store list." +- Wood category: "Pick at least one wood category." +- Edge type: "Pick an edge type." +- Figure: "Pick at least one figure." +- Grade: "Pick at least one grade." +- Thickness class: "Confirm the store thickness band." (filled from the thickness you typed; mark it if it is missing) +- Moisture: "Pick moisture." (starts kiln-dried; only marks if you clear it) +- Figure tags: "Pick at least one figure tag." +- Photos: "Add a listing photo." (already true after a good capture) + +Feature tags have no missing mark. Title and description have no missing mark; templates write a name if you leave them blank. ### Overrides @@ -136,7 +190,7 @@ If the store is down, times out, or auth fails: one banner, "Couldn't reach the 4. Length axis: rotate and confirm by eye; retake if the shot is still wrong. 5. Optional size gate: after crop, if the short side is under the tech-spec minimum, that photo cannot list until retake. No invented pixels. 6. Vision on and sure: fields filled, still editable. -7. Vision unsure: species, wood category, edge, figure, grade, and feature tags empty. Continue stays off until the whole listing is filled, not only those fields. +7. Vision unsure: species, wood category, figure, edge, grade, and feature tags empty, with lines under every still-required control (including price, moisture if cleared, figure tags). Continue stays off until the full submit list is filled, not only species and figure. 8. Species list is only synced names. You cannot type a name that is not there. 9. Duplicate SKU: message under SKU, two actions, no status number. 10. Stale category: message under that field, current options.