sentryagent-idp/openspec/changes/bedroom-developer-docs/design.md

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)