meridianhub · bjcoombs · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026
diff --git a/docs/demo/ARCHITECTURE.md → docs/archive/ARCHITECTURE.md b/docs/demo/ARCHITECTURE.md → docs/archive/ARCHITECTURE.md
diff --git a/docs/demo/DEMO_GUIDE.md → docs/archive/DEMO_GUIDE.md b/docs/demo/DEMO_GUIDE.md → docs/archive/DEMO_GUIDE.md
diff --git a/docs/archive/README.md b/docs/archive/README.md
@@ -9,6 +9,13 @@ historical context but superseded by actual implementation.
 - **immutability-audit.md** - Analysis document from code review. Implementation details now covered in CONTRIBUTING.md
 under Code Standards.
 - **rbac-testing-guide.md** - RBAC testing guidance. Content has been integrated into relevant test documentation.
+- **audit-analysis-findings.md** - One-time audit analysis report. Findings have been addressed.
+- **panic-audit-inventory.md** - One-time panic audit inventory. Findings have been addressed.
+- **ARCHITECTURE.md** - Early demo architecture diagram describing a 2-service system.
+  Superseded by `services/README.md` and production deployment runbook.
+- **DEMO_GUIDE.md** - Early demo walkthrough. Superseded by current demo environment docs.
+- **authentication-integration.md** - Auth integration guide referencing old
+  `internal/platform/auth` path and Keycloak. Superseded by identity service.
 
 ## When to Archive
 

diff --git a/docs/audit-analysis-findings.md → docs/archive/audit-analysis-findings.md b/docs/audit-analysis-findings.md → docs/archive/audit-analysis-findings.md
diff --git a/docs/authentication-integration.md → docs/archive/authentication-integration.md b/docs/authentication-integration.md → docs/archive/authentication-integration.md
diff --git a/docs/panic-audit-inventory.md → docs/archive/panic-audit-inventory.md b/docs/panic-audit-inventory.md → docs/archive/panic-audit-inventory.md
diff --git a/docs/guides/new-bian-service-checklist.md b/docs/guides/new-bian-service-checklist.md
@@ -757,7 +757,7 @@ func TestIntegration(t *testing.T) {
         t.Skip("skipping integration test")
     }
 
-    db, cleanup := testdb.SetupPostgres(t, []interface{}{&persistence.{Entity}Entity{}})
+    db, cleanup := testdb.SetupCockroachDB(t, []interface{}{&persistence.{Entity}Entity{}})
     defer cleanup()
 
     repo := persistence.NewRepository(db)

diff --git a/docs/guides/starlark-built-ins-reference.md b/docs/guides/starlark-built-ins-reference.md
@@ -7,7 +7,7 @@
 **Related:**
 
 - **[Style Guide](starlark-style-guide.md)** - Syntax and conventions
-- **[Patterns](../starlark-patterns.md)** - Common workflow patterns
+- **[Patterns](./manifest-design-patterns.md)** - Common workflow patterns
 - **[Service Catalog](../saga-service-catalog.md)** - Service module handlers
 
 ---
@@ -638,4 +638,4 @@ assert.Equal(t, "COMPLETED", result["status"])
 - **[CEL Specification](https://github.com/google/cel-spec)** - Expression language
 - **[handlers.yaml](../../shared/pkg/saga/schema/handlers.yaml)** - Service module API
 - **[Style Guide](starlark-style-guide.md)** - Conventions and best practices
-- **[Patterns](../starlark-patterns.md)** - Common workflow patterns
+- **[Patterns](./manifest-design-patterns.md)** - Common workflow patterns
diff --git a/docs/guides/testcontainers-usage.md b/docs/guides/testcontainers-usage.md
@@ -1,19 +1,19 @@
 # Testcontainers Usage Guide
 
-This guide describes how to use testcontainers for PostgreSQL integration tests across Meridian services.
+This guide describes how to use testcontainers for CockroachDB integration tests across Meridian services.
 
-**Shared utility**: `shared/platform/testdb/` - Provides reusable testcontainer setup for all services.
+**Shared utility**: `shared/platform/testdb/` - Provides reusable testcontainer setup for all services via `testdb.SetupCockroachDB`.
 
 The examples below use position-keeping but the pattern applies to all services.
 
 ## Overview
 
 The testhelpers package implements a complete testing environment with:
 
-- **Isolated PostgreSQL containers** - Each test gets its own database
-- **Automatic schema setup** - Position-keeping schema loaded automatically
-- **Connection pooling** - pgx connection pool configured and ready
-- **Repository instances** - Pre-configured PostgresRepository for immediate use
+- **Isolated CockroachDB containers** - Each test gets its own database
+- **Automatic schema setup** - Service schema loaded automatically
+- **GORM database handle** - Configured and ready for repository use
+- **Repository instances** - Pre-configured repository for immediate use
 - **Proper cleanup** - Automatic container termination and resource management
 
 ## Quick Start
@@ -90,10 +90,9 @@ deleted.
 
 ## Container Configuration
 
-- **Image**: postgres:16-alpine
-- **Database**: test_position_keeping
-- **User**: test / test
-- **Wait Strategy**: Wait for "database system is ready" (2 occurrences, 30s timeout)
+- **Image**: CockroachDB (via testcontainers)
+- **Database**: Service-specific test database
+- **Wait Strategy**: Container readiness check with timeout
 - **Connection**: SSL disabled for test performance
 
 ## Performance

diff --git a/docs/runbooks/production-deployment.md b/docs/runbooks/production-deployment.md
@@ -209,7 +209,7 @@ SERVICES=(
   "gateway"
   "internal-account"
   "market-information"
-  "utilization-metering-consumer"
+  "event-router"
 )
 
 # Note: reference-data is a library embedded in other services, not a standalone deployment.
@@ -370,7 +370,7 @@ flowchart TD
     subgraph Tier4["Tier 4: Edge and Supporting Services"]
         GW["Gateway :8080"]
         AW["AuditWorker :8080"]
-        UMC["UtilizationMeteringConsumer :8080"]
+        ER["EventRouter :8080"]
         AC["AuditConsumers :8080"]
     end
 
@@ -386,7 +386,7 @@ flowchart TD
     GW --> PO
     GW --> Party
     GW --> MI
-    UMC --> PK
+    ER --> PK
 ```
 
 ### Tier 1: Platform Services
@@ -479,8 +479,8 @@ done
 3. **Audit Consumers** -- Per-service Kafka consumers that write audit events to `audit_log` tables.
    One deployment per domain service.
 
-4. **Utilization Metering Consumer** (:8080) -- Consumes audit events from all services for
-   platform billing. Records measurements to Position Keeping's tenant-zero.
+4. **Event Router** (:8080) -- CEL-filtered saga dispatcher. Consumes domain events from Kafka
+   and triggers saga workflows. Also handles platform billing via utilization metering.
 
 ```bash
 # Deploy Gateway
@@ -496,9 +496,9 @@ for svc in current-account financial-accounting position-keeping party payment-o
   kubectl apply -k deployments/k8s/audit-consumer/overlays/${svc}
 done
 
-# Deploy Utilization Metering Consumer
-kubectl apply -k services/utilization-metering-consumer/k8s/
-kubectl wait --for=condition=Available deployment/utilization-metering-consumer -n production --timeout=120s
+# Deploy Event Router
+kubectl apply -k services/event-router/k8s/
+kubectl wait --for=condition=Available deployment/event-router -n production --timeout=120s
 ```
 
 ## 4. Health Check Verification
@@ -658,7 +658,7 @@ kubectl rollout status deployment/<service-name> -n production
 
 **Rollback order** (reverse of deployment order):
 
-1. Tier 4: Gateway, Audit Consumers, Audit Worker, Utilization Metering Consumer
+1. Tier 4: Gateway, Audit Consumers, Audit Worker, Event Router
 2. Tier 3: Payment Order, Current Account
 3. Tier 2: Financial Accounting, Position Keeping, Internal Account, Market Information
 4. Tier 1: Reference Data, Party, Tenant
@@ -725,7 +725,7 @@ kubectl scale deployment <service>-audit-consumer -n production --replicas=<prev
 | Payment Order | 50054 | 8080 | 9090 | `payment-order` |
 | Gateway | - | 8080 | 8080 | `gateway` |
 | Audit Worker | - | 8080 | 8080 | `audit-worker` |
-| Utilization Metering Consumer | - | 8080 | 8080 | `utilization-metering-consumer` |
+| Event Router | - | 8080 | 8080 | `event-router` |
 
 All gRPC services use Kubernetes DNS for service discovery:
 `<service-name>.<namespace>.svc.cluster.local:<port>`

diff --git a/docs/runbooks/saga-validation-failure.md b/docs/runbooks/saga-validation-failure.md
@@ -17,6 +17,8 @@ instructions: |
 **When to use this runbook**: Saga validation failures are reported through
 metrics, tenant support requests, or CI pipeline failures.
 
+**See also**: [Saga Validation Guide](../guides/saga-validation.md) for validation levels, usage, and security constraints.
+
 ## Quick Reference
 
 | Error Category | Typical Cause | Recovery Time | Escalation |