docs: comprehensive API documentation

- Create enhanced health endpoints with /health and /health/db
- Add comprehensive docstrings to all API endpoints
- Add Pydantic response models with Field descriptions
- Create apps/api/README.md with setup guide
- Create ADR-001 for session auth decision
- Create ADR-002 for async SQLAlchemy decision
- Quality gates: Python syntax OK, TypeScript OK

openspec/changes/api-documentation/tasks.md

@@ -0,0 +1,94 @@
+# API Documentation - Tasks
+
+## Phase 1: Health Endpoints
+
+- [ ] **Task 1.1**: Enhance `/health` endpoint
+  - Add timestamp, version, uptime
+  - Add disk space check
+  - Add comprehensive checks object
+  - Create HealthCheck Pydantic models
+
+- [ ] **Task 1.2**: Create `/health/db` endpoint
+  - Database connection check
+  - Response time measurement
+  - Connection pool status
+
+## Phase 2: Endpoint Documentation
+
+- [ ] **Task 2.1**: Document auth endpoints
+  - Add docstrings to `src/api/auth.py`
+  - Add response model descriptions
+  - Add error responses
+
+- [ ] **Task 2.2**: Document projects endpoints
+  - Add docstrings to `src/api/projects.py`
+  - Document request/response models
+
+- [ ] **Task 2.3**: Document repositories endpoints
+  - Add docstrings to `src/api/git_repositories.py`
+  - Document file operations
+
+- [ ] **Task 2.4**: Document user endpoints
+  - Add docstrings to `src/api/users.py`
+  - Document profile endpoints
+
+- [ ] **Task 2.5**: Document tool endpoints
+  - Add docstrings to `src/api/tool_types.py`
+  - Add docstrings to `src/api/tool_instances.py`
+
+- [ ] **Task 2.6**: Document SSH keys endpoints
+  - Add docstrings to `src/api/ssh_keys.py`
+
+- [ ] **Task 2.7**: Document config endpoints
+  - Add docstrings to `src/api/user_config.py`
+
+- [ ] **Task 2.8**: Document dashboard endpoint
+  - Add docstrings to `src/api/dashboard.py`
+
+- [ ] **Task 2.9**: Document terminal endpoint
+  - Add docstrings to `src/api/terminal.py`
+
+## Phase 3: Model Documentation
+
+- [ ] **Task 3.1**: Document Pydantic models
+  - Add descriptions to all response models
+  - Add example values
+  - Document in `src/schemas/` or inline
+
+## Phase 4: API README
+
+- [ ] **Task 4.1**: Create `apps/api/README.md`
+  - Overview section
+  - Quick start guide
+  - Environment variables table
+  - Development setup
+  - Testing instructions
+  - Architecture overview
+  - Common commands
+
+## Phase 5: Architecture Decision Records
+
+- [ ] **Task 5.1**: Create ADR for session auth
+  - Document why cookies vs JWT
+  - Trade-offs and risks
+
+- [ ] **Task 5.2**: Create ADR for async SQLAlchemy
+  - Document async pattern choice
+  - PostgreSQL decision
+
+## Phase 6: Quality Gates
+
+- [ ] **Task 6.1**: Verify `/docs` endpoint
+  - Check all endpoints appear
+  - Verify schemas are documented
+
+- [ ] **Task 6.2**: Verify health endpoints
+  - Test `/health`
+  - Test `/health/db`
+
+- [ ] **Task 6.3**: Run linting
+  - ruff check
+  - mypy
+
+- [ ] **Task 6.4**: Run tests
+  - pytest