## Context

Phase 1 MVP is complete: 46 source files, 14 API endpoints across 4 OpenAPI 3.0 specs, 244 passing tests. The implementation is production-grade and live on `git.sentryagent.ai`. However, the developer experience stops at the code. There is no entry point for a bedroom developer who has never heard of AgentIdP, AGNTCY, or client credentials OAuth 2.0.

The documentation must be written, owned, and maintained as a first-class deliverable — not an afterthought. It is produced by a Virtual Technical Writer subagent with full access to the codebase and OpenAPI specs.

**Constraints:**
- Audience: bedroom developers — assume competence with HTTP and basic programming, assume no prior knowledge of AgentIdP or AGNTCY
- Format: Markdown only — renders on GitHub, no external tooling required
- No build step — docs are static `.md` files in `docs/developers/`
- All code examples must be real, runnable, and copy-pasteable
- Tone: direct, practical, no enterprise jargon

## Goals / Non-Goals

**Goals:**
- Bedroom developer can register their first agent and issue a token in under 5 minutes using only the quick-start guide
- Every API endpoint is documented in plain English with at least one working curl example
- Core concepts are explained without assuming prior knowledge of OAuth 2.0 or AGNTCY
- All four P0 workflows (register, credential, token, audit) have step-by-step guides
- FAQ covers the most likely failure points and free-tier limits

**Non-Goals:**
- No web-rendered documentation site (Phase 2 — out of scope)
- No SDK documentation (Node.js SDK not yet built — Phase 1 P1 remaining)
- No video tutorials or interactive demos
- No multi-language code examples (Node.js + curl only for now)
- No enterprise deployment documentation (separate from bedroom developer focus)

## Decisions

**Decision 1: Single flat folder vs nested structure**
Chosen: flat `docs/developers/` with a `tutorials/` subfolder only for multi-step guides.
Alternative considered: deep nesting by category. Rejected — adds navigation friction for a small doc set.

**Decision 2: Raw OpenAPI YAML as API reference vs human-written reference**
Chosen: human-written `api-reference.md` alongside the existing OpenAPI specs.
Alternative considered: link to raw YAML only. Rejected — YAML is not readable for bedroom developers; the whole point is accessibility.

**Decision 3: Standalone docs vs inline code comments**
Chosen: standalone Markdown files in `docs/developers/`.
Alternative considered: JSDoc-generated docs. Rejected — JSDoc is for library consumers, not REST API users.

**Decision 4: Who writes the docs**
Chosen: Virtual Technical Writer subagent — spawned by CTO with full codebase + OpenAPI spec context.
Alternative considered: Virtual Principal Developer writes docs. Rejected — developer time should stay on code; writing accessible prose for non-technical audiences is a distinct skill warranting a dedicated role.

**Decision 5: Versioning**
Chosen: docs live in the same repo as code, versioned together via git. No separate docs versioning scheme in Phase 1.

## Risks / Trade-offs

- **[Risk] Docs drift from implementation** → Mitigation: Virtual QA Engineer verifies API reference examples against actual endpoints before sign-off; curl examples are tested against a running instance
- **[Risk] Tone inconsistency across docs** → Mitigation: Technical Writer receives a unified style brief in the subagent prompt (plain English, second person, imperative voice, no jargon)
- **[Risk] Quick-start prerequisites unclear** → Mitigation: Quick-start lists exact prerequisites (Docker, curl, nothing else) and links to docker-compose.yml

## Migration Plan

Documentation only — no migration required. Files are added to `docs/developers/` and committed to `develop`. No rollback needed.

## Open Questions

*(none — scope is fully defined)*