| name | document-ai-hero-api |
| description | Generate or update documentation for the AI Hero API by reading the source code at ~/repos/ai/course-builder. Use when user wants to document, update docs for, or understand the AI Hero API endpoints. |
| disable-model-invocation | true |
Document AI Hero API
Generate/update API documentation by reading the AI Hero source code.
Prerequisites: Ensure Read Permissions
Before reading the AI Hero source, update .claude/settings.local.json to include read permission for the course-builder repo. Add this entry to the permissions.allow array if not already present:
"Read(/home/mattpocock/repos/ai/course-builder/**)"
Workflow
1. Scan API Source
Read the AI Hero API source at ~/repos/ai/course-builder/apps/ai-hero/src/. Focus on:
- REST endpoints:
src/app/api/ — each folder is a route segment. Read every route.ts file.
- tRPC routers:
src/trpc/api/routers/ — each file is a typed RPC router.
- Database schema:
src/db/schema.ts — table definitions and relationships.
- Auth:
src/app/api/auth/ and any middleware files for auth patterns.
2. For Each Endpoint, Capture
- HTTP method + path (REST) or procedure name + type (tRPC query/mutation)
- Request body / query params with TypeScript types
- Response shape with TypeScript types
- Auth requirements (public, Bearer token, session, HMAC)
- Side effects (Inngest events, webhooks, S3 uploads)
3. Cross-Reference with This Project
Check how endpoints are consumed in this codebase:
app/services/ai-hero-auth-service.ts — OAuth device flowapp/services/ai-hero-upload-service.ts — Upload & post creationapp/features/upload-manager/ — SSE client for progress
Flag any endpoints used here that have changed in the source.
4. Write Documentation
Output to docs/ai-hero-api.md in this repo. Follow the structure in TEMPLATE.md.
5. Summary
After updating, print a short summary of:
- Number of endpoints documented
- Any breaking changes detected vs. current usage
- Any new endpoints not yet consumed by this project
