feat(openapi): document every registered route — completeness pass

[mastermanas805]

Summary

Audits the agent API's OpenAPI 3.1 spec against the actually-registered routes in internal/router/router.go and fills in every gap. 36 paths that were live but undocumented now have a summary, description, security, parameters, request body schema (where applicable), and an exhaustive list of response statuses. Two supporting component schemas (StorageProvisionResponse, DeployItem) added.

The diff is additive — no existing path was changed. Existing TestOpenAPISpecParses and all TestOpenAPI_* sibling gates still pass.

What was missing

Anonymous / public surface

• GET /metrics — Prometheus scrape, token-gated when METRICS_TOKEN set
• GET /openapi.json — self-describing
• POST /storage/new — full schema, including the (one-shot) secret_access_key
• GET /resources/{token}/logs — SSE pod logs (growth-tier only; token is the credential)
• GET /stacks/{slug}/logs/{svc} — SSE stack service logs
• PATCH /stacks/{slug}/env — env-vars-noted-for-next-redeploy MVP shape
• POST /razorpay/webhook — HMAC-verified Razorpay subscription lifecycle (charged/cancelled/payment.failed)
• POST /billing/checkout — legacy alias of /api/v1/billing/checkout

Auth surface (browser + programmatic + magic-link + CLI device flow)

• POST /auth/github, GET /auth/github/start, GET /auth/github/callback
• POST /auth/email/start, GET /auth/email/callback
• POST /auth/cli, GET /auth/cli/{id}

Authenticated /api/v1 surface

• GET /api/v1/resources/{id}/credentials (the AES-decrypted connection URL read)
• Team-member CRUD: /api/v1/team/members, .../members/invite, .../members/leave, .../members/{user_id}, .../invitations, .../invitations/{id}, .../invitations/{id}/accept
• Deployment list/get/delete aliases under /api/v1/deployments
• Stack list under /api/v1/stacks
• Custom-domain CRUD: /api/v1/stacks/{slug}/domains, .../verify, .../{id}
• Personal Access Tokens: /api/v1/auth/api-keys (POST/GET) and .../{id} (DELETE)
• GET /api/v1/audit — Recent Activity feed

Internal / ops (dev-only) — flagged with "x-instanode-internal": true and clearly noted in description as only enabled when ENVIRONMENT=development

• POST /internal/set-tier — bypass-Razorpay manual tier elevation

Verification

go test -run TestOpenAPISpecParses ./internal/handlers/...   # PASS
go test -run TestOpenAPI ./internal/handlers/... -v          # 8/8 PASS

Test plan

• TestOpenAPISpecParses passes (spec is valid JSON 3.1.0)
• All 7 sibling TestOpenAPI_* gates still pass (whoami, claim flow, deploy env vars, stacks, etc.)
• Spot-check curl http://localhost:30080/openapi.json | jq '.paths | keys | length' after deploy and confirm count jumped by ~36
• Spot-check a couple of new schemas render in any OpenAPI viewer (Swagger UI, Redoc, etc.)

🤖 Generated with Claude Code