docs(api): generate auth docs and archive p00 change

openspec/changes/archive/2026-02-18-p00-api-documentation/proposal.md

@@ -0,0 +1,51 @@
+# Proposal: API Documentation with Scribe
+
+## Overview
+Add comprehensive API documentation annotations to all Laravel controllers using Laravel Scribe. This enables auto-generated SwaggerUI documentation accessible at `/api/documentation`.
+
+## Goals
+- Annotate existing authentication API endpoints with Scribe annotations
+- Generate browsable API documentation
+- Ensure documentation stays in sync with implementation
+- Enable frontend developers to reference accurate API specs
+
+## Non-Goals
+- Creating new API endpoints
+- Modifying existing API responses
+- Setting up API versioning
+
+## Priority
+**HIGH** - This is a prerequisite for UI changes (p01-p05) to ensure API contracts are documented.
+
+## Scope
+
+### Controllers to Document
+1. **AuthController** - Login, logout, token refresh endpoints
+
+Other controller groups in the broader roadmap are deferred until those controllers/routes are present in this repository.
+
+### Annotations Required
+Each endpoint must have:
+- `@group` - Logical grouping (e.g., "Authentication", "Team Members")
+- `@authenticated` - For protected endpoints
+- `@bodyParam` - Request body parameters
+- `@response` - Example success response
+- `@response 401|403|422` - Error responses
+
+## Success Criteria
+- [ ] AuthController endpoints have Scribe annotations
+- [ ] `php artisan scribe:generate` runs without errors
+- [ ] SwaggerUI accessible at `/api/documentation`
+- [ ] Authentication endpoints documented with request/response examples
+- [ ] Authentication section explains JWT flow
+
+## Estimated Effort
+2-3 hours
+
+## Dependencies
+- Existing Laravel backend with controllers
+- tymon/jwt-auth for authentication examples
+
+## References
+- docs/headroom-decision-log.md → Architecture Decisions → API Documentation
+- openspec/config.yaml → documentation rules