AGENTS.md for Remix

# AGENTS.md

Instructions for coding agents working in this Remix repository. Cursor, Claude Code, Codex, Copilot, and other agents should follow this file before they guess.

## Stack

This repository is a Remix app. Data loads in loaders, mutations happen in actions, and forms work without a custom client fetch.

## Layout

- Route modules live in the routes directory the project already uses.
- Shared UI lives next to routes or in a components folder the repo has.
- Server-only modules stay out of client imports.

## Commands

- Dev server: `npm run dev`
- Typecheck: `npm run typecheck`
- Tests: `npm test`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Load data in a `loader`. Mutate in an `action`.
- Use Form or the project's fetcher. Do not hand-roll fetch for a mutation the action can do.
- Return `json` or the typed response helper the version of Remix in the repo uses.
- Validate form data on the server. The client check is a convenience.
- Keep nested route boundaries. Do not lift every loader to the root.
- Match the existing session and cookie helpers.

## Testing

Add or update tests when behavior changes.

Call the loader or action with a Request in a unit test. Cover the invalid form case.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Return a 4xx Response or the typed error the app uses for bad input. Unexpected errors hit the error boundary.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not fetch the route's own loader data from useEffect.
- Do not import server code into a file that ships to the browser.
- Do not throw a bare string. Use the project's error response.
- Do not add a global client cache for data the loader already owns.

## Done when

- The requested behavior works.
- The route loader and action typecheck, and the form still works without JavaScript if it did before.
- The diff stays inside the task.
- You list anything you could not run.