docs: bedroom developer documentation — complete docs/developers/ set

Adds the full bedroom-developer-docs OpenSpec change implementation:

- docs/developers/README.md — index page
- docs/developers/quick-start.md — bootstrap to working token in 7 steps
- docs/developers/concepts.md — AgentIdP, AGNTCY, lifecycle, OAuth 2.0, free tier
- docs/developers/guides/README.md — guide index
- docs/developers/guides/register-an-agent.md — all fields, validation, common errors
- docs/developers/guides/manage-credentials.md — generate, list, rotate, revoke
- docs/developers/guides/issue-and-revoke-tokens.md — OAuth 2.0 flow, introspect, revoke
- docs/developers/guides/query-audit-logs.md — filters, pagination, 90-day retention
- docs/developers/api-reference.md — all 14 endpoints, all error codes, curl examples

Also commits deferred OpenSpec housekeeping from previous session:
- Archives phase-1-mvp-implementation change to openspec/changes/archive/
- Adds bedroom-developer-docs change artifacts (30/30 tasks complete)
- Syncs 4 delta specs to openspec/specs/

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

openspec/changes/bedroom-developer-docs/tasks.md

@@ -0,0 +1,50 @@
+## 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