@wix/agent-skills 1.0.0

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

@@ -0,0 +1,423 @@
+# 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.
+
+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.
+
+## Why this replaces sidecars
+
+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:
+
+- ~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.
+
+## The contract
+
+Every subagent's final message ends with a fenced JSON block (language tag: `json` or `jsonc`). Format:
+
+~~~markdown
+... agent's human-readable summary ...
+
+```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>",
+  "scope": "<scope string from the agent's prompt>",
+  "summary": "<one-line description of what was done>",
+  "data": { ... phase-specific structured data ... },
+  "files": ["list", "of", "files", "written", "or", "modified"],
+  "errors": [],
+  "notes": "<optional — anything the parent skill should know>"
+}
+```
+~~~
+
+The JSON block MUST be the **last** content in the message. The parent skill parses the last fenced JSON block as the return.
+
+### 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
+```
+
+No LLM-generated timestamps anywhere in the observability pipeline.
+
+### 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.
+
+**Correct pattern — end with the fenced block, no trailing prose:**
+
+~~~markdown
+✅ CORRECT
+
+All files written. Contract classes referenced: productCard, productGrid, optionPill, quantityBtn.
+
+```json
+{
+  "status": "complete",
+  "phase": "stores-components",
+  "scope": "components",
+  "summary": "Wrote React islands + utils; contract classes referenced: 11",
+  "data": { ... },
+  "files": [ ... ],
+  "errors": []
+}
+```
+~~~
+
+~~~markdown
+❌ WRONG — trailing prose after the block
+
+```json
+{ "status": "complete", ... }
+```
+
+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
+
+| Status | Meaning | Parent action |
+|--------|---------|---------------|
+| `complete` | All work done successfully | Proceed to next phase |
+| `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:
+
+```json
+{
+  "status": "partial",
+  "phase": "stores-pages-products",
+  "errors": [
+    {
+      "file": "src/pages/products/[slug].astro",
+      "code": "MISSING_SEO_DATA",
+      "message": "product.seoData was null; fell back to product.name for <title>",
+      "severity": "warning"
+    }
+  ],
+  "data": {...}
+}
+```
+
+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
+
+| 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 |
+
+### Build
+
+| 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 |
+
+## Notes for agent authors
+
+When writing a new agent, include a **Returns** section in its `INSTRUCTIONS.md` that lists:
+
+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.

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

@@ -0,0 +1,117 @@
+# 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.
+
+## 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]"`. |
+| **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. |
+
+## Default direction
+
+**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.
+
+## Decision tree
+
+When you find yourself reaching for a `class="..."` value, ask:
+
+1. **Can this be expressed as 2–4 Tailwind utilities derived from `@theme`?** → Use utilities. Don't create a class.
+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`).
+
+## What does NOT belong as a global semantic class
+
+These are layout/spacing/typography concerns that should always be utilities, never standalone classes:
+
+- Section padding / margins (`py-4xl`, `mt-3xl`, `mb-2xl`)
+- Flex / grid layouts (`flex flex-col gap-md`, `grid grid-cols-3 gap-lg`)
+- 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`)
+
+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.
+
+## 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.
+
+The retained set:
+
+- **Button family** — `btn`, `btn-primary`, `btn-secondary`, `btn-ghost`. Compound + `:hover`/`:disabled`. Used on every page across every vertical.
+- **`[data-decorative-slot]`** — cross-cutting decorative pattern; the orchestrator injects images here regardless of vertical.
+- **`editorial-rule`** — cross-cutting decorative pattern (gold-rule / accent dividers used by hero/section dividers across verticals).
+- **Site shell shells** — `.site-nav`, `.site-footer`, `.nav-progress`. Sticky header, footer scaffold, top progress bar — universal site chrome with markers that verticals contribute into via `<!-- nav:links -->` etc.
+
+That's it. The full list of always-required classes for a site lives in designer `INSTRUCTIONS.md`; this file states the principle.
+
+## 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 fix is structural: move component-specific CSS out of `global.css` entirely.
+
+| What | Where it lives | Owner |
+|---|---|---|
+| `.product-card`, `.product-card-media`, `.product-card-ribbon`, `.product-card-index`, `.product-grid` | `src/styles/components-stores.css` | Stores Phase 3 components agent (or scoped `<style>` in the component's `.astro`) |
+| `.offer-callout` family (`-item`, `-badge`, `-name`, `-detail`, `-foot`) | `src/styles/components-stores.css` | Stores Phase 3 components agent |
+| `.cart-summary`, `.cart-total`, `.cart-empty`, `.checkout-btn` | `src/styles/components-ecom.css` | Ecom Phase 3 components agent |
+| Anything used by exactly one component | Co-located `<style>` block in the component's `.astro` or the matching `components-<pack>.css` | The pack that owns the component |
+
+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:
+
+- 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:
+
+```
+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/*/
+```
+
+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.
+
+## Co-located styles — the locality default for one-offs
+
+Astro's `<style>` blocks scope automatically to the `.astro` file by default — no class-name collision risk across routes. When a page needs decoration that doesn't fit utilities and isn't reusable, the rule lives next to its only caller:
+
+```astro
+<section class="relative py-4xl">
+  <div class="hero-stamp">Made in small batches</div>
+</section>
+
+<style>
+  .hero-stamp {
+    position: absolute;
+    bottom: var(--spacing-lg);
+    right: var(--spacing-lg);
+    background: rgba(27, 26, 23, 0.75);
+    color: var(--color-paper);
+    padding: 0.5rem 0.875rem;
+    font-family: var(--font-display);
+    font-style: italic;
+  }
+</style>
+```
+
+No coordination with the designer needed; no entry to forget on the always-required list. If this stamp later becomes a pattern used on three routes, *then* promote it to a global semantic class.
+
+## 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.