# Repository Guidelines

## Project Structure & Module Organization

Keep the single Go module defined in `go.mod`. The executable entrypoint lives in `cmd/server/main.go`; reusable HTTP and auth helpers belong under `internal/` (e.g., `internal/server`, `internal/auth`). Store templates and static assets beneath `web/` and embed them into the binary so deployments stay self-contained. Reserve `tmp/` for generated artifacts (binaries, logs) and keep it out of version control.

## Approved Technologies & Dependencies

Favor the Go standard library for routing, templating, crypto, and storage. The only pre-approved third-party package is `github.com/go-chi/chi/v5` when the default mux falls short. Pico.css provides styling, while htmx and Alpine.js deliver client interactivity; stick to semantic HTML. `golangci-lint` is the endorsed aggregator when linting beyond `go vet`. Introduce anything else only after discussion and an update here.

## Authentication Flow Requirements

Implement email/password authentication with secure password hashing, CSRF protection, and clear failure states. Use semantic forms enhanced by htmx for progressive enhancement and Alpine.js for lightweight client behavior. Persist session state on the server with HTTP-only cookies and render authenticated views without leaking sensitive data.

## Build, Lint, and Test Commands

- `make run` launches the server locally (defaults to <http://localhost:8000>), while `make dev` hot-reloads via Air.
- `make build` compiles to `bin/auth-server`; always execute it before formatting, linting, or testing to honor the compile-first rule.
- After a clean build, run `make fmt`, `make lint`, and `make test` so every change flows through the formatter, static analyzers, and `go test ./... -cover -count=1`.

## Coding Style & Naming Conventions

Trust `gofmt`; avoid manual formatting. Use CamelCase for exported Go identifiers and snake_case for embedded assets. Keep handlers slim, factor shared logic into helpers, and add concise comments only when intent needs clarification. Promote named constants/variables over magic numbers or strings. Template IDs and Alpine component names should reflect their role (e.g., `login_form`). Name handlers that render full pages with a `PageHandler` suffix and reserve the plain `Handler` suffix for non-page actions.

## Testing Guidelines

Adopt Go’s `testing` package with table-driven cases. Name files `<feature>_test.go`, colocated with the code under test. Run `go test ./... -cover -count=1` before opening a PR so coverage is measured on fresh binaries; we don’t enforce a target, but avoid notable drops when adding code.

## Commit & Pull Request Guidelines

Follow Conventional Commits (`feat:`, `fix:`, `chore:`). PRs must summarize the change, link relevant issues, include manual verification notes (commands executed, browsers checked), and attach screenshots or recordings for UI updates.

## Living Document

This guide evolves with the project. Whenever you add a tool, workflow, or architectural rule, update this section so future contributors inherit the collective knowledge.