## 1. Folder Structure & Setup

- [x] 1.1 Create `docs/developers/` directory
- [x] 1.2 Create `docs/developers/guides/` subdirectory
- [x] 1.3 Create `docs/developers/README.md` — index page listing all docs with one-line descriptions and links

## 2. Quick-Start Guide

- [x] 2.1 Create `docs/developers/quick-start.md` — prerequisites section (Docker + curl only)
- [x] 2.2 Write Step 1: start infrastructure with docker-compose command + confirmation of services and ports
- [x] 2.3 Write Step 2: start AgentIdP server with npm command + expected startup output
- [x] 2.4 Write Step 3: register an agent — complete curl for `POST /agents` with example request body and expected JSON response
- [x] 2.5 Write Step 4: generate a credential — complete curl for `POST /agents/{agentId}/credentials` with example response showing `clientId` and `clientSecret`
- [x] 2.6 Write Step 5: issue an access token — complete curl for `POST /token` with form-encoded body and example JWT response
- [x] 2.7 Write "What's Next" section linking to concepts.md, guides/README.md, and api-reference.md

## 3. Core Concepts Guide

- [x] 3.1 Create `docs/developers/concepts.md` — intro section: what is AgentIdP in one paragraph
- [x] 3.2 Write "What is an AI Agent Identity" section — plain-English explanation of agent identities vs human identities
- [x] 3.3 Write "AGNTCY Alignment" section — what AGNTCY is, why it matters, benefit to the developer (no external reading required)
- [x] 3.4 Write "Agent Lifecycle" section — four states (active, suspended, decommissioned) and what each means for credentials and tokens, including irreversibility of decommission
- [x] 3.5 Write "OAuth 2.0 Client Credentials" section — plain-English explanation of client_id, client_secret, and how agents use them; no RFC jargon
- [x] 3.6 Write "Free Tier Limits" section — table of all four limits (100 agents, 10k tokens/month, 100 req/min, 90-day audit) with notes on what happens when each is exceeded

## 4. Developer Guides

- [x] 4.1 Create `docs/developers/guides/README.md` — index listing all four guides with descriptions and links
- [x] 4.2 Create `docs/developers/guides/register-an-agent.md` — step-by-step registration guide with all required/optional fields, validation rules, and example success + error responses (including common validation errors and fixes)
- [x] 4.3 Create `docs/developers/guides/manage-credentials.md` — guide covering all four credential operations: generate (with secret handling note), list (with pagination), rotate (explaining same credentialId, old secret immediately invalid), revoke (with comparison to agent decommission)
- [x] 4.4 Create `docs/developers/guides/issue-and-revoke-tokens.md` — token guide covering: issuance with form-encoded body, JWT structure explanation, using token as Bearer in subsequent requests, introspection (`active` field), revocation and immediate invalidation
- [x] 4.5 Create `docs/developers/guides/query-audit-logs.md` — audit log guide covering: available filters (agentId, action, outcome, date range), pagination params, audit event structure, 90-day retention behaviour

## 5. API Reference

- [x] 5.1 Create `docs/developers/api-reference.md` — top section: base URL, port config via env var, versioning note (Phase 1 unversioned)
- [x] 5.2 Write table of contents linking to all four service sections
- [x] 5.3 Write errors reference section: all error response shapes, all custom error codes (ValidationError, AgentNotFoundError, AgentAlreadyExistsError, CredentialError, AuthenticationError, AuthorizationError, RateLimitError, FreeTierLimitError), HTTP status mappings
- [x] 5.4 Document Agent Registry endpoints (5): `POST /agents`, `GET /agents`, `GET /agents/{agentId}`, `PATCH /agents/{agentId}`, `DELETE /agents/{agentId}` — each with method, path, auth requirement, request fields table, response codes table, and complete curl example
- [x] 5.5 Document OAuth 2.0 Token endpoints (3): `POST /token`, `POST /token/introspect`, `POST /token/revoke` — each with method, path, auth requirement, request fields table (noting form-encoded for /token), response codes table, curl example, and X-RateLimit header documentation for 429s
- [x] 5.6 Document Credential Management endpoints (4): `POST /agents/{agentId}/credentials`, `GET /agents/{agentId}/credentials`, `POST /agents/{agentId}/credentials/{credentialId}/rotate`, `DELETE /agents/{agentId}/credentials/{credentialId}` — each with method, path, auth requirement, request fields table, response codes table, and complete curl example
- [x] 5.7 Document Audit Log endpoints (2): `GET /audit`, `GET /audit/{eventId}` — each with method, path, auth requirement, query parameter table (including all filter options), response codes table, and complete curl example

## 6. QA & Review

- [x] 6.1 Verify all curl examples are syntactically correct and complete (no ellipses, no missing flags)
- [x] 6.2 Verify all 14 endpoints from the OpenAPI specs are covered in api-reference.md
- [x] 6.3 Verify all internal links (cross-references between docs) resolve correctly
- [x] 6.4 Verify free-tier limits in concepts.md match README.md Section 3.3
- [x] 6.5 Verify quick-start guide is self-contained — a developer can complete it using only that file
