Files

T

Ty d6aa79b593 docs(m3): regroup METADATA and remove the false fallback framing

METADATA was ordered as it was written, not by topic, and used Call 1 /
Call 2 without defining them.

- Add a short METADATA preamble stating the inference flow: Call 1 vision
  proposes taxonomy, the name and short description are deterministic, Call 2
  writes the long description.
- Regroup the rows: taxonomy, then Call 1, then deterministic copy, then
  Call 2, then cross-cutting.
- METADATA-70 said the deterministic name and short description were an
  inference-off fallback; they are unconditional. It now covers only the
  inference-off description.
- METADATA-81 folded into METADATA-80 (same rule, two strings).
- METADATA-45 now names the below-threshold outcome.
- METADATA-90 now states what the fact block drives.

153 requirements; check_requirements and check_coverage both pass.

2026-09-19 12:10:11 -07:00

6.5 KiB

Raw Blame History

Listing copy and payload intent

Status: SPEC · 2026-09-18. Owns how listing copy is produced and the intent of the create payload. The wire shape is docs/contracts/WOO-API.md; the create sequence is docs/contracts/API.md; prompts are docs/contracts/PROMPTS.md.

Requirements impact

Requirement	Impact on this design
REVIEW-10, REVIEW-15, REVIEW-40, REVIEW-50	required prose, primary category, editability, limits
METADATA-55, METADATA-60, METADATA-65, METADATA-66	Call 2, inputs, dimension safety, logging
METADATA-70, METADATA-75, METADATA-80, METADATA-85, METADATA-90, METADATA-95, METADATA-110	deterministic copy, inference-off path, pattern selection, fact block, overlay exclusion, control
PUBLISH-5, PUBLISH-10, PUBLISH-15, PUBLISH-20, PUBLISH-25, PUBLISH-30, PUBLISH-31, PUBLISH-40, PUBLISH-45, PUBLISH-50, PUBLISH-55, PUBLISH-60	payload and create outcomes
SETTINGS-30, SETTINGS-65	brand voice and geo context; create status
METADATA-10, METADATA-15, METADATA-30	categories, attributes, tags on the payload

1. Copy sources

Three fields, three sources (REVIEW-10):

name — assembled deterministically by the server from the primary wood category's title pattern and the dimension fact block (METADATA-80). The model does not write it.
short_description — assembled deterministically as a spec line from the primary wood category's short-description pattern (METADATA-80). The model does not write it.
description — written by Call 2 when it runs (METADATA-55), from the inputs in METADATA-60; with inference off the server produces it (METADATA-70).

The primary wood category selects the title pattern, the short-description pattern, and the Call 2 prompt (METADATA-85, REVIEW-15). The owner can edit any field until create (REVIEW-40), and every field respects the limits in docs/contracts/WOO-API.md §9 (REVIEW-50).

The model writes the long description only, from the fact block; it never invents a dimension (METADATA-65, METADATA-90). The dimension-overlay image is never sent (METADATA-95). The Generate text control appears only when content generation is enabled and the endpoint is reachable (METADATA-110); a failed generation never blocks create (METADATA-75). Every generation is logged (METADATA-66).

2. Deterministic title and short description

Both patterns are assembled by the server and use only synced taxonomy terms and capture facts (METADATA-80). Placeholders use {field}; every number comes from the deterministic pipeline, never the model (METADATA-90).

The shape follows the convention a working mill store uses: descriptor-led, dimension-light titles, with the measurements carried separately. See "Provenance" below.

2.1 Title

Slot order:

[Figure] {species} [Live Edge] {noun} [(dims)]

Figure leads as a Title-Case adjective and is omitted when the Figure term is plain.
Grade is not used in the title.
Live Edge appears only when the Edge Type term is Live Edge.
There is no separator between slots.
Dimensions ride in the title only for the turning leaves, as a trailing (L x W x T).

Per-leaf patterns:

Leaf	Pattern	Example
Live edge wood	`[Figure] {species} Live Edge Slab`	`Figured Black Walnut Live Edge Slab`
Dimensional wood	`[Figure] {species} [Live Edge] Dimensional`	`Figured Red Oak Dimensional`
Knife blanks	`[Figure] {species} Knife Blank (L x W x T)`	`Figured Mirindiba Knife Blank (12 x 6.5 x 1.5 in)`
Bowl blanks	`[Figure] {species} [Live Edge] Bowl Blank (L x W x T)`	`Spalted Cherry Bowl Blank (8 x 8 x 3 in)`
logs and caps	`[Figure] {species} Log Cap`	`Figured Black Walnut Log Cap`
Pen blanks	`[Figure] {species} Pen Blank (L x W x T)`	`Figured Purpleheart Pen Blank (5.5 x 1.1 x 1.1 in)`
Pepper mill blanks	`[Figure] {species} Pepper Mill Blank (L x W x T)`	`Birdseye Olive Pepper Mill Blank (10 x 3.2 x 3 in)`

Specialty cuts has no M3 pattern.

length_ft = floor(length_in / 12), length_in_remainder = length_in mod 12 (1 dp).

2.2 Short description

One spec line, so the measurements appear even when the title omits them:

[Figure] {species} {noun}, {length} x {width} x {thickness}, {bdft} bdft

Leaf	Example
Live edge wood	`Figured Black Walnut Live Edge Slab, 9ft 6in x 24.3in x 1.75in, 18.4 bdft`
Dimensional wood	`Figured Red Oak Dimensional, 8ft 0in x 5.8in x 1.25in, 4.8 bdft`
Pepper mill blanks	`Birdseye Olive Pepper Mill Blank, 10in x 3.2in x 3in, 0.7 bdft`

2.3 Description

The long description is the model's prose when Call 2 runs (METADATA-55); with inference off the server produces it (METADATA-70). The per-leaf prose templates that guide Call 2 are authored with that slice and are not defined here.

2.4 Provenance

The title and short-description form was modeled on the live product titles of Cook Woods (cookwoods.com), captured 2026-09-19. Borrowed: descriptor-led titles; dimension-free titles for slabs, lumber, and caps; parenthetical dimensions only for turning stock; no separator; title case. Not borrowed: their size-class nouns (Mini Slab, Table, Micro Lumber, Long) and pack counts (5 Pack), which have no synced taxonomy term, and their grade adjectives, which are not used in our titles.

3. Payload intent

The exact wire shape is docs/contracts/WOO-API.md. Intent:

Only non-null fields are sent (PUBLISH-55).
The payload carries an explicit slug: the sanitized product name plus the lowercased SKU. Dimensions never appear in the slug (PUBLISH-55).
status comes from woo_create_status (default draft); SLAB-UAT-* always draft (SETTINGS-65, PUBLISH-10).
Categories are the species leaf plus each wood-category leaf; attributes are the five locked attributes by synced term; tags are fig-* and feat-* (METADATA-10, METADATA-15, METADATA-30). Missing attributes or terms are skipped, never created (METADATA-20).
Images are the processed transparent PNGs in photos-ready order, with no cap (PUBLISH-40, PUBLISH-45).
sold_individually is true; each product is one slab (PUBLISH-60).
Create checks the SKU first and blocks on a duplicate (PUBLISH-15); a stale value is a field-level error (PUBLISH-20). Success purges photos and deletes the local row (PUBLISH-25); failure retains photos and logs (PUBLISH-30), including the orphaned-media cleanup note (PUBLISH-31). Published means the create succeeded, not that it is live (PUBLISH-50).

6.5 KiB Raw Blame History