diff --git a/docs/reference/how-to-work-with-both-tools.md b/docs/reference/how-to-work-with-both-tools.md
new file mode 100644
index 0000000..de04ce0
--- /dev/null
+++ b/docs/reference/how-to-work-with-both-tools.md
@@ -0,0 +1,211 @@
+# How to Work with Claude Code and Antigravity
+
+A plain-English guide for day-to-day use.
+
+---
+
+## The basic idea
+
+You have two AI tools open at once. Claude Code runs in the terminal (inside
+Antigravity or standalone). Antigravity is the IDE with a built-in browser and
+its own AI chat panel. They each have strengths, and the setup is designed so
+they don't step on each other.
+
+Think of it like having two specialists in the room:
+- **Claude Code** is the engineer — writes code, manages tokens, runs quality
+  checks, handles git, keeps the project memory files up to date.
+- **Antigravity** is the visual reviewer — opens Storybook in a real browser,
+  takes screenshots, checks how things look at different screen sizes, spots
+  spacing and alignment issues.
+
+They share the same project files and the same set of rules (`AGENTS.md`), so
+they're always on the same page about conventions.
+
+---
+
+## When to use Claude Code
+
+Use the terminal (Claude Code) when you need something **built, fixed, or analysed**.
+
+**Building things:**
+- "Build me a new Button atom" → Claude Code uses `/build-atom`
+- "Create tokens for this new component" → Claude Code uses `/create-tokens`
+- "Write stories for the VenueCard" → Claude Code uses `/write-stories`
+
+**Fixing things:**
+- "The spacing on ProvidersStep is off" → tell Claude Code what to fix
+- "This component needs to handle empty states" → Claude Code edits the code
+- "Update the copy on the intro page" → Claude Code modifies the JSX
+
+**Quality checks:**
+- "Audit this component" → Claude Code runs `/audit`, `/critique`, `/harden`
+- "Is this ready to commit?" → Claude Code runs `/preflight`
+- "Check consistency across all atoms" → Claude Code runs `/normalize atoms`
+
+**Project management:**
+- "What did we do last session?" → Claude Code reads the memory files
+- "Log this design decision" → Claude Code updates decisions-log.md
+- "Commit and push" → Claude Code handles git
+
+**Rule of thumb:** if it involves writing or changing code, tokens, or memory
+files — use Claude Code.
+
+---
+
+## When to use Antigravity
+
+Use the Antigravity chat panel when you need something **looked at visually**.
+
+**Visual QA:**
+- "How does the HomePage look on mobile?" → type `/fa-visual-qa HomePage` in
+  Antigravity. It opens the story, checks at 375px, 768px, and 1280px, takes
+  screenshots, and reports issues.
+
+**Page review (your most common task right now):**
+- "Review the CoffinsStep" → type `/fa-page-review CoffinsStep`. It reads the
+  source, opens the story, runs through the review checklist (spacing, typography,
+  colour, responsive, copy, interactions, edge cases), and reports findings with
+  severity ratings.
+
+**Quick checks:**
+- "Does this look right?" → open Storybook in Antigravity's browser panel and
+  eyeball it yourself. The built-in browser is faster than using Playwright
+  screenshots through Claude Code.
+
+**Pre-commit (either tool works):**
+- `/fa-preflight` in Antigravity runs the same checks as `/preflight` in Claude
+  Code. Use whichever you have open.
+
+**Rule of thumb:** if it involves looking at something in a browser and judging
+whether it looks right — use Antigravity.
+
+---
+
+## The typical flow for your current work (tweaking pages)
+
+Most of your work right now is reviewing and polishing existing pages. Here's the
+natural rhythm:
+
+### 1. Start your session
+
+In Claude Code: I automatically read the memory files and report what's pending.
+Or in Antigravity: type `/fa-session-start` for the same status report.
+
+### 2. Pick a page to work on
+
+You say something like "let's look at the ProvidersStep."
+
+### 3. Assess (Antigravity)
+
+In the Antigravity chat: `/fa-page-review ProvidersStep`
+
+It opens the page in Storybook, checks it at three screen sizes, and gives you a
+list of issues — spacing inconsistencies, typography problems, copy that could be
+warmer, responsive breakpoint issues.
+
+### 4. Fix (Claude Code)
+
+You bring the findings to me: "Fix the spacing between the filter chips and the
+provider list, and tighten up the heading hierarchy."
+
+I make the targeted changes in the code.
+
+### 5. Verify (Antigravity)
+
+Back in Antigravity: `/fa-visual-qa ProvidersStep`
+
+It screenshots the page at all three breakpoints again so you can compare
+before and after.
+
+### 6. Commit (Claude Code)
+
+Once you're happy: "commit and push." I handle git.
+
+That's the **sandwich**: Antigravity sees the problem → Claude Code fixes it →
+Antigravity confirms the fix.
+
+---
+
+## The flow for building new components
+
+When you need something new built (a new atom, molecule, organism, or page):
+
+1. **Tell Claude Code what you need.** I'll check the component registry, verify
+   dependencies, and build it following the lifecycle.
+2. **I run internal QA automatically** (`/audit`, `/critique`, `/harden`) before
+   showing it to you.
+3. **Visual sign-off in Antigravity.** Use `/fa-visual-qa ComponentName` to check
+   it at all breakpoints.
+4. **You give feedback.** I fix, Antigravity re-verifies. One or two rounds.
+5. **Preflight and commit.** Either tool can run preflight. I handle the commit.
+
+---
+
+## What about the workflows?
+
+You have six workflows available in Antigravity's chat. Type `/` followed by the
+name:
+
+| Workflow | What it does | When to use it |
+|----------|-------------|----------------|
+| `/fa-session-start` | Reads memory files, reports project status | Start of a session |
+| `/fa-page-review` | Full review of an existing page | When tweaking/polishing pages |
+| `/fa-visual-qa` | Visual check at 3 breakpoints | After any visual change |
+| `/fa-preflight` | Runs all quality checks (auto-approves) | Before committing |
+| `/fa-token-sync` | Rebuilds token outputs (auto-approves) | After changing token JSON |
+| `/fa-build-component` | Scaffolds a new component | When building something new |
+
+The ones marked "auto-approves" run without asking — they're safe, read-only or
+deterministic operations.
+
+---
+
+## What not to worry about
+
+**You don't need to keep the tools in sync.** They both read `AGENTS.md` for
+shared rules. Claude Code reads `CLAUDE.md` for its extra instructions.
+Antigravity reads `GEMINI.md` for its extra instructions. There's no overlap
+between those two files, so nothing drifts.
+
+**You don't need to tell both tools the same thing.** If you make a design
+decision, tell Claude Code — I'll log it in `decisions-log.md`, and Antigravity
+can read it from there next time.
+
+**You don't need to worry about file conflicts.** Claude Code writes code and
+memory files. Antigravity only reads those files and writes to its own workflow
+directory. They don't touch each other's files.
+
+---
+
+## When the backend comes
+
+When you start the Payload CMS work, the same structure holds:
+
+- The **backend agent** (whether it runs in Antigravity or a separate Claude Code
+  session) will own `src/payload/` and `src/api/`. It reads the flow-definition
+  YAML files to know what API endpoints and data shapes to build.
+- **Claude Code** continues owning frontend components, tokens, and theme.
+- **Antigravity** continues owning visual QA.
+- The **flow-definition.yaml** is the contract between frontend and backend — it
+  defines the step IDs, field names, branching logic, and visibility rules that
+  both sides reference.
+
+We'll add a backend section to `AGENTS.md` when that starts. For now, the
+boundaries are already defined so the transition will be smooth.
+
+---
+
+## Quick reference card
+
+| I want to... | Use |
+|--------------|-----|
+| Build a component | Claude Code |
+| Fix spacing/copy/alignment | Claude Code |
+| Check how something looks | Antigravity (`/fa-visual-qa`) |
+| Review a whole page | Antigravity (`/fa-page-review`) |
+| Run quality checks | Either (`/preflight` or `/fa-preflight`) |
+| Rebuild tokens | Either (`/sync-tokens` or `/fa-token-sync`) |
+| Commit and push | Claude Code |
+| Log a design decision | Claude Code |
+| Check project status | Either (`/status` or `/fa-session-start`) |
+| Extract from Figma | Claude Code (has Figma MCP) |