docs: update all documentation for OpenCode and deployment

- Update architecture.md with spawn service and auth proxy sections
- Update deployment.md with production stack details
- Update development.md with spawn workflow documentation
- Update mvp-scope.md, project-brief.md, tool-manifest-spec.md
- Update conversation-handoff.md with current status
- Replace all RunFusion references with OpenCode

docs/development.md

@@ -31,6 +31,29 @@ Copy the frontend environment example:
 cp apps/web/.env.example apps/web/.env
 ```
 
+### Frontend Authentication (OIDC)
+
+The frontend uses OpenID Connect (OIDC) with PKCE for authentication. Configure the following environment variables in `apps/web/.env`:
+
+| Variable | Description | Example |
+|----------|-------------|---------|
+| `VITE_API_URL` | Backend API base URL | `http://localhost:8000` |
+| `VITE_OIDC_ISSUER` | OIDC provider issuer URL | `https://authentik.example.com/application/o/headquarter` |
+| `VITE_OIDC_CLIENT_ID` | OIDC client ID | `headquarter-web` |
+| `VITE_OIDC_REDIRECT_URI` | Post-login redirect URL | `http://localhost:5173/callback` |
+
+**Authentication Flow:**
+1. User clicks login → redirected to OIDC provider authorize endpoint
+2. User authenticates with provider
+3. Provider redirects to `/callback` with authorization code
+4. Frontend exchanges code for access token (PKCE)
+5. Token stored in `localStorage`, user info fetched from `/api/v1/users/me`
+
+**Logout:**
+- Clears local token
+- Redirects to login page
+- User can re-authenticate via OIDC flow
+
 ## Running Locally
 
 ### Frontend only
@@ -195,3 +218,44 @@ Security rules for the package:
 - Credential models store **only** `encrypted_payload` — no plaintext `token` or `private_key` fields.
 - SSH private keys are encrypted before storage; the field uses `repr=False`.
 - Real encryption of the payload is deferred to FN-009; the current placeholder is base64-only.
+
+## Tool Spawn Workflow
+
+The platform supports spawning development tools (e.g., code-server) as Docker containers via Docker Compose.
+
+### Architecture
+
+1. **Tool Manifest** (`apps/api/app/tools/manifests/*.yml`):
+   - Defines Docker image, ports, volumes, environment variables, health checks
+   - Loaded into in-memory registry at application startup
+
+2. **Spawn Service** (`apps/api/app/services/spawn.py`):
+   - Generates Docker Compose service definitions from manifests
+   - Handles container lifecycle: spawn, stop, status polling
+   - Integrates Traefik label generation for subdomain routing
+
+3. **API Endpoints** (`apps/api/app/routers/tool_instances.py`):
+   - `POST /projects/{id}/tool-instances` — Spawn a new tool instance
+   - `POST /projects/{id}/tool-instances/{id}/stop` — Stop a running instance
+   - `POST /projects/{id}/tool-instances/{id}/start` — Restart a stopped instance
+   - `GET /projects/{id}/tool-instances/{id}/status` — Get container status
+
+4. **Frontend UI**:
+   - `/tools/spawn` — Form to select tool, project, and spawn
+   - `/projects/{id}/instances/{id}` — Instance detail with status, controls, and "Open Tool" link
+
+### Auth Proxy
+
+Spawned tools are protected behind Traefik forwardAuth middleware:
+- Traefik forwards requests to `/api/v1/auth/validate` for session validation
+- code-server built-in auth is disabled (`PASSWORD: ""`)
+- Only authenticated platform users can access spawned tools
+
+### Local Development
+
+Ensure Docker socket is accessible and the `tools` network exists:
+```bash
+docker network create tools  # One-time setup
+```
+
+Spawned containers use the `tools` network for Traefik routing.