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/engineering/04-codebase-structure.md

@@ -28,9 +28,15 @@ sentryagent-idp/
 ├── sdk-python/                # Python SDK (sentryagent-idp) — sync + async clients
 ├── sdk-go/                    # Go SDK (github.com/sentryagent/idp-sdk-go) — context-aware, goroutine-safe
 ├── sdk-java/                  # Java SDK (ai.sentryagent:idp-sdk) — builder pattern, CompletableFuture
+├── sdk-rust/                  # Rust SDK (sentryagent-idp crate) — async, tokio, reqwest, typed errors
 ├── policies/                  # OPA policy files
 │   ├── authz.rego             # Rego policy — normalise_path + scope-intersection allow rule
 │   └── data/scopes.json       # Endpoint permission map — used by Rego and TypeScript fallback
+├── portal/                    # Developer Portal — Next.js 14 App Router, Tailwind CSS
+│   ├── app/                   # Next.js App Router pages (get-started, pricing, sdks, analytics, settings, login)
+│   ├── components/            # Shared UI components (Nav.tsx, SwaggerExplorer.tsx, GetStartedWizard.tsx)
+│   ├── hooks/                 # React hooks (useAuth.ts)
+│   └── types/                 # TypeScript type definitions for portal-only types
 ├── terraform/                 # Terraform infrastructure as code
 │   ├── modules/               # Reusable modules: agentidp, lb, rds, redis
 │   └── environments/          # Environment configs: aws/ (ECS+RDS+ElastiCache), gcp/ (Cloud Run+SQL+Memorystore)
@@ -44,6 +50,11 @@ sentryagent-idp/
 │   ├── agntcy/                # AGNTCY alignment documentation
 │   └── openapi/               # OpenAPI 3.0 specification files
 ├── openspec/                  # OpenSpec change management — proposals, designs, specs, tasks, archives
+├── tests/                     # Jest test suite — mirrors src/ structure
+│   ├── unit/                  # Unit tests (mocked dependencies) — mirrors src/
+│   ├── integration/           # Integration tests (real DB + Redis)
+│   ├── agntcy-conformance/    # AGNTCY conformance test suite (separate Jest config)
+│   └── load/                  # k6 load test scripts
 ├── Dockerfile                 # Multi-stage production build (build + runtime stages)
 ├── docker-compose.yml         # Local development: PostgreSQL 14 (port 5432) + Redis 7 (port 6379)
 ├── docker-compose.monitoring.yml  # Monitoring overlay: Prometheus (port 9090) + Grafana (port 3001)
@@ -69,6 +80,8 @@ sentryagent-idp/
 | `src/metrics/` | Prometheus metrics registry — all `Counter` and `Histogram` definitions in one place | Only file that calls `new Counter()` or `new Histogram()`; all other files import from here |
 | `src/db/` | PostgreSQL connection pool factory (`pool.ts`) and numbered SQL migration files in `migrations/` | Pool is a singleton created once in `src/app.ts` and passed to repositories |
 | `src/cache/` | Redis client factory — creates and caches a single `redis` client instance | Client is a singleton created once in `src/app.ts` and passed to repositories |
+| `src/config/` | Configuration constants — `tiers.ts` exports `TIER_CONFIG`, `TIER_RANK`, `TierName`, and `isTierName()` type guard | Imported by `TierService` and `tierMiddleware`; never imports from services |
+| `src/middleware/tier.ts` | Tier enforcement middleware — reads org tier from `TierService`, checks daily call counter in Redis, throws `TierLimitError` (429) when limit is exceeded, increments counter on pass | Applied only to API routes; skips `/health`, `/metrics`, and static file routes |
 
 ---
 
@@ -84,6 +97,10 @@ sentryagent-idp/
 | A new environment variable | `src/utils/config.ts` (if it exists) or the relevant consumer file + `docs/devops/environment-variables.md` | `RATE_LIMIT_MAX` controlling the rate-limit ceiling |
 | A new Prometheus metric | `src/metrics/registry.ts` | A `Histogram` for Vault lookup duration |
 | A new TypeScript type used in 2+ files | `src/types/index.ts` | A new `AgentGroupMembership` interface |
+| A new tier-gated feature | `src/config/tiers.ts` (add limit field) + `src/middleware/tier.ts` (add check) + service (enforce) | Adding a `maxWebhooksPerOrg` tier limit |
+| A webhook event handler | `src/services/WebhookService.ts` (add event type to `WebhookEventType`) + the producer that calls `void webhookService.dispatch(orgId, eventType, payload)` | Emitting `agent.decommissioned` events to subscriber URLs |
+| A new analytics metric type | `src/services/AnalyticsService.ts` (call `recordEvent(tenantId, 'new_metric')` in the relevant service using `void`) | Recording `credential_rotated` events for analytics |
+| A new DID endpoint | `src/controllers/DIDController.ts` + `src/routes/did.ts` + `src/services/DIDService.ts` (if new method needed) + `policies/data/scopes.json` | Adding `GET /api/v1/agents/:id/did/rotate-key` |
 
 ---