diff --git a/.agent/workflows/fa-build-component.md b/.agent/workflows/fa-build-component.md
new file mode 100644
index 0000000..77e897c
--- /dev/null
+++ b/.agent/workflows/fa-build-component.md
@@ -0,0 +1,51 @@
+---
+description: Scaffold and build a new component following FA conventions and the full component lifecycle.
+---
+
+# Build Component
+
+Create a new component following the FA design system conventions and the
+component lifecycle defined in `docs/reference/component-lifecycle.md`.
+
+## Arguments
+
+Provide the tier and component name (e.g., `atom Button`, `molecule PriceCard`).
+
+## Pre-flight
+
+1. Read `docs/memory/component-registry.md` — confirm component is planned, not already in-progress
+2. **Dependency check (molecules):** all constituent atoms must be `done`
+3. **Dependency check (organisms):** all constituent molecules and atoms must be `done`
+4. Read `docs/conventions/component-conventions.md` — follow the template
+5. Read `docs/design-system.md` — understand brand context for this component
+6. Read `docs/memory/token-registry.md` — know available tokens
+
+If any dependency is not met, STOP and report what's missing.
+
+## Build
+
+1. Create folder: `src/components/{tier}/{ComponentName}/`
+2. Create `ComponentName.tsx`:
+   - Extend appropriate MUI base component props
+   - All visual values from theme (never hardcode)
+   - `React.forwardRef` for interactive elements
+   - Forward `sx` prop
+   - JSDoc on every prop
+   - `displayName` set
+3. Create `ComponentName.stories.tsx`:
+   - `tags: ['autodocs']` in meta
+   - Stories: Default, AllVariants, AllSizes, Disabled, Loading, Error, LongContent, MinimalContent
+4. Create `index.ts` barrel export
+5. Create component tokens in `tokens/component/{component}.json` if needed
+
+## Verify
+
+- Open story in Storybook at `localhost:6006`
+- Confirm all stories render without errors
+- Check visual appearance matches design system
+
+## After
+
+- Update `docs/memory/component-registry.md` — mark as `review`
+- Update `docs/memory/token-registry.md` if tokens were created
+- Update `docs/memory/decisions-log.md` with any design decisions
diff --git a/.agent/workflows/fa-page-review.md b/.agent/workflows/fa-page-review.md
new file mode 100644
index 0000000..664a05d
--- /dev/null
+++ b/.agent/workflows/fa-page-review.md
@@ -0,0 +1,91 @@
+---
+description: Review and tweak an existing page — visual QA, spacing adjustments, copy refinement, responsive check. Current phase focus.
+---
+
+# Page Review
+
+Review an existing page component for visual quality, consistency, and polish.
+This is the primary workflow for the current project phase (tweaking and
+finalising pages rather than building from scratch).
+
+## Arguments
+
+Provide the page name (e.g., `ProvidersStep`, `HomePage`, `CoffinsStep`).
+
+## Steps
+
+### 1. Gather context
+
+- Read the page source: `src/components/pages/{PageName}/{PageName}.tsx`
+- Read its stories: `src/components/pages/{PageName}/{PageName}.stories.tsx`
+- Check `docs/memory/session-log.md` for recent changes to this page
+- Check `docs/memory/decisions-log.md` for relevant design decisions
+
+### 2. Open in Storybook
+
+Navigate to `localhost:6006` and open the page's default story.
+
+### 3. Review checklist
+
+At each breakpoint (375px mobile, 768px tablet, 1280px desktop):
+
+**Visual hierarchy**
+- Heading sizes follow a clear progression (display → h1 → h2 → body)
+- Primary action is visually prominent
+- Whitespace groups related content, separates unrelated
+
+**Spacing**
+- All spacing uses `theme.spacing()` — no magic numbers
+- Consistent gaps between sections (typically spacing(4) or spacing(6))
+- No visual crowding; no excessive empty space
+
+**Typography**
+- Body text line length between 45-75 characters
+- Line heights readable (1.5 for body, tighter for headings)
+- Font weights create clear distinction between labels and content
+
+**Colour**
+- All colours from theme/tokens — no raw hex in source
+- Contrast meets WCAG AA (4.5:1 normal text, 3:1 large text)
+- Error states use copper (#B0610F), not red
+
+**Responsive**
+- Content reflows cleanly between breakpoints
+- No horizontal overflow or content clipping
+- Touch targets at least 44px on mobile
+- Images and cards scale proportionally
+
+**Copy**
+- Warm but not gushy — understated empathy
+- Labels are clear, unambiguous, sentence case
+- CTAs use action verbs ("Continue", "Select", "Save")
+- No jargon or funeral-industry terms without context
+
+**Interactive states**
+- Hover, focus, disabled visible on all controls
+- Focus indicators: 2px solid, 2px offset, visible on `:focus-visible`
+- Disabled: reduced opacity, no pointer events
+
+**Edge cases**
+- Long content handled (truncation, scroll, or wrap)
+- Empty/minimal content doesn't break layout
+- Loading states present where data is async
+
+### 4. Make targeted fixes
+
+For issues found:
+- Make small, focused changes (spacing, copy, alignment)
+- Do NOT restructure the page — this is polish, not redesign
+- Reference design decisions from decisions-log.md when relevant
+
+### 5. Before/after comparison
+
+- Screenshot the page at each breakpoint BEFORE and AFTER changes
+- Present both to the user for approval
+
+### 6. Report
+
+Summarise:
+- Changes made (with file and line references)
+- Remaining issues (with severity P0/P1/P2)
+- Suggested next steps (e.g., "run fa-preflight before committing")
diff --git a/.agent/workflows/fa-preflight.md b/.agent/workflows/fa-preflight.md
new file mode 100644
index 0000000..adbc177
--- /dev/null
+++ b/.agent/workflows/fa-preflight.md
@@ -0,0 +1,52 @@
+---
+description: Pre-commit quality checks — TypeScript, ESLint, Prettier, Storybook build, token sync, hardcoded values. // turbo
+---
+
+# Preflight Checks
+
+Run all quality gates before committing. Report PASS/FAIL/WARN for each.
+
+## Checks
+
+1. **TypeScript compilation**
+   Run `npx tsc --noEmit`
+   FAIL if any type errors. Report file and line for each error.
+
+2. **ESLint**
+   Run `npm run lint`
+   FAIL if any errors (warnings are WARN). Report count and top issues.
+
+3. **Prettier**
+   Run `npm run format:check`
+   FAIL if any files need formatting. List files.
+
+4. **Storybook build**
+   Run `npx storybook build --quiet`
+   FAIL if build errors. Report the failing component.
+
+5. **Token sync**
+   Compare timestamps: are any `tokens/**/*.json` files newer than `src/theme/generated/`?
+   WARN if generated files are stale. Fix: `npm run build:tokens`
+
+6. **Hardcoded values scan**
+   Search `src/components/**/*.tsx` (excluding `*.stories.tsx`) for hex colour patterns (`#[0-9a-fA-F]{3,8}`).
+   WARN for each match not on a line containing `// ok-hardcode`.
+
+7. **Component exports**
+   For each component folder in `src/components/`, verify `index.ts` exists and re-exports the component.
+   FAIL if any component is missing its barrel export.
+
+## Report format
+
+| Check | Status | Details |
+|-------|--------|---------|
+| TypeScript | PASS/FAIL | error count |
+| ESLint | PASS/FAIL/WARN | error/warning count |
+| Prettier | PASS/FAIL | files needing format |
+| Storybook | PASS/FAIL | failing component |
+| Token sync | PASS/WARN | stale files |
+| Hardcoded values | PASS/WARN | matches found |
+| Exports | PASS/FAIL | missing index.ts |
+
+If all PASS: safe to commit.
+If any FAIL: fix before committing.
diff --git a/.agent/workflows/fa-session-start.md b/.agent/workflows/fa-session-start.md
new file mode 100644
index 0000000..a04f210
--- /dev/null
+++ b/.agent/workflows/fa-session-start.md
@@ -0,0 +1,37 @@
+---
+description: Start a work session — read memory files, check project status, report what needs attention.
+---
+
+# Session Start
+
+Read project state and report a summary before beginning work.
+
+## Steps
+
+1. **Read recent activity**
+   - Read `docs/memory/session-log.md` — summarise the last 2-3 sessions
+   - Note any incomplete work or open questions
+
+2. **Check component status**
+   - Read `docs/memory/component-registry.md`
+   - Count components by status: done, in-progress, planned, needs-revision
+   - Flag any components stuck in "in-progress" or "needs-revision"
+
+3. **Check token status**
+   - Read `docs/memory/token-registry.md`
+   - Note any gaps or recently added tokens
+
+4. **Check pending reviews**
+   - Read `docs/reference/retroactive-review-plan.md`
+   - List any tiers or components that haven't been reviewed yet
+
+5. **Check recent decisions**
+   - Read `docs/memory/decisions-log.md`
+   - Note the 3 most recent decisions and their status
+
+6. **Report**
+   Present a brief summary:
+   - Recent activity (1-2 sentences)
+   - Component stats (done/in-progress/planned)
+   - Pending review items
+   - Suggested next actions
diff --git a/.agent/workflows/fa-token-sync.md b/.agent/workflows/fa-token-sync.md
new file mode 100644
index 0000000..a3825ba
--- /dev/null
+++ b/.agent/workflows/fa-token-sync.md
@@ -0,0 +1,28 @@
+---
+description: Rebuild CSS and JS outputs from token JSON sources. // turbo
+---
+
+# Token Sync
+
+Validate token JSON and regenerate all outputs.
+
+## Steps
+
+1. **Validate token files**
+   Read each file in `tokens/primitives/`, `tokens/semantic/`, `tokens/component/`.
+   Every token object must have `$value`, `$type`, and `$description`.
+   Report any tokens missing required fields.
+
+2. **Build tokens**
+   Run `npm run build:tokens`
+   Report success or failure with error details.
+
+3. **Verify outputs**
+   Confirm these generated files exist and are non-empty:
+   - `src/theme/generated/tokens.css`
+   - `src/theme/generated/tokens.js`
+   Report any missing or empty outputs.
+
+4. **Check theme integration**
+   Read `src/theme/index.ts` — are any newly added tokens missing from the MUI theme mapping?
+   Report tokens that exist in generated output but aren't consumed by the theme.
diff --git a/.agent/workflows/fa-visual-qa.md b/.agent/workflows/fa-visual-qa.md
new file mode 100644
index 0000000..8b01fb5
--- /dev/null
+++ b/.agent/workflows/fa-visual-qa.md
@@ -0,0 +1,40 @@
+---
+description: Browser-based visual QA of a component or page in Storybook. Checks spacing, alignment, states, responsive behaviour.
+---
+
+# Visual QA
+
+Open a component or page story in Storybook and perform a visual quality check
+at multiple breakpoints.
+
+## Arguments
+
+Provide the component name or story path (e.g., `ProvidersStep`, `Button`, `Pages/HomePage`).
+
+## Steps
+
+1. **Ensure Storybook is running** at `localhost:6006`
+
+2. **Navigate to the story**
+   Construct URL: `http://localhost:6006/?path=/story/{tier}-{componentname}--default`
+   If the component is a page: `pages-{pagename}--default`
+
+3. **Check at three breakpoints**
+   For each of mobile (375px), tablet (768px), desktop (1280px):
+
+   - **Spacing:** consistent use of the spacing scale, no visual crowding or excessive gaps
+   - **Alignment:** elements aligned to grid, no off-by-one shifts
+   - **Typography:** hierarchy readable, line lengths between 45-75 characters, weights distinct
+   - **Colour:** all values appear to come from the design system (warm golds, neutral greys, copper accents)
+   - **Interactive states** (if applicable): hover, focus, disabled look correct
+   - **Overflow:** no content clipping, horizontal scroll, or text truncation issues
+   - **Touch targets:** buttons and interactive elements appear at least 44px at mobile
+
+4. **Screenshot each breakpoint**
+   Capture and present to user for review.
+
+5. **Report findings**
+   List issues found with severity:
+   - **P0:** Broken layout, missing content, inaccessible controls
+   - **P1:** Spacing inconsistency, contrast failure, overflow at one breakpoint
+   - **P2:** Minor alignment, typography weight, polish items
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..efbea43
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,90 @@
+# FA 2.0 Design System
+
+## Project
+
+Funeral Arranger (funeralarranger.com.au) design system rebuild. Client: Parsons
+(H.Parsons Funeral Directors). Users are often in distress — the design language
+must be warm, professional, trustworthy, and calm.
+
+## Tech stack
+
+- React 18 + TypeScript
+- Material UI (MUI) v5
+- Storybook 8+ with autodocs
+- Style Dictionary for token transformation
+- W3C DTCG token format (2025.10 stable spec)
+
+## Architecture
+
+Source of truth: token JSON files in `tokens/` (DTCG format).
+Flow: Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook
+
+Token tiers: primitives (`tokens/primitives/`) → semantic (`tokens/semantic/`) → component (`tokens/component/`)
+Component tiers: atoms → molecules → organisms → templates → pages (in `src/components/`)
+
+## Commands
+
+- `npm run build:tokens` — regenerate CSS/JS from token JSON (run after any token change)
+- `npm run storybook` — dev server on localhost:6006
+- `npm run type-check` — TypeScript compilation check
+- `npm run lint` / `npm run lint:fix` — ESLint
+- `npm run format` / `npm run format:check` — Prettier
+- `npm run test` — Vitest
+
+## Rules (always)
+
+1. Consume the MUI theme for all visual values — `theme.palette.*`, `theme.spacing()`, `theme.typography.*`
+2. Every token has `$value`, `$type`, and `$description` (DTCG format)
+3. Error styling uses copper (#B0610F) not red — grief-sensitive context
+4. Read `docs/memory/` before starting work (decisions-log, component-registry, token-registry, session-log)
+5. Update `docs/memory/` after completing work
+6. Run `npm run build:tokens` after any token JSON change
+7. Verify in Storybook before marking any component done
+8. Follow the component lifecycle in `docs/reference/component-lifecycle.md`
+9. Commit and push after each coherent unit of work
+
+## Rules (never)
+
+- Use raw hex values in component source files — map to semantic tokens
+- Mix token access methods — semantic via `theme.*`, component via `var(--fa-*)`
+- Skip the barrel export (`index.ts`) for any component
+- Edit files owned by another agent without coordinating (see File ownership)
+
+## Git workflow
+
+Remote: Gitea at `http://192.168.50.211:3000/richie/ParsonsFA.git`
+Branch: all work on `main` for now.
+
+Stage specific files (not `git add -A`). Commit message format:
+```
+Short summary (imperative mood, <70 chars)
+
+- Bullet points with detail if needed
+- Reference decision IDs (D001, D002...) when relevant
+```
+
+## File conventions
+
+- Component folders: PascalCase — `Button/`, `PriceCard/`
+- Token files: camelCase — `colours.json`, `typography.json`
+- Each component folder: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
+- CSS custom properties prefix: `--fa-`
+- Semantic tokens via theme, component tokens via CSS vars — see `docs/conventions/token-conventions.md`
+- Component structure and props: see `docs/conventions/component-conventions.md`
+
+## Key references
+
+- Design spec: `docs/design-system.md`
+- Component lifecycle: `docs/reference/component-lifecycle.md`
+- Flow architecture (wizard steps, branching, fields): `documentation/flow-definition.yaml`
+- Redesigned flow spec: `documentation/steps/flow-definition.yaml` + `documentation/steps/flow-spec.md`
+- Cross-tool workflow: `docs/reference/cross-tool-workflow.md`
+
+## File ownership
+
+One file, one owner at a time. Check `docs/memory/session-log.md` before starting.
+
+- **Component source, tokens, theme, memory files:** Claude Code owns writes
+- **Visual QA, browser verification, screenshots:** Antigravity owns
+- **Shared read:** all documentation, all source files, AGENTS.md
+- **When backend agent starts:** backend owns `src/payload/`, `src/api/`; frontend agents never touch those. `documentation/flow-definition.yaml` is the shared contract.
diff --git a/CLAUDE.md b/CLAUDE.md
index 89df72f..4d513f2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,113 +1,45 @@
-# FA 2.0 Design System
+# Claude Code — FA 2.0 Design System
 
-## Project overview
+Follow all rules in `AGENTS.md`. This file contains Claude-specific behaviour only.
 
-Rebuilding the Funeral Arranger (funeralarranger.com.au) design system using a
-code-first approach. Parsons (H.Parsons Funeral Directors) is the client. FA is
-an Australian funeral planning platform — the design language must be warm,
-professional, trustworthy, and calm. Users are often in distress.
+## Session startup (automatic)
 
-## Tech stack
+At the start of every session, automatically:
+1. Read `docs/memory/session-log.md`, `decisions-log.md`, `component-registry.md`
+2. Check `docs/reference/retroactive-review-plan.md` for pending review tiers
+3. If reviews remain, run the next step (~30-60 min) before the user's main request
+4. Report findings, then shift to whatever the user wants to work on
 
-- React 18 + TypeScript
-- Material UI (MUI) v5
-- Storybook 8+ with autodocs
-- Style Dictionary for token transformation
-- W3C DTCG token format (2025.10 stable spec)
-- Chromatic for Storybook hosting (later)
-
-## Architecture
-
-**Source of truth:** Token JSON files in `tokens/` (DTCG format)
-**Flow:** Token JSON → Style Dictionary → MUI theme + CSS vars → React components → Storybook
-
-### Token tiers
-1. **Primitives** (`tokens/primitives/`): Raw values — hex, px, font names, scales
-2. **Semantic** (`tokens/semantic/`): Design intent — `color.text.primary`, `color.surface.default`
-3. **Component** (`tokens/component/`): Per-component — `button.background.default`
-
-### Component tiers (atomic design)
-1. **Atoms** (`src/components/atoms/`): Button, Input, Typography, Badge, Icon, Avatar, Divider, Chip, Card, Link
-2. **Molecules** (`src/components/molecules/`): SearchBar, PriceCard, ServiceOption, FormField
-3. **Organisms** (`src/components/organisms/`): ServiceSelector, PricingTable, ArrangementForm, Navigation
-
-## Critical rules
-
-1. **Every component MUST consume the MUI theme** — never hardcode colours, spacing, typography, or shadows
-2. **Every token MUST have a `$description`** — this is how agents maintain context about design intent
-3. **Always read docs/design-system.md** before creating or modifying anything
-4. **Always check docs/memory/** before starting work — these files contain decisions and state from previous sessions
-5. **Always update docs/memory/** after completing work — log what was done, decisions made, and open questions
-6. **Run `npm run build:tokens`** after any token JSON change
-7. **Verify in Storybook** before marking any component done
-8. **Follow the component lifecycle** — see `docs/reference/component-lifecycle.md` for the full quality gate sequence (build → QA → polish → present → iterate → normalize → preflight → commit)
-9. **Commit and push after completing each unit of work** — see Git workflow below
-
-## Git workflow
-
-**Remote:** Gitea at `http://192.168.50.211:3000/richie/ParsonsFA.git` (credentials stored via git credential helper)
-
-**After completing each unit of work** (a component, a token change, a bug fix, etc.):
-1. Stage the changed files (`git add` — prefer naming specific files over `git add -A`)
-2. Commit with a clear message describing what was done
-3. Push to origin (`git push`)
-
-This is **not optional** — the user relies on the git history for rollback safety. Each commit should represent a coherent, working state (Storybook builds, TypeScript compiles). Do not batch multiple unrelated changes into a single commit.
-
-**Commit message format:**
-```
-Short summary (imperative mood, <70 chars)
-
-- Bullet points with detail if needed
-- Reference decision IDs (D001, D002...) when relevant
-
-Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-```
-
-**Branch strategy:** All work on `main` for now. Feature branches when the project grows.
+This is "morning housekeeping" — the user has approved this and expects it.
 
 ## Memory system
 
-This project uses structured markdown files for cross-session memory.
+Before starting any work, read:
+- `docs/memory/decisions-log.md` — all design decisions with rationale
+- `docs/memory/component-registry.md` — status of every component
+- `docs/memory/token-registry.md` — all tokens with values and usage notes
+- `docs/memory/session-log.md` — recent sessions; older in `docs/memory/archive/`
 
-**Before starting any work, read these files:**
-- `docs/memory/decisions-log.md` — All design decisions with rationale
-- `docs/memory/component-registry.md` — Status of every component (planned/in-progress/done)
-- `docs/memory/token-registry.md` — All tokens with their current values and usage notes
-- `docs/memory/session-log.md` — Recent sessions (last 2-3); older sessions in `docs/memory/archive/`
-
-**Session startup — proactive review pass (do this automatically):**
-Check `docs/reference/retroactive-review-plan.md` for the current review state. If
-there are tiers or components that haven't been reviewed yet, run the next review
-step (typically `/normalize {tier}` or `/audit {component}`) at the start of the
-session before the user's main request. Keep this to ~30-60 min, then report
-findings and shift to whatever the user wants to work on. This is "morning
-housekeeping" — the user has approved this and expects it to happen without asking.
-
-**After completing work, update:**
-- The relevant memory files with what changed
-- `docs/memory/session-log.md` with a summary of what was accomplished and next steps
+After completing work, update the relevant memory files and `session-log.md`.
 
 ## MCP servers
 
-- **Figma remote MCP** (`figma-remote-mcp`): Read FA 1.0 designs, extract design context
-- **Storybook MCP** (`storybook`): Query component library for available components and props
+- **Figma remote MCP** — read FA 1.0 designs, extract design context
+- **Storybook MCP** — query component library for available components and props
 
-Setup instructions in `docs/reference/mcp-setup.md`.
+Setup instructions: `docs/reference/mcp-setup.md`
 
-## File conventions
+## Commit co-author
 
-- Component folders: PascalCase (`Button/`, `PriceCard/`)
-- Token files: camelCase (`colours.json`, `typography.json`)
-- Each component folder contains: `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
-- CSS custom properties prefix: `--fa-` (e.g., `--fa-color-brand-primary`)
-- MUI theme paths: follow MUI conventions (`palette.primary.main`)
+Append to every commit message:
+```
+Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
+```
 
-## Naming conventions for tokens
+## Cross-tool workflow
 
-See `docs/conventions/token-conventions.md` for the full specification.
+This project uses both Claude Code and Google Antigravity.
+See `docs/reference/cross-tool-workflow.md` for task routing and coordination.
 
-Quick reference:
-- Primitives: `color.blue.500`, `spacing.4`, `fontSize.base`
-- Semantic: `color.text.primary`, `color.surface.default`, `color.interactive.default`
-- Component: `button.background.default`, `button.background.hover`
+Claude Code owns: component building, token creation, code quality, memory updates, git.
+Antigravity owns: visual QA, browser-based verification, page-level review screenshots.
diff --git a/GEMINI.md b/GEMINI.md
index 6910db8..a7b2d2f 100644
--- a/GEMINI.md
+++ b/GEMINI.md
@@ -1,58 +1,26 @@
-# FA 2.0 Design System — Antigravity Rules
+# Antigravity — FA 2.0 Design System
 
-## Project context
+Follow all rules in `AGENTS.md`. This file contains Antigravity-specific behaviour only.
 
-Funeral Arranger (funeralarranger.com.au) design system rebuild. Parsons is the
-client. The design language must be warm, professional, trustworthy, and calm.
-Users are often in distress.
-
-## Tech stack
-
-- React 18 + TypeScript
-- Material UI (MUI) v5
-- Storybook 8+ (running on localhost:6006)
-- Style Dictionary for token transformation
-- W3C DTCG token format
-
-## Hard rules
-
-1. **Never hardcode colours, spacing, typography, or shadows** — always consume the MUI theme (`theme.palette.*`, `theme.spacing()`, `theme.typography.*`) or CSS custom properties (`var(--fa-*)`)
-2. **Never use raw hex values in components** — map to semantic tokens
-3. **Follow atomic design tiers:** atoms → molecules → organisms → templates → pages
-4. **Component folders:** PascalCase, each contains `ComponentName.tsx`, `ComponentName.stories.tsx`, `index.ts`
-5. **Token files:** camelCase in `tokens/` directory (primitives → semantic → component tiers)
-6. **CSS custom properties prefix:** `--fa-`
-7. **Error styling uses copper (#B0610F)** not red — this is intentional for grief-sensitive context
-8. **Copy tone:** warm but not gushy. Understated empathy. Let UI structure be the empathy.
-
-## Token access convention
-
-- Semantic tokens: `theme.palette.*`, `theme.typography.*`, `theme.spacing()`
-- Component tokens: `var(--fa-component-property-state)`
-- Never mix — semantic via theme, component via CSS vars
-
-## Storybook
-
-Dev server runs on `localhost:6006`. When verifying components visually, navigate
-to the specific story URL. Story IDs follow the pattern:
-`/story/{tier}-{componentname}--{variantname}`
-
-## File structure
-
-```
-src/components/atoms/       — Button, Input, Typography, Card, etc.
-src/components/molecules/   — SearchBar, PriceCard, ServiceOption, etc.
-src/components/organisms/   — Navigation, Footer, ArrangementDialog, etc.
-src/components/templates/   — WizardLayout
-src/components/pages/       — IntroStep, ProvidersStep, etc. (wizard steps)
-tokens/primitives/          — Raw values (hex, px, font names)
-tokens/semantic/            — Design intent (color.text.primary)
-tokens/component/           — Per-component tokens
-```
-
-## When making visual changes
+## Visual verification
 
+When reviewing or making visual changes:
 1. Make the code change
-2. Open the Storybook story in the browser to verify
+2. Open the Storybook story in the browser at `localhost:6006`
 3. Screenshot and check spacing, alignment, visual weight
 4. Self-correct if something looks off before presenting
+
+Story URL pattern: `/story/{tier}-{componentname}--{variantname}`
+
+## Cross-tool workflow
+
+This project uses both Claude Code and Google Antigravity.
+See `docs/reference/cross-tool-workflow.md` for task routing and coordination.
+
+Antigravity owns: visual QA, browser verification, page-level review screenshots.
+Claude Code owns: component building, token creation, code quality, memory updates, git.
+
+## Workflows
+
+Custom workflows available in `.agent/workflows/`:
+`fa-session-start`, `fa-preflight`, `fa-token-sync`, `fa-visual-qa`, `fa-build-component`, `fa-page-review`
diff --git a/docs/reference/cross-tool-workflow.md b/docs/reference/cross-tool-workflow.md
new file mode 100644
index 0000000..b7d7e3c
--- /dev/null
+++ b/docs/reference/cross-tool-workflow.md
@@ -0,0 +1,184 @@
+# Cross-Tool Workflow: Claude Code + Google Antigravity
+
+## How the tools work together
+
+**Claude Code** (terminal) — code generation, refactoring, quality analysis, memory
+management. Has 18 custom skills, 3 agents, MCP access (Figma, Storybook).
+Strengths: deep code reasoning, multi-file refactors, token architecture, grief-sensitive
+copy review, git operations.
+
+**Antigravity** (IDE) — visual verification, browser interaction, page-level review.
+Has 6 custom workflows in `.agent/workflows/`. Strengths: built-in browser for
+Storybook verification, screenshot comparison across breakpoints, multi-agent
+parallelism via Manager View.
+
+**Both read:** `AGENTS.md` (shared rules), `docs/memory/` (shared state), all source files.
+
+---
+
+## Task routing
+
+### Always Claude Code
+
+- Creating new components (`/build-atom`, `/build-molecule`, `/build-organism`)
+- Token creation and architecture (`/create-tokens`, `/sync-tokens`)
+- Code quality analysis (`/audit`, `/critique`, `/harden`, `/normalize`)
+- Writing tests and stories (`/write-tests`, `/write-stories`)
+- Visual polish skills (`/polish`, `/typeset`, `/adapt`, `/quieter`, `/clarify`)
+- Memory file updates (decisions-log, component-registry, session-log)
+- Git operations (commit, push)
+- Multi-file refactors
+- Figma MCP interactions (design extraction)
+
+### Always Antigravity
+
+- Browser-based visual QA (`/fa-visual-qa` workflow)
+- Screenshot comparison across breakpoints (375/768/1280px)
+- Page-level visual review (`/fa-page-review` workflow)
+- Storybook visual regression checks
+
+### Either tool (user's choice)
+
+- Preflight checks (Claude: `/preflight` | Antigravity: `/fa-preflight`)
+- Token sync rebuild (Claude: `/sync-tokens` | Antigravity: `/fa-token-sync`)
+- Session status report (Claude: `/status` | Antigravity: `/fa-session-start`)
+- Reading and analysing existing code
+- Copy and content review
+
+---
+
+## The sandwich workflow
+
+Every significant change should follow a three-step pattern that uses both tools.
+
+### For new components or features
+
+1. **Plan (Claude Code):** Read memory files, check registry, design the approach
+2. **Build (Claude Code):** Implement — component, tokens, stories, tests
+3. **Verify (Antigravity):** Open in Storybook, screenshot at 3 breakpoints, report issues
+
+### For page tweaking (current phase)
+
+1. **Assess (Antigravity):** Run `/fa-page-review`, screenshot current state, identify issues
+2. **Fix (Claude Code):** Make targeted fixes to spacing, copy, alignment, responsive
+3. **Verify (Antigravity):** Re-run `/fa-visual-qa`, confirm fixes, screenshot final state
+
+The sandwich ensures no change goes live without both code quality AND visual verification.
+
+---
+
+## Quality gates
+
+The 10-stage component lifecycle (`docs/reference/component-lifecycle.md`) applies
+regardless of which tool does the work.
+
+| Stage | Primary tool | Gate |
+|-------|-------------|------|
+| 1. BUILD | Claude Code | — |
+| 2. STORIES | Claude Code | — |
+| 3. INTERNAL QA | Claude Code (`/audit`, `/critique`, `/harden`) | P0 = blocking |
+| 4. FIX | Claude Code | Until P0/P1 = 0 |
+| 5. POLISH | Claude Code (`/polish`, `/typeset`, `/adapt`) | — |
+| 6. PRESENT | Antigravity (`/fa-visual-qa`) | Visual sign-off |
+| 7. ITERATE | Both (Claude fixes, Antigravity verifies) | User approves |
+| 8. NORMALIZE | Claude Code (`/normalize`) | — |
+| 9. PREFLIGHT | Either (`/preflight` or `/fa-preflight`) | Critical = blocking |
+| 10. COMMIT | Claude Code | — |
+
+**Enforcement:** No component moves past PRESENT without Antigravity visual sign-off.
+No component moves to COMMIT without preflight passing.
+
+---
+
+## File ownership boundaries
+
+### Current phase (frontend only)
+
+| Scope | Claude Code | Antigravity |
+|-------|------------|-------------|
+| `src/components/**/*.tsx` | write | read only |
+| `src/components/**/*.stories.tsx` | write | read only |
+| `src/components/**/index.ts` | write | read only |
+| `tokens/**/*.json` | write | read only |
+| `src/theme/**` | write | read only |
+| `docs/memory/**` | write | read only |
+| `docs/conventions/**`, `docs/reference/**` | write | read only |
+| `.agent/workflows/*.md` | read only | write (own workflows) |
+| `AGENTS.md` | write (coordinate first) | write (coordinate first) |
+| `CLAUDE.md` | write | never |
+| `GEMINI.md` | never | write |
+
+### When backend starts (Payload CMS)
+
+- **Backend agent writes:** `src/payload/**`, `src/api/**`, database schemas, server config
+- **Frontend agents never touch:** anything in `src/payload/` or `src/api/`
+- **Backend agent never touches:** `src/components/**`, `tokens/**`, `src/theme/**`
+- **Shared contract:** `documentation/flow-definition.yaml` is the interface between
+  frontend and backend. Field names, step IDs, and visibility rules in that file
+  dictate both component props and API data shapes. Changes require both sides
+  to acknowledge.
+
+### Conflict resolution
+
+- If two agents need to edit the same file: **STOP**, flag it in `docs/memory/session-log.md`,
+  let the user decide who proceeds.
+- If agents produce conflicting output: `docs/memory/decisions-log.md` is the tiebreaker.
+  Whoever's approach matches a logged decision wins.
+
+---
+
+## Error mitigation
+
+### Pre-flight checklist (before any agent work)
+
+- [ ] Read `docs/memory/session-log.md` — is another agent mid-task?
+- [ ] Read `docs/memory/component-registry.md` — is the target component in-progress by someone else?
+- [ ] Confirm file ownership — am I allowed to write these files?
+- [ ] Storybook running? (`localhost:6006`)
+- [ ] Git clean? No uncommitted changes from a previous session
+
+### Memory file update protocol
+
+1. Read the file before writing (always)
+2. Append, do not overwrite existing entries
+3. Use the established format (each file documents its own format)
+4. Include decision IDs (D001, D002...) for traceability
+5. Log agent name and date in every session-log entry
+
+### Verification after every change
+
+- TypeScript compiles: `npx tsc --noEmit`
+- Storybook renders the specific story (not just builds)
+- Visual check: at least desktop breakpoint for small changes, all three for layout changes
+- Token sync: if tokens changed, run `npm run build:tokens` and verify output
+
+### When agents produce conflicting output
+
+1. Check `docs/memory/decisions-log.md` for a prior decision
+2. If a decision exists: follow it, flag the conflict in session-log
+3. If no decision exists: **STOP**, do not proceed, ask the user
+4. Never silently override another agent's work
+
+### Common failure modes and recovery
+
+| Failure | Symptom | Recovery |
+|---------|---------|----------|
+| Stale tokens | Generated files older than source JSON | Run `npm run build:tokens` |
+| Hardcoded values | Hex colours in `.tsx` files | Run preflight scan, replace with theme refs |
+| Memory drift | Session log not updated | Always update session-log as last step |
+| Story rendering failure | Component changed but stories broken | Run `/write-stories` to regenerate |
+| File ownership violation | Two agents edited same file | `git diff` to see both changes, manually merge |
+
+---
+
+## Adapting for backend work
+
+When Payload CMS implementation begins:
+
+1. Add a `## Backend (Payload CMS)` section to `AGENTS.md` with Payload-specific rules
+2. Add backend file ownership to the boundaries above
+3. `documentation/flow-definition.yaml` becomes the API contract — field names, step IDs,
+   and visibility rules dictate both frontend props and backend data shapes
+4. Backend agent reads `documentation/flow-definition.yaml` and `documentation/steps/*.yaml`
+   as its primary specifications
+5. Frontend agents continue unchanged — the boundary is the data interface, not the UI