Add cross-tool workflow: AGENTS.md, Antigravity workflows, documentation

- Create AGENTS.md (90 lines) as shared foundation for Claude Code + Antigravity
- Slim CLAUDE.md from 113 to 45 lines (Claude-specific only, references AGENTS.md)
- Slim GEMINI.md from 58 to 26 lines (Antigravity-specific only, references AGENTS.md)
- Add 6 Antigravity workflows in .agent/workflows/ (session-start, preflight, token-sync, visual-qa, build-component, page-review)
- Add docs/reference/cross-tool-workflow.md with task routing, quality gates, file ownership, error mitigation
- Zero content overlap between CLAUDE.md and GEMINI.md (was ~80%)
- File ownership boundaries defined for current phase and future backend work

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.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

.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")

.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.

.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

.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.

.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