diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..bbe2300
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,97 @@
+# AGENTS.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Conventions
+
+- Do not edit `CHANGELOG.md`. It is generated by the release pipeline; hand edits will be overwritten.
+
+## Commands
+
+```bash
+# Build
+go build ./cmd/session-manager
+
+# Lint
+golangci-lint run --build-tags=integration ./...
+golangci-lint run --fix --build-tags=integration ./...   # auto-fix
+
+# Unit + integration tests (full suite)
+make test
+
+# Unit tests only (no k3d cluster required)
+go test -count=1 -race ./...
+
+# Integration tests only (requires running k3d cluster)
+go test -v -count=1 -race -tags=integration ./integration
+
+# Single test
+go test -run TestName ./path/to/package
+
+# Code generation (OpenAPI + sqlc)
+make codegen
+# expands to:
+go generate ./...
+go tool github.com/sqlc-dev/sqlc/cmd/sqlc generate
+
+# Local k3d cluster with PostgreSQL + Valkey
+make start
+```
+
+## Architecture
+
+Session Manager is an OIDC authorization code flow service with a pluggable module system, dual REST+gRPC APIs, and multi-tenant support.
+
+### Data Flow
+
+```
+REST (:8080)              gRPC (:9091)
+/sm/auth                  Session.Check / Introspect
+/sm/callback              TrustMapping CRUD
+/sm/logout
+      |                         |
+      └──────── Session Manager (internal/session/manager.go) ──────────
+                      |                     |
+               ValKey (sessions,      PostgreSQL (trust
+               OIDC state, TTL)        mappings via sqlc)
+```
+
+`internal/business/business.go` is the main orchestrator: it starts the HTTP and gRPC servers concurrently and waits for the first error to shut down both.
+
+### Key Packages
+
+| Package | Purpose |
+|---|---|
+| `internal/session/` | Session lifecycle: login, callback, logout, token refresh |
+| `internal/grpc/` | gRPC server implementations (session, trust mapping) |
+| `internal/openapi/` | Generated REST handlers (do not edit manually) |
+| `internal/business/` | Orchestration: startup, housekeeper, DB migration |
+| `internal/config/` | Config structs (koanf-based unmarshaling) |
+
+### Session & State Storage
+
+- **Sessions and OIDC state**: ValKey (Redis-compatible), TTL-based. Implementation in `internal/session/valkey/`.
+- **Trust mappings**: PostgreSQL, accessed through sqlc-generated.
+- **In-memory cache**: `jellydator/ttlcache` used for OIDC configuration and introspection results.
+
+### Background Jobs
+
+`internal/business/housekeeper.go` runs two periodic tasks:
+- Session cleanup (configurable `triggerInterval`, default 10m)
+- Token refresh for sessions nearing expiry (`tokenRefreshTriggerInterval`, default 15m)
+
+### CLI Commands
+
+The binary (`cmd/session-manager/`) exposes four Cobra subcommands: `api-server`, `housekeeper`, `migrate`, `version`.
+
+### Code Generation
+
+- `internal/openapi/` is generated from `api/session-manager.yaml` via oapi-codegen — never edit directly.
+- `trust/internal/sql/queries/` is generated by sqlc from SQL migrations — never edit directly.
+- Mock files are generated and excluded from linting.
+
+### Testing Conventions
+
+- Integration tests live in `integration/` and require `//go:build integration` tag.
+- `internal/dbtest/` provides test helpers for database-backed tests.
+- Import tests (e.g. `internal/grpc/import_test.go`) verify module wiring without full server startup.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md