@wix/agent-skills 1.6.0 → 1.8.0

package/skills/wix-headless/references/shared/PRODUCTION_SHARP_EDGES.md

@@ -13,7 +13,7 @@ Use this reference when a Wix Headless run touches production release, SEO-contr
 - `temporary system error`
 - `try again shortly`
 
-The bundled `scripts/release.sh` retries these known transient release failures. Do not retry build failures; TypeScript, Astro, missing import, and missing module failures are code issues that must be fixed before another release attempt.
+The conductor's release step (the shared release tail, `BUILD.md` § "Shared release tail" — `BUILD-astro.md` § "Build & Release" for astro, `BUILD-own-build.md` § "Release" for no-build frameworks) retries these known transient release failures serially — up to 3× with `attempt * 5`s backoff. Do not retry build failures; TypeScript, Astro, missing import, and missing module failures are code issues that must be fixed before another release attempt.
 
 For batch releases across many projects, prefer releasing failed sites one by one after the current deployment state settles. Parallel release is useful for throughput, but retry serially when Wix reports state-machine errors.
 
@@ -63,7 +63,7 @@ PUT https://www.wixapis.com/promote-seo-robots-server/v2/llms
 }
 ```
 
-Do not use `default: true` for custom `llms.txt`; in observed runs it caused `/llms.txt` to return `404`.
+Do not use `default: true` for custom `llms.txt` — setting `default: true` returns `404` for custom `llms.txt` content.
 
 Wix may mutate `llms.txt` content by:
 
@@ -94,4 +94,4 @@ For production checks, verify the final rendered HTML and edge-controlled files
 - For `llms.txt`: fetch `/llms.txt` after the REST update and account for Wix-injected sections.
 - For custom domains: check both the Wix-hosted URL and custom domain when available, because domain propagation and redirects can differ.
 
-Do not construct URLs by editing the release URL from memory. Use the exact release URL printed by the CLI or the configured custom domain.
+Do not construct URLs by editing the release URL from memory. Use the exact release URL printed by the CLI or the configured custom domain.

package/skills/wix-headless/references/shared/RETURN_CONTRACT.md

@@ -1,18 +1,24 @@
 # Agent Return Contract
 
-Replaces the sidecar-file coordination model (`.wix/logs/*.md`) with **in-memory structured returns**. Every agent returns a JSON block at the end of its completion message; the skill parses these returns directly from session context.
+Coordination between agents uses **in-memory structured returns**, not sidecar files (`.wix/logs/*.md`, `.wix/seed-returns/*.json`, `.wix/image-urls.md`). Every agent returns a JSON block at the end of its completion message; the skill parses these returns directly from session context.
 
-At end of run, the skill writes ONE file (`.wix/run.json`) aggregating every return. This is the only observability artifact on the project side.
+The orchestrator consumes each return directly from context; nothing is aggregated to disk. The one end-of-run file is the project-root `AGENTS.md` (see `references/shared/AGENTS_MD.md`) — content about the site, not telemetry.
 
-## Why this replaces sidecars
+This document is the **universal envelope** every agent shares: the rules, the JSON skeleton, status semantics, and the generic failure shape. **The phase-specific `data` shape you must emit does NOT live here — it lives in your own role doc** (the one your scope already reads). See the index at the bottom.
 
-Sidecar files were designed assuming agents are independent processes without shared memory. But subagents run as child model calls under the parent skill's context — they can return structured data directly. Writing/reading markdown files between them adds:
+## The JSON return is your sole output channel
+
+Subagents MUST NOT write coordination files (`.wix/seed-returns/<pack>.json`, `.wix/image-urls.md`, `.wix/logs/*.md`, etc.). The orchestrator parses your fenced JSON block from the message body and either acts on the data directly or pipes it to a deterministic helper script via stdin (e.g. `emit-design-tokens.mjs`, `patch-decorative-slots.mjs`). Any data the orchestrator needs from you belongs under `data` in the return block — files in `.wix/` that aren't build-consumed (CSS, .d.ts) or external-system-owned (`wix.config.json`) are not part of the contract.
+
+## Why structured returns, not files
+
+Writing markdown files between agents assumes they're independent processes without shared memory. But subagents run as child model calls under the parent skill's context — they can return structured data directly. File-based coordination adds:
 
 - ~10s per sidecar write (file I/O + narration)
 - ~5s per sidecar read from the parent (another tool call)
 - Coordination complexity (timing, status-line parsing, retry logic)
 
-Prior runs spent **~1–2 minutes total** on sidecar ceremony. Eliminating that buys back meaningful critical-path time.
+That overhead is pure critical-path cost with no benefit here.
 
 ## The contract
 
@@ -24,10 +30,10 @@ Every subagent's final message ends with a fenced JSON block (language tag: `jso
 ```json
 {
   "status": "complete" | "partial" | "failed",
-  "phase": "<phase identifier — pack.seed / pack.components / pack.pages[*].name / design-system / image-phase-1-decorative / image-phase-2-entity>",
+  "phase": "<phase identifier — see your role doc's Returns section for the exact value>",
   "scope": "<scope string from the agent's prompt>",
   "summary": "<one-line description of what was done>",
-  "data": { ... phase-specific structured data ... },
+  "data": { ... phase-specific structured data — shape defined in your role doc ... },
   "files": ["list", "of", "files", "written", "or", "modified"],
   "errors": [],
   "notes": "<optional — anything the parent skill should know>"
@@ -39,28 +45,11 @@ The JSON block MUST be the **last** content in the message. The parent skill par
 
 ### Timing is NOT the agent's responsibility
 
-Prior versions of this contract asked agents to include `started` / `ended` ISO-8601 timestamps. **Remove those fields.** Agents fabricate placeholder timestamps (`T00:00:00Z` / `T00:05:00Z`) roughly 60% of the time, which makes `run.json` useless for perf comparison.
-
-**Authoritative timing source is the runtime `duration_ms`** captured by the parent skill from task-notifications when the subagent completes. The orchestrator MUST prefer `duration_ms` over any agent-reported timing. If an older agent still emits `started`/`ended`, the orchestrator ignores them.
-
-For Bash calls made by the skill itself (scaffold, env-pull, npm-install, app-install), wrap in `date -u` captures:
-
-```bash
-STARTED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-# ... run the command ...
-ENDED_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-# compute seconds and append to run.json
-```
+Agents don't self-report timing or status — the return is just `data`. Emit no `started`/`ended` timestamps; any wall-clock measurement is the harness's job, taken from the session trace.
 
-No LLM-generated timestamps anywhere in the observability pipeline.
+### No trailing prose after the fenced JSON
 
-### Observed failure mode — narrative ending instead of fenced JSON
-
-Agents sometimes end with prose like:
-
-> *"All three files are correctly written. Let me verify the key requirements… Everything looks good."*
-
-…with no fenced JSON block at the end. The parent skill then has to reconstruct `data.products` etc. from narrative text — fragile, and when Phase 4 relies on pre-seeded data from Phase 1 Seed returns (see `SKILL.md` Step 7), a missing JSON block means Phase 4 agents don't get their pre-seeded data inline and fall back to re-querying MCP, costing 5–15s each.
+The fenced JSON block must be the **last** content in the message. A trailing sentence — or no block at all — means the parent skill has to reconstruct `data.products` etc. from narrative text. That's fragile, and when a later phase relies on pre-seeded data from earlier returns, a missing block means downstream agents don't get their data inline and fall back to re-querying the REST API, costing 5–15s each.
 
 **Correct pattern — end with the fenced block, no trailing prose:**
 
@@ -92,14 +81,6 @@ All files written. Contract classes referenced: productCard, productGrid, option
 All three files are correctly written. Let me verify the key requirements are met before returning.
 ~~~
 
-~~~markdown
-❌ WRONG — no JSON block at all
-
-All three files are correctly written. The ProductPurchase island uses contract classes
-throughout, AddToCartButton wires to @wix/ecom, and CartView handles the two-step
-checkout redirect. Build should pass.
-~~~
-
 The parent skill looks for the **last** fenced JSON block in the message. A trailing sentence means it's no longer the last content; scanning falls back to heuristics. Just stop writing after the closing ` ``` `.
 
 ## Status semantics
@@ -110,200 +91,6 @@ The parent skill looks for the **last** fenced JSON block in the message. A trai
 | `partial` | Some work done, some failed — `errors` explains | Decide per-case: retry, work around, or fail the run |
 | `failed` | Nothing usable produced — `errors` explains | Retry with corrective prompt or fail the run |
 
-## Phase-specific `data` shapes
-
-The skill uses `data` to carry information forward to later phases. Each phase has a known shape.
-
-### Phase 1: stores seed
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-seed",
-  "scope": "seed",
-  "summary": "Deleted 12 default products; created 3 on-brand products with variants",
-  "data": {
-    "products": [
-      {
-        "id": "2d1bce83-...",
-        "name": "Tero Dining Table",
-        "slug": "tero-dining-table",
-        "variantId": "ffc1caa2-...",
-        "price": 2890,
-        "inventory": 12,
-        "sku": "TAB-TERO-OAK"
-      }
-    ],
-    "deletedCount": 12,
-    "createdCount": 3
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-Phase 4 agents consume `data.products[*].slug` and `data.products[*].variantId` to wire live SDK queries.
-
-### Phase 1: CMS seed
-
-```json
-{
-  "status": "complete",
-  "phase": "cms-seed",
-  "scope": "seed",
-  "data": {
-    "collections": [
-      {
-        "name": "about-content",
-        "itemIds": ["665f3363-..."],
-        "fields": ["heading", "body", "image"]
-      },
-      {
-        "name": "faq",
-        "itemIds": ["abc", "def", "ghi", "jkl", "mno", "pqr"],
-        "fields": ["question", "answer", "sortOrder"]
-      }
-    ]
-  }
-}
-```
-
-Phase 4 CMS page agents reference these collection names; the image agent attaches entity images to CMS items by ID.
-
-### Phase 2: shared wiring
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-components",
-  "scope": "components",
-  "summary": "Wrote React islands + utils; wired analytics; contract classes referenced: 7",
-  "data": {
-    "islands": ["ProductPurchase.tsx", "CartView.tsx", "AddToCartButton.tsx", "CartBadge.tsx"],
-    "utils": ["wix-image.ts", "analytics.ts"],
-    "astroComponents": ["SeoTags.astro"]
-  },
-  "files": [
-    "src/utils/wix-image.ts",
-    "src/utils/analytics.ts",
-    "src/components/SeoTags.astro",
-    "src/components/AddToCartButton.tsx",
-    "src/components/CartBadge.tsx",
-    "src/components/ProductPurchase.tsx",
-    "src/components/CartView.tsx"
-  ]
-}
-```
-
-### Phase 2: page rewrites
-
-```json
-{
-  "status": "complete",
-  "phase": "stores-pages-products",
-  "scope": "pages-products",
-  "data": {
-    "pagesWired": 2,
-    "wixMetadataExported": true,
-    "seoTagsMounted": true,
-    "analyticsEvents": ["AddProductImpression", "ClickProduct", "ViewContent"]
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/components/ProductCard.astro"
-  ]
-}
-```
-
-### Designer foundation
-
-```json
-{
-  "status": "complete",
-  "phase": "design-system",
-  "data": {
-    "contractKeys": 19,
-    "cssLines": 247,
-    "fonts": ["Cormorant Garamond", "DM Sans"],
-    "palette": {"cream": "#FFF8F0", "charcoal": "#1A1A1A", "roseGold": "#B76E79"}
-  },
-  "files": [
-    "src/styles/global.css",
-    "src/layouts/Layout.astro",
-    "src/components/Navigation.astro",
-    "src/components/Footer.astro",
-    ".wix/design-tokens.css"
-  ]
-}
-```
-
-### Designer page groups
-
-```json
-{
-  "status": "complete",
-  "phase": "designer-store-pages",
-  "data": {
-    "pagesDesigned": ["/products", "/products/[slug]", "/cart", "/thank-you"],
-    "placeholderDataUsed": true,
-    "contractClassesHonored": 11
-  },
-  "files": [
-    "src/pages/products/index.astro",
-    "src/pages/products/[slug].astro",
-    "src/pages/cart.astro",
-    "src/pages/thank-you.astro",
-    "src/components/ProductCard.astro",
-    "src/components/ProductPurchase.astro",
-    "src/components/CartView.astro"
-  ]
-}
-```
-
-### Images (split into two image phases, dispatched separately)
-
-The image agent runs in two scopes dispatched by the parent in different steps. Each emits its own return block.
-
-**`image-phase-1-decorative` — dispatched in Step 3 (no dependencies):**
-
-```json
-{
-  "status": "complete",
-  "phase": "image-phase-1-decorative",
-  "scope": "image-phase-1-decorative",
-  "summary": "Generated 3 decorative images; uploaded to Wix Media; wrote .wix/image-urls.md",
-  "data": {
-    "decorativeCount": 3,
-    "purposes": ["hero", "about", "background"],
-    "model": "google:4@2",
-    "totalCredits": 0.297
-  },
-  "files": [".wix/image-urls.md"],
-  "errors": []
-}
-```
-
-**`image-phase-2-entity` — dispatched in Step 7 (Phase 1 Seed return data inline in prompt):**
-
-```json
-{
-  "status": "complete",
-  "phase": "image-phase-2-entity",
-  "scope": "image-phase-2-entity",
-  "summary": "Generated + attached images for 6 products and 1 CMS item",
-  "data": {
-    "entityCount": { "products": 6, "cmsAboutContent": 1, "blogPosts": 0 },
-    "model": "google:4@2",
-    "totalCredits": 0.693
-  },
-  "files": [],
-  "errors": []
-}
-```
-
-(Image agent writes to Wix Media via MCP, not to project files — Image Phase 2 `files` is empty.)
-
 ## Failure returns
 
 On `failed` or `partial`, `errors` is populated and `data` may still contain partial results:
@@ -326,98 +113,31 @@ On `failed` or `partial`, `errors` is populated and `data` may still contain par
 
 Severity levels: `warning` (keep running), `error` (parent should retry), `fatal` (parent must stop).
 
-## Final `.wix/run.json` (written once by the skill at end of run)
-
-The skill aggregates every agent return into one file.
-
-**Timing is required** — the `run` object MUST include `started`, `ended`, and `totalSeconds`, and every entry in `phases` MUST include `seconds`. All timing values are captured by the parent skill (from runtime `duration_ms` for subagents, from `date -u` wraps for its own Bash calls) — agents do not self-report. If timing is missing for any phase, record `seconds: null` + `errors: [{code: "MISSING_TIMING"}]` and investigate what broke capture. See `skills/wix-headless/SKILL.md` § "Timing — required in run.json" for the capture protocol.
-
-Example:
-
-```json
-{
-  "version": "1.0",
-  "run": {
-    "started": "2026-01-15T09:16:14Z",
-    "ended": "2026-01-15T09:28:03Z",
-    "totalSeconds": 709,
-    "brand": "Acme Coffee",
-    "prompt": "I want to sell tables online",
-    "verticals": ["stores", "cms"],
-    "packs": ["stores", "cms"]
-  },
-  "outcome": {
-    "build": "success",
-    "previewUrl": "https://goj5lj-tabula-...-alexp775.wix-host.com",
-    "dashboardUrl": "https://manage.wix.com/dashboard/<siteId>"
-  },
-  "phases": [
-    { "phase": "scaffold", "status": "complete", "seconds": 45 },
-    { "phase": "app-install-stores", "status": "complete", "seconds": 6 },
-    { "phase": "env-pull", "status": "complete", "seconds": 4 },
-    { "phase": "npm-install", "status": "complete", "seconds": 42, "packageCount": 725 },
-    { "phase": "stores-seed", "status": "complete", "seconds": 112, "data": { ... } },
-    { "phase": "cms-seed", "status": "complete", "seconds": 98, "data": { ... } },
-    { "phase": "stores-components", "status": "complete", "seconds": 134, "data": { ... } },
-    { "phase": "design-system", "status": "complete", "seconds": 165, "data": { ... } },
-    { "phase": "designer-home", "status": "complete", "seconds": 287, "data": { ... } },
-    { "phase": "designer-static", "status": "complete", "seconds": 265, "data": { ... } },
-    { "phase": "designer-store-pages", "status": "complete", "seconds": 298, "data": { ... } },
-    { "phase": "stores-pages-products", "status": "complete", "seconds": 89, "data": { ... } },
-    { "phase": "stores-pages-cart-checkout", "status": "complete", "seconds": 67, "data": { ... } },
-    { "phase": "stores-pages-home-and-nav", "status": "complete", "seconds": 54, "data": { ... } },
-    { "phase": "pages", "status": "complete", "seconds": 78, "data": { ... } },
-    { "phase": "image-phase-1-decorative", "status": "complete", "seconds": 112, "data": { "decorativeCount": 3, ... } },
-    { "phase": "image-phase-2-entity", "status": "complete", "seconds": 287, "data": { "entityCount": { "products": 6, "cmsAboutContent": 1 }, ... } },
-    { "phase": "build", "status": "complete", "seconds": 9 },
-    { "phase": "preview", "status": "complete", "seconds": 21 }
-  ],
-  "notes": []
-}
-```
-
-Observations post-run (including this doc's example):
-- Total serial wall time ≈ max parallel paths, not sum of seconds
-- `data` blocks preserve what each agent returned — recoverable without re-reading agent transcripts
-- `files` lists omitted from aggregate; query individual phase `data` if needed
-
-## Common failure modes
-
-Agents should check their output for these before returning `complete`:
-
-### Astro/React
-
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| HTML-style comments in `.astro` frontmatter | `grep '<!--' *.astro frontmatter` | Use `//` or `/* */` — frontmatter is TypeScript |
-| Missing `wixMetadata` on `/products/[slug]` | Check exports | Add the metadata export — required for Wix platform indexing |
-| `import { products }` instead of `productsV3` | `grep 'from "@wix/stores"' -- import line` | V1 silently returns 0 on V3 catalogs |
-| Missing `variantId` in cart operations | Check `catalogReference.options` | Always include — single-variant products have one |
-| React island using default Tailwind color class | `grep 'bg-blue-\|bg-green-\|text-red-\|bg-gray-' *.tsx` | Use brand `@theme` utilities (`bg-bark`, `text-cream`) or contract class names |
-
-### MCP
+## Where your phase-specific `data` shape lives
 
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| `UNSUPPORTED_FORM_NAMESPACE` after app install | Error on first MCP call post-install | Wait 10s, retry up to 3x (namespace propagation) |
-| `CallWixSiteAPI` with stringified `body` | Tool rejects the call shape | Load the tool schema via your runtime's tool-discovery primitive, then pass `body` as a real object |
-| Tool-not-found on Wix MCP call | Tool name without the session's prefix | Use `<prefix>ToolName`; see `MCP_PREFIX.md` recovery |
+The envelope above is universal. The exact `data` shape — plus the known `error.code` values and required `files` — lives in **your role doc**, the one your scope already reads. Do not look for them here; read your own doc. This keeps each shape single-sourced (no drift) and means you never load shapes for phases you don't emit.
 
-### Build
+| Your agent / scope | `phase` value(s) | Shape lives in |
+|---|---|---|
+| Seed — stores | `stores-seed` | `references/stores/INSTRUCTIONS.md` § Seed return |
+| Seed — CMS | `cms-seed` | `references/cms/INSTRUCTIONS.md` § Seed return |
+| Seed — other verticals | `<pack>-seed` | per-vertical `INSTRUCTIONS.md` (same generic shape as stores) |
+| Components | `<pack>-components` | `references/shared/IMPLEMENTER.md` § Return contract |
+| Pages | `<pack>-pages[-<group>]` | `references/shared/IMPLEMENTER.md` § Return contract |
+| Design System Designer | `design-system` | `references/DESIGN_SYSTEM.md` § What you write and return |
+| Design System Composer (`scripts/compose.mjs`, not a subagent — manifest printed to stdout) | `compose` | `scripts/compose.mjs` header (the manifest shape) |
+| Page Designer | `designer-<scope>` | `references/astro/designer/INSTRUCTIONS.md` (per-scope) |
+| Images | `image-phase-1-decorative`, `image-phase-2-entity` | `references/images/INSTRUCTIONS.md` § Return Contract |
 
-| Failure | How to detect | Fix |
-|---------|---------------|-----|
-| `Legacy HTML single-line comments` | `npx @wix/cli build` stderr | See Astro/React row 1 above — Phase 2 agent emitted HTML comments |
-| `Missing environment variable WIX_CLIENT_ID` | Build stderr | Run `npx @wix/cli env pull` then retry |
-| `Cannot find module '@wix/…'` | Build stderr | npm install didn't include that package; check pack's `packages` list |
+The **orchestrator** is the one audience that needs every shape — it parses each return directly; there is no aggregated file. This table is its index.
 
 ## Notes for agent authors
 
-When writing a new agent, include a **Returns** section in its `INSTRUCTIONS.md` that lists:
+When writing a new agent, put a **Returns** section in its role doc (`INSTRUCTIONS.md` or equivalent) listing:
 
 1. The `phase` identifier this agent emits
 2. The exact `data` shape for successful returns
 3. Known `error.code` values
 4. Required `files` entries
 
-Agents should produce the JSON return block deterministically — don't let creative prose overrun the fenced block. Parent skill parsing assumes the JSON is well-formed and complete.
+Then add a row to the index table above so the orchestrator can find it. Do **not** copy the shape back into this file — one source per shape. Produce the JSON return block deterministically; don't let creative prose overrun the fenced block. Parent skill parsing assumes the JSON is well-formed and complete and is the **last** content in the message.

package/skills/wix-headless/references/shared/STYLING.md

@@ -1,12 +1,14 @@
 # Styling — Three Categories, One Default
 
-Every visual decision in a generated site falls into one of three categories. Each has a single owner and a single home. This file is the canonical reference; designer `INSTRUCTIONS.md` and `IMPLEMENTER.md` link here.
+Every visual decision in a generated site falls into one of three categories. Each has a single owner and a single home. This file is the canonical reference; `DESIGN_SYSTEM.md` (Designer), `scripts/compose.mjs` (Composer — deterministic script, self-documenting), `astro/designer/INSTRUCTIONS.md` (Phase 4 page designers), and `IMPLEMENTER.md` link here.
+
+> **Design-system ownership (the design-vs-application split).** The **Designer** (`DESIGN_SYSTEM.md`) owns the token *values* and their *completeness* — a coherent, complete brand visual authored as a **DESIGN.md** (`data.design`; format spec in `shared/DESIGN_MD.md`). The **Composer** (`scripts/compose.mjs`; self-documenting) owns the *application* — it writes the `@theme` block in `global.css` from those values (mapping each semantic role to a `--var` name) and guarantees the required-token contract below resolves. Component and page authors still compose those tokens as Tailwind utilities at their call sites. So: Designer picks "paper = `#FAF6EF`"; Composer writes `--color-paper: #FAF6EF` into `@theme`; a page writes `class="bg-paper"`.
 
 ## The three categories
 
 | Category | Lives in | Owned by | Use for |
 |---|---|---|---|
-| **Tokens (composed as utilities)** | `@theme` block in `src/styles/global.css`, mirrored to `.wix/site.json.designTokens`, `.wix/design-tokens.css`, `.wix/site.d.ts` | Designer (Phase 2) | All color, spacing, typography scale, radii, aspect ratios, shadows, transitions. Pages compose tokens at call sites as Tailwind utilities — `class="py-4xl bg-sand aspect-[16/5]"`. |
+| **Tokens (composed as utilities)** | the canonical `DESIGN.md` + its projections: the `@theme` block in `src/styles/global.css` (written by `scripts/compose.mjs`), plus `.wix/design-tokens.css` and `.wix/site.d.ts` (written by `scripts/emit-design-tokens.mjs`) — all from Designer's `DESIGN.md` | Designer picks values (Phase 2); `compose.mjs` writes `@theme` | All color, spacing, typography scale, radii, aspect ratios, shadows, transitions. Pages compose tokens at call sites as Tailwind utilities — `class="py-4xl bg-sand aspect-[16/5]"`. |
 | **Global semantic classes** | `src/styles/global.css` (outside `@theme`) and `src/styles/components-<pack>.css` | Designer + Phase 3 component agents | Compound multi-element patterns, interactive states (`:hover`, `:focus`, `:disabled`), and JS/React DOM query targets. |
 | **Co-located styles** | `<style>` block at the bottom of the same `.astro` file (or component CSS module for islands) | Page or component author | One-off page decoration: hero stamps, custom dividers, ornamental overlays that won't be reused elsewhere. |
 
@@ -14,7 +16,7 @@ Every visual decision in a generated site falls into one of three categories. Ea
 
 **Tokens-as-utilities is the default.** When you're about to write a class for layout, spacing, typography, alignment, simple background/text color, or aspect ratio, write Tailwind utilities derived from `@theme` instead. The site's design tokens give you `py-4xl`, `gap-sm`, `bg-paper-warm`, `text-ink`, `font-display`, `aspect-[16/5]` etc. Compose them in markup; do not invent semantic classes for these concerns.
 
-The token namespace is the contract. Read `.wix/site.json.designTokens` (or its typed mirror at `.wix/site.d.ts`) at the start of any pages or components scope to know which tokens this run published. If a token you need isn't there, that's a designer-side gap — flag it in your return JSON, don't paper over it with a custom class.
+The token namespace is the contract. The design tokens (the DESIGN.md token vocabulary — `colors`/`typography`/`spacing`/`rounded`/`containers`) live on disk at `.wix/design-tokens.css` (gate-verified present before the build wave) — **read that file at the start of any pages or components scope** to know which tokens this run published. The orchestrator does **not** inline them in your prompt. (`.wix/site.d.ts` is also on disk for the build.) If a token you need isn't in `.wix/design-tokens.css`, that's a designer-side gap — flag it in your return JSON, don't paper over it with a custom class.
 
 ## Decision tree
 
@@ -24,7 +26,7 @@ When you find yourself reaching for a `class="..."` value, ask:
 2. **Is it a compound multi-element pattern** (e.g., a bordered card with header + body + foot rules), an **interactive state** (`:hover`/`:focus`/`:disabled`/`:hover .child`), or a **JS query target** the DOM is inspected for? → Global semantic class in `global.css` (designer-owned) or `components-<pack>.css` (Phase 3 components agent-owned).
 3. **Is it a one-off page decoration** that won't be reused on any other route? → Co-located `<style>` block at the bottom of the same `.astro` file. Reference tokens via `var(--color-foo)` from `:root` (auto-loaded by `design-tokens.css`).
 
-If none fit, you're probably trying to do something the tokens don't support yet — talk to the designer (for new runs, return a `MISSING_TOKEN` error; for existing projects, add the token to `@theme` and propagate to `.wix/site.json.designTokens`).
+If none fit, you're probably trying to do something the tokens don't support yet — talk to the designer (for new runs, return a `MISSING_TOKEN` error; for existing projects, add the token to `@theme`).
 
 ## What does NOT belong as a global semantic class
 
@@ -35,10 +37,45 @@ These are layout/spacing/typography concerns that should always be utilities, ne
 - Aspect ratios (`aspect-[4/5]`, `aspect-square`)
 - Plain typography choices (`text-display-lg font-display`, `text-mute uppercase tracking-wide`)
 - Background / foreground color application without state (`bg-paper`, `text-ink-soft`)
-- Container widths derived from tokens (`max-w-prose`, `w-full`)
+- Container widths derived from tokens (`max-w-prose`, `w-full`) **only when** the designer declared matching `--container-*` keys in `@theme`
+
+### Prose / reading width (CMS, FAQ, About)
+
+Tailwind v4 resolves `max-w-3xl` to `var(--container-3xl)`, **not** `var(--spacing-3xl)`. If the designer published `--spacing-3xl: 5rem` but no `--container-3xl`, FAQ/About columns collapse to ~80px.
+
+**Page agents (Phase 4):**
+
+- **Do not** use `max-w-2xl`, `max-w-3xl`, etc. unless `global.css` `@theme` documents the matching `--container-*` key (grep `@theme` before choosing).
+- **Prefer** `container-reading` (designer `@utility`), `max-w-6xl` when `--container-6xl` exists, or explicit arbitrary width `max-w-[48rem]`.
+- **Do not** confuse spacing scale with container scale — `py-3xl` uses `--spacing-3xl`; `max-w-3xl` uses `--container-3xl`.
 
 If a designer's `global.css` contains rules like `.featured-section { padding-block: var(--spacing-4xl); }` or `.product-card-body { display: flex; flex-direction: column; gap: var(--spacing-xs); }`, those are misplaced — they belong in markup as utilities. Inventing such classes ships broken layouts: every consumer needs the designer to have pre-declared the class, and Tailwind v4 silently drops the references when the rule is missing.
 
+## Required tokens — the component-CSS template contract
+
+The per-pack `components-<pack>.css` templates at `<SKILL_ROOT>/references/astro/templates/<pack>/components-<pack>.css` reference a fixed set of CSS custom properties via `var(--token)` (never `@apply`). Those templates are copied verbatim into the project by the orchestrator at BUILD-astro.md § Step 4.5, so **the Composer's `@theme` block MUST declare every token below** for the build to pass (the Composer maps the Designer's framework-agnostic spec onto these `--var` names, deriving any required role the Designer omitted). If a token is missing, the rule that references it collapses silently and the corresponding component renders unstyled (or worse, half-styled).
+
+| Token | Required? | Fallback in templates | Used by |
+|---|---|---|---|
+| `--color-paper` | **required** | — | every pack — primary background |
+| `--color-paper-warm` | **required** | `var(--color-paper, var(--color-cream))` | stores summary bg, ecom cart-summary bg, gift-cards |
+| `--color-ink` | **required** | — | every pack — primary text + dark fills |
+| `--color-ink-soft` | optional | `var(--color-mute)` | stores option-label, ecom cart-item-option |
+| `--color-mute` | **required** | — | every pack — muted text + remove buttons |
+| `--color-rule` | **required** | — | every pack — borders + dividers |
+| `--color-accent` | **required** | — | every pack — brand emphasis |
+| `--color-cream` | optional | inner fallback in `var(--color-paper-warm, var(--color-paper, var(--color-cream)))` | stores form bg, gift-cards |
+| `--color-error` | optional | `var(--color-accent)` or hardcode | ecom cart-item-unavailable, stores back-in-stock-error |
+| `--font-display` | **required** | — | every pack — headings + labels |
+| `--font-body` | **required** | — | every pack — body text + UI |
+| `--spacing-2xs` … `--spacing-4xl` | **required (full scale)** | — | every template uses `gap: var(--spacing-md)` and similar |
+| `--radius-sm`, `--radius-md` | **required** | — | buttons, inputs, cards |
+| `--radius-lg`, `--radius-xl` | optional | — | stores product-card |
+
+The templates do NOT use `@apply` — every rule is `property: var(--token);` directly. This means missing utilities don't fail at build time (the way `@apply gap-sm` would). Missing tokens degrade silently to `var(missing) → unset → initial`. That makes the failure mode "ugly component" not "broken build" — easier to recover from but harder to detect, so verify the full set above is in `@theme` before returning.
+
+**Why this contract exists.** The component templates are authored against a stable, brand-agnostic token vocabulary so they don't need to be regenerated per run. Using `@apply` against brand-specific tokens (e.g. `bark`, `cream`, `parchment`) that designers don't publish fails the build with `Cannot apply unknown utility class`. Direct `var()` against the required-token list above avoids that class of failure entirely.
+
 ## What DOES belong in `global.css` (designer-owned)
 
 The designer's `global.css` is small — tokens plus a short list of truly cross-cutting patterns. Anything specific to a single vertical's component (a product card, a cart row, a discount callout) does NOT belong here. Those live with the component, in `components-<pack>.css` (Phase 3 components agent-owned) or in a co-located `<style>` block inside the component's `.astro` file.
@@ -54,7 +91,7 @@ That's it. The full list of always-required classes for a site lives in designer
 
 ## Component-specific CSS is owned by the component, not the designer
 
-The boundary that previously caused leaks: the designer published partial rules for `.product-card`, `.product-grid`, `.product-card-media`, `.offer-callout`, `.cart-summary`, etc. — all classes used by exactly one vertical's component. The designer doesn't know how those components should be laid out for a particular brand, so the rules ship as stubs and templates quietly add the missing layout in scoped CSS. Result: the same class behaves differently on different pages (e.g. `/products` rendering with `.product-grid { transition: opacity }` and no `display: grid`, while `/category/<slug>` defines a separate scoped `.product-grid` with the actual grid).
+The boundary that causes leaks: if the designer publishes partial rules for `.product-card`, `.product-grid`, `.product-card-media`, `.offer-callout`, `.cart-summary`, etc. — all classes used by exactly one vertical's component — the designer doesn't know how those components should be laid out for a particular brand, so the rules ship as stubs and templates quietly add the missing layout in scoped CSS. The same class then behaves differently on different pages (e.g. `/products` rendering with `.product-grid { transition: opacity }` and no `display: grid`, while `/category/<slug>` defines a separate scoped `.product-grid` with the actual grid).
 
 The fix is structural: move component-specific CSS out of `global.css` entirely.
 
@@ -67,25 +104,15 @@ The fix is structural: move component-specific CSS out of `global.css` entirely.
 
 The Phase 3 components agents already write to `components-<pack>.css` (the file is imported by the designer's `Layout.astro` from the start). This change just makes it the *only* place those classes live — no parallel partial rule in `global.css`.
 
-### Why this is structural
-
-Tokens + truly cross-cutting patterns (buttons, decorative slots, site shell) are stable across verticals and brands — fine for the designer to own. Component-specific layout and spacing evolves with the component. Putting it next to the component means:
+### Pre-return checklist for the Composer
 
-- One author per class. No drift.
-- Verticals can ship new component variants without round-tripping the designer.
-- `overflow: hidden` + `border-radius` traps are caught by the same person who set the radius — no second author who has to *know* the radius value.
-
-### Pre-return checklist for the designer
-
-Before returning the design-system scope, the designer agent runs:
+`compose.mjs` writes `global.css` by substituting the `@theme` palette into a pinned skeleton, so this leak is **structurally prevented** — the skeleton declares no `.product-card`/`.cart-summary`-family rules and the script never adds any. The grep below is a maintainer guard for when the skeleton itself is edited; confirm it declares none of these:
 
 ```
-grep -r --include="*.astro" --include="*.tsx" -lE "class(\\Name)?=.*(\\.|\\b)(product-card|product-grid|product-card-media|product-card-ribbon|product-card-index|offer-callout|cart-summary|cart-total|cart-empty|checkout-btn)\\b" $SKILL_ROOT/templates/*/
+grep -r --include="*.astro" --include="*.tsx" -lE "class(\\Name)?=.*(\\.|\\b)(product-card|product-grid|product-card-media|product-card-ribbon|product-card-index|offer-callout|cart-summary|cart-total|cart-empty|checkout-btn)\\b" $SKILL_ROOT/references/astro/templates/*/
 ```
 
-For every class name listed above that the designer's `global.css` declares: if any template references it, the class is component-specific and must NOT be in `global.css`. Move the rule to the appropriate `components-<pack>.css` template (or to a scoped `<style>` block in the component template). Do NOT ship a partial rule in `global.css` that the template "completes" — that's the leak this file is preventing.
-
-The check is mechanical and bounded — it scans templates, not the live project.
+For any listed class the Composer's `global.css` declares: if a template references it, move the rule to the appropriate `components-<pack>.css` template (or a scoped `<style>` block). Do NOT ship a partial rule in `global.css` that the template "completes".
 
 ## Co-located styles — the locality default for one-offs
 
@@ -114,4 +141,4 @@ No coordination with the designer needed; no entry to forget on the always-requi
 
 ## Why this protocol
 
-The bug class this prevents: markup writers (designer's shells, vertical pages agents, committed templates) and the CSS writer (designer's `global.css`) operate in different phases with no handshake. When the markup writer types a class string the CSS writer didn't pre-declare, Tailwind v4 silently drops it and ships a site with broken styling. Tokens-as-utilities collapses that handshake — there's no class to forget, only utilities derived from a token list everyone reads.
+The bug class this prevents: markup writers (designer's shells, vertical pages agents, committed templates) and the CSS writer (designer's `global.css`) operate in different phases with no handshake. When the markup writer types a class string the CSS writer didn't pre-declare, Tailwind v4 silently drops it and ships a site with broken styling. Tokens-as-utilities collapses that handshake — there's no class to forget, only utilities derived from a token list everyone reads.