# AGENTS.md

Go web application built with the Congo framework (HTMX + DaisyUI).

## Build & Run

```bash
congo dev         # development server with hot reload
congo build       # production binary
congo launch      # deploy infrastructure
```

## Structure

```
<<.Dir>>/controllers/   Route handlers + template methods
<<.Dir>>/models/        Database models with auto-migration ORM
<<.Dir>>/views/         Go HTML templates with DaisyUI components
<<- if .WithFrontend>>
<<.Dir>>/components/    React island components (hydrated via data-component)
<<- end>>
internal/               Vendored Congo framework (modifiable)
```

## Key Patterns

- **Controller factory**: `Home() (string, *HomeController)` returns name + instance
- **Value receiver on `Handle()`** creates a copy per request for isolation
- **Public methods** on controllers are callable from templates: `{{home.AllItems}}`
- **IDs are always strings** (UUIDs), never integers
- **SQL uses PascalCase**: `WHERE UserID = ?` not `WHERE user_id = ?`
- **Templates by filename only**: `{{template "nav.html" .}}` not `"partials/nav.html"`
- **Error handling**: `c.RenderError(w, r, err)` returns 200 OK with error HTML for HTMX
- **HTMX + SameSite=Lax cookies** = CSRF protection (no tokens needed)
- **No custom ServeMux** — all routes go on `http.DefaultServeMux`

## Adding a Feature

1. Create controller in `<<.Dir>>/controllers/` with factory function
2. Register in `<<.Dir>>/main.go` with `application.WithController()`
3. Add views in `<<.Dir>>/views/`
4. Add model struct in `<<.Dir>>/models/`, register with `database.Manage(DB, new(Model))` in `db.go`

## Editing Guidelines

- After changes, verify with `congo build`
- `internal/` contains vendored framework source — you may modify it to customize behavior
- Route handlers use `app.Serve("template.html", nil)` for GET, `app.Method(c, "Create", nil)` for POST
- POST handlers respond with `c.Refresh(w, r)` (HX-Refresh header) or `c.Redirect(w, r, "/path")` (HX-Location header)
- PathValue in handlers: `r.PathValue("id")`, in template methods: `c.PathValue("id")`