diff --git a/docs/atoms.md b/docs/atoms.md
new file mode 100644
index 000000000..beaf33f54
--- /dev/null
+++ b/docs/atoms.md
@@ -0,0 +1,96 @@
+# First-party atom catalog
+
+> The atomic capabilities Open Design exposes to plugins.
+> Spec: [`docs/plugins-spec.md`](plugins-spec.md) §10.
+> Source of truth: [`apps/daemon/src/plugins/atoms.ts`](../apps/daemon/src/plugins/atoms.ts).
+> Live discovery: `GET /api/atoms` (also reachable via `od atoms list --json` in a future PR).
+
+A **plugin** assembles atoms into ordered stages (`od.pipeline.stages[].atoms[]`).
+The Open Design daemon is responsible for resolving each atom into a system-prompt
+fragment, tool gating, and (when applicable) GenUI surface declarations. Plugins
+never own the atom implementations; they only reference them by id.
+
+## Reading this document
+
+- **id** — what you write inside `od.pipeline.stages[*].atoms[]` and
+  `od.context.atoms[]`. Stable across daemon versions.
+- **status** — `implemented` (live in v1) or `planned` (id reserved; the daemon
+  will accept it but emit a doctor warning until the matching atom is wired in).
+- **task kinds** — which of the four product scenarios (`new-generation`,
+  `code-migration`, `figma-migration`, `tune-collab`) the atom is intended for.
+  Plugins may reference an atom outside its declared task kinds, but doctor
+  flags this as suspicious.
+
+## Implemented atoms (v1)
+
+| id | label | task kinds |
+| --- | --- | --- |
+| `discovery-question-form` | Discovery question form — turn-1 question form for ambiguous briefs. | `new-generation`, `tune-collab` |
+| `direction-picker` | Direction picker — 3–5 direction picker before the final commit. | `new-generation`, `tune-collab` |
+| `todo-write` | Todo write — TodoWrite-driven plan. | all |
+| `file-read` / `file-write` / `file-edit` | File ops on the project cwd. | all |
+| `research-search` | Research search — Tavily-backed shallow research. | `new-generation` |
+| `media-image` / `media-video` / `media-audio` | Media generation through configured providers. | `new-generation`, `tune-collab` |
+| `live-artifact` | Create / refresh live artifacts. | `new-generation`, `tune-collab` |
+| `connector` | Composio connector tool calls. | `new-generation`, `tune-collab` |
+| `critique-theater` | 5-dimension panel critique; emits the `critique.score` signal that drives devloop convergence. | all |
+
+## Planned atoms (reserved ids)
+
+These ids are reserved so plugins authored against the v1 spec do not have to
+churn names when the daemon adds the matching capability. Until promotion, the
+daemon treats references as "doctor warning" rather than "unknown atom error".
+
+| id | label | task kinds |
+| --- | --- | --- |
+| `code-import` | Clone / read existing repo. | `code-migration` |
+| `design-extract` | Extract design tokens from source code / Figma / screenshots. | `code-migration`, `figma-migration` |
+| `figma-extract` | Extract Figma node tree + tokens + assets. | `figma-migration` |
+| `token-map` | Map extracted tokens onto the active design system. | `code-migration`, `figma-migration` |
+| `rewrite-plan` | Long-running multi-file rewrite plan. | `code-migration`, `tune-collab` |
+| `patch-edit` | Small-step file patches. | `code-migration`, `tune-collab` |
+| `diff-review` | Render rewrite as a reviewable diff. | `code-migration`, `tune-collab` |
+| `handoff` | Push artifact to downstream surfaces (cli / cloud / desktop). | `tune-collab` |
+
+## How the daemon resolves an atom
+
+1. The plugin manifest's `od.pipeline.stages[*].atoms[]` is parsed into a
+   `PipelineStage[]` by `apps/daemon/src/plugins/pipeline.ts`.
+2. At run time, `apps/daemon/src/plugins/pipeline-runner.ts` walks the stages.
+   For each stage entry it:
+   - emits a `pipeline_stage_started` SSE event,
+   - asks the caller-supplied stage runner to execute the atom (today this is
+     a stub; Phase 4's atom migration into `plugins/_official/<atom>/SKILL.md`
+     makes this fully data-driven),
+   - persists one row into `run_devloop_iterations` for audit,
+   - emits a `pipeline_stage_completed` event with the resulting signals.
+3. The atom's prompt fragment / tool gating is currently inline in
+   `apps/daemon/src/prompts/system.ts`. Phase 4 patch 2 (spec §23.3.2) lifts
+   each fragment out into `plugins/_official/atoms/<atom>/SKILL.md` so the
+   prompt becomes fully data-driven.
+
+## Atom signals + the `until` vocabulary
+
+Spec §10.1 locks the v1 `until` vocabulary to:
+
+- `critique.score` — emitted by `critique-theater`.
+- `iterations` — built-in per-stage counter.
+- `user.confirmed` — emitted when a `confirmation` GenUI surface resolves.
+- `preview.ok` — emitted by the live-artifact preview pipeline.
+
+Atoms outside that list contribute signals through `critique.score` (which is
+how today's `build-test`-shaped community plugins encode pass/fail). Phase 7
+(spec §21.4) extends the vocabulary so atoms can declare named signals
+through `od.atom.untilSignals[]`; until then, the closed vocabulary is the
+contract.
+
+## Adding a new atom
+
+1. Author the atom out-of-tree as a plugin (per spec §22.5 promotion path).
+2. Once the SKILL.md / MCP tool / pipeline shape stabilises, append the
+   matching row to `FIRST_PARTY_ATOMS` in `apps/daemon/src/plugins/atoms.ts`.
+3. Update this document and the spec §10 / §21 / §23 tables in the same PR.
+4. The atom is now reachable via:
+   - `od.pipeline.stages[*].atoms[]` references in any plugin,
+   - `GET /api/atoms` discovery,
+   - `od plugin doctor` validation.