docs(website): update architecture and relay docs for RLS and key.Binding (#876)

## Summary

- **architecture.md**: Fix stale "kong" CLI framework reference (now
Cobra), document `key.Binding` / `AppKeyMap` migration in key dispatch
section and data flow diagram
- **relay-architecture.md**: Add "Row-level security" section covering
RLS policies, `rlsdb` package (`Tx` / `WithoutHousehold`), and protected
tables matrix; add `rlsdb/` to package layout; cross-reference RLS in
schema section
- **self-hosting.md**: Add brief RLS callout with `relref` link to the
relay architecture page

Generated with [Claude Code](https://claude.ai/code)

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cpcloud

docs/content/docs/development/architecture.md

@@ -11,10 +11,10 @@ application following The Elm Architecture (TEA): Model, Update, View.
 ## Package layout
 
 ```
-cmd/micasa/          CLI entry point (kong argument parsing)
+cmd/micasa/          CLI entry point (Cobra argument parsing)
 internal/
   app/               Bubble Tea application layer
-    model.go         Model struct, Init, Update, key dispatch
+    model.go         Model struct, Init, Update, key dispatch (key.Binding)
     types.go         Mode, Tab, cell, columnSpec, etc.
     handlers.go      TabHandler interface + entity implementations
     tables.go        Column specs, row builders, table construction
@@ -68,8 +68,9 @@ free.
 
 ### Modal key handling
 
-micasa uses three modes: Nav, Edit, and Form. The key dispatch chain in
-`Update()` is:
+micasa uses three modes: Nav, Edit, and Form. Key dispatch uses structured
+`key.Binding` / `key.Matches()` from bubbles, centralized in an `AppKeyMap`
+struct. The dispatch chain in `Update()` is:
 
 1. Window resize handling
 2. <kbd>ctrl+q</kbd> always quits
@@ -115,7 +116,7 @@ roles are defined in `styles.go`.
 User keystroke
   -> tea.KeyMsg
   -> Model.Update()
-  -> key dispatch (mode-aware)
+  -> key dispatch (mode-aware, via key.Matches)
   -> data mutation (Store CRUD)
   -> reloadAfterMutation() (refreshes effective tab, marks others stale)
   -> Model.View()

docs/content/docs/development/relay-architecture.md

@@ -1,7 +1,7 @@
 +++
 title = "Encrypted Relay"
 weight = 3
-description = "How the sync relay works: store interface, auth, encryption, key exchange."
+description = "How the sync relay works: store interface, auth, encryption, key exchange, row-level security."
 linkTitle = "Encrypted Relay"
 +++
 
@@ -136,6 +136,63 @@ Documents are synced as encrypted blobs, separate from the oplog:
 - Oplog entries reference blobs via `blob_ref` field, which is
   stripped before applying to the local database
 
+## Row-level security
+
+The relay enforces tenant isolation at the database level using
+[Postgres row-level security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html)
+(RLS). Even if application code has a bug, one household's data
+cannot leak to another.
+
+### How it works
+
+RLS policies on `ops` and `blobs` restrict every query to rows
+matching the current session's `app.household_id`:
+
+```sql
+CREATE POLICY ops_household_isolation ON ops
+  USING (household_id = NULLIF(current_setting('app.household_id', true), ''))
+  WITH CHECK (household_id = NULLIF(current_setting('app.household_id', true), ''));
+```
+
+`FORCE ROW LEVEL SECURITY` ensures policies apply even to the
+table owner, so no connection can bypass them.
+
+### rlsdb package
+
+The `rlsdb` package (`internal/relay/rlsdb/`) wraps the raw
+`*gorm.DB` in an unexported struct, making direct database access
+structurally impossible from outside the package. All queries go
+through one of two methods:
+
+- **`Tx(ctx, householdID, fn)`** — opens a transaction, calls
+  `set_config('app.household_id', householdID, true)`, then
+  executes `fn`. This is the standard path for all household-scoped
+  operations.
+- **`WithoutHousehold(ctx, fn)`** — opens a transaction with
+  `app.household_id` cleared to empty string. RLS treats this as
+  NULL, so no `ops` or `blobs` rows are visible. Reserved for
+  methods that only touch non-RLS tables (`households`, `devices`,
+  `invites`, `key_exchanges`) where no household ID is available
+  yet (e.g. device authentication, join flow).
+
+Construction-time helpers:
+- **`Migrate(models...)`** — runs `AutoMigrate` with a dummy
+  household ID so GORM's schema introspection works under `FORCE
+  ROW LEVEL SECURITY`.
+- **`InitRLS(tables)`** — idempotently enables RLS and creates
+  isolation policies for the given tables.
+
+### Protected tables
+
+| Table | Scoping column | RLS enforced |
+|-------|---------------|--------------|
+| `ops` | `household_id` | Yes |
+| `blobs` | `household_id` | Yes |
+| `households` | — | No (looked up by ID) |
+| `devices` | — | No (looked up by token hash) |
+| `invites` | — | No (looked up by code) |
+| `key_exchanges` | — | No (short-lived, scrubbed after use) |
+
 ## Database schema (PostgreSQL)
 
 ```
@@ -147,6 +204,9 @@ key_exchanges  — id, household_id, joiner info, encrypted credentials
 blobs          — household_id, hash, data, size_bytes
 ```
 
+RLS policies on `ops` and `blobs` enforce household isolation at the
+database level (see [Row-level security](#row-level-security) above).
+
 All table names use bare English (not `pg_` prefixed). The Go
 struct names use a `pg` prefix (`pgHousehold`, `pgDevice`) to
 distinguish them from the `sync.Household` and `sync.Device`
@@ -183,7 +243,8 @@ sequenceDiagram
     R->>R: assign sequence numbers, store ciphertext
     end
 
-    Note over A,B: User runs `micasa pro invite`, shares code
+    Note over A: User runs `micasa pro invite`
+    Note over A,B: share invite code out-of-band
 
     rect rgb(240, 235, 228)
     Note over A,B: Key exchange
@@ -233,6 +294,7 @@ internal/
     store.go         Store interface (21 methods)
     memstore.go      In-memory implementation (testing)
     pgstore.go       PostgreSQL implementation (production)
+    rlsdb/           RLS-aware DB wrapper (unexported *gorm.DB, Tx/WithoutHousehold)
     stripe.go        Webhook signature verification
     tokencrypt.go    AES-256-GCM token encryption at rest
     blob.go          Blob storage constants and validation

docs/content/docs/getting-started/self-hosting.md

@@ -18,7 +18,11 @@ The relay runs two containers: PostgreSQL for storage and the relay
 binary for sync traffic. PostgreSQL holds encrypted sync operations,
 encrypted document blobs, device registrations, and invite state.
 All household data is end-to-end encrypted — the relay never sees
-plaintext.
+plaintext. PostgreSQL
+[row-level security]({{< relref "/docs/development/relay-architecture#row-level-security" >}})
+provides an additional isolation layer, ensuring one household's
+data is invisible to queries from another even if application code
+has a bug.
 
 ## Quick start
 

docs/layouts/_default/baseof.html

@@ -174,6 +174,9 @@
     fontFamily: '"Source Serif 4", Georgia, serif',
     fontSize: "14px",
     background: "transparent"
+  },
+  sequence: {
+    noteMargin: 14
   }
 });
 await mermaid.run();
@@ -218,13 +221,30 @@
     parent.replaceChild(frag, textNode);
   });
 
+  // Widen note rects when monospace text overflows the original box.
+  svg.querySelectorAll(".note").forEach(function(noteRect) {
+    var g = noteRect.closest("g");
+    if (!g) return;
+    var text = g.querySelector(".noteText");
+    if (!text) return;
+    var textWidth = text.getBBox().width;
+    var rectWidth = parseFloat(noteRect.getAttribute("width") || 0);
+    var pad = 16;
+    if (textWidth + pad > rectWidth) {
+      var diff = textWidth + pad - rectWidth;
+      noteRect.setAttribute("width", textWidth + pad);
+      var x = parseFloat(noteRect.getAttribute("x") || 0);
+      noteRect.setAttribute("x", x - diff / 2);
+    }
+  });
+
   // Replace hardcoded rect group fills with a CSS variable so they
   // adapt to theme toggles without re-rendering.
   svg.querySelectorAll("rect").forEach(function(rect) {
     var fill = (rect.getAttribute("fill") || "").replace(/\s/g, "");
     if (fill === "rgb(240,235,228)") {
       rect.removeAttribute("fill");
-      rect.style.fill = "var(--linen)";
+      rect.style.fill = "var(--rect-fill)";
     }
   });
 });

docs/static/css/docs.css

@@ -764,7 +764,7 @@ h2:hover .badge-experimental .badge-label {
 }
 
 .docs-main pre.mermaid .actor-line {
-  stroke: var(--rule) !important;
+  stroke: var(--warm-gray) !important;
 }
 
 .docs-main pre.mermaid .messageLine0,
@@ -783,25 +783,28 @@ h2:hover .badge-experimental .badge-label {
 }
 
 .docs-main pre.mermaid .labelBox {
-  stroke: var(--rule) !important;
-  fill: var(--cream) !important;
+  stroke: none !important;
+  fill: var(--terracotta) !important;
+  rx: 4;
 }
 
 .docs-main pre.mermaid .labelText,
 .docs-main pre.mermaid .labelText > tspan,
 .docs-main pre.mermaid .loopText,
 .docs-main pre.mermaid .loopText > tspan {
-  fill: var(--charcoal-soft) !important;
+  fill: var(--cream) !important;
+  dominant-baseline: central !important;
 }
 
 .docs-main pre.mermaid .loopLine {
-  stroke: var(--rule) !important;
-  fill: var(--rule) !important;
+  stroke: var(--terracotta) !important;
+  stroke-opacity: 0.3 !important;
+  fill: none !important;
 }
 
 .docs-main pre.mermaid .note {
-  stroke: var(--rule) !important;
-  fill: var(--cream) !important;
+  stroke: var(--warm-gray) !important;
+  fill: var(--linen) !important;
 }
 
 .docs-main pre.mermaid .noteText,

docs/static/css/variables.css

@@ -21,6 +21,7 @@
   --toggle-bg-hover: #e8e2da;
   --toggle-hover-speed: 0.15s;
   --cloud: #b8b0a5;
+  --rect-fill: rgba(192, 94, 60, 0.15);
 }
 
 [data-theme="dark"] {
@@ -39,6 +40,7 @@
   --overlay-bg: rgba(0, 0, 0, 0.5);
   --toggle-bg: #342f29;
   --toggle-bg-hover: var(--rule);
+  --rect-fill: rgba(212, 118, 78, 0.10);
 }
 
 /* --- Theme toggle (shared across all pages) --- */