61ea975c79
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>
57 lines
3.6 KiB
Markdown
57 lines
3.6 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Developer guides index exists at docs/developers/guides/README.md
|
|
The system SHALL provide a guides index at `docs/developers/guides/README.md` listing all available guides with one-line descriptions and links.
|
|
|
|
#### Scenario: Developer finds the right guide quickly
|
|
- **WHEN** the developer opens the guides folder
|
|
- **THEN** they SHALL see a list of all guides with descriptions so they can choose the one relevant to their task
|
|
|
|
### Requirement: Agent registration guide exists at docs/developers/guides/register-an-agent.md
|
|
The system SHALL provide a step-by-step guide for registering an agent, including all required and optional fields, validation rules, and how to handle the response.
|
|
|
|
#### Scenario: Developer registers their first agent
|
|
- **WHEN** the developer follows the registration guide
|
|
- **THEN** they SHALL successfully create an agent and understand what `agentId`, `clientId`, and `status` mean in the response
|
|
|
|
#### Scenario: Developer understands registration validation errors
|
|
- **WHEN** the guide covers validation
|
|
- **THEN** it SHALL show examples of common validation errors (missing required fields, invalid email format) and how to fix them
|
|
|
|
### Requirement: Credential management guide exists at docs/developers/guides/manage-credentials.md
|
|
The system SHALL provide a guide covering all four credential operations: generate, list, rotate, and revoke — with curl examples and explanation of when to use each.
|
|
|
|
#### Scenario: Developer rotates a compromised credential
|
|
- **WHEN** the developer follows the rotation section
|
|
- **THEN** they SHALL understand that rotation replaces the secret while keeping the same `credentialId`, and the old secret is immediately invalid
|
|
|
|
#### Scenario: Developer understands credential revocation vs agent decommission
|
|
- **WHEN** the developer reads the guide
|
|
- **THEN** they SHALL understand the difference: revoking a credential leaves the agent active with other credentials; decommissioning the agent revokes everything permanently
|
|
|
|
### Requirement: Token guide exists at docs/developers/guides/issue-and-revoke-tokens.md
|
|
The system SHALL provide a guide covering token issuance, introspection, and revocation — explaining the JWT structure, expiry, and how to use the Bearer token in API requests.
|
|
|
|
#### Scenario: Developer uses a token to authenticate a request
|
|
- **WHEN** the developer follows the token guide
|
|
- **THEN** they SHALL see an example of using the issued token as a Bearer token in an Authorization header on a subsequent API call
|
|
|
|
#### Scenario: Developer introspects a token to check validity
|
|
- **WHEN** the developer reads the introspection section
|
|
- **THEN** they SHALL understand what `active: true/false` means and what fields are returned
|
|
|
|
#### Scenario: Developer revokes a token
|
|
- **WHEN** the developer follows the revocation section
|
|
- **THEN** they SHALL understand that revoked tokens are immediately invalid even if not yet expired
|
|
|
|
### Requirement: Audit log guide exists at docs/developers/guides/query-audit-logs.md
|
|
The system SHALL provide a guide for querying the audit log — covering available filters (agentId, action, outcome, date range), pagination, and how to interpret audit events.
|
|
|
|
#### Scenario: Developer queries audit events for a specific agent
|
|
- **WHEN** the developer follows the audit guide
|
|
- **THEN** they SHALL see a curl example filtering by `agentId` and understand the structure of each audit event
|
|
|
|
#### Scenario: Developer understands audit log retention
|
|
- **WHEN** the developer reads the guide
|
|
- **THEN** they SHALL understand that free-tier audit logs are retained for 90 days and what happens after that window
|