# AGENTS.md: htmx 2 hypermedia app

## Principles
- The server returns HTML, not JSON. Each interactive area has a template partial the server can render alone.
- Pages must work without JavaScript first: real `<a href>` and `<form action method>`; htmx attributes enhance them (`hx-boost`, `hx-get`, `hx-post`).
- Check the `HX-Request` header to return a partial vs. the full page from the same route.
- Target precisely: `hx-target` with an id, `hx-swap="outerHTML"` for replacing a component, `hx-swap-oob` for side updates like counters or flash messages.
- Show progress with `hx-indicator`; disable double submits with `hx-disabled-elt="this"`.
- Validation errors re-render the form partial with status 422 and messages next to fields (configure htmx to swap 4xx responses if the project does).
- Redirect after a mutation with the `HX-Redirect` or `HX-Location` response header.
- Small client behavior: htmx events plus a few lines of vanilla JS or Alpine.js. No SPA framework.

## Security
- Escape all output through the template engine; never build HTML strings by hand.
- CSRF token on every non-GET request (via `hx-headers` on `<body>` or a hidden input).

## Don't
- Don't add React/Vue, client-side routing, or JSON endpoints just for htmx.

## Done
Click through the changed flow with JS on and off, then run the backend test suite.