diff --git a/AGENTS.md b/AGENTS.md index 215c12c..c828bc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -13,7 +13,7 @@ When docs disagree, use this order: 1. **`docs/TECH-SPEC-PIPELINE.md`** — deterministic math, image prep, constants, test vectors 2. **`docs/ARCHITECTURE.md`** — hybrid topology, what-runs-where, secrets why, status machine 3. This **`AGENTS.md`** — hard rules for agents (verbatim locks below) -4. **`docs/DATA-MODEL.md`**, **`docs/OPENAPI.md`**, **`docs/CONTENT-WOO.md`**, **`docs/PROMPTS.md`**, **`docs/DEPLOYMENT.md`** +4. **`docs/DATA-MODEL.md`**, **`docs/OPENAPI.md`**, **`docs/CONTENT-WOO.md`**, **`docs/PROMPTS.md`**, **`docs/DEPLOYMENT.md`**, **`docs/UX.md`** (presentation; functional gates stay in this file) 5. **`docs/IMPL-PLAN.md`** — hybrid-aligned Phases 0–6. Phase 2 is a deferred stub only (offline PWA / OCR / ruler). Do not implement deferred stubs or any server happy-path measure/crop as SoT. 6. **`README.md`** — orientation only 7. **`docs/archive/PRD-2026-08.txt`** — frozen archive only. Not a source for new work. @@ -32,7 +32,7 @@ Archived PRD lines that conflict with the files above are non-authoritative (see ### Open doc defects -None known after the 2026-09-01 docs refactor on `docs/refactor-v2`. If a greppable DoD item fails, list it here before deleting reconciliation notes. +POC issue wave (docs on this branch): Application Passwords (#5), Call 1 confidence gate (#9), `WOO_BASE_URL` compose-only (#11), Call 1 prefill (#8), synced-species-only (#12), inline mask knobs (#15), taxonomy cache anchor (#14), Call1→Call2 portable context (#2), shared validation (#17), 409/422 recovery (#18), UX spec (#10 → `docs/UX.md`). --- @@ -64,7 +64,7 @@ Docs refactor stack on `docs/refactor-v2` (2026-09-01) applies OPENAPI store-onl **Client (SvelteKit) owns the happy path:** - Capture 1–5 photos -- Sheet detect + chroma-key / black threshold + sliders (sensitivity, edge offset, feather) +- Sheet detect + chroma-key / black threshold + **four knobs inline on capture** (sheet, sensitivity, edge offset, feather) with **live re-run** and mask overlay on the source photo - Mask overlay + **user confirm** before measurement - Length axis overlay (rotate / confirm) - sqft, bdft, 6" width samples @@ -74,7 +74,7 @@ Docs refactor stack on `docs/refactor-v2` (2026-09-01) applies OPENAPI store-onl **Server (FastAPI) owns:** - Store drafts / settings / taxonomy cache -- **U2Net on demand only** (“Try harder” / coverage failure) — one photo in, mask out; sliders still apply on client +- **U2Net “Try harder”** — **deferred from POC**, not deleted. Architecture keeps the one-photo server path for awkward backgrounds post-POC. POC mask tuning is **client-side only** (sheet + four knobs, live re-run). Do not implement U2Net in Gate C / first listing. - WooCommerce (taxonomy sync, SKU check, create product) — browser never calls Woo - Inference **proxy** (Call 1 / Call 2) — keys never in browser - Prompt files (server text files, read fresh) @@ -94,6 +94,7 @@ Depth: `docs/ARCHITECTURE.md`. | Ruler detection / OpenCV on client for scale | Manual length; scale = longest_axis_px / L | | Server-side happy-path pipeline | No server chroma-key / crop / bdft math as SoT | | Fake upscale / inventing pixels | Warn + retake if < 1600 after crop | +| U2Net “Try harder” server mask | Deferred from POC (keep in architecture; do not delete) | | LoRA / fine-tune | Deferred | | Figure-/category-weighted pricing | v1.5 | | Auto-dimension overlay | v1.5 | @@ -122,14 +123,12 @@ Depth: `docs/TECH-SPEC-PIPELINE.md`. **Never in browser storage / JS bundles:** - Woo WordPress username + application password (not consumer keys) -- Inference base URL + API key +- Inference API key (treat inference URL as sensitive) - AES master key (`SLAB_AES_KEY` env only; never in DB or repo) -**Server:** AES-GCM at rest in SQLite for Woo + inference secrets. Settings UI -POSTs to FastAPI; server encrypts. All Woo and inference calls are server-side. -Woo auth is a dedicated low-privilege WP user's application password over HTTPS -Basic Auth to `/wp-json/wc/v3/`. Do not implement WooCommerce consumer keys -(`ck_`/`cs_`) or the Woo → Settings → Advanced → REST API key UI. +**`WOO_BASE_URL`:** compose / host `.env` only (`https://` required). Settings shows it **read-only**. Not a SQLite settings row. Not user-editable. FastAPI rejects `http://` at startup. Do not reintroduce an editable store URL. + +**Server:** AES-GCM at rest in SQLite for Woo Application Password + inference secrets. Settings UI POSTs username + application password to FastAPI; server encrypts. All Woo and inference calls are server-side. Dedicated low-privilege WP user (product create/edit + media). Rotate by revoking the application password in WP Users → Profile and re-entering in Settings. Do not implement WooCommerce consumer keys (`ck_`/`cs_`) or the Woo → Settings → Advanced → REST API key UI. **Browser may persist (non-secret):** sheet mode, sensitivity, edge offset, feather (localStorage OK; reset-to-default required). @@ -139,12 +138,12 @@ Why/flow: `docs/ARCHITECTURE.md` §5. Ciphertext key inventory: `docs/DATA-MODEL ## 5. Woo UAT and create status (Ty locked 2026-08-31) -- Store: **PROD** `www.whidbeywoodstore.com` +- Store URL: **`WOO_BASE_URL`** from Docker Compose (`https://` only). Intended UAT/POC store is Whidbey Wood Store production; the compose value is the SoT, not a Settings field. - Mid-phase UAT creates: Woo status **draft**, SKU prefix **`SLAB-UAT-*`** - Settings field **`woo_create_status`**: **`draft | publish`**, default **`draft`** - Hard rule: if SKU matches `SLAB-UAT-*`, force **Woo draft** even if Settings say publish - Final POC success: one real (non-UAT) SKU → **Woo publish** only after Ty review -- Duplicate SKU → stop, surface error; no edit-same-SKU in MVP +- Duplicate SKU → stop; UI maps **409** to the SKU field (edit SKU or open existing). No edit-in-place of the other listing in MVP - After successful publish: purge originals + processed images on server - Do **not** conflate with slab lifecycle status (below) @@ -158,7 +157,9 @@ Payload and publish sequence depth: `docs/CONTENT-WOO.md` (cites this section fo - **Gate C** claimable path: inference **OFF**; manual taxonomy + deterministic numbers + Woo draft path. - **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). Confidence threshold 0.7 (configurable) lives in IMPL Phase 5 / PROMPTS. +- 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: exactly one species, ≥1 wood category, ≥1 figure. Presentation (inline nudges): `docs/UX.md`. Inference never auto-publishes. +- Call 2 must run on a provider that supports **portable Call 1→Call 2 context** (full history resend default; stateful `previous_response_id` only if probe says so). `test-inference` fails closed if neither path works. - LoRA deferred. No numeric/dimension invention by LLM; templates inject deterministic numbers. Prompt file mechanics: `docs/PROMPTS.md`. @@ -170,8 +171,8 @@ 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:** mandatory fields filled (manual and/or Call 1); inference optional. -- Inference does not gate publish. +- **ready:** mandatory fields filled (exactly one species, ≥1 wood category, ≥1 figure, plus remaining required listing fields). Values from Call 1 only when confidence ≥ 0.7, else manual. Inference optional. +- 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`). --- @@ -192,5 +193,6 @@ Prompt file mechanics: `docs/PROMPTS.md`. - Target: inventoried Docker host. Docker Compose (`frontend` + `fastapi`) + Caddy → `https://${APP_HOSTNAME}` (LAN/Tailscale). - Fill `deploy/INVENTORY.md` before binding ports or merging Caddy (co-resident apps can collide; bolt.diy is one example). - Health: `GET https://${APP_HOSTNAME}/api/health`. +- `WOO_BASE_URL` in compose (HTTPS). Settings displays it read-only. - Inference is a remote configurable endpoint, not on the app host by default. - Historical lab IP/hostname examples in older notes are non-normative. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e3c8bd7..240c60d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -123,6 +123,7 @@ flowchart TB 2. Inference endpoint base URL + API key. Stored encrypted. Server proxies all inference calls. 3. AES master key. Env var on server (`SLAB_AES_KEY`), never in the DB. +4. `WOO_BASE_URL` env (compose). HTTPS only. Not user-editable; Settings displays it read-only. **Browser-side (no secrets):** 1. User preferences: sheet mode, sensitivity, edge offset, feather. Persisted in localStorage, reset-to-default available. @@ -130,10 +131,11 @@ flowchart TB 3. Taxonomy snapshot (categories, attributes, tags). Read from server. No auth needed. **Flow:** -1. Operator creates a low-privilege WP user on the store (HTTPS required for - Application Passwords UI). Generates an application password under - Users → Profile. -2. User enters that username + application password in Settings UI on the phone. +1. Deploy sets `WOO_BASE_URL` (`https://`) in compose. Operator creates a + low-privilege WP user on that store (HTTPS required for Application + Passwords UI). Generates an application password under Users → Profile. +2. User enters that username + application password in Settings UI + (store URL shown read-only from env). 3. Browser POSTs them to `/api/v1/settings` on FastAPI. Server encrypts with AES-GCM and stores ciphertext only. 4. Server syncs taxonomy from Woo, caches in SQLite. @@ -153,9 +155,17 @@ 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). Values can come from Call 1, manual entry, or a mix. Inference is optional; the user can fill everything by hand and go straight to ready. +3. **ready** — all mandatory fields populated (species, wood category, edge type, + figure, grade, thickness, price, title/desc/short desc, at least one photo). + Values can come from Call 1 (≥ threshold pre-fill the user kept), manual + entry, or a mix. **Review gate:** if Call 1 returned below-threshold for a + field, that field stays empty until the user fills it. At minimum **species** + and **≥1 figure attribute** must be set before ready. 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. -Call 1 and Call 2 are assist-only. They do not gate the flow. If the user skips inference, the path is: calibrated → ready → publishing → published. +Call 1 and Call 2 are assist-only. They do not gate publish. Low-confidence Call 1 +results do not auto-fill. If the user skips inference, the path is: calibrated → +ready → publishing → published. diff --git a/docs/CONTENT-WOO.md b/docs/CONTENT-WOO.md index d89bf6a..ec0b455 100644 --- a/docs/CONTENT-WOO.md +++ b/docs/CONTENT-WOO.md @@ -60,7 +60,7 @@ and the final stored content. ## 2. WooCommerce integration (FR24–28) ### 2.1 Auth & client -- REST v3 surface unchanged: `GET/POST/PATCH/DELETE {woo_base_url}/wp-json/wc/v3/…` +- REST v3 surface unchanged: `GET/POST/PATCH/DELETE {WOO_BASE_URL}/wp-json/wc/v3/…` - Auth is **WordPress Application Passwords**, not WooCommerce consumer keys (`ck_`/`cs_`) and not the user's login password. - Create a **dedicated low-privilege WordPress user** (shop manager, or a custom @@ -76,7 +76,8 @@ and the final stored content. - Rotation: revoke the application password in the WP user profile, enter a new one in Settings UI, then `POST /api/v1/settings/test-woo`. - Client: `httpx` with timeouts (connect 10s, read 60s for image-heavy create). -- `woo_base_url` default: `https://www.whidbeywoodstore.com`. +- Store URL is **`WOO_BASE_URL`** from Docker Compose / host `.env` (HTTPS only). + FastAPI refuses `http://` at startup. Not a Settings field; UI shows it read-only. ### 2.2 Taxonomy sync (FR25) `POST /api/admin/taxonomy/sync` pulls, in order: @@ -86,19 +87,33 @@ and the final stored content. 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) -- **Categories**: species leaf category (1 required) plus wood-category leaf ids (1+). - Match by name against the synced Woo category cache (case-insensitive, trimmed). - No match → user override in review, or empty (Woo required-field validation surfaces it). -- **Tags**: `fig-*` only for figure tags (1+ required) and `feat-*` only for feature tags - (0+). Call 1 free-text observations (character / inclusions / voids / checks) map to - existing Woo `feat-*` tags. Do not invent generic character or species product tags. - WooCommerce is authoritative for tag definitions. +### 2.3 Taxonomy assignment (FR26) + +**Primary source when inference is on and confidence ≥ threshold (default 0.7):** +Call 1 vision results pre-fill the review screen for species, wood categories, +edge type, figure, grade, and mapped `fig-*` / `feat-*` tags (character / +inclusions / voids / checks → existing `feat-*`). All pre-filled values are +mutable. The user confirms or overrides; manual entry always wins. + +**Below threshold:** those fields stay empty. The review screen gates continue +until the user manually selects at least **species** and **one figure attribute** +(and the rest of the ready mandatory set). Do not auto-fill below-threshold +guesses. Full rules: AGENTS §6. + +**Deterministic name-matching** resolves Call 1 names (or manual picks) to synced +Woo IDs case-insensitive, trimmed. No match → empty; user picks in review. Woo +required-field validation still surfaces gaps at publish. + +Field rules: +- **Categories**: species leaf (1 required) plus wood-category leaf ids (1+). +- **Tags**: `fig-*` (1+ required) and `feat-*` (0+). Do not invent generic + character or species product tags. Woo is authoritative for tag definitions. - **Attributes**: the five locked Woo attributes only — Edge Type, Figure, Grade, - Thickness, Moisture — using term ids from the cache. Do not publish species, character, - length, or free-text thickness as product attributes. Missing attributes are skipped, - not created (v1: no attribute creation). -- Every assignment is overridable in the review screen (FR26). + Thickness, Moisture — using term ids from the cache. Do not publish species, + character, length, or free-text thickness as product attributes. Missing + attributes are skipped, not created (v1: no attribute creation). + +Call 1 is assist-only and never gates publish. Inference OFF → full manual path. ### 2.4 Product create payload (FR27) `POST /products` — body (only non-null fields sent): diff --git a/docs/IMPL-PLAN.md b/docs/IMPL-PLAN.md index 2fb143e..d551a0b 100644 --- a/docs/IMPL-PLAN.md +++ b/docs/IMPL-PLAN.md @@ -161,8 +161,10 @@ Deliverables: - Show client-processed transparent PNGs (and originals while retained). No server re-crop UI as SoT. - Inference UI (only meaningful after Gate C and when `inference_enabled`): Call 1 - results with confidence; manual confirm required below threshold **0.7** - (configurable). "Generate text" triggers Call 2; never auto. + results with confidence. **≥ 0.7** (configurable default) → pre-fill mutable + fields. **< 0.7** → leave empty; block continue until species + ≥1 figure + (and other mandatories) are set by hand. "Generate text" triggers Call 2; + never auto. - Publish button (online-only), poll `publishing` → `published` | `failed`, surface error detail from sync_log. - Settings UI: WP username + application password + test-woo, inference endpoint + @@ -226,8 +228,11 @@ Deliverables: - Call 1 (vision) proxy: **all inventory photos** downscaled to 1024 + Woo taxonomy snapshot + user metadata; OpenAI-compatible endpoint; model constrained to cached - taxonomy; confidence threshold **0.7** (configurable; relocate from older PRD FR22a). - Auto-run on calibrated create only if `inference_enabled`. Not top-down-only. + taxonomy; confidence threshold **0.7** (configurable default; not a POC Settings + slider). Auto-run on calibrated create only if `inference_enabled`. Not top-down-only. +- Apply AGENTS §6 gate: ≥ threshold → pre-fill mutable species/categories/attributes/ + tags; < threshold → empty fields + review gate requiring species + ≥1 figure + before ready. - Call 2 (text) proxy: never auto. User taps Generate text. LLM prose only; templates inject deterministic numbers. See `docs/PROMPTS.md`. - `test-inference` endpoint (vision capability check) before Call 2 is allowed. @@ -236,8 +241,12 @@ Deliverables: Acceptance: -- Local vision model configured: taxonomy suggestions appear with confidence; below - 0.7 → manual confirm required. +- Local vision model configured: ≥ 0.7 fields pre-fill and remain editable; user + override sticks. +- Below 0.7: fields stay empty; UI blocks continue/ready until species and ≥1 + figure attribute are set manually (asserted in integration or UI test). +- No doc/code path auto-fills below-threshold guesses or treats inference as a + publish gate. - Inference OFF: app works end-to-end; tests assert zero calls to the inference endpoint. - Audit payloads present after a call; prompt file edits apply without server restart. - Gate C path remains green with inference OFF. diff --git a/docs/PROMPTS.md b/docs/PROMPTS.md index 9286f2b..d6ebce3 100644 --- a/docs/PROMPTS.md +++ b/docs/PROMPTS.md @@ -95,10 +95,17 @@ Return valid JSON matching this schema: duplicate them. - **Pre-population (when `inference_enabled`):** Call 1 results are the primary source that fills the review screen for species, character, wood categories, - figure/edge/grade attributes, and mapped `fig-*`/`feat-*` tags. The user - confirms or overrides. Manual entry always wins. Call 1 does not gate publish. -- Confidence threshold behavior (≥0.7 pre-fill vs <0.7 empty + gate) is locked - in AGENTS §6. + figure/edge/grade attributes, and mapped `fig-*`/`feat-*` tags. +- **Confidence gate (default threshold 0.7):** + - Field confidence **≥ threshold** → pre-populate that field (mutable; + user may clear or change it). + - Field confidence **< threshold** → leave empty. Do not show the model's + low-confidence guess as a default. + - Before the slab can leave review toward ready/publishable, the user must + have **species** and **≥1 figure attribute** set (manually if Call 1 left + them empty), plus the rest of the mandatory ready set. +- Manual entry always wins. Call 1 is assist-only and does not gate publish. + Full suite must pass with inference OFF. Canonical lock: AGENTS §6. ---