# Tasks: API Documentation with Scribe

## Phase 1: Configure Scribe

- [x] 0.1 Install Scribe (if not already installed): `composer require knuckleswtf/scribe`
- [x] 0.2 Publish Scribe config: `php artisan vendor:publish --tag=scribe-config`
- [x] 0.3 Configure `config/scribe.php` with Headroom settings
- [x] 0.4 Add `/api/documentation` to CORS allowed paths

## Phase 2: Annotate Controllers

### AuthController
- [x] 0.5 Add `@group Authentication` to class
- [x] 0.6 Document `POST /api/auth/login` with @bodyParam, @response
- [x] 0.7 Document `POST /api/auth/refresh` with @authenticated, @response
- [x] 0.8 Document `POST /api/auth/logout` with @authenticated, @response
- [x] 0.9 Add authentication section to Scribe config

### TeamMemberController
- [ ] 0.10 Add `@group Team Members` to class
- [ ] 0.11 Document `GET /api/team-members` with @queryParam filters
- [ ] 0.12 Document `POST /api/team-members` with @bodyParam
- [ ] 0.13 Document `GET /api/team-members/{id}`
- [ ] 0.14 Document `PUT /api/team-members/{id}`
- [ ] 0.15 Document `DELETE /api/team-members/{id}`

### ProjectController
- [ ] 0.16 Add `@group Projects` to class
- [ ] 0.17 Document `GET /api/projects` with @queryParam filters
- [ ] 0.18 Document `POST /api/projects` with @bodyParam
- [ ] 0.19 Document `GET /api/projects/{id}`
- [ ] 0.20 Document `PUT /api/projects/{id}`
- [ ] 0.21 Document `PUT /api/projects/{id}/status`
- [ ] 0.22 Document `PUT /api/projects/{id}/estimate`
- [ ] 0.23 Document `PUT /api/projects/{id}/forecast`

### AllocationController
- [ ] 0.24 Add `@group Allocations` to class
- [ ] 0.25 Document `GET /api/allocations` (matrix view)
- [ ] 0.26 Document `POST /api/allocations`
- [ ] 0.27 Document `PUT /api/allocations/{id}`
- [ ] 0.28 Document `DELETE /api/allocations/{id}`
- [ ] 0.29 Document `POST /api/allocations/bulk`

### ActualController
- [ ] 0.30 Add `@group Actuals` to class
- [ ] 0.31 Document `GET /api/actuals`
- [ ] 0.32 Document `POST /api/actuals`
- [ ] 0.33 Document `PUT /api/actuals/{id}`
- [ ] 0.34 Document validation rules (future month rejection)

### CapacityController
- [ ] 0.35 Add `@group Capacity` to class
- [ ] 0.36 Document `GET /api/capacity`
- [ ] 0.37 Document `GET /api/capacity/team`
- [ ] 0.38 Document `GET /api/capacity/revenue`
- [ ] 0.39 Document `POST /api/holidays`
- [ ] 0.40 Document `POST /api/ptos`

### ReportController
- [ ] 0.41 Add `@group Reports` to class
- [ ] 0.42 Document `GET /api/reports/forecast`
- [ ] 0.43 Document `GET /api/reports/utilization`
- [ ] 0.44 Document `GET /api/reports/costs`
- [ ] 0.45 Document `GET /api/reports/variance`
- [ ] 0.46 Document `GET /api/reports/allocation`

### MasterDataController
- [ ] 0.47 Add `@group Master Data` to class
- [ ] 0.48 Document `GET /api/roles`
- [ ] 0.49 Document `POST /api/roles`
- [ ] 0.50 Document `PUT /api/roles/{id}`
- [ ] 0.51 Document `DELETE /api/roles/{id}`
- [ ] 0.52 Document project-statuses endpoints
- [ ] 0.53 Document project-types endpoints

## Phase 3: Generate & Verify

- [ ] 0.54 Run `php artisan scribe:generate`
- [ ] 0.55 Verify no errors in generation
- [ ] 0.56 Access `/api/documentation` in browser
- [ ] 0.57 Verify all endpoints appear in documentation
- [ ] 0.58 Test "Try it out" for login endpoint
- [ ] 0.59 Verify authentication flow is documented

## Commits

1. `chore(docs): Configure Laravel Scribe for API documentation`
2. `docs(api): Add Scribe annotations to AuthController`
3. `docs(api): Add Scribe annotations to TeamMemberController`
4. `docs(api): Add Scribe annotations to ProjectController`
5. `docs(api): Add Scribe annotations to AllocationController`
6. `docs(api): Add Scribe annotations to remaining controllers`
7. `docs(api): Generate and verify SwaggerUI documentation`