---
name: docs
description: Documents API endpoints, generates wiki structure, and tracks documentation coverage
category: development
---

# Documentation Engineer

Documents API endpoints, maintains wiki structure, and reports documentation gaps.

## When to Use

```
/docs
/docs api
/docs wiki
/docs check
```

## Sub-Commands

### `/docs api`
Scans `src/` for API endpoints and updates `docs/api/`.

### `/docs wiki`
Suggests or updates wiki structure in `docs/wiki/`.

### `/docs check`
Reports which endpoints/classes lack documentation.

## Skill Steps

### 1. Scan for API Endpoints
- Search `src/` for route files (REST patterns: `*Route.php`, `*Controller.php`)
- Search for HTTP method annotations: `@Route`, `@Get`, `@Post`, `@Put`, `@Delete`
- Detect endpoint patterns in plain PHP files

### 2. Update API Documentation
- Create/update `docs/api/ENDPOINTS.md` with endpoint inventory
- Create individual files per resource: `docs/api/users.md`, `docs/api/tasks.md`
- Format:

```markdown
# Users API

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | /api/users | List all users |
| GET | /api/users/{id} | Get single user |
| POST | /api/users | Create user |
| PUT | /api/users/{id} | Update user |
| DELETE | /api/users/{id} | Delete user |

## Request/Response Examples

### GET /api/users
**Response:**
```json
{
  "data": [...],
  "total": 42,
  "page": 1,
  "per_page": 20
}
```
```

### 3. Wiki Structure
If `docs/wiki/` doesn't exist, suggest structure:

```
docs/wiki/
├── README.md           <- Wiki home
├── getting-started.md  <- Setup guide
├── api-reference.md    <- API overview
├── database.md         <- DB schema
└── deployment.md        <- Hosting guide
```

### 4. Documentation Coverage Report
Track which classes/features have docs:

| Class/File | Has Docs | Last Updated |
|------------|----------|--------------|
| UserController | ✅ docs/api/users.md | 2026-01-15 |
| TaskController | ❌ missing | - |

## Output

- `docs/api/*.md` - API endpoint documentation
- `docs/wiki/README.md` - Wiki home (if created)
- Coverage report printed to user

## Rules

- Use English for all documentation content
- One endpoint file per resource
- Include request/response examples
- Document error responses (400, 401, 403, 404, 500)
- Keep docs in sync with code (check on every run)

## Context Recovery

If context is compacted:
1. Re-scan `src/` for endpoint files
2. Check which docs already exist
3. Continue from missing documentation