# .ai — EzyOrder project context

Hand-written context for AI coding sessions (Claude Code, Codex, Cursor) working on **EzyOrder**.
It complements, and never replaces, the material the EzyFlow template generates into the App.

## Two sources of truth, one rule

| Material | Where | Written by | Edit it? |
| --- | --- | --- | --- |
| **Brief** — EzyFlow rules every session must hold | marked block in `AGENTS.md` | `pnpm ezyflow:agents` | **Never.** Rewritten whole on every run |
| **Primer** — API facts, event lists, projections, MCP tools | `docs/ezyflow/` | `pnpm ezyflow:agents` | **Never.** `--check` fails on drift |
| **This folder** — what EzyOrder is, why, how we build it | `.ai/` | humans (and agents, on request) | Yes |

**Rule:** facts that move with the API release (event types, field names, operation names,
variable lists) live in the Primer. This folder states *product* intent and *project* choices,
and points at the Primer for API facts instead of copying them. If something here contradicts
`docs/ezyflow/` or the generated SDK types, the generated material wins — fix this folder.

## Reading order

1. [`context.md`](context.md) — what EzyOrder is, who uses it, scope and non-goals
2. [`glossary.md`](glossary.md) — the words to use (and the ones to avoid)
3. [`architecture.md`](architecture.md) — stack, layout, data flow, identities
4. [`domain.md`](domain.md) — orders and receipt notices, mapped to EzyFlow events
5. [`conventions.md`](conventions.md) — language, code, security, testing rules
6. [`workflows.md`](workflows.md) — run, add a screen, add a push form, add a handler, upgrade
7. [`decisions.md`](decisions.md) — template ADRs that bind us, plus EzyOrder's own decisions
8. [`roadmap.md`](roadmap.md) — what to build, in order, with acceptance criteria
9. [`references.md`](references.md) — Concepts and Tutorial pages, template, docs and schemas repos

## Wiring it into the App

- Paste [`AGENTS-snippet.md`](AGENTS-snippet.md) into `AGENTS.md` **outside** the
  `<!-- ezyflow:brief:begin -->` / `<!-- ezyflow:brief:end -->` markers.
- Copy `.claude/agents/ezyorder-engineer.md` into the App's `.claude/agents/`.
- Commit both. `CLAUDE.md` already imports `AGENTS.md`, so Claude Code picks everything up.