meridianhub · bjcoombs · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026 · Mar 5, 2026
diff --git a/README.md b/README.md
@@ -24,76 +24,32 @@ Now you're maintaining a financial system — and you're not a financial company
 
 ## How It Works
 
-You write business logic in [Starlark](https://github.com/google/starlark-go)
-(a deterministic Python subset — no imports, no filesystem, no network).
-Meridian runs it on a double-entry ledger with automatic compensation on failure.
-
-```python
-deposit_saga = saga(name="current_account_deposit")
-
-def execute_deposit():
-    amount = Decimal(input_data["amount"])
-    account_id = input_data["account_id"]
-
-    step(name="log_position")
-    position_keeping.initiate_log(
-        position_id=account_id,
-        amount=amount,
-        currency=input_data["currency"],
-        direction="CREDIT",
-        transaction_id=input_data["transaction_id"],
-    )
-
-    step(name="post_to_ledger")
-    financial_accounting.capture_posting(
-        account_id=account_id,
-        amount=amount,
-        currency=input_data["currency"],
-        direction="CREDIT",
-        transaction_id=input_data["transaction_id"],
-    )
-
-execute_deposit()
-```
-
-When you need revenue splits across participants, the same engine handles it:
-
-```python
-def execute_distribution():
-    total = Decimal(input_data["total_amount"])
-
-    step(name="list_participants")
-    participants = party.list_participants(org_id=input_data["org_id"])
-
-    for p in participants:
-        share = Decimal(str(p["metadata"]["allocation_share"]))
-        account_ref = build_org_account_ref(
-            party_id=p["party_id"],
-            org_id=input_data["org_id"],
-            currency="GBP",
-        )
-        account_id = resolve_account(reference=account_ref)
-
-        step(name="credit_" + p["party_id"])
-        position_keeping.initiate_log(
-            position_id=account_id,
-            amount=total * share,
-            currency="GBP",
-            direction="CREDIT",
-            transaction_id=input_data["transaction_id"],
-        )
-```
+Define your economy in a declarative manifest — instruments, account types, and
+settlement rules. Meridian provisions the ledger, enforces double-entry
+bookkeeping, and handles compensation when something fails.
 
-Validation and pricing rules use [CEL](https://cel.dev/) expressions:
+```bash
+# Register a customer
+curl -X POST http://localhost:8090/v1/parties \
+  -H "X-Tenant-ID: default" \
+  -d '{"partyType": "PARTY_TYPE_PERSON", "legalName": "Alice Smith"}'
 
-```cel
-// Enforce daily spending limit
-transaction.amount <= account.daily_limit - account.daily_spent
+# Open an account
+curl -X POST http://localhost:8090/v1/current-accounts \
+  -H "X-Tenant-ID: default" \
+  -d '{"partyId": "...", "baseCurrency": "CURRENCY_GBP"}'
 
-// Time-of-use pricing
-rate_schedule.lookup(timestamp.hour) * quantity
+# Deposit — ledger entries, position updates, and audit trail created atomically
+ACCOUNT_ID="<account-id-from-above>"
+curl -X POST "http://localhost:8090/v1/current-accounts/$ACCOUNT_ID/deposits" \
+  -H "X-Tenant-ID: default" \
+  -d '{"amount": {"amount": {"currencyCode": "GBP", "units": "100"}}}'
 ```
 
+Behind the scenes, each operation runs as a **saga** — a multi-step workflow
+that either completes fully or compensates automatically. Sagas are written in
+sandboxed scripts that Meridian validates before execution.
+
 ## What's Built
 
 - **Double-entry ledger** with immutable, bi-temporal audit trail
@@ -302,13 +258,20 @@ Built on [BIAN](https://bian.org/) banking service domain patterns.
 | **CurrentAccount** | Customer accounts, transaction orchestration |
 | **PositionKeeping** | Pre-ledger transaction log, position tracking |
 | **FinancialAccounting** | Double-entry bookkeeping |
-| **PaymentOrder** | Saga orchestration, settlement, Stripe integration |
-| **MarketInformation** | Pricing data with quality ladder (estimate / actual / verified) |
+| **PaymentOrder** | Settlement, Stripe Connect integration |
 | **Party** | Customer data, identity verification |
+| **MarketInformation** | Pricing data with quality ladder (estimate / actual / verified) |
 | **Reconciliation** | Variance detection, dispute management |
-| **ControlPlane** | Tenant management, billing configuration |
-
-See [docs/adr/](docs/adr/) for architectural decisions.
+| **Forecasting** | Forward curves and forecast generation |
+| **ControlPlane** | Tenant management, manifest configuration, Stripe billing |
+| **EventRouter** | CEL-filtered event routing, saga triggering |
+| **FinancialGateway** | External payment provider dispatch and reconciliation |
+| **OperationalGateway** | Non-financial outbound dispatch (KYC, IoT, partner) |
+| **Identity** | OIDC authentication and identity provider integration |
+| **MCP Server** | AI assistant integration via Model Context Protocol |
+
+See [services/README.md](services/README.md) for the full architecture diagram
+and [docs/adr/](docs/adr/) for architectural decisions.
 
 ## Technology
 

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