Add CLAUDE.md with library overview, packages, and design decisions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,96 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MCDSL (Metacircular Dynamics Standard Library) is the shared Go library for the Metacircular platform. It extracts common patterns from production services into reusable, tested packages. MCDSL is not a deployed service — it is imported by other services.
+
+**Module path:** `git.wntrmute.dev/kyle/mcdsl`
+
+## Build Commands
+
+```bash
+make all          # vet -> lint -> test -> build
+make build        # go build ./...
+make test         # go test ./...
+make vet          # go vet ./...
+make lint         # golangci-lint run ./...
+make clean        # go clean ./...
+```
+
+Run a single test:
+```bash
+go test ./auth/ -run TestCacheExpiry
+```
+
+## Packages
+
+| Package | Purpose |
+|---------|---------|
+| `auth` | MCIAS token validation with 30s SHA-256 cache |
+| `db` | SQLite setup (WAL, foreign keys, busy timeout), migration runner, VACUUM INTO snapshots |
+| `config` | TOML loading with env var overrides, Base config struct with standard sections |
+| `httpserver` | TLS 1.3 HTTP server with chi, logging middleware, JSON helpers, graceful shutdown |
+| `grpcserver` | gRPC server with TLS, auth/admin interceptors, default-deny for unmapped methods |
+| `csrf` | HMAC-SHA256 double-submit cookie CSRF protection |
+| `web` | Session cookies, auth middleware, template rendering for htmx UIs |
+| `health` | REST and gRPC health check handlers |
+| `archive` | tar.zst snapshots with SQLite-aware backup (VACUUM INTO) |
+
+## Import Pattern
+
+Services import individual packages with aliased imports:
+
+```go
+import (
+    mcdslauth   "git.wntrmute.dev/kyle/mcdsl/auth"
+    mcdsldb     "git.wntrmute.dev/kyle/mcdsl/db"
+    mcdslconfig "git.wntrmute.dev/kyle/mcdsl/config"
+    "git.wntrmute.dev/kyle/mcdsl/httpserver"
+    "git.wntrmute.dev/kyle/mcdsl/grpcserver"
+)
+```
+
+## Inter-Package Dependencies
+
+```
+archive --> db
+auth --> (mcias client library)
+config --> auth (for auth.Config type)
+csrf --> (stdlib only)
+db --> (modernc.org/sqlite)
+grpcserver --> auth, config
+health --> db
+httpserver --> config
+web --> auth, csrf
+```
+
+No circular dependencies. Each package can be imported independently except where noted.
+
+## Key Design Decisions
+
+- **No global state, no init().** Explicit construction, explicit errors.
+- **Stdlib-compatible types.** Functions accept and return `*sql.DB`, `http.Handler`, `*slog.Logger`, `context.Context` — not custom wrappers.
+- **TLS 1.3 minimum is non-configurable.** `httpserver` and `grpcserver` enforce this unconditionally.
+- **Default-deny for unmapped gRPC methods.** A method not in the MethodMap is rejected, not allowed. This is the most important safety property.
+- **Cookie security flags are non-configurable.** Session cookies are always `HttpOnly`, `Secure`, `SameSite=Strict`.
+- **Extract, don't invent.** Every package comes from patterns proven across multiple services. No speculative abstractions.
+- **Optional composition.** Services import only the packages they need.
+
+## Critical Rules
+
+- No CGo — all builds use `CGO_ENABLED=0`, SQLite via `modernc.org/sqlite`
+- Testing uses stdlib `testing` only, real SQLite in `t.TempDir()`, no mocks for databases
+- Token cache keys are SHA-256 of the raw token (never use raw token as map key)
+- CSRF secrets must come from `crypto/rand`, unique per service instance
+- Database file permissions are always `0600`
+- Verify changes with `go build ./...` and `go test ./...` before claiming resolution
+
+## Key Documents
+
+- `ARCHITECTURE.md` — Full library specification with all package APIs
+- `README.md` — Usage examples and quick start
+- `PROJECT_PLAN.md` — Implementation phases
+- `PROGRESS.md` — Development status
+- `../engineering-standards.md` — Platform-wide standards (authoritative reference)