docs(openspec): add OpenSpec changes for FN-005, FN-006, FN-008, FN-009, FN-010

- Add frontend-foundation change (FN-005) with 46 tasks - Add deployment-config change (FN-006) with 27 tasks - Add runfusion-poc/opencode-poc change (FN-008) with 25 tasks - Add config-secrets change (FN-009) with 31 tasks - Add codeserver-spawn change (FN-010) with 38 tasks - Include project specsheet and configuration - Archive completed deployment-config change
2026-05-14 17:35:20 +02:00
parent 1539a67883
commit 78aaddb2b5
41 changed files with 1585 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14
@@ -0,0 +1,67 @@
+## Context
+
+code-server is a VS Code instance running in a browser. The platform needs to spawn it as a Docker container with proper mounts, auth, and routing. This builds on the tool registry (FN-003) and deployment config (FN-006).
+
+Current state:
+- code-server manifest exists in apps/api/app/tools/manifests/code-server.yml
+- ToolInstance model exists with status field
+- No spawn orchestration logic
+- No frontend UI for spawning
+
+## Goals / Non-Goals
+
+**Goals:**
+- Spawn code-server containers via Docker Compose
+- Mount user workspace, configs, secrets, and SSH keys
+- Route via Traefik subdomain
+- Track container status (creating, running, stopped, error)
+- Provide spawn UI in frontend
+
+**Non-Goals:**
+- Support for other IDEs (deferred post-MVP)
+- Container resource limits (CPU/memory) - basic only
+- Automatic workspace backup
+- Multi-instance load balancing
+
+## Decisions
+
+**1. Docker Compose API for container management**
+- Rationale: Higher-level than Docker SDK, handles networking and volumes declaratively
+- Alternative: Docker SDK directly - more control but more complex
+
+**2. code-server runs with platform auth proxy**
+- Rationale: Don't manage separate code-server passwords. Traefik middleware handles auth.
+- Implementation: Traefik forwardAuth to platform API for session validation
+
+**3. Workspace mounted from host directory**
+- Rationale: Persistent storage between restarts. Easy backup.
+- Path: `/data/workspaces/{user_slug}/{project_slug}`
+
+**4. SSH keys mounted as read-only volume**
+- Rationale: code-server needs Git access but shouldn't modify keys
+- Mount: `/home/coder/.ssh/` with 0400 permissions
+
+**5. Spawn is synchronous (blocking) API**
+- Rationale: Simpler UX. Container creation is fast (< 5s).
+- Alternative: Async with polling - more complex, unnecessary for MVP
+
+## Risks / Trade-offs
+
+**[Risk] Docker socket exposure is a security risk**
+→ Mitigation: Run API with limited Docker access. Consider Docker socket proxy in production.
+
+**[Risk] Container failures leave dangling resources**
+→ Mitigation: Implement cleanup on error. Periodic garbage collection of orphaned containers.
+
+**[Risk] code-server auth bypass**
+→ Mitigation: Disable code-server auth (PASSWORD: ""). Rely entirely on Traefik forwardAuth.
+
+## Migration Plan
+
+No migration. New feature.
+
+## Open Questions
+
+1. Should we pre-pull Docker images or let Compose handle it?
+2. Do we need container health checks before marking as "running"?
+3. Should spawned containers auto-stop after inactivity?
@@ -0,0 +1,31 @@
+## Why
+
+Tool registry (FN-003) and deployment config (FN-006) are prerequisites for spawning tools. code-server is the primary user-facing tool in MVP. Without a spawn flow, users cannot launch development environments, which is the core value proposition.
+
+## What Changes
+
+- **code-server manifest refinement**: Update the built-in manifest with proper Docker image, ports, volumes, and config options
+- **Spawn flow API**: Backend endpoint that creates a tool instance, generates Docker Compose service, and starts the container
+- **Frontend spawn UI**: Form for selecting tool, project, and optional config overrides
+- **Runtime integration**: Mount workspace, configs, secrets, and SSH keys into the code-server container
+- **Auth proxy**: Ensure code-server is protected behind the platform's auth (no separate code-server password)
+- **Status tracking**: Poll container status and expose it via API
+
+## Capabilities
+
+### New Capabilities
+- `tool-spawn-api`: Backend endpoint for spawning tool instances
+- `codeserver-manifest`: Refined code-server manifest with runtime configuration
+- `spawn-ui`: Frontend form for tool selection and spawn configuration
+- `container-lifecycle`: Start, stop, and status tracking for tool containers
+
+### Modified Capabilities
+- None (extends existing tool registry)
+
+## Impact
+
+- **apps/api/app/tools/manifests/code-server.yml**: Updated manifest
+- **apps/api/app/routers/tool_instances.py**: Spawn endpoint enhancements
+- **apps/api/app/services/spawn.py**: New spawn orchestration service
+- **apps/web/src/**: New spawn UI components
+- **docker-compose.yml**: May need updates for Docker socket access
@@ -0,0 +1,23 @@
+## ADDED Requirements
+
+### Requirement: code-server manifest defines runtime configuration
+The system SHALL provide a complete code-server manifest.
+
+#### Scenario: Manifest includes Docker configuration
+- **WHEN** the code-server manifest is loaded
+- **THEN** it specifies the Docker image (codercom/code-server)
+- **AND** it defines exposed ports (8080)
+- **AND** it defines volume mounts (workspace, config, ssh)
+
+#### Scenario: Manifest includes environment variables
+- **WHEN** the manifest is used for spawning
+- **THEN** it defines required environment variables
+- **AND** it defines optional config overrides
+
+### Requirement: code-server manifest is valid
+The system SHALL validate the code-server manifest against the tool manifest schema.
+
+#### Scenario: Schema validation
+- **WHEN** the manifest is loaded at startup
+- **THEN** it passes schema validation
+- **AND** any errors prevent application startup
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: Tool instance status is tracked
+The system SHALL track the lifecycle status of tool instances.
+
+#### Scenario: Status transitions
+- **WHEN** a tool instance is created
+- **THEN** its status is "creating"
+- **AND** when the container starts, status becomes "running"
+- **AND** when stopped, status becomes "stopped"
+- **AND** on error, status becomes "error"
+
+#### Scenario: Status polling
+- **WHEN** the user views a tool instance
+- **THEN** the frontend polls the status endpoint
+- **AND** updates the UI when status changes
+
+### Requirement: Tool instances can be stopped and restarted
+The system SHALL allow stopping and restarting tool instances.
+
+#### Scenario: Stop instance
+- **WHEN** the user clicks "Stop" on a running instance
+- **THEN** the system stops the Docker container
+- **AND** updates the status to "stopped"
+
+#### Scenario: Restart instance
+- **WHEN** the user clicks "Start" on a stopped instance
+- **THEN** the system starts the existing container
+- **AND** updates the status to "running"
@@ -0,0 +1,21 @@
+## ADDED Requirements
+
+### Requirement: User can spawn a tool from the UI
+The system SHALL provide a user interface for spawning tools.
+
+#### Scenario: Spawn form
+- **WHEN** the user navigates to /tools/spawn
+- **THEN** a form is displayed with tool selection
+- **AND** project selection dropdown
+- **AND** optional config override fields
+
+#### Scenario: Tool selection
+- **WHEN** the user selects a tool from the dropdown
+- **THEN** the form shows tool-specific configuration options
+- **AND** a description of the tool
+
+#### Scenario: Spawn submission
+- **WHEN** the user submits the spawn form
+- **THEN** the frontend calls POST /api/v1/tool-instances
+- **AND** displays a loading state
+- **AND** redirects to the tool instance detail page on success
@@ -0,0 +1,29 @@
+## ADDED Requirements
+
+### Requirement: API can spawn a tool instance
+The system SHALL provide an endpoint to create and start a tool instance.
+
+#### Scenario: Spawn code-server
+- **WHEN** a POST request is made to /api/v1/tool-instances with tool_id and project_id
+- **THEN** the system creates a ToolInstance record
+- **AND** generates a Docker Compose service definition
+- **AND** starts the container via Docker Compose API
+- **AND** returns the tool instance with status "creating"
+
+#### Scenario: Spawn with config overrides
+- **WHEN** a spawn request includes config overrides
+- **THEN** the overrides are merged with scope-resolved configs
+- **AND** applied to the container environment
+
+### Requirement: Spawn validates prerequisites
+The system SHALL validate prerequisites before spawning.
+
+#### Scenario: Valid project
+- **WHEN** the spawn request references a project
+- **THEN** the project must exist and belong to the user
+- **AND** the tool definition must exist in the registry
+
+#### Scenario: Duplicate spawn prevention
+- **WHEN** a spawn request is made for an already-running instance
+- **THEN** the system returns the existing instance
+- **AND** does not create a duplicate container
@@ -0,0 +1,58 @@
+## 1. Manifest Refinement
+
+- [x] 1.1 Update apps/api/app/tools/manifests/code-server.yml with complete runtime config
+- [x] 1.2 Add Docker image, ports, volumes, env vars to manifest
+- [x] 1.3 Validate manifest against ToolManifest schema
+- [x] 1.4 Test manifest loading at application startup
+
+## 2. Spawn Service
+
+- [x] 2.1 Create apps/api/app/services/spawn.py with SpawnService class
+- [x] 2.2 Implement Docker Compose service generation from manifest
+- [x] 2.3 Implement container start/stop via Docker Compose API
+- [x] 2.4 Integrate Traefik label generation (FN-006)
+- [x] 2.5 Integrate config/secrets runtime injection (FN-009)
+- [x] 2.6 Implement workspace volume mounting
+- [x] 2.7 Implement SSH key mounting for Git access
+- [x] 2.8 Add container status polling
+
+## 3. Backend API
+
+- [x] 3.1 Enhance POST /api/v1/tool-instances with spawn logic
+- [x] 3.2 Add DELETE /api/v1/tool-instances/:id/stop endpoint
+- [x] 3.3 Add POST /api/v1/tool-instances/:id/start endpoint
+- [x] 3.4 Add GET /api/v1/tool-instances/:id/status endpoint
+- [x] 3.5 Add validation for project ownership and tool existence
+- [x] 3.6 Prevent duplicate spawn of running instances
+
+## 4. Frontend UI
+
+- [x] 4.1 Create ToolSpawn page at /tools/spawn
+- [x] 4.2 Implement tool selection dropdown from registry
+- [x] 4.3 Implement project selection dropdown
+- [x] 4.4 Add config override fields based on manifest
+- [x] 4.5 Create ToolInstanceDetail page at /tools/:id
+- [x] 4.6 Display instance status, subdomain URL, and controls (stop/start)
+- [x] 4.7 Add "Open Tool" button that opens subdomain in new tab
+
+## 5. Auth Integration
+
+- [x] 5.1 Configure Traefik forwardAuth middleware for code-server
+- [x] 5.2 Implement auth validation endpoint for Traefik
+- [x] 5.3 Disable code-server built-in auth (PASSWORD: "")
+- [x] 5.4 Test that unauthenticated requests are blocked
+
+## 6. Testing & Verification
+
+- [x] 6.1 Write backend tests for SpawnService
+- [x] 6.2 Write backend tests for tool instance lifecycle endpoints
+- [x] 6.3 Test container spawn in local Docker environment
+- [x] 6.4 Verify Traefik routing to spawned container
+- [x] 6.5 Run full test suite: `make test`
+- [x] 6.6 Run linters: `make lint`
+
+## 7. Documentation
+
+- [x] 7.1 Update docs/development.md with spawn workflow
+- [x] 7.2 Add code-server setup guide to docs/architecture.md
+- [x] 7.3 Document auth proxy configuration
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-05-14
@@ -0,0 +1,75 @@
+## Context
+
+The frontend is currently a static scaffold (FN-002) with no routing, auth, or API integration. The backend has complete domain models, CRUD routers, and auth dependencies (FN-004, FN-011). This design bridges the gap by establishing the frontend architecture needed for all user-facing features.
+
+Current frontend state:
+- Single App.tsx with static HTML
+- No routing, state management, or API client
+- No auth integration
+- Tests only verify static rendering
+
+## Goals / Non-Goals
+
+**Goals:**
+- Deliver a functional auth flow (login/logout via Authentik OIDC)
+- Provide a responsive dashboard shell with navigation
+- Enable project CRUD operations from the UI
+- Establish typed API client patterns
+- Set up environment-based configuration
+
+**Non-Goals:**
+- Full tool spawn UI (deferred to FN-010/FN-008)
+- Config/secrets management UI (deferred to FN-009)
+- Repository connection UI (deferred to future task)
+- Real-time updates or WebSockets
+- Mobile-optimized responsive design (basic responsiveness only)
+
+## Decisions
+
+**1. React Router v7 for routing**
+- Rationale: Industry standard, integrates well with React 19, supports nested routes and loaders
+- Alternative: TanStack Router - more type-safe but steeper learning curve, overkill for MVP
+
+**2. TanStack Query (React Query) for server state**
+- Rationale: Standard for API caching, background refetching, and optimistic updates
+- Alternative: SWR - similar but TanStack Query has better TypeScript support and devtools
+
+**3. Zustand for client state**
+- Rationale: Lightweight, TypeScript-friendly, minimal boilerplate vs Redux
+- Alternative: Context API - sufficient for auth but Zustand scales better for future features
+
+**4. HTTP client: fetch API with thin wrapper**
+- Rationale: No extra dependency needed, native fetch is sufficient
+- Alternative: Axios - adds bundle size, fetch handles our use cases
+
+**5. Auth: OIDC Authorization Code flow with PKCE**
+- Rationale: Secure, recommended by OAuth 2.1, Authentik supports it
+- Implementation: redirect to Authentik authorize endpoint, callback handles code exchange
+
+**6. Component library: Headless UI + Tailwind CSS**
+- Rationale: Unstyled primitives give full control, Tailwind is already in Vite scaffold
+- Alternative: Material UI - opinionated, harder to customize
+
+## Risks / Trade-offs
+
+**[Risk] Auth token storage in browser**
+→ Mitigation: Use httpOnly cookies (set by backend callback) or secure storage. Never localStorage. Implement CSRF protection.
+
+**[Risk] OIDC library bundle size**
+→ Mitigation: Use lightweight oauth4webapi or implement PKCE manually (~2KB vs 50KB+ for oidc-client-ts)
+
+**[Risk] CORS complexity between web and API**
+→ Mitigation: Configure CORS in FastAPI to allow web origin. Use same-origin deployment in production (Traefik routes both).
+
+**[Risk] Test complexity with auth flows**
+→ Mitigation: Mock auth context in tests, test components in isolation. E2E tests deferred post-MVP.
+
+## Migration Plan
+
+No migration needed - this is additive to the scaffold.
+
+## Open Questions
+
+1. Should we use a pre-built OIDC client library or implement PKCE manually?
+2. Do we need refresh token rotation or are short-lived access tokens sufficient?
+3. Should the API client auto-retry on 401 or redirect immediately?
@@ -0,0 +1,32 @@
+## Why
+
+The backend API is fully scaffolded with domain models, routers, and authentication dependencies, but the frontend remains a static scaffold page (FN-002). Users cannot sign in, view projects, or interact with any backend functionality. This change delivers the foundational frontend architecture needed to unlock all user-facing MVP features.
+
+## What Changes
+
+- **Authentik OIDC integration**: Auth provider with login/logout flow, token management, and automatic user provisioning
+- **Dashboard shell**: Responsive layout with header, navigation sidebar, and main content area
+- **Navigation routes**: Dashboard, Projects, Repositories, Tools, Settings pages with React Router
+- **Typed API client**: Generated or hand-written client for all `/api/v1/*` endpoints
+- **Project list UI**: Display user's projects with create/edit capabilities
+- **Environment config layer**: Vite env var integration for API URL, auth endpoints
+- **Auth-guarded routes**: Redirect unauthenticated users to login
+
+## Capabilities
+
+### New Capabilities
+- `auth-oidc`: Authentik OIDC authentication flow, token storage, session management
+- `dashboard-shell`: Responsive layout with navigation, header, and content area
+- `project-management-ui`: Project list, create, edit, delete views
+- `api-client`: Typed HTTP client for backend API consumption
+- `route-guards`: Authentication-based route protection and redirects
+
+### Modified Capabilities
+- None (this is purely additive to the existing scaffold)
+
+## Impact
+
+- **apps/web/src/**: All new frontend code
+- **apps/web/package.json**: New dependencies (react-router-dom, @tanstack/react-query, etc.)
+- **apps/api/app/auth/dependencies.py**: CORS and auth flow alignment
+- **docs/development.md**: Updated frontend development instructions
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: API client handles all backend endpoints
+The system SHALL provide a typed HTTP client for all backend API endpoints.
+
+#### Scenario: GET request
+- **WHEN** the client calls api.get('/projects')
+- **THEN** it sends a GET request to /api/v1/projects
+- **AND** returns typed Project[] data
+- **AND** includes the Authorization header with the current access token
+
+#### Scenario: POST request
+- **WHEN** the client calls api.post('/projects', data)
+- **THEN** it sends a POST request with JSON body
+- **AND** returns typed Project data
+
+#### Scenario: Error handling
+- **WHEN** a request returns 4xx or 5xx
+- **THEN** the client throws an ApiError with status code and message
+- **AND** the error can be caught and displayed to the user
+
+### Requirement: API client supports request/response types
+The system SHALL use TypeScript interfaces matching the backend Pydantic schemas.
+
+#### Scenario: Type safety
+- **WHEN** a developer uses the API client
+- **THEN** request and response types are checked at compile time
+- **AND** mismatches produce TypeScript errors
@@ -0,0 +1,36 @@
+## ADDED Requirements
+
+### Requirement: User can authenticate via Authentik OIDC
+The system SHALL provide an authentication flow using Authentik as the OIDC provider.
+
+#### Scenario: Successful login
+- **WHEN** an unauthenticated user clicks "Sign In"
+- **THEN** the system redirects to Authentik's authorization endpoint with PKCE parameters
+- **AND** after successful authentication, Authentik redirects back with an authorization code
+- **AND** the system exchanges the code for tokens
+- **AND** the user is redirected to the dashboard
+
+#### Scenario: Automatic user provisioning
+- **WHEN** a user authenticates for the first time
+- **THEN** the backend creates a User record automatically
+- **AND** the user can access their projects immediately
+
+#### Scenario: Logout
+- **WHEN** an authenticated user clicks "Sign Out"
+- **THEN** the system clears all session data
+- **AND** redirects to Authentik's end_session_endpoint
+- **AND** the user is redirected back to the login page
+
+### Requirement: Auth state is managed globally
+The system SHALL maintain authentication state accessible throughout the application.
+
+#### Scenario: Auth context available
+- **WHEN** the application loads
+- **THEN** an auth context provider wraps the component tree
+- **AND** child components can read the current auth state (loading, authenticated, unauthenticated, error)
+
+#### Scenario: Token refresh
+- **WHEN** an API request returns 401 due to expired token
+- **THEN** the system attempts token refresh
+- **AND** retries the original request with the new token
+- **AND** if refresh fails, redirects to login
@@ -0,0 +1,28 @@
+## ADDED Requirements
+
+### Requirement: Dashboard provides responsive layout
+The system SHALL provide a consistent layout with header, navigation, and content area.
+
+#### Scenario: Layout structure
+- **WHEN** the user views any authenticated page
+- **THEN** a header displays the application name and user avatar
+- **AND** a sidebar shows navigation links (Dashboard, Projects, Repositories, Tools, Settings)
+- **AND** the main content area renders the current route's component
+
+#### Scenario: Collapsible sidebar
+- **WHEN** the user is on a mobile device
+- **THEN** the sidebar is initially collapsed
+- **AND** a hamburger menu toggles the sidebar visibility
+
+### Requirement: Navigation reflects auth state
+The system SHALL show/hide navigation items based on authentication status.
+
+#### Scenario: Authenticated navigation
+- **WHEN** the user is authenticated
+- **THEN** all navigation links are visible
+- **AND** "Sign Out" is available in the user menu
+
+#### Scenario: Unauthenticated navigation
+- **WHEN** the user is not authenticated
+- **THEN** only "Sign In" is shown
+- **AND** accessing protected routes redirects to login
@@ -0,0 +1,39 @@
+## ADDED Requirements
+
+### Requirement: User can view their projects
+The system SHALL display a list of projects belonging to the authenticated user.
+
+#### Scenario: Project list page
+- **WHEN** the user navigates to /projects
+- **THEN** the system fetches projects from /api/v1/projects
+- **AND** displays each project with name, description, and created date
+- **AND** shows an empty state when no projects exist
+
+#### Scenario: Project detail
+- **WHEN** the user clicks on a project
+- **THEN** the system navigates to /projects/:id
+- **AND** displays project details including repositories and tool instances
+
+### Requirement: User can create a project
+The system SHALL allow authenticated users to create new projects.
+
+#### Scenario: Create project form
+- **WHEN** the user clicks "New Project"
+- **THEN** a form appears with name and description fields
+- **AND** the name field validates for non-empty and URL-friendly slug generation
+- **AND** submitting the form POSTs to /api/v1/projects
+- **AND** on success, the user is redirected to the new project
+
+### Requirement: User can edit and delete projects
+The system SHALL allow project owners to modify or remove their projects.
+
+#### Scenario: Edit project
+- **WHEN** the user clicks "Edit" on a project
+- **THEN** a pre-filled form appears
+- **AND** submitting updates the project via PUT /api/v1/projects/:id
+
+#### Scenario: Delete project
+- **WHEN** the user clicks "Delete" on a project
+- **THEN** a confirmation dialog appears
+- **AND** confirming sends DELETE /api/v1/projects/:id
+- **AND** the project is removed from the list
@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: Protected routes require authentication
+The system SHALL prevent unauthenticated users from accessing protected pages.
+
+#### Scenario: Unauthenticated access attempt
+- **WHEN** an unauthenticated user navigates to /projects
+- **THEN** the system redirects to /login
+- **AND** stores the intended destination for post-login redirect
+
+#### Scenario: Authenticated access
+- **WHEN** an authenticated user navigates to /projects
+- **THEN** the route renders normally
+
+### Requirement: Public routes are accessible
+The system SHALL allow unauthenticated access to public pages.
+
+#### Scenario: Login page
+- **WHEN** an unauthenticated user navigates to /login
+- **THEN** the login page renders without redirect
+
+#### Scenario: Health/status pages
+- **WHEN** any user navigates to /health
+- **THEN** the page renders without authentication
@@ -0,0 +1,72 @@
+## 1. Setup & Dependencies
+
+- [x] 1.1 Install frontend dependencies: react-router-dom, @tanstack/react-query, zustand, @headlessui/react
+- [x] 1.2 Set up Tailwind CSS configuration (tailwind.config.js, postcss.config.js)
+- [x] 1.3 Create environment type definitions in apps/web/src/env.d.ts
+- [x] 1.4 Add Vite environment variables to .env.example (VITE_API_URL, VITE_OIDC_ISSUER, etc.)
+
+## 2. API Client & Types
+
+- [x] 2.1 Create apps/web/src/api/client.ts with typed fetch wrapper and auth header injection
+- [x] 2.2 Generate or create TypeScript interfaces matching backend schemas (Project, User, etc.)
+- [x] 2.3 Implement error handling with ApiError class
+- [x] 2.4 Add request/response logging in debug mode
+
+## 3. Authentication
+
+- [x] 3.1 Create apps/web/src/auth/oidc.ts with PKCE code generation and token exchange
+- [x] 3.2 Implement auth store (Zustand) with state: loading, authenticated, unauthenticated, error
+- [x] 3.3 Create AuthProvider component wrapping the app
+- [x] 3.4 Implement login redirect to Authentik authorize endpoint
+- [x] 3.5 Implement callback handler (/callback route) for code exchange
+- [x] 3.6 Implement logout with end_session_endpoint redirect
+- [x] 3.7 Add token refresh logic for expired access tokens
+
+## 4. Routing & Layout
+
+- [x] 4.1 Set up React Router with route definitions in apps/web/src/router.tsx
+- [x] 4.2 Create DashboardLayout component with header, sidebar, and outlet
+- [x] 4.3 Implement RouteGuard component for protected routes
+- [x] 4.4 Add public routes: /login, /callback
+- [x] 4.5 Add protected routes: /, /projects, /projects/:id, /tools, /settings
+
+## 5. Dashboard Shell
+
+- [x] 5.1 Create Header component with app name and user avatar dropdown
+- [x] 5.2 Create Sidebar component with navigation links
+- [x] 5.3 Implement mobile-responsive sidebar toggle
+- [x] 5.4 Add active route highlighting in sidebar
+- [x] 5.5 Create Dashboard home page with welcome content
+
+## 6. Project Management UI
+
+- [x] 6.1 Create ProjectList page fetching from /api/v1/projects
+- [x] 6.2 Implement ProjectCard component for list view
+- [x] 6.3 Add empty state when no projects exist
+- [x] 6.4 Create ProjectDetail page at /projects/:id
+- [x] 6.5 Implement NewProject form with validation (name, description)
+- [x] 6.6 Implement EditProject form with pre-filled data
+- [x] 6.7 Add delete confirmation dialog for projects
+- [x] 6.8 Wire up TanStack Query mutations for create/update/delete
+
+## 7. Placeholder Pages
+
+- [x] 7.1 Create Tools page placeholder
+- [x] 7.2 Create Settings page placeholder
+- [x] 7.3 Create Repositories page placeholder
+
+## 8. Testing & Verification
+
+- [x] 8.1 Write unit tests for auth store
+- [x] 8.2 Write unit tests for API client error handling
+- [x] 8.3 Write tests for RouteGuard component
+- [x] 8.4 Update App.test.tsx to test routing
+- [x] 8.5 Run `pnpm test` and fix any failures
+- [x] 8.6 Run `pnpm lint` and fix any issues
+- [x] 8.7 Run `pnpm typecheck` and fix any errors
+
+## 9. Documentation
+
+- [x] 9.1 Update docs/development.md with frontend auth setup instructions
+- [x] 9.2 Update README.md with new environment variables
+- [x] 9.3 Add frontend architecture notes to docs/architecture.md