diff --git a/CLAUDE.md b/CLAUDE.md
index 50af487..4ce217d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -52,18 +52,31 @@ bd close <id>         # Complete work
 
 ## Build & Test
 
-_Add your build and test commands here_
-
-```bash
-# Example:
-# npm install
-# npm test
-```
+- `make build` — `./fjmcp-broker` with `-trimpath` + ldflags-stamped build info
+- `make test` — `go test -race ./...` (includes integration tests under `cmd/broker/`)
+- `make lint` — `go vet`; `golangci-lint` if installed
+- `make tidy` — `go mod tidy`
+- `./fjmcp-broker --version` — inspect build info without supplying the rest of the config
 
 ## Architecture Overview
 
-_Add a brief overview of your project architecture_
+OAuth 2.1 authorization-server facade that fronts `forgejo-mcp`: brokers the OAuth dance against Forgejo, then spawns a per-session `forgejo-mcp --transport stdio` subprocess with the authenticated user's token in env. Module path: `kode.naiv.no/olemd/forgejo-mcp-broker`.
+
+Full design: `docs/design.md`. Phased plan: `docs/plan.md`.
+
+Layout: `cmd/broker/` → `internal/config` → `internal/store` → `internal/httpserver`, with `internal/buildinfo` (ldflags-stamped) and `internal/log` (slog) as shared utilities.
 
 ## Conventions & Patterns
 
-_Add your project-specific conventions here_
+- SQLite driver: `modernc.org/sqlite` (pure Go, no CGO). DSN pragmas via `?_pragma=name(value)`.
+- Migrations: `embed.FS` under `internal/store/migrations/NNNN_name.sql`; `loadMigrations` takes `fs.FS` so tests inject synthetic sets via `testing/fstest`.
+- Graceful HTTP shutdown: `srv.Shutdown()` does NOT interrupt active connections; on deadline, fall back to `srv.Close()` to force-close and cancel handler contexts.
+- Signal handling belongs in `main` via `signal.NotifyContext(SIGINT, SIGTERM)`; packages take a `ctx` and never wire signals themselves.
+- Config validation aggregates errors via `errors.Join` so operators see every problem at once.
+- Logger: `internal/log.New(w, debug)` (JSON slog); `internal/log.Discard()` for tests (uses `slog.DiscardHandler`, Go ≥ 1.24).
+- Empty future packages carry a `doc.go` stub whose package comment references the bd issue that will fill it in.
+- Integration tests under `cmd/broker/*_integration_test.go` build the binary once in `TestMain` and exercise it as a subprocess.
+- Tests use `t.Context()` (Go 1.24+) and `t.TempDir()` throughout — no `context.Background()` or manual cleanup.
+- `bd link A B` means "A depends on B" (B blocks A). `bd create --deps "blocks:id"` reverses this and is usually wrong — prefer bare `--deps "id"`.
+- `bd init` auto-commits its scaffolding; a follow-up `git commit` for the same files will be a no-op.
+- `fj` outside a cloned repo needs `-H kode.naiv.no` to know the host.