docs: sync all documentation with post-cleanup state

Author: mariuspruvot

CLAUDE.md

@@ -15,13 +15,13 @@ Monorepo with two apps, skills, and shared infra. See [ADR-001](docs/adr-001-cla
 apps/api/          — FastAPI backend (Python 3.12, uv)
   src/helprs/
     core/          — config, database, dependencies, exceptions, middleware, security
-    modules/       — domain modules: identity, installation, webhook, container (Phase 2)
+    modules/       — domain modules: identity, installation, webhook, container
     admin/         — SQLAdmin panel + credential management
   tests/           — mirrors modules/ structure
   alembic/         — DB migrations
 apps/web/          — React frontend (Vite, TypeScript)
-  src/features/    — feature modules: auth, dashboard, installation, session
-  src/shared/      — shared components/utils
+  src/features/    — feature modules: auth, landing, installation, session
+  src/shared/      — API client (shared/api/client.ts)
 skills/            — Claude Code skill definitions (mounted into ephemeral containers)
 infra/
   docker/          — Dockerfiles (api, web, claude-runner)
@@ -57,8 +57,6 @@ Skills are pluggable Claude Code agent definitions in `skills/`. See `skills/SKI
 | Skill | Purpose | PR fetch strategy |
 |-------|---------|-------------------|
 | `challenge-me` | Socratic quiz on PR changes | Shallow clone |
-| `code-review` | Multi-layer adversarial review | Shallow clone |
-| `security-audit` | Vulnerability scan on diff | Diff only |
 
 ## Code Style
 

PROJECT-STATUS.md

@@ -57,8 +57,6 @@ sequenceDiagram
 | **webhook** | `apps/api/src/helprs/modules/webhook/` | Webhook signature verification, event dispatch, persistent event storage, crash-recovery replay, periodic reaper |
 | **container** | `apps/api/src/helprs/modules/container/` | Container session CRUD, Docker lifecycle (create/start/stop/remove), SSE log streaming, TTL-based cleanup |
 | **admin** | `apps/api/src/helprs/admin/` | SQLAdmin panel at `/admin` for credential management |
-| **comprehension** | `apps/api/src/helprs/modules/comprehension/` | Pre-pivot DDD module (empty -- only `__pycache__` remains) |
-| **billing** | `apps/api/src/helprs/modules/billing/` | Removed per open-source pivot (empty -- only `__pycache__` remains) |
 
 ### Frontend features
 
@@ -67,8 +65,8 @@ sequenceDiagram
 | **auth** | `apps/web/src/features/auth/` | OAuth callback handler, protected route wrapper, Zustand auth store |
 | **landing** | `apps/web/src/features/landing/` | Landing page with GitHub App install CTA |
 | **installation** | `apps/web/src/features/installation/` | Post-install setup flow (SetupView) and settings management (SettingsView) |
-| **session** | `apps/web/src/features/session/` | Skill selection UI (SkillSelector), container session management (ContainerSession), terminal output renderer (TerminalOutput), plus pre-pivot components (ChatPanel, ChatView, ScoreCard, etc.) |
-| **shared** | `apps/web/src/shared/` | SSE parser hook (`useSSE`), reduced-motion hook, viewport hook, theme tokens |
+| **session** | `apps/web/src/features/session/` | Skill selection UI (SkillSelector), container session management (ContainerSession), terminal output renderer (TerminalOutput) |
+| **shared** | `apps/web/src/shared/` | API client with auth token management |
 
 ### Skills system
 
@@ -91,7 +89,7 @@ Skills are mounted read-only into ephemeral containers via Docker volume binds.
 
 ## 3. What's Built
 
-### Backend (35 source files, 25 test files)
+### Backend (25 source files, 25 test files)
 
 **Core infrastructure** -- stable, tested:
 - App factory with async lifespan managing DB engine (`apps/api/src/helprs/main.py`)
@@ -113,17 +111,17 @@ Skills are mounted read-only into ephemeral containers via Docker volume binds.
 - BYOK credential storage (Fernet-encrypted Anthropic API keys)
 - Installation access token minting via GitHub API
 - PR comment posting with retry logic
-- 4 test files (router, service, BYOK router, BYOK service, suppression service)
+- 5 test files (router, service, BYOK router, BYOK service, suppression service)
 
 **Webhook module** -- stable, tested:
 - HMAC-SHA256 signature verification
 - Event dispatcher routing by event type + action
 - Persistent webhook event storage for crash recovery
 - Replay system: boot-time replay + periodic reaper (5-minute interval)
 - PR opened handler: creates container session + posts PR comment with session link
-- 5 test files (dispatcher, handlers, repository, replay, router, verification)
+- 6 test files (dispatcher, handlers, repository, replay, router, verification)
 
-**Container module** -- new, tested (no real Docker integration yet):
+**Container module** -- tested (no real Docker integration yet):
 - `ContainerSession` ORM model with status enum (pending/running/completed/failed/timeout)
 - `DockerClient` protocol + `AioDockerClient` production implementation (aiodocker)
 - Session CRUD: create, get, get-or-404
@@ -133,13 +131,9 @@ Skills are mounted read-only into ephemeral containers via Docker volume binds.
 - Resource limits: 512MB memory, 1 CPU, 15-minute TTL
 - 3 test files + 1 integration test (service, router, models, container flow)
 
-**Alembic migrations** -- 10 migration files:
-- `github_users`, `installations`, `webhook_events`, `sessions`
-- `byok_configs`, `suppression` (installation settings)
-- `questions`, `answers`, `scores`, `reports_and_feedback` (pre-pivot, may need cleanup)
-- `container_sessions` (new)
+**Alembic migrations** -- 10 migration files covering all tables. Note: 5 pre-pivot comprehension migrations remain in history (sessions, questions, answers, scores, reports_and_feedback) -- the backend code is removed but migration files are retained for history.
 
-### Frontend (42 source files, 23 test files)
+### Frontend (14 source files, 6 test files)
 
 **Auth flow** -- stable:
 - `OAuthCallback.tsx` -- handles GitHub OAuth redirect, exchanges code for token
@@ -154,31 +148,16 @@ Skills are mounted read-only into ephemeral containers via Docker volume binds.
 - `SetupView.tsx` -- post-install configuration wizard
 - `SettingsView.tsx` -- installation settings management
 
-**Session flow** -- new container components + pre-pivot comprehension components:
-
-New (container-based):
+**Session flow** -- container-based:
 - `SkillSelector.tsx` -- displays available skills as cards (challenge-me, code-review, security-audit), 1 test
 - `ContainerSession.tsx` -- manages container lifecycle (create session, connect SSE, display output, stop), 1 test
-- `TerminalOutput.tsx` -- terminal-like renderer with macOS-style window chrome, auto-scroll, amber accent, 1 test
+- `TerminalOutput.tsx` -- terminal-like renderer with macOS-style window chrome, auto-scroll, 1 test
 - `containerApi.ts` -- API client for container endpoints
 - `containerTypes.ts` -- TypeScript types for container sessions
 - `SessionView.tsx` -- route component orchestrating SkillSelector and ContainerSession
 
-Pre-pivot (still in tree, partially orphaned):
-- `ChatPanel.tsx`, `ChatView.tsx`, `ChatMessage.tsx` -- interactive Q&A session UI (pre-pivot comprehension flow)
-- `ScoreCard.tsx`, `SessionFeedback.tsx`, `ReportButton.tsx` -- scoring and feedback components
-- `DiffViewer.tsx`, `CodeLink.tsx` -- code diff rendering
-- `AnswerInput.tsx`, `SessionHeader.tsx` -- session interaction components
-- `SplitLayout.tsx`, `MobileLayout.tsx`, `TabbedLayout.tsx` -- layout components
-- `store.ts`, `useSession.ts`, `types.ts` -- session state management
-- 17 test files for pre-pivot components
-
-**Shared** -- stable:
-- `useSSE.ts` -- SSE connection hook with reconnection logic, 1 test
-- `parseSSE.ts` -- SSE event parser, 1 test
-- `useReducedMotion.ts` -- accessibility hook for reduced motion preference
-- `useViewport.ts` -- responsive viewport hook
-- `tokens.ts` -- design system theme tokens
+**Shared**:
+- `api/client.ts` -- fetch wrapper with auth header injection, 401 retry, re-auth redirect
 
 **Routing** (`app.tsx`):
 - `/` -- Landing page
@@ -239,14 +218,11 @@ Pre-pivot (still in tree, partially orphaned):
 ### Frontend integration
 
 - **Frontend calls the right endpoints but hasn't been tested against a running backend.** The `containerApi.ts` client, `ContainerSession.tsx` SSE connection, and `TerminalOutput.tsx` renderer are built but only unit-tested with mocks.
-- **No dashboard page exists.** The app routes from landing -> install -> settings -> session, but there's no `/dashboard` showing all installations and their sessions. (Referenced in project memory as a known gap.)
+- **No dashboard page exists.** The app routes from landing -> install -> settings -> session, but there's no `/dashboard` showing all installations and their sessions.
 
-### Cleanup needed
+### Package cleanup
 
-- **Pre-pivot comprehension components**: 15+ files in `apps/web/src/features/session/` (ChatPanel, ChatView, ChatMessage, ScoreCard, DiffViewer, AnswerInput, SessionHeader, etc.) with 17 test files are from the pre-pivot interactive Q&A approach. They are not used by the new container-based flow but remain in the tree.
-- **Pre-pivot comprehension module**: `apps/api/src/helprs/modules/comprehension/` has empty directory structure (domain, application, infrastructure, presentation) with only `__pycache__`.
-- **Pre-pivot billing module**: `apps/api/src/helprs/modules/billing/` is empty (only `__pycache__`).
-- **Pre-pivot migrations**: `questions`, `answers`, `scores`, `reports_and_feedback` tables were created for the comprehension flow and are no longer needed by the container approach. They add schema weight without serving the current architecture.
+- `react-diff-view` and `react-resizable-panels` remain in `package.json` but are no longer used by any component. They should be removed.
 
 ---
 
@@ -268,7 +244,7 @@ Pre-pivot (still in tree, partially orphaned):
 3. **Error handling and retry logic.** Container creation failures, Docker daemon unavailability, SSE connection drops.
 4. **Logging and monitoring.** Structured logs for container lifecycle events are in place; add metrics (container count, duration, success rate) and alerting.
 5. **Rate limiting per installation.** Current rate limits are per-IP; add per-installation limits to prevent abuse.
-6. **Pre-pivot code cleanup.** Remove empty `comprehension` and `billing` modules, pre-pivot frontend components, and orphaned database migrations.
+6. **Remove unused npm packages.** `react-diff-view`, `react-resizable-panels`, `refractor`, `react-markdown`, `remark-gfm` are leftover from the pre-pivot UI and no longer imported.
 
 ### P2 -- Feature expansion
 
@@ -285,7 +261,6 @@ Pre-pivot (still in tree, partially orphaned):
 2. **Mobile responsive layout.** Terminal output and skill selection on small screens.
 3. **Documentation site.** MkDocs config exists (`mkdocs.yml`) but is not deployed.
 4. **Contributing guide for skill authors.** How to create a new skill, test it locally, submit a PR.
-5. **Accessibility.** `useReducedMotion` hook exists but is not wired to all animated components.
 
 ---
 
@@ -325,9 +300,6 @@ Pre-pivot (still in tree, partially orphaned):
 | Zustand | ^5.0.12 | State management |
 | React Query | ^5.97.0 | Server state / data fetching |
 | React Router | ^7.14.0 | Client-side routing |
-| react-markdown | 10.1.0 | Markdown rendering |
-| react-diff-view | 3.3.3 | Diff rendering (pre-pivot) |
-| react-resizable-panels | 4.9.0 | Split panel layout (pre-pivot) |
 | Vitest | ^4.1.4 | Testing |
 | Testing Library | ^16.3.2 | Component testing utilities |
 | ESLint | ^10.2.0 | Linting |

README.md

@@ -1,51 +1,55 @@
 # helPRs
 
-Socratic comprehension sessions for pull requests. helPRs helps developers deeply understand code changes by guiding them through interactive question-and-answer sessions on PRs.
+Pluggable AI skill runner for pull requests. helPRs spins up ephemeral Docker containers running Claude Code CLI to execute skills (comprehension quizzes, code reviews, security audits) against PRs and streams results back in real time.
+
+**BYOK model** -- users provide their own Claude credentials. The backend never calls the Claude API directly; containers use the credentials natively.
 
 ## Quick Start
 
 ```bash
-# Copy environment variables
-cp .env.example .env
+# Start all services (API :8000, Web :5173, Postgres :5432)
+docker compose up --build
+
+# Run tests
+make test
 
-# Start all services (api, web, db)
-make dev
+# Lint
+make lint
 ```
 
-Services:
-- **API**: http://localhost:8000 (FastAPI + OpenAPI docs at `/docs`)
-- **Web**: http://localhost:5173 (React + Vite)
-- **DB**: PostgreSQL 16 on port 5432
+## How It Works
 
-## Development
-
-```bash
-make lint    # Run ruff (backend) + eslint (frontend)
-make test    # Run pytest (backend) + vitest (frontend)
-make build   # Build production Docker images
-make migrate # Run Alembic database migrations
-```
+1. GitHub PR event hits the webhook receiver
+2. API posts a PR comment with a session link
+3. User selects a skill (or auto-trigger if configured)
+4. Backend spins up an ephemeral Docker container with Claude Code CLI
+5. Container runs the skill against the PR
+6. Results stream back via SSE passthrough to the frontend
+7. Container is destroyed after completion or timeout
 
 ## Project Structure
 
 ```
-helprs/
-├── apps/
-│   ├── api/          # FastAPI backend (Python 3.12, uv)
-│   └── web/          # React frontend (Vite, Tailwind v4)
-├── infra/
-│   ├── docker/       # Dockerfiles + nginx config
-│   └── coolify/      # Production deployment config
-├── docker-compose.yml
-├── Makefile
-└── .env.example
+apps/api/          -- FastAPI backend (Python 3.12, uv)
+apps/web/          -- React frontend (Vite, TypeScript, Tailwind 4)
+skills/            -- Claude Code skill definitions
+infra/docker/      -- Dockerfiles (api, web, claude-runner)
+infra/coolify/     -- Production docker-compose
 ```
 
 ## Tech Stack
 
-| Layer    | Technology                          |
-|----------|-------------------------------------|
-| Backend  | Python 3.12, FastAPI, SQLAlchemy 2  |
-| Frontend | React 19, Vite, Tailwind CSS v4     |
-| Database | PostgreSQL 16                       |
-| Infra    | Docker, GitHub Actions, Coolify     |
+| Layer      | Technology                                |
+|------------|-------------------------------------------|
+| Backend    | Python 3.12, FastAPI, SQLAlchemy 2, uv    |
+| Frontend   | React 19, Vite, Tailwind CSS v4, Zustand  |
+| Database   | PostgreSQL 16                             |
+| Containers | Docker, aiodocker, Claude Code CLI        |
+| Infra      | GitHub Actions, Coolify, GHCR             |
+
+## Documentation
+
+- **[PROJECT-STATUS.md](PROJECT-STATUS.md)** -- detailed status, what's built, what's not yet working, roadmap
+- **[CLAUDE.md](CLAUDE.md)** -- developer context (quick start, patterns, gotchas)
+- **[docs/](docs/)** -- architecture, data models, API contracts, component inventory
+- **[docs/adr-001-claude-code-container-pivot.md](docs/adr-001-claude-code-container-pivot.md)** -- architecture decision record for the container pivot

docs/architecture-api.md

@@ -1,6 +1,6 @@
 # Architecture -- Backend (api)
 
-> Auto-generated on 2026-04-17 (post-pivot rewrite)
+> Updated 2026-04-17 (post-cleanup)
 
 ## Executive Summary
 
@@ -15,7 +15,7 @@ FastAPI backend serving as a container orchestrator, webhook receiver, and admin
 | ORM | SQLAlchemy | >= 2.0.36 | Async ORM (asyncpg driver) |
 | Migrations | Alembic | >= 1.14 | Schema migrations |
 | Settings | Pydantic Settings | >= 2.7 | Typed env var config |
-| Container | Docker SDK | TBD | Ephemeral container lifecycle |
+| Container | aiodocker | >= 0.23 | Async Docker client for ephemeral container lifecycle |
 | Logging | structlog | >= 24.4 | Structured logging |
 | Monitoring | Sentry SDK | >= 2.19 | Error tracking |
 | Rate Limiting | SlowAPI | >= 0.1.9 | Per-IP rate limiting |
@@ -26,8 +26,6 @@ FastAPI backend serving as a container orchestrator, webhook receiver, and admin
 | Testing | pytest + pytest-asyncio | >= 8.3 | Test framework |
 | Linting | ruff | >= 0.8 | Linter + formatter |
 
-**Removed:** pydantic-ai (no longer needed -- AI runs in containers)
-
 ## Architecture Pattern
 
 ```
@@ -50,14 +48,16 @@ FastAPI backend serving as a container orchestrator, webhook receiver, and admin
          |   +-- middleware.py     CORS, timing
          |   +-- security.py      JWT, Fernet, HMAC
          |
-         +-- modules/
-             +-- identity/       (Flat: router -> service -> model)
-             +-- installation/   (Flat: router -> service -> model)
-             +-- webhook/        (Flat: router -> dispatcher -> handlers -> model)
-             +-- container/      (NEW: container orchestration + result relay)
+         +-- modules/        (All flat pattern)
+             +-- identity/       (router -> service -> model)
+             +-- installation/   (router -> service -> model)
+             +-- webhook/        (router -> dispatcher -> handlers -> model)
+             +-- container/      (router -> service -> model)
 ```
 
-### Flat Modules (identity, installation, webhook)
+### Flat Module Pattern
+
+All four modules use the same structure:
 
 ```
 module/
@@ -67,20 +67,9 @@ module/
 +-- schemas.py   # Pydantic request/response schemas
 ```
 
-### Container Module (new)
-
-```
-container/               # Coming in Phase 2
-+-- router.py            # Container session endpoints + SSE relay
-+-- service.py           # Container lifecycle (provision, inject creds, destroy)
-+-- orchestrator.py      # Docker SDK integration (create, start, stream, remove)
-+-- models.py            # ContainerSession SQLAlchemy model
-+-- schemas.py           # Request/response schemas
-```
-
-**Removed:** `comprehension/` DDD module (domain/, application/, infrastructure/, presentation/) and `billing/` stub.
+The webhook module adds `dispatcher.py`, `handlers.py`, `verification.py`, `tasks.py`, and `repository.py` for its event processing pipeline.
 
-## Backend Role (Post-Pivot)
+## Backend Role
 
 The backend is a **thin orchestrator**, not an AI host:
 
@@ -120,5 +109,5 @@ The backend is a **thin orchestrator**, not an AI host:
 1. **No AI in the backend**: all AI logic runs inside ephemeral containers
 2. **BYOK model**: each installation provides their own Claude credentials
 3. **SSE passthrough**: backend relays container output, does not generate AI responses
-4. **Flat modules only**: removed DDD layer -- all modules use the simple flat pattern
+4. **Flat modules only**: all modules use the simple flat pattern (router/service/models/schemas)
 5. **Background webhook processing**: raw events persisted first, dispatched async with retry