## ADDED Requirements

### Requirement: Service deep-dive documents
The system SHALL include a document (`docs/engineering/05-services.md`) providing a deep-dive reference for every core service and component, following a consistent template: Purpose → Responsibility boundary → Public interface → Key methods → Database schema (if applicable) → Error types → Configuration.

#### Scenario: AgentService documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the AgentService section covering: responsibility (agent CRUD only), public methods (createAgent, getAgent, listAgents, updateAgent, deleteAgent), the `agents` table schema, AgentNotFoundError and AgentAlreadyExistsError, and what AgentService does NOT do (no auth, no credentials — Single Responsibility)

#### Scenario: OAuth2Service documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the OAuth2Service section covering: responsibility (token issuance and revocation only), public methods (issueToken, validateToken, revokeToken), Redis token storage schema, JWT payload structure, token TTL configuration, and the Vault credential verification path vs bcrypt path

#### Scenario: CredentialService documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the CredentialService section covering: responsibility (credential lifecycle only), public methods (generateCredential, rotateCredential, revokeCredential, listCredentials), the `credentials` table schema, bcrypt vs Vault storage decision, and the `vault_path` column purpose

#### Scenario: AuditService documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the AuditService section covering: responsibility (immutable audit logging only), public methods (logEvent, queryLogs), the `audit_logs` table schema, event types enum, 90-day retention policy, and why audit records are never updated or deleted

#### Scenario: VaultClient documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the VaultClient section covering: purpose (wraps node-vault for KV v2 operations), public methods (writeSecret, readSecret, verifySecret, deleteSecret), the opt-in configuration (VAULT_ADDR env var), and the constant-time comparison in verifySecret and why it matters (timing attack prevention)

#### Scenario: OPA policy engine documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the OPA section covering: purpose (dynamic access control beyond static OAuth scopes), how policies are loaded, how authorization decisions are made, the policy file locations, and how to write and test a new policy

#### Scenario: Web Dashboard documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the Web Dashboard section covering: React 18 + Vite 5 + TypeScript structure, how it authenticates against the AgentIdP API, the main views (agent list, credential management, audit log viewer, policy editor), and how to run it locally

#### Scenario: Monitoring stack documented
- **WHEN** a new engineer reads 05-services.md
- **THEN** they SHALL find the monitoring section covering: Prometheus metrics exposed by the API server (`/metrics`), the key metrics (request count, latency histograms, active tokens, agent count), Grafana dashboard structure, and how to add a new metric to the API server

#### Scenario: Consistent template enforced
- **WHEN** a new engineer looks up any service
- **THEN** every service section SHALL follow the same template so the engineer knows exactly where to find each type of information