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

@@ -0,0 +1,54 @@
+# API Documentation
+
+## Problem
+
+The API lacks comprehensive documentation:
+- No auto-generated OpenAPI/Swagger UI
+- Health endpoint is minimal (only checks database)
+- Missing endpoint documentation and docstrings
+- No API README for developer onboarding
+- No Architecture Decision Records (ADRs)
+
+## Solution
+
+Provide comprehensive API documentation:
+
+1. **Auto-generated OpenAPI docs** - FastAPI native `/docs` and `/redoc` endpoints
+2. **Enhanced health checks** - `/health` with full system status, `/health/db` for database
+3. **Endpoint documentation** - Proper docstrings, Pydantic models, response codes
+4. **API README** - Developer onboarding guide
+5. **Architecture Decision Records** - Document key architectural choices
+
+## Key Features
+
+### OpenAPI Documentation
+- Interactive Swagger UI at `/docs`
+- ReDoc at `/redoc`
+- All endpoints with schemas and examples
+- Authentication documented
+
+### Health Monitoring
+- `/health` - Overall system health (database, disk, uptime)
+- `/health/db` - Database-specific health check
+- JSON responses with status indicators
+
+### Developer Documentation
+- `apps/api/README.md` - Setup, env vars, testing
+- ADRs in `docs/architecture/decisions/`
+- Inline code documentation
+
+## Benefits
+
+- **Developer onboarding** - New devs can understand the API quickly
+- **API discoverability** - Interactive docs for testing endpoints
+- **Health monitoring** - Operations can monitor system health
+- **Knowledge preservation** - ADRs capture why decisions were made
+
+## Success Criteria
+
+- [ ] `/docs` loads Swagger UI with all endpoints
+- [ ] `/health` returns comprehensive health data
+- [ ] `/health/db` returns database status
+- [ ] All endpoints have docstrings
+- [ ] API README exists with setup instructions
+- [ ] At least one ADR exists