sentryagent-idp/openspec/changes/bedroom-developer-docs/specs/developer-guides/spec.md

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