docs: update alerting docs (AlertManager) and add key rotation API

[OneStepAt4time]

Summary

Updates docs for v0.5.0-alpha:

docs/enterprise.md — AlertManager

• Replaced outdated "no built-in alerting" statement with actual AlertManager docs
• Added endpoint documentation
• Added endpoint documentation
• Documented what AlertManager monitors: session failures, dead sessions, tmux crashes

docs/api-reference.md — Key Rotation

• Added endpoint (admin-only)
• Documents optional parameter
• Returns updated key metadata

Changes

• 2 files changed, +30/-1 lines
• No code examples changed
• Version: 0.5.0-alpha

Checklist

• AlertManager documented with actual endpoints
• Key rotation endpoint added to API reference
• Old "no built-in alerting" statement removed
• Version: 0.5.0-alpha

---

Aegis version: 0.5.0-alpha
Milestone: Documentation
Assignee: Scribe

[OneStepAt4time]

📋 Documentation Review: Critical Issues Found

🔴 CRITICAL ERRORS - Must Fix Before Merge

1. API Key Rotation Parameter Mismatch

Problem: Docs show incorrect parameter format

• Docs claim: {"expiresAt":"2025-12-31T23:59:59Z"} (ISO timestamp)
• Actual code: Expects ttlDays (positive integer)

Current cURL example (WRONG):

curl -X POST http://localhost:9100/v1/auth/keys/key-abc123/rotate \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresAt":"2025-12-31T23:59:59Z"}'

Should be:

curl -X POST http://localhost:9100/v1/auth/keys/key-abc123/rotate \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttlDays": 365}'

Code reference: src/server.ts line 660-670 defines rotateKeySchema with ttlDays: z.number().int().positive().optional()

---

2. Alert Test Endpoint Request Body is Incorrect

Problem: Documentation falsely claims test endpoint accepts webhookUrl and secret parameters

• Docs show: {"webhookUrl":"https://example.com/alerts","secret":"test-secret"}
• Actual code: Takes NO request body — fires test alert to pre-configured webhooks only

Current cURL example (WRONG):

curl -X POST http://localhost:9100/v1/alerts/test \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://example.com/alerts","secret":"test-secret"}'

Should be:

curl -X POST http://localhost:9100/v1/alerts/test \
  -H "Authorization: Bearer $AEGIS_AUTH_TOKEN"

Code reference: src/server.ts line 563-572 shows no body schema validation, calls alertManager.fireTestAlert() which ignores request body

---

🟡 IMPORTANT GAPS - Should Fix

3. Missing Authorization Requirements Documentation

Add to AlertManager section:

• POST /v1/alerts/test requires: admin or operator role
• GET /v1/alerts/stats requires: admin, operator, or viewer role

Code reference: src/server.ts lines 563 and 576

---

4. Incomplete Alert Type Coverage

Current docs list: session failures, dead sessions, tmux crashes
Actual supported types: session_failure, tmux_crash, api_error_rate (missing from docs)

Add to "AlertManager monitors" list:

• Session failures (crashes, unexpected exits)
• Dead sessions (tmux process gone)
• Tmux crashes
• API error rate threshold breaches

Code reference: src/alerting.ts line 14 defines all three alert types

---

5. Missing Environment Variable Configuration Details

Current docs: "Configure via config.yaml or environment variables"
Should specify: The actual environment variable name and format

Add documentation for:

export AEGIS_ALERT_WEBHOOKS="https://example.com/alerts,https://backup.com/alerts"

Or via config.yaml:

alerting:
  webhooks:
    - https://example.com/alerts
  failureThreshold: 5
  cooldownMs: 600000

---

✅ What's Correct

• Endpoint paths are accurate
• Admin-only role mention for key rotation is correct
• Overall AlertManager documentation structure is good
• Webhook payload description matches implementation

---

Summary

Status: ⛔ Needs Changes

• 2 critical parameter mismatches (API rotation + alert test)
• 3 documentation gaps (permissions, alert types, env vars)
• Tests will fail if users copy-paste these examples

Requesting changes on:

1. docs/api-reference.md — Fix rotation endpoint request format
2. docs/enterprise.md — Fix test endpoint example + add permissions + add api_error_rate + add env var docs

[OneStepAt4time]

✅ Documentation Issues Fixed

I've corrected all the issues identified in the review:

Fixed (2 Critical Issues):

1. ✅ API Key Rotation Parameter — Changed from {"expiresAt":"2025-12-31T23:59:59Z"} to {"ttlDays": 365}
2. ✅ Alert Test Endpoint — Removed false request body parameters (webhookUrl, secret)

Added (3 Documentation Gaps):

3. ✅ Authorization Requirements — Documented role requirements for both endpoints
4. ✅ API Error Rate Alert Type — Added to "AlertManager monitors" list
5. ✅ Configuration Examples — Added env vars and config.yaml format

Status: All corrections pushed to branch. PR now contains accurate, working documentation.

Files modified:

• docs/api-reference.md — API key rotation endpoint fixed
• docs/enterprise.md — AlertManager documentation completed

[OneStepAt4time]

✅ PR Rebased and Ready to Merge

The PR has been rebased onto the latest develop branch to resolve staleness issues.

Status:

• ✅ Rebased to latest develop (9f30530)
• ✅ No merge conflicts
• ✅ All documentation fixes preserved (2 commits)
• ✅ CI checks running

Commits on this PR:

1. 00d4277 - docs: update alerting docs (AlertManager) and add key rotation API
2. 16e7622 - fix: correct AlertManager and key rotation API documentation

What was fixed:

• API key rotation parameter corrected to ttlDays
• Alert test endpoint body parameters removed
• Authorization requirements documented
• Missing alert type added
• Configuration examples included

The PR is now mergeable and ready for approval.