SlabUploader/docs/capabilities/CREATE.md

Create capability

Status: SPEC · 2026-09-18 · Milestone M3. Behavior and acceptance for turning a Photos-ready slab into a submitted WooCommerce product. This doc cites requirement IDs; docs/REQUIREMENTS.md is the only normative text. Interface detail lives in docs/contracts/ (API.md, WOO-API.md, DATA-MODEL.md, PROMPTS.md, UX.md, CONTENT-WOO.md).

Requirements impact

Requirement	Impact on this capability
REVIEW-5, REVIEW-10, REVIEW-15, REVIEW-20	ready set, prose fields, primary category, inline nudges
REVIEW-25, REVIEW-30, REVIEW-35, REVIEW-40, REVIEW-45, REVIEW-50	price, read-only math, stale picks, editability, SKU and caps
METADATA-5, METADATA-10, METADATA-15, METADATA-20, METADATA-25, METADATA-30	synced taxonomy, cardinality, no term creation
METADATA-35, METADATA-40, METADATA-45, METADATA-50	Call 1 inputs, results, confidence gate, precedence
METADATA-55, METADATA-60, METADATA-65, METADATA-66	Call 2, context, dimension safety, logging
METADATA-70, METADATA-75, METADATA-80, METADATA-81, METADATA-85, METADATA-90, METADATA-95	deterministic copy, non-blocking, pattern selection, fact block
METADATA-100, METADATA-105, METADATA-110, METADATA-115	feat mapping, prompt storage, Generate text control, failure triage
PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20	create sequence, draft rule, duplicate, stale
PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-35, PUBLISH-36, PUBLISH-37, PUBLISH-38	success, failure, partial failure, triage
PUBLISH-40, PUBLISH-45, PUBLISH-50, PUBLISH-55, PUBLISH-60	images, lineup, meaning of published, payload, quantity
SETTINGS-5, SETTINGS-10, SETTINGS-15, SETTINGS-20, SETTINGS-25, SETTINGS-30, SETTINGS-35	store URL, auth, crypto, inference config, rates
SETTINGS-40, SETTINGS-45, SETTINGS-50, SETTINGS-51, SETTINGS-55, SETTINGS-60, SETTINGS-65	tests, taxonomy sync and anchor, create status
SETTINGS-70, SETTINGS-75, SETTINGS-80, SETTINGS-85, SETTINGS-90	vision cap, secret masking, test-woo, URL reject, flags
APP-15, APP-20, APP-30, APP-35, APP-40, APP-45, APP-50, APP-55, APP-60, APP-65	device draft, revisions, API base, envelope, health, logs, accessibility, redaction
QUALITY-20, QUALITY-35, QUALITY-50, QUALITY-90, QUALITY-95, QUALITY-105, QUALITY-110, QUALITY-120, QUALITY-125	M3 test bar and exit evidence
OPS-40	UAT host

1. Review to ready

Review is reached from a Photos-ready draft. The owner fills or confirms every field; each empty required field shows an inline nudge as they work, and the slab cannot reach ready until the full set is filled (REVIEW-5, REVIEW-20). Widths, sqft, and bdft are read-only client math (REVIEW-30); every other field stays editable until create (REVIEW-40).

The owner declares one primary wood category and any secondary ones; the first selected is primary (REVIEW-15). Price is the bdft times the species rate; with no rate it starts empty and the owner must enter one; an override sticks (REVIEW-25). SKU is 3–24 alphanumeric and hyphen (REVIEW-45). Title, short_description, and description are required and satisfy typed, generated, or templated text (REVIEW-10); title and short_description warn past 60 and 160 characters (REVIEW-50). A picked id that vanished shows as no longer valid and is never silently swapped (REVIEW-35).

2. Inference assist

Call 1 runs only when inference is enabled, after a calibrated draft uploads or on demand; it sends the clean processed photos at 1024 px long edge or less plus user metadata and the synced taxonomy, and returns suggestions constrained to those lists (METADATA-35, METADATA-40). At or above the threshold (default 0.7) a field pre-fills and stays editable; below it the field stays empty (METADATA-45). Typed values always win (METADATA-50). Free-text observations map to synced feat-* tags only (METADATA-100).

Call 2 is user-triggered only and produces the product description (METADATA-55). It receives the processed photos, the review-confirmed metadata, the primary and secondary wood categories, the parent-category path, the dimension fact block, and brand/geo context; the model never invents a dimension (METADATA-60, METADATA-65, METADATA-90). The Generate text control appears only when content generation is enabled and the endpoint is reachable (METADATA-110). All generation is logged (METADATA-66).

With inference off, the server assembles the name and short description and produces the description (METADATA-70). The name and short description are assembled from the primary wood category's patterns (METADATA-80, METADATA-81, METADATA-85). Prompts live in the database with all revisions (METADATA-105). Inference never blocks create and never auto-publishes (METADATA-75); a runtime failure offers Retry when recoverable or explains when it is not (METADATA-115).

3. Settings prerequisite

Store URL is env-only, HTTPS, read-only (SETTINGS-5, SETTINGS-10); the settings API rejects a write to it (SETTINGS-85). Woo auth is a WordPress application password stored AES-GCM (SETTINGS-15, SETTINGS-20). SLAB_AES_KEY is env-only (SETTINGS-25). Inference URL and key are encrypted; flags, model, brand voice, and geo context are settings (SETTINGS-30); the flags default off (SETTINGS-90). Species rates are one flat value per synced leaf (SETTINGS-35). woo_create_status defaults to draft (SETTINGS-65).

test-woo returns ok and detail, fails closed on missing credentials or non-HTTPS, and always resyncs taxonomy on success (SETTINGS-80, SETTINGS-40). test-inference returns ok, mode (stateful, stateless, or fail), vision_capable, and detail; fail blocks Call 2 only (SETTINGS-45). Taxonomy sync keeps only fig-* and feat-* tag families (SETTINGS-51), rebuilds in one transaction, keeps the previous cache on failure (SETTINGS-50), and bumps the anchor only on a real stored-subset change (SETTINGS-55). The client re-pulls when the anchor advances, and publish refreshes when the last sync is over an hour old (SETTINGS-60).

4. Publish

The sequence validates the ready set, looks up the SKU and stops if it exists, refreshes taxonomy when stale, resolves categories, tags, and attributes, uploads the processed PNGs, calls POST /products per docs/contracts/WOO-API.md, then finalizes (PUBLISH-5). A SLAB-UAT-* SKU always creates a draft (PUBLISH-10). A duplicate SKU blocks create with edit-SKU or open-existing (PUBLISH-15). A stale value is a field-level error showing current options (PUBLISH-20).

Success sets woo_product_id, purges photos, deletes the local row, and clears the device draft (PUBLISH-25, APP-15). Failure keeps photos, writes sync_log, and shows a plain message on the affected field with retry (PUBLISH-30); the failure is classified recoverable or unrecoverable (PUBLISH-36, PUBLISH-37, PUBLISH-38) and never shows a raw code (PUBLISH-35). Partial failure leaves orphaned media with a cleanup note (PUBLISH-31). Images upload as processed PNGs in photos-ready order with no cap (PUBLISH-40, PUBLISH-45). Published means the store create succeeded, not that it is live (PUBLISH-50). The payload is per docs/contracts/WOO-API.md (PUBLISH-55) and each product is one slab (PUBLISH-60).

5. Acceptance

• The full suite passes with inference disabled and asserts zero inference calls (QUALITY-20).
• Integration tests cover success, error, duplicate SKU, stale field, and taxonomy anchor against a Woo mock (QUALITY-35).
• UI and end-to-end tests run against a Compose stack with mocked Woo (QUALITY-50).
• Vectors TV-8 (pricing) and TV-9 (thickness band) pass (QUALITY-90, QUALITY-95).
• The M3 exit evidence is a real SLAB-UAT-* Woo draft matching the reviewed ready set, with inference off, plus test-woo and test-inference results (QUALITY-110).
• No raw status code, stack trace, or internal code reaches the owner (QUALITY-120); encrypted credentials round-trip (QUALITY-125).
• Dishonest proxies are rejected (QUALITY-105).

6. Out of scope

Offline capture and U2Net matting (CAPTURE-15, CAPTURE-165), backup and restore (OPS-30, OPS-35), and cross-browser end-to-end verification (QUALITY-115). The V1 instrumentation work is out of M3.