Ty
120e0be871
Encode the recovered per-leaf title/short-description rule and the Call 2 input set into the point of record. - REQUIREMENTS.md: METADATA-55 now produces the description only; METADATA-60 carries the ruled input set; METADATA-80 is the deterministic title; new METADATA-81 is the deterministic spec-line short description; METADATA-85 selects the patterns; REVIEW-15 declares the primary before Call 2; PUBLISH-55 carries an explicit name+SKU slug. - CONTENT-WOO.md: per-leaf title and short-description catalog, slot order, dimension placement, and the Cook Woods provenance. - PROMPTS.md: Call 2 inputs and output; the deterministic patterns are cited, not restated. - CREATE.md, WOO-API.md, MILESTONES.md, task_breakdown.md updated to match. Modeled on Cook Woods product-title form; the seven per-leaf prose templates and Specialty cuts are parked in the M3 breakdown.
128 lines
6.5 KiB
Markdown
128 lines
6.5 KiB
Markdown
# 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-81, METADATA-85, METADATA-90, METADATA-95, METADATA-110 | deterministic copy, fallback, 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`):
|
|
|
|
1. **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.
|
|
2. **short_description** — assembled deterministically as a spec line from the primary wood
|
|
category's short-description pattern (`METADATA-81`). The model does not write it.
|
|
3. **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`, `METADATA-81`). 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)]
|
|
```
|
|
|
|
1. `Figure` leads as a Title-Case adjective and is omitted when the Figure term is `plain`.
|
|
2. Grade is not used in the title.
|
|
3. `Live Edge` appears only when the Edge Type term is Live Edge.
|
|
4. There is no separator between slots.
|
|
5. 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`).
|