merge queue: embarking main (e862bec), #189, #207 and #225 together

docs-cms/adr/index.md

@@ -9,6 +9,66 @@ slug: /
 
 Architecture Decision Records document significant architectural choices made in Prism. Each ADR captures the problem context, decision rationale, alternatives considered, and consequences—creating a historical record of "why" behind the architecture.
 
+## Prism Architecture at 10,000 Meters
+
+```mermaid
+flowchart TB
+    subgraph Clients["Client Applications"]
+        App1["Service A"]
+        App2["Service B"]
+        App3["Service C"]
+    end
+
+    subgraph Proxy["Prism Proxy (Rust)"]
+        direction TB
+        API["Unified gRPC/HTTP API"]
+        Router["Request Router"]
+        Auth["Auth & Policy<br/>(mTLS, OAuth2)"]
+    end
+
+    subgraph Patterns["Pattern Layer (Go)"]
+        KV["KeyValue"]
+        PS["PubSub"]
+        Q["Queue"]
+        TS["TimeSeries"]
+        Composite["Composite Patterns<br/>(Outbox, CDC, Claim-Check)"]
+    end
+
+    subgraph Backends["Backend Drivers"]
+        Kafka["Kafka"]
+        Postgres["Postgres"]
+        Redis["Redis"]
+        NATS["NATS"]
+        S3["S3/MinIO"]
+    end
+
+    subgraph Config["Configuration"]
+        NS["Namespace<br/>Requests"]
+        Policy["Platform<br/>Policy"]
+        Registry["Backend<br/>Registry"]
+    end
+
+    Clients --> Proxy
+    API --> Router
+    Router --> Auth
+    Auth --> Patterns
+    Patterns --> Backends
+    Config -.-> Proxy
+    Config -.-> Patterns
+
+    style Clients fill:#e3f2fd,stroke:#1565c0
+    style Proxy fill:#fff8e1,stroke:#f57f17
+    style Patterns fill:#f3e5f5,stroke:#7b1fa2
+    style Backends fill:#e8f5e9,stroke:#2e7d32
+    style Config fill:#fce4ec,stroke:#c2185b
+```
+
+**Key architectural decisions**:
+- **[ADR-001](/adr/adr-001)**: Rust proxy for 10-100x performance over JVM
+- **[ADR-002](/adr/adr-002)**: Client-originated configuration for self-service
+- **[ADR-003](/adr/adr-003)**: Protobuf as single source of truth
+- **[ADR-005](/adr/adr-005)**: Pluggable backend architecture
+
 ## 🎯 New to Prism? Start Here
 
 If you're exploring Prism's architecture, start with these foundational decisions:

docs/.gitignore

@@ -0,0 +1,39 @@
+# docs/.gitignore - GitHub Pages Build Output Directory
+#
+# CRITICAL: This directory contains BUILD OUTPUT ONLY (except img/)
+#
+# - Build output is generated by CI (docusaurus build --out-dir ../docs)
+# - NEVER manually commit HTML/JS/CSS files from this directory
+# - Source documentation is in docusaurus/docs/ and docs-cms/
+#
+# What IS allowed (tracked in git):
+# - .nojekyll (required by GitHub Pages to bypass Jekyll processing)
+# - CNAME (custom domain configuration, if used)
+# - .gitattributes (git attributes for docs/, if needed)
+# - This .gitignore file itself
+# - img/ directory and all images (logos, icons, etc.)
+
+# Ignore HTML pages (all generated)
+*.html
+
+# Ignore generated search index and sitemap
+search-index.json
+sitemap.xml
+
+# Ignore generated directories (docusaurus output)
+/adr/
+/rfc/
+/memos/
+/user-guide/
+/search/
+/netflix/
+/prds/
+/docs/
+
+# Ignore generated JS/CSS in assets/
+/assets/css/
+/assets/js/
+
+# Allow img/ directory and all images
+!/img/
+!/img/**

docusaurus/docs/intro.md

@@ -27,21 +27,29 @@ Recent highlights:
 
 **Three layers separate what, how, and where**:
 
-```
-┌────────────────────────────────────┐
-│   Client API (What)                │  Applications use stable APIs
-│   KeyValue | PubSub | Queue        │
-└────────────────────────────────────┘
-               ↓
-┌────────────────────────────────────┐
-│   Patterns (How)                   │  Prism applies reliability patterns
-│   Outbox | CDC | Claim Check       │
-└────────────────────────────────────┘
-               ↓
-┌────────────────────────────────────┐
-│   Backends (Where)                 │  Data stored in optimal backend
-│   Kafka | Postgres | Redis | NATS  │
-└────────────────────────────────────┘
+```mermaid
+flowchart TB
+    subgraph L1["Client API (What)"]
+        A1["Applications use stable APIs"]
+        A2["KeyValue | PubSub | Queue"]
+    end
+
+    subgraph L2["Patterns (How)"]
+        B1["Prism applies reliability patterns"]
+        B2["Outbox | CDC | Claim Check"]
+    end
+
+    subgraph L3["Backends (Where)"]
+        C1["Data stored in optimal backend"]
+        C2["Kafka | Postgres | Redis | NATS"]
+    end
+
+    L1 --> L2
+    L2 --> L3
+
+    style L1 fill:#e1f5fe,stroke:#01579b
+    style L2 fill:#fff3e0,stroke:#e65100
+    style L3 fill:#e8f5e9,stroke:#1b5e20
 ```
 
 **Benefits**:

docusaurus/docs/key.md

@@ -143,6 +143,28 @@ Same pattern works with Redis+NATS+Postgres OR DynamoDB+SNS+SQS by swapping Laye
 
 ---
 
+### Phase 3.5: Configuration Model (10 min)
+
+**Read**: [Configuration Overview](/docs/configuration/overview)
+
+**Why read this**: Understand the 6-layer configuration model that separates user needs from platform implementation.
+
+**The six layers**:
+1. **User Request** (Layer 1) - Applications declare needs via namespace configuration
+2. **Platform Policy** (Layer 2) - Teams have permission levels (Guided, Advanced, Expert)
+3. **Pattern Selection** (Layer 3) - Prism automatically selects patterns based on requirements
+4. **Backend Registry** (Layer 4) - Operators register available backends
+5. **Frontend Registry** (Layer 5) - API protocol bindings (REST, gRPC, GraphQL)
+6. **Runtime Execution** (Layer 6) - Pattern runners and proxy configuration
+
+**Key documents**:
+- [Namespace Configuration](/docs/configuration/namespace-request) - How applications declare needs
+- [Backend Registry](/docs/configuration/backend-registry) - Available backends and capabilities
+- [Slot Matching](/docs/configuration/slot-matching) - How patterns bind to backends
+- [RFC-056: Unified Configuration Model](/rfc/rfc-056) - Complete specification
+
+---
+
 ### Phase 4: Implementation Roadmap (10 min)
 
 #### [RFC-018: POC Implementation Strategy](/rfc/rfc-018) (7 min)
@@ -196,16 +218,17 @@ Same pattern works with Redis+NATS+Postgres OR DynamoDB+SNS+SQS by swapping Laye
 
 ## Your Reading Path
 
-### New to Prism? (35 min)
+### New to Prism? (45 min)
 
 Follow this sequence to build complete understanding:
 
 1. **Vision** (10 min): [PRD](/prds/prd-001)
 2. **Decisions** (15 min): [ADR-001](/adr/adr-001), [ADR-002](/adr/adr-002), [ADR-003](/adr/adr-003), [ADR-004](/adr/adr-004)
 3. **Architecture** (10 min): [MEMO-006](/memos/memo-006)
-4. **Development** (5 min): [CLAUDE.md](https://github.com/jrepp/prism-data-layer/blob/main/CLAUDE.md)
+4. **Configuration** (10 min): [Configuration Overview](/docs/configuration/overview)
+5. **Development** (5 min): [CLAUDE.md](https://github.com/jrepp/prism-data-layer/blob/main/CLAUDE.md)
 
-**After this**: You'll understand Prism's vision, technical foundation, architecture, and development practices.
+**After this**: You'll understand Prism's vision, technical foundation, architecture, configuration model, and development practices.
 
 ---
 
@@ -243,6 +266,7 @@ Understand the decision-making context:
 | [PRD](/prds/prd-001) | Product vision | Onboarding, strategic decisions |
 | [ADR-001](/adr/adr-001) - [ADR-004](/adr/adr-004) | Core decisions | Understanding technical foundation |
 | [MEMO-006](/memos/memo-006) | Three-layer architecture | Designing patterns, understanding backend abstraction |
+| [Configuration Overview](/docs/configuration/overview) | 6-layer config model | Understanding namespace configuration |
 | [RFC-018](/rfc/rfc-018) | POC roadmap | Planning implementation work |
 | [CLAUDE.md](https://github.com/jrepp/prism-data-layer/blob/main/CLAUDE.md) | Development guide | Daily development, code reviews |
 
@@ -274,4 +298,4 @@ This guide evolves as the project grows. When adding foundational documents:
 
 *Reading time estimates assume focused reading with note-taking. Skim faster if reviewing familiar concepts.*
 
-*Last updated: 2025-10-14*
+*Last updated: 2025-11-25*