docs: consolidate and prune stale documentation

Remove docs that describe removed code or abandoned deployment targets,
consolidate the four architecture docs into a single architecture.md,
regenerate the frontend component inventory from the current tree, and
bring API contracts + data models back in sync with the code.

- Drop 8 stale docs (AWS ECS guide, architecture-api/web/infra
  projections, source-tree-analysis, integration-architecture,
  project-overview, old component-inventory-web).
- Rewrite docs/architecture.md as the single human-facing source of
  truth (CLAUDE.md stays the agent-facing one).
- Regenerate component-inventory-web.md from apps/web/src/ (adds the
  dashboard feature, removes dangling landing/ references).
- Rewrite api-contracts-api.md with all current routes, including
  /auth/me/stats, installation session listing, post-results toggle,
  and the full /containers/sessions/* surface.
- Update data-models-api.md: add Installation.post_results_to_pr,
  the session_events table, the ContainerSession scorecard/xp_earned
  columns, and the missing Pydantic schemas.
- Align .env.example with what the compose files actually need
  (VITE_GITHUB_APP_SLUG, DOCKER_GID, POSTGRES_PASSWORD).
- Clean up development-guide.md, deployment-guide.md, self-hosting.md,
  CONTRIBUTING.md, and docs/index.md (drop FRONTEND_URL, AWS ECS
  references, "Coming in Phase 2" placeholders; add the new docs/backlog.md
  to the index).

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

Author: mariuspruvot

.env.example

@@ -52,6 +52,10 @@ SENTRY_DSN=
 # API URL as seen by the frontend (Vite build-time variable)
 VITE_API_URL=http://localhost:8000
 
+# GitHub App slug (from the GitHub App settings URL, e.g. "helprs-dev").
+# Build-time Vite variable used by the frontend to build the "Install app" link.
+VITE_GITHUB_APP_SLUG=
+
 # Public URL of the frontend (used by the backend to build links in PR comments)
 APP_BASE_URL=http://localhost:5173
 
@@ -75,9 +79,16 @@ UVICORN_WORKERS=4
 # Absolute path to skills/ directory on the Docker host.
 # Required for Docker-in-Docker volume mounts (the API container mounts this
 # path into claude-runner containers). Must be an absolute path on the HOST,
-# not inside the container.
+# not inside the container. In local dev, docker-compose.yml defaults this to
+# ${PWD}/skills; only set it explicitly in production.
 # SKILLS_HOST_PATH=/absolute/path/to/helprs/skills
 
+# GID of the `docker` group on the host. The API container joins this group
+# so it can talk to the mounted Docker socket. Defaults to 994 if unset.
+# Find it with: getent group docker | cut -d: -f3
+# DOCKER_GID=994
+
 # --- Postgres (production compose only) -------------------------------------
-# Only used by infra/coolify/docker-compose.prod.yml
-# POSTGRES_PASSWORD=
+# Only used by infra/coolify/docker-compose.prod.yml (required there).
+# The dev docker-compose.yml hardcodes the dev password.
+POSTGRES_PASSWORD=

CONTRIBUTING.md

@@ -20,21 +20,19 @@ cd helprs
 cp .env.example .env
 # Fill in .env (at minimum: SECRET_KEY, FERNET_KEY, GitHub App credentials)
 
-# Start all services
+# Start all services (also builds the claude-runner image as a build-only service)
 docker compose up --build      # API :8000, Web :5173, Postgres :5432
 
-# Build the claude-runner image (needed for running skills)
-make build-runner
-
 # Create test database (once)
 docker exec helprs-db-1 psql -U helprs -c "CREATE DATABASE helprs_test;"
 ```
 
 ### Running checks
 
 ```bash
-make lint     # Ruff check + format (API), ESLint (Web)
-make test     # pytest (API), vitest (Web)
+make lint        # ruff check + format + mypy (non-strict) + eslint
+make typecheck   # mypy only (shortcut for API type-checking)
+make test        # pytest (API) + vitest (Web)
 ```
 
 Or run backend/frontend checks individually:
@@ -44,6 +42,7 @@ Or run backend/frontend checks individually:
 cd apps/api
 uv run ruff check src/ tests/
 uv run ruff format --check src/ tests/
+uv run mypy src/
 uv run pytest
 uv run pytest tests/modules/identity/     # Single module
 

docs/api-contracts-api.md

@@ -1,133 +1,215 @@
-# API Contracts -- Backend
+# API Contracts
 
-> Auto-generated on 2026-04-17 (post-pivot rewrite)
+REST reference for the helPRs API. All endpoints under `/api/v1/*` require auth unless noted. Pydantic schemas are defined in `apps/api/src/helprs/modules/*/schemas.py`; see [data-models-api.md](data-models-api.md) for the field details.
 
-## Overview
+**Conventions**
 
-- Base prefix: `/api/v1`
-- Auth mechanism: JWT Bearer tokens (HS256). Access tokens (15 min) issued after GitHub OAuth. Refresh tokens (7 days) stored as httpOnly cookies.
-- Rate limiting: SlowAPI (per-IP via `get_remote_address`)
-- Error format: `{"error": "<error_code>", "message": "<text>", "detail": <any>}`
-- Webhook auth: HMAC SHA-256 signature verification via `X-Hub-Signature-256` header
+- Base path: `/api/v1`
+- Unauthenticated endpoints return `401 Unauthorized` when a bearer token is missing or invalid. Installation/session access failures return `403 Forbidden`.
+- Rate limiting is applied per route (via `slowapi`). Limits are shown inline below.
+- `{installation_id}` in paths is the **GitHub installation ID** (integer), not the internal UUID.
+- Session IDs are UUIDs.
 
-## Route Groups
+## Health
 
-### Health -- /health
+### `GET /health`
 
-| Method | Path | Auth | Rate Limit | Description |
-|--------|------|------|------------|-------------|
-| GET | `/health` | None | None | Health check |
+Unauthenticated liveness probe that also checks DB reachability.
 
-#### GET /health
+- **200** `{"status": "ok", "db": "ok"}` — API + DB healthy.
+- **503** `{"status": "degraded", "db": "unreachable"}` — API up, DB unreachable.
 
-- Response: `{"status": "ok"}`
-- Notes: Mounted directly on the app, not under `/api/v1`
+## Auth — `/api/v1/auth/*`
 
----
+### `GET /auth/github`
 
-### Auth -- /api/v1/auth
+Redirects to GitHub OAuth (`github.com/login/oauth/authorize`). Sets an httpOnly `oauth_state` cookie for CSRF (10 min TTL). Scopes requested: `read:user user:email read:org`.
 
-| Method | Path | Auth | Rate Limit | Description |
-|--------|------|------|------------|-------------|
-| GET | `/api/v1/auth/github` | None | 10/min | Redirect to GitHub OAuth |
-| GET | `/api/v1/auth/github/callback` | None | 10/min | Handle OAuth callback |
-| POST | `/api/v1/auth/refresh` | Refresh cookie | 10/min | Refresh access token |
-| GET | `/api/v1/auth/me` | Bearer JWT | 30/min | Get current user |
-| POST | `/api/v1/auth/logout` | None | None | Clear refresh cookie |
+- **302** redirect to GitHub.
+- Rate limit: 10/min.
 
-#### GET /api/v1/auth/github
+### `GET /auth/github/callback`
 
-- Response: 302 redirect to `https://github.com/login/oauth/authorize`
-- Sets `oauth_state` cookie (httpOnly, samesite=lax, 600s max-age)
+Handles two entry flows: OAuth login (with `state`) and GitHub App install (with `installation_id` + `setup_action`, no `state`).
 
-#### GET /api/v1/auth/github/callback
+Query params: `code` (required), `state` (OAuth flow), `installation_id` + `setup_action` (install flow).
 
-- Query params: `code` (required), `state` (required)
-- Response: 302 redirect to `{frontend_url}/auth/callback?access_token={jwt}`
-- Sets `refresh_token` cookie (httpOnly, 7-day max-age)
+On success: creates/updates the user, issues an access token, sets an httpOnly `refresh_token` cookie (7 days), and redirects to `{APP_BASE_URL}/auth/callback?access_token=...`.
 
-#### POST /api/v1/auth/refresh
+- **302** redirect on success.
+- **401** on missing/invalid `state`.
+- Rate limit: 10/min.
 
-- Auth: `refresh_token` httpOnly cookie
-- Response: `TokenResponse { access_token, token_type }`
+### `POST /auth/refresh`
 
-#### GET /api/v1/auth/me
+Rotates the access token using the `refresh_token` httpOnly cookie. Writes a new `refresh_token` cookie on the response.
 
-- Auth: Bearer JWT
-- Response: `UserResponse { id, github_id, github_login, email, avatar_url, created_at }`
+- **200** `TokenResponse { access_token, token_type: "bearer" }`.
+- **401** if the refresh cookie is missing or invalid.
+- Rate limit: 10/min.
 
-#### POST /api/v1/auth/logout
+### `GET /auth/me`
 
-- Response: `{"status": "ok"}`
-- Deletes `refresh_token` cookie
+Requires auth. Returns the authenticated user.
 
----
+- **200** `UserResponse`.
+- Rate limit: 30/min.
 
-### Installations -- /api/v1/installations
+### `GET /auth/me/stats`
 
-| Method | Path | Auth | Rate Limit | Description |
-|--------|------|------|------------|-------------|
-| GET | `/api/v1/installations` | Bearer JWT | 30/min | List accessible installations |
-| GET | `/api/v1/installations/{installation_id}` | Bearer JWT | 30/min | Get installation detail |
-| POST | `/api/v1/installations/{installation_id}/byok` | Bearer JWT | 10/min | Configure credentials |
-| DELETE | `/api/v1/installations/{installation_id}/byok` | Bearer JWT | 10/min | Remove credentials |
-| PUT | `/api/v1/installations/{installation_id}/suppression-labels` | Bearer JWT | 10/min | Update suppression labels |
+Requires auth. Returns aggregated session statistics for the user.
 
-**Path params:** `installation_id` is the **GitHub installation ID** (integer), not the internal UUID.
+- **200** `UserStatsResponse { daily_counts: [...], totals: {...} }`.
+- Rate limit: 30/min.
 
-#### GET /api/v1/installations
+### `POST /auth/logout`
 
-- Response: `InstallationListResponse { items: InstallationResponse[], total: int }`
+Clears the `refresh_token` cookie.
 
-#### POST /api/v1/installations/{installation_id}/byok
+- **200** `{"status": "ok"}`.
 
-- Request: `BYOKConfigureRequest { api_key: str }` -- Claude credentials, min 20 chars
-- Response: `BYOKConfigResponse { key_hint, key_status, validated_at }`
-- Notes: Key is Fernet-encrypted at rest.
+## Installations — `/api/v1/installations/*`
 
-#### DELETE /api/v1/installations/{installation_id}/byok
+All endpoints require auth. Admin endpoints additionally call `verify_admin_permission`.
 
-- Response: 204 No Content
+### `GET /installations`
 
-#### PUT /api/v1/installations/{installation_id}/suppression-labels
+List installations the user has access to (owns, or org member).
 
-- Request: `SuppressionLabelsRequest { labels: list[str] }` -- max 20 items
-- Response: `SuppressionLabelsResponse { labels: list[str] }`
+- **200** `InstallationListResponse { items: InstallationResponse[], total }`. Each item includes `session_count`, BYOK status, suppression labels, and `post_results_to_pr`.
+- Rate limit: 30/min.
 
----
+### `GET /installations/{installation_id}`
 
-### Webhooks -- /api/v1/webhooks
+Installation detail — requires admin permission on the installation.
 
-| Method | Path | Auth | Rate Limit | Description |
-|--------|------|------|------------|-------------|
-| POST | `/api/v1/webhooks/github` | HMAC SHA-256 | 100/min | Receive GitHub webhooks |
+- **200** `InstallationDetailResponse`.
+- **404** if unknown.
+- Rate limit: 30/min.
 
-#### POST /api/v1/webhooks/github
+### `POST /installations/{installation_id}/byok`
 
-- Auth: `X-Hub-Signature-256` header
-- Response: `{"status": "ok", "duplicate": false}`
-- Handled events: `installation.*`, `pull_request.opened`, `pull_request.synchronize`
+Configure the BYOK Claude credential. Accepts API keys (`sk-ant-api03-...`) and OAuth tokens (`sk-ant-oat...`). OAuth tokens skip server-side validation.
 
----
+- Request: `BYOKConfigureRequest { api_key }`.
+- **200** `BYOKConfigResponse`.
+- **404** if installation unknown.
+- Rate limit: 10/min.
 
-### Container Sessions -- Coming in Phase 2
+### `DELETE /installations/{installation_id}/byok`
 
-Container session endpoints will be added when the container module is implemented. Expected endpoints:
+Remove the BYOK credential.
 
-| Method | Path | Auth | Description |
-|--------|------|------|-------------|
-| POST | `/api/v1/sessions/{id}/run` | Bearer JWT | Trigger skill execution in container |
-| GET | `/api/v1/sessions/{id}/stream` | Bearer JWT | SSE stream of container output |
-| GET | `/api/v1/sessions/{id}` | Bearer JWT | Get session status + results |
+- **204** No Content.
+- **404** if installation unknown.
+- Rate limit: 10/min.
 
-Exact schemas TBD.
+### `PUT /installations/{installation_id}/suppression-labels`
 
----
+Update the list of PR labels that cause helPRs to skip session creation.
 
-### Admin -- /admin
+- Request: `SuppressionLabelsRequest { labels: string[] }`.
+- **200** `SuppressionLabelsResponse { labels }`.
+- Rate limit: 10/min.
 
-- SQLAdmin panel at `/admin`
-- Auth: session-based. Development mode accepts any login. Production requires `ADMIN_PASSWORD` env var.
-- Full CRUD for: GitHubUser, Installation, BYOKConfig
-- Read-only views for: WebhookEvent
-- Sensitive fields excluded: `github_access_token_enc`, `encrypted_api_key`
+### `GET /installations/{installation_id}/sessions`
+
+Paginated session history for an installation.
+
+- Query params: `page` (default 1), `per_page` (default 20, max 100), `status` (optional filter).
+- **200** `PaginatedSessionsResponse { items, total, page, per_page, total_pages }`.
+- Rate limit: 30/min.
+
+### `PUT /installations/{installation_id}/post-results`
+
+Enable or disable automatic posting of challenge-me score cards to PRs.
+
+- Request: `PostResultsSettingRequest { post_results_to_pr: boolean }`.
+- **200** `PostResultsSettingResponse { post_results_to_pr }`.
+- Rate limit: 10/min.
+
+## Webhooks — `/api/v1/webhooks/*`
+
+### `POST /webhooks/github`
+
+Unauthenticated but HMAC-verified via the `X-Hub-Signature-256` header (shared secret `GITHUB_WEBHOOK_SECRET`). Required header: `X-GitHub-Delivery`.
+
+Flow: verify HMAC → persist raw event → return 200 → dispatch processing as a background task. Duplicate deliveries (same `X-GitHub-Delivery`) are idempotent.
+
+- **200** `{"status": "ok", "duplicate": false|true}`.
+- **400** on missing `X-GitHub-Delivery`, invalid JSON, or HMAC failure.
+- Handled events: `installation.*`, `pull_request.opened`, `pull_request.synchronize`. Other events are logged and ignored (still stored for audit).
+- Rate limit: 100/min.
+
+## Container sessions — `/api/v1/containers/*`
+
+All endpoints require auth. Installation access is checked at session creation; session-level access (`verify_session_access`) is checked on all other routes.
+
+### `POST /containers/sessions`
+
+Create a session record and start a Claude runner container for a given PR + skill.
+
+- Request: `CreateSessionRequest { installation_id, pr_number, repo_full_name: "owner/repo", skill_name }`.
+- **201** `ContainerSessionResponse`.
+- **404** if the installation is unknown or has no BYOK configured.
+- Rate limit: 10/min.
+
+### `GET /containers/sessions/{session_id}`
+
+Current session status and metadata.
+
+- **200** `ContainerSessionResponse`.
+- Rate limit: 30/min.
+
+### `GET /containers/sessions/{session_id}/stream`
+
+SSE stream of live container output (while `status = RUNNING`).
+
+- Query param: `offset` (default 0) — number of events to skip, for client-side resume. Also read from `Last-Event-ID` header (set automatically by `EventSource` on reconnect).
+- **200** `text/event-stream`. Headers: `Cache-Control: no-cache`, `X-Accel-Buffering: no`.
+- **404** if the container is not running.
+- Each event is a line-delimited SSE message carrying a stream-json object. On stream end, a final `event: done` carries `{"message": "...", "status": "completed" | "failed"}`.
+- Rate limit: 60/min.
+
+### `GET /containers/sessions/{session_id}/events`
+
+Persisted stream-json events (JSONB) for replay without SSE. Suitable for rendering completed sessions.
+
+- **200** `SessionEventsListResponse { session_id, events: SessionEventResponse[], total }`, ordered by `event_id`.
+- Rate limit: 30/min.
+
+### `GET /containers/sessions/{session_id}/scorecard`
+
+Parsed score card for a completed session (currently only emitted by the `challenge-me` skill).
+
+- **200** `ScorecardResponse { session_id, scorecard, xp_earned }`. `scorecard` is `null` if none was extracted.
+- Rate limit: 30/min.
+
+### `POST /containers/sessions/{session_id}/message`
+
+Send a follow-up message to a running container. Delivered to the container's Claude CLI stdin via a FIFO (`docker exec`).
+
+- Request: `SendMessageRequest { content }`.
+- **200** `SendMessageResponse { session_id, status: "sent", message }`.
+- Rate limit: 30/min.
+
+### `POST /containers/sessions/{session_id}/stop`
+
+Stop a running container (graceful SIGTERM then kill). Marks the session as `COMPLETED` or `FAILED`.
+
+- **200** `StopSessionResponse { id, status, message }`.
+- Rate limit: 10/min.
+
+### `DELETE /containers/sessions/{session_id}`
+
+Delete a session and its persisted events.
+
+- **200** `{"status": "deleted", "id": "..."}`.
+- Rate limit: 10/min.
+
+## Admin — `/admin`
+
+SQLAdmin panel mounted at `/admin`. Not part of the REST contract; see `admin/views.py` for the exposed models. Credentials:
+
+- **Development**: any password (auto-auth).
+- **Production**: the `ADMIN_PASSWORD` env var.