# Agents: start here (/dev/agents)



**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](./how-we-work.md#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](./how-we-work.md#the-flow-four-steps-and-a-guard-that-refuses-the-rest)
wins, and the page that disagrees is a bug: fix it in the landing you are on
([see something: fix it](./how-we-work.md#see-something-fix-it-or-write-it-down-in-the-same-landing)).
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](https://remy-auth.gedw99.workers.dev) (staging, with the automatic sign-in:
[https://remy-auth-staging.gedw99.workers.dev](https://remy-auth-staging.gedw99.workers.dev)); the developer docs [https://remy-auth-docs.gedw99.workers.dev/dev](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`).

1. [Development principles](./development.md): ownership, single source of truth, test gates,
   generated code, owner decisions.
2. [Developer tooling](./tooling.md): the scripts and commands, pinned tools and agent skills. Run
   project commands through `npm run <script>`.
3. [GUI runtime workflow](./gui.md): one Worker, local and remote test targets.
4. [How we work](./how-we-work.md): 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.
5. [Sign-in and permissions](./auth.md): the guard, the relation engine, `<Allowed>`, environments
   and mail: what every Remy app gets, and where remy-auth uses each itself.
6. The plan in [`.plans/`](https://github.com/joeblew999/remy-auth/tree/main/.plans) covering your
   task, and its [Executor/Reviewer roles](./development.md#plans-and-roles).

Start with `npm run dev:status` (what is going on) and
[the project's own tools](./how-we-work.md#use-the-projects-own-tools-first), and finish through
[the flow](./how-we-work.md#the-flow-four-steps-and-a-guard-that-refuses-the-rest): `npm run dev:change`
after every change, `npm run dev:land -- "<what changed>"` when the work is finished and the check is
green.