SlabUploader/docs/STRUCTURE.md

Structure contract

This file defines the shape of the docs/ system and how requirements enter it. tools/check_requirements.py enforces it.

If the repo and this file disagree, fix one deliberately. Do not let them drift.

Artifact registry

Every Markdown file under docs/ is registered here. docs/archive/** and docs/_templates/** are exempt.

Path	Role
docs/README.md	index
docs/PRODUCT.md	intent
docs/STRUCTURE.md	meta
docs/REQUIREMENTS.md	requirements
docs/MILESTONES.md	scope
docs/CAPTURE.md	capability
docs/PHOTOS.md	capability
docs/CREATE.md	capability
docs/CONTENT-WOO.md	contract
docs/UAT-PRACTICE.md	practice
docs/capabilities/README.md	index
docs/contracts/README.md	index

Roles:

• index — navigation only.
• intent — why and what; not testable requirements.
• meta — this contract.
• requirements — the only normative text.
• scope — milestone-to-ID mapping.
• capability — behavior and acceptance for one capability; cites IDs, does not define them.
• contract — cross-cutting interface detail; cites IDs, does not define them.
• practice — human walkthrough.

ID namespaces

Namespaces are owner jobs, not technology layers. A requirement belongs to the job it serves, and each namespace owns that job's screen, rules, server behavior, and data. There is no separate API, data, or UX layer to fight over.

All requirement text lives only in docs/REQUIREMENTS.md. This table assigns the home and prefix.

Prefix	The owner is...	Covers
CAPTURE	capturing ecommerce-ready pics	photo intake, pick calibration/dimension photo, BG removal, crop, axis, length/width, calculations, inventory PNG, dimension overlay, lineup
METADATA	building the listing	wood attributes and tags, title, short/deep description, via up to 2 inference calls
REVIEW	reviewing and correcting	confidence display, field gating, tweaks, per-slab price suggestion and override, ready gate
PUBLISH	submitting to the store	WooCommerce create, draft/live, duplicate SKU, cleanup
SETTINGS	configuring before the session	Woo connection, inference config, species $/bdft rates, brand/geo
APP	(foundation, not a job)	device draft, slab status, resume, server seams, secret handling
OPS	(foundation, not a job)	deploy, hosts, release, UAT
QUALITY	(foundation, not a job)	test obligations, vectors, anti-metrics

Price has two homes by design: the species $/bdft rates are configured in SETTINGS; the per-slab suggestion and override live in REVIEW.

Requirement format

Defined only in docs/REQUIREMENTS.md, as table rows:

| ID | Requirement | Scope | Test |
| CAPTURE-5 | Statement of one testable requirement | shipped | frontend/src/measure/measure.test.ts |

• Scope is shipped, M3, or later.
• Test is a repo-relative test path, a requirement ID, or —. A path given for a shipped requirement must exist; a given ID must resolve to a defined requirement.
• IDs advance by 5 within each namespace (5, 10, 15, ...), resetting for each prefix. The gaps are intentional room for later insertions; never renumber to close a gap.

How to change a requirement

• Modify: edit the single row in REQUIREMENTS.md; update Test; if scope changed, update MILESTONES.md. Do not create a doc.
• Add: pick the prefix and home from the namespace table; append a row; add the test. Do not create a doc.
• New domain: that is a structure change. Add a namespace row and a home here first, deliberately. Do not create a drive-by artifact.

Nothing outside REQUIREMENTS.md may define a requirement. Capability and contract docs cite IDs only.

Enforced by tools/check_requirements.py

1. Every docs/ Markdown file (except archive/** and _templates/**) is registered above.
2. Every registered file exists on disk.
3. Requirement IDs match ^[A-Z]+-\d+$, are unique, and use a registered prefix.
4. Scope is one of shipped | M3 | later.
5. Test references resolve: a path given for a shipped requirement exists; an ID given resolves to a defined requirement; — is allowed.
6. Requirement rows appear only in REQUIREMENTS.md.
7. Every ID listed in MILESTONES.md exists in REQUIREMENTS.md.

Planned (Phase 2)

• Migrate capability docs to docs/capabilities/ and contracts to docs/contracts/.
• Populate REQUIREMENTS.md from the pre-simplification tag and the current docs.
• Enforce branch-neutral language in trunk docs.
• Wire this check into CI.

Migration plan (Phase 2)

Current	Canonical home
docs/CAPTURE.md	docs/capabilities/CAPTURE.md
docs/PHOTOS.md	docs/capabilities/PHOTOS.md
docs/CREATE.md	docs/capabilities/CREATE.md
docs/CONTENT-WOO.md	docs/contracts/CONTENT-WOO.md
tag OPENAPI.md	docs/contracts/API.md
tag DATA-MODEL.md	docs/contracts/DATA-MODEL.md
tag UX.md	docs/contracts/UX.md
tag PROMPTS.md	docs/contracts/PROMPTS.md
tag TEST-SPEC.md	docs/contracts/TEST-SPEC.md