docs: commit all Phase 6 documentation updates and OpenSpec archives

- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook)
- developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added
- engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview)
- OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update
- VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added
- .gitignore: exclude session artifacts, build artifacts, and agent workspaces

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/developers/guides/use-analytics-dashboard.md

@@ -0,0 +1,135 @@
+# Use the Analytics Dashboard
+
+This guide explains how to query the three analytics endpoints to understand your organization's
+token usage and agent activity patterns.
+
+All analytics endpoints require Bearer token authentication and are scoped to the organization
+embedded in your token.
+
+---
+
+## Prerequisites
+
+- A running AgentIdP instance
+- A valid Bearer token with `organization_id` in its claims
+- At least one agent registered and some token issuance activity
+
+---
+
+## Token issuance trend
+
+`GET /api/v1/analytics/tokens`
+
+Returns daily token issuance counts for the past N days (default 30, max 90). Use this to
+track usage growth, identify traffic spikes, and plan capacity.
+
+```bash
+curl -s "http://localhost:3000/api/v1/analytics/tokens?days=30" \
+  -H "Authorization: Bearer $TOKEN" | jq .
+```
+
+Response:
+
+```json
+{
+  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
+  "days": 30,
+  "data": [
+    { "date": "2026-03-06", "count": 142 },
+    { "date": "2026-03-07", "count": 198 },
+    { "date": "2026-03-08", "count": 0 }
+  ]
+}
+```
+
+**Interpreting the data**: Each item in `data` is one calendar day (UTC) with the number of
+tokens issued on that day. Days with zero issuance are included with `count: 0`. The array
+is ordered chronologically, oldest first.
+
+**Using it**: Compare day-over-day counts to identify growth or anomalies. A sudden spike in
+`count` may indicate an agent retry loop or a credential leak. Zero-count days during expected
+operation may indicate a deployment issue.
+
+**Query parameter**: `days` — positive integer, max 90. Returns `400 VALIDATION_ERROR` if
+exceeded.
+
+```bash
+# Last 7 days
+curl -s "http://localhost:3000/api/v1/analytics/tokens?days=7" \
+  -H "Authorization: Bearer $TOKEN" | jq .
+
+# Last 90 days (maximum)
+curl -s "http://localhost:3000/api/v1/analytics/tokens?days=90" \
+  -H "Authorization: Bearer $TOKEN" | jq .
+```
+
+---
+
+## Agent activity heatmap
+
+`GET /api/v1/analytics/agents/activity`
+
+Returns request counts grouped by day-of-week (0 = Sunday, 6 = Saturday) and hour (0–23, UTC).
+Use this to identify peak usage windows for capacity planning and rate limit tuning.
+
+```bash
+curl -s "http://localhost:3000/api/v1/analytics/agents/activity" \
+  -H "Authorization: Bearer $TOKEN" | jq .
+```
+
+Response:
+
+```json
+{
+  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
+  "data": [
+    { "dow": 1, "hour": 9, "count": 54 },
+    { "dow": 1, "hour": 10, "count": 87 },
+    { "dow": 3, "hour": 14, "count": 201 }
+  ]
+}
+```
+
+**Interpreting the data**: `dow` is 0 (Sunday) through 6 (Saturday). `hour` is 0–23 UTC.
+Only non-zero cells are returned — missing combinations had zero activity. Sort by `count`
+descending to find your peak windows.
+
+**Using it**: If most activity is on weekday mornings UTC, ensure your rate limit headroom
+covers that window. If weekend activity is unexpectedly high, investigate which agents are
+active.
+
+---
+
+## Per-agent usage summary
+
+`GET /api/v1/analytics/agents`
+
+Returns token issuance counts per agent for the current calendar month (UTC). Use this to
+identify your most active agents and check if any single agent is consuming a
+disproportionate share of your monthly token budget.
+
+```bash
+curl -s "http://localhost:3000/api/v1/analytics/agents" \
+  -H "Authorization: Bearer $TOKEN" | jq .
+```
+
+Response:
+
+```json
+{
+  "tenantId": "org-0a1b2c3d-e4f5-6789-abcd-ef0123456789",
+  "month": "2026-04",
+  "data": [
+    { "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "tokenCount": 312 },
+    { "agentId": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "tokenCount": 87 }
+  ]
+}
+```
+
+**Interpreting the data**: Each item shows an agent UUID and the number of tokens it has
+issued this month. The response covers the full current calendar month from day 1 to now.
+It resets on the first day of each month.
+
+**Using it**: Cross-reference `agentId` values against `GET /api/v1/agents` to identify which
+agents by name. If one agent accounts for >80% of usage, investigate whether it is token
+caching correctly or requesting tokens unnecessarily.