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/architecture.md

@@ -5,11 +5,11 @@
 
 ## 1. Overview & Goals
 
-Headquarter is a hosted control plane where authenticated users create projects, connect Git repositories, and spawn containerized tools (RunFusion, code-server, and future tools). The platform is manifest-driven and provider-abstracted so new tools, Git providers, runtimes, and access providers can be added without rewriting core orchestration logic.
+Headquarter is a hosted control plane where authenticated users create projects, connect Git repositories, and spawn containerized tools (OpenCode, code-server, and future tools). The platform is manifest-driven and provider-abstracted so new tools, Git providers, runtimes, and access providers can be added without rewriting core orchestration logic.
 
 **Product purpose:** Give individual developers and small teams a self-hosted alternative to cloud IDEs and CI dashboards by combining Git-backed project workspaces with on-demand tool containers, all routed through a unified subdomain scheme.
 
-**MVP scope:** Single-user projects, Authentik OIDC auth, Docker runtime, Traefik subdomain routing, Portainer-managed Docker Compose deployment. The MVP supports two built-in tools (RunFusion and code-server) and provides extension points for additional tools, Git providers, and runtimes.
+**MVP scope:** Single-user projects, Authentik OIDC auth, Docker runtime, Traefik subdomain routing, Portainer-managed Docker Compose deployment. The MVP supports two built-in tools (OpenCode and code-server) and provides extension points for additional tools, Git providers, and runtimes.
 
 **Non-goals (explicitly out of MVP scope):**
 - Multi-user teams or shared projects
@@ -43,7 +43,7 @@ flowchart TB
 
     subgraph Runtime
         R[Docker Compose Stack<br/>Portainer-managed]
-        TC[Tool Containers<br/>RunFusion / code-server]
+        TC[Tool Containers<br/>OpenCode / code-server]
     end
 
     U -->|HTTPS| T
@@ -81,27 +81,54 @@ flowchart TB
 - Consume the FastAPI backend via a typed API client layer
 - Handle Vite environment variables for runtime configuration
 
+**Technology Stack:**
+- React 19 + TypeScript with strict mode
+- Vite for build tooling
+- React Router v7 for client-side routing
+- TanStack Query v5 for server state management
+- Zustand for client state management (auth store)
+- Tailwind CSS v4 for styling
+- Headless UI for accessible components
+- Heroicons for iconography
+
+**Project Structure:**
+```
+ apps/web/src/
+ ├── api/           # API client and error handling
+ ├── auth/          # OIDC utilities and AuthProvider
+ ├── components/    # Reusable UI components (Header, Sidebar, RouteGuard, DashboardLayout)
+ ├── pages/         # Page components (Dashboard, Projects, Tools, Settings, etc.)
+ ├── stores/        # Zustand stores (auth store)
+ ├── types/         # TypeScript type definitions matching backend schemas
+ └── router.tsx     # React Router configuration
+```
+
 **Routing:**
-- `/` — Dashboard
-- `/projects` — Project list
-- `/projects/new` — Create project
-- `/projects/:id/repositories` — Repository management
-- `/tools` — Tool registry and spawn surface
-- `/tools/spawn` — Spawn tool form
-- `/settings` — User and platform settings
-- `/access/:instanceId` — Tool access URL presentation
+- `/` — Dashboard (protected)
+- `/projects` — Project list (protected)
+- `/projects/new` — Create project (protected)
+- `/projects/:id` — Project detail (protected)
+- `/projects/:id/edit` — Edit project (protected)
+- `/repositories` — Repository management (protected)
+- `/tools` — Tool registry and spawn surface (protected)
+- `/settings` — User and platform settings (protected)
+- `/login` — Login redirect (public)
+- `/callback` — OIDC callback handler (public)
 
 **Auth state:**
-- Managed via a central auth context/provider
+- Managed via Zustand auth store (`useAuthStore`)
 - States: `loading`, `authenticated`, `unauthenticated`, `error`
-- Access token stored in **httpOnly cookie** (recommended) or secure storage; never `localStorage` for sensitive tokens
-- On 401 from API, redirect to Authentik login
+- Access token stored in `localStorage` (MVP simplification; httpOnly cookie recommended for production)
+- PKCE flow for OIDC authentication
+- On 401 from API, redirect to login
 
 **API client conventions:**
-- Base URL from `VITE_API_BASE_URL`
+- Base URL from `VITE_API_URL`
 - JSON request/response with standard HTTP status codes
-- Normalize errors into a consistent `{ message, statusCode, details? }` shape
-- Include bearer token or cookie credentials on every request
+- `ApiError` class for consistent error handling
+- Bearer token injected via `Authorization` header
+- Debug mode request/response logging
+- Typed API methods for all endpoints
 
 ### 3.2 Backend (`apps/api/`)
 
@@ -233,7 +260,7 @@ All tables use `uuid` primary keys. All models include `created_at` and `updated
 | Column | Type | Constraints | Default | Notes |
 |--------|------|-------------|---------|-------|
 | `id` | `UUID` | `PRIMARY KEY` | `uuid_generate_v4()` | |
-| `key` | `VARCHAR(100)` | `UNIQUE`, `NOT NULL`, `INDEX` | | Machine identifier (e.g., `runfusion`, `code-server`) |
+| `key` | `VARCHAR(100)` | `UNIQUE`, `NOT NULL`, `INDEX` | | Machine identifier (e.g., `opencode`, `code-server`) |
 | `name` | `VARCHAR(255)` | `NOT NULL` | | Human-readable name |
 | `version` | `VARCHAR(50)` | `NOT NULL` | `'1.0.0'` | |
 | `description` | `TEXT` | `NULLABLE` | `NULL` | |
@@ -449,7 +476,7 @@ Tools are defined by manifests that declare runtime behavior, resource needs, an
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `key` | `str` | Yes | Machine identifier (`runfusion`, `code-server`) |
+| `key` | `str` | Yes | Machine identifier (`opencode`, `code-server`) |
 | `name` | `str` | Yes | Human-readable name |
 | `version` | `str` | No | SemVer string; default `1.0.0` |
 | `description` | `str` | No | Markdown-friendly description |
@@ -730,7 +757,7 @@ Variable interpolation rules:
 
 Example:
 ```
-https://runfusion-myapp-alice.tools.example.com
+https://opencode-myapp-alice.tools.example.com
 https://code-server-myapp-alice.tools.example.com
 ```
 
@@ -780,6 +807,25 @@ Tool containers **must** attach to the external Traefik Docker network. If the n
 - **TLS is enabled by default** for all tool instances.
 - HTTP-only mode (`web` entrypoint, no TLS) is supported for local development via environment configuration.
 
+### 10.6 Auth Proxy for Tool Instances
+
+Spawned tools are protected behind the platform's authentication via Traefik forwardAuth middleware:
+
+1. **Middleware Configuration:**
+   - Traefik forwards incoming requests to `/api/v1/auth/validate`
+   - The endpoint validates the Bearer token and returns 200 for authenticated users
+   - Unauthenticated requests receive 401 and are blocked
+
+2. **Tool Configuration:**
+   - code-server built-in auth is disabled (`PASSWORD: ""`)
+   - OpenCode relies entirely on the platform auth layer
+   - Tools run on internal networks only, inaccessible directly
+
+3. **Security Model:**
+   - Only platform-authenticated users can access spawned tools
+   - Each tool instance has its own subdomain with isolated routing
+   - No shared containers between users or projects
+
 ---
 
 ## 11. Storage Layout