# Design — developer-docs-phase6-update

**Status:** Complete  
**Archived:** 2026-04-04

## Context

Developer documentation in `docs/developers/` was last updated during Phase 2. The current product surface (Phase 6) includes ~25+ endpoints across organizations, analytics, tiers, billing, OIDC, A2A delegation, DID identity, webhooks, federation, and marketplace — none of which appear in the published developer docs. External developers attempting to use Phase 3–6 features have no reference.

## Goals / Non-Goals

**Goals:**
- Bring all developer-facing docs current with Phase 6 surface
- Update API reference to cover all 50+ endpoints (was 14)
- Add Phase 3–6 concepts to concepts.md
- Update quick-start to reflect org-first registration flow
- Add 5 new guides for Phase 3–6 features

**Non-Goals:**
- Not a rewrite — existing Phase 1–2 content is preserved and extended
- Not engineering internals — this is for external developers, not contributors
- No changes to `docs/engineering/` or `docs/devops/`

## Decisions

### D1: Extend, don't replace
Existing content in concepts.md, quick-start.md, and guides/ is preserved as-is. New sections are appended. This avoids breaking any existing bookmarks or references.

### D2: Single api-reference.md, complete replacement
The 14-endpoint Phase 1 api-reference.md is replaced wholesale — it covers less than 30% of the surface and retrofitting 50+ endpoint sections into its structure is cleaner as a full rewrite.

### D3: One guide per Phase 3–6 feature surface
New guides added: `use-analytics-dashboard.md`, `manage-api-tiers.md`, `a2a-delegation.md`, `configure-webhooks.md`, `agntcy-compliance.md`. Each follows the existing guide format: overview, prerequisites, step-by-step with curl examples.

### D4: README.md index updated
`docs/developers/README.md` guide index expanded from 4 to 9 entries to include all new guides.