Agents: start here

Where an AI agent starts in this repository: the documents that own the rules, in reading order, the live sites, and the flow every piece of work goes through.

For AI agents (Claude Code, Codex, any other) working in this repository, and the people driving them. The rules live in these developer docs, each in the document that owns it; this page is the reading order. The root AGENTS.md and CLAUDE.md only point here (where rules live). Read the documents below before changing anything, and follow them over your own defaults.

When two pages disagree, the flow's table wins, and the page that disagrees is a bug: fix it in the landing you are on (see something: fix it). A contradiction between pages is never a reason to stop, or to ask the owner which is right.

Live: the app https://remy-auth.gedw99.workers.dev (staging, with the automatic sign-in: https://remy-auth-staging.gedw99.workers.dev); the developer docs https://remy-auth-docs.gedw99.workers.dev/dev (the product guide /docs, the API reference /reference; MCP servers /api/mcp/dev, /api/mcp/reference, /api/mcp/docs; everything for AI tools at /llms.txt). These pages' source is docs/content/dev/*.md: read those, not the translations beside them (*.es.md).

Development principles: ownership, single source of truth, test gates, generated code, owner decisions.
Developer tooling: the scripts and commands, pinned tools and agent skills. Run project commands through npm run <script>.
GUI runtime workflow: one Worker, local and remote test targets.
How we work: project tools first, surveys before tool choices, shadcn and TanStack all the way for UI, the flow and who runs each step, multi-agent work. Record working rules there, not in agent memory.
Sign-in and permissions: the guard, the relation engine, <Allowed>, environments and mail: what every Remy app gets, and where remy-auth uses each itself.
The plan in .plans/ covering your task, and its Executor/Reviewer roles.

Start with npm run dev:status (what is going on) and the project's own tools, and finish through the flow: npm run dev:change after every change, npm run dev:land -- "<what changed>" when the work is finished and the check is green.