# OpenSpec Proposal — developer-docs-phase6-update

**Status:** Approved  
**Proposed:** 2026-04-04  
**Approved by:** CEO  

## Problem Statement

The developer documentation in `docs/developers/` was written during Phase 2. Phases 3–6 shipped
analytics, API tiers, AGNTCY compliance, A2A delegation, DID identity, OIDC, webhooks, federation,
and the marketplace — none of which appear in the developer docs. The API reference covers only
14 endpoints; the current codebase has ~25+ endpoints. The README contains a "bedroom developers"
typo. External developers cannot use Phase 3–6 features without documentation.

## Workstreams

### WS1 — api-reference.md
Update to document all current endpoints with full request/response schemas, auth requirements,
and error codes. Replace the 14-endpoint Phase 1 reference with the complete Phase 6 surface.

### WS2 — concepts.md
Add Phase 3–6 concepts: multi-tenancy/organizations, DID identity (did:web), OIDC provider,
A2A delegation, API tier plans (Free/Pro/Enterprise), and AGNTCY compliance.

### WS3 — quick-start.md
Update to add org creation as Step 1 (now required before agent registration), and verify all
endpoint paths match current routes.

### WS4 — guides/
Revise the 4 existing guides for current endpoint paths and org-scoped requests.
Add new guides: analytics dashboard, tier management, A2A delegation, webhooks, AGNTCY compliance.

### WS5 — README.md
Fix "bedroom developers" typo → "developers". Update document index to list all new guides.