From 28fe71b8c0d494c371a315e86ed69b7226ab6fc4 Mon Sep 17 00:00:00 2001
From: rock <locartrock@gmail.com>
Date: Thu, 3 Sep 2026 16:08:56 -0700
Subject: [PATCH] docs(README): expand RBAC section with fine-grained roles

Added:
- Two-level access control explanation (capabilities + scopes)
- Scope types table (projects, visibility, owner, groups)
- All built-in roles (admin, portfolio-agent, authenticated-user)
- Owner constraint example (self)
- JWT claims to RBAC mapping
- AccessGuard post-retrieval filtering note
---
 README.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 48 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 779d816..db9f3d0 100644
--- a/README.md
+++ b/README.md
@@ -115,10 +115,34 @@ Agents can cite sources: *"Based on 23 previous occurrences (source: troubleshoo
 
 ### 4. Hierarchical RBAC
 
-Fine-grained access control integrated with Authentik OIDC:
+Two-level access control integrated with Authentik OIDC:
+
+**Level 1: Capabilities** (HTTP endpoint access)
+```
+memory:read   → /query, /context, /projects, /skills
+memory:write  → /ingest, /learn
+*             → all endpoints (admin)
+```
+
+**Level 2: Resource Scopes** (fine-grained filtering)
+
+| Scope | Description | Example |
+|-------|-------------|--------|
+| `projects` | Allowed project names | `[homelab, portfolio]` |
+| `visibility` | Public or private docs | `public` |
+| `owner` | Resource ownership | `self` (own only) |
+| `groups` | Required group membership | `[engineering]` |
+
+**Built-in Roles:**
 
 ```yaml
-# Portfolio visitor: public docs only
+# Admin: full access
+- role: admin
+  rules:
+    - resources: ["*"]
+      verbs: [read, write, delete, query]
+
+# Portfolio visitor: public docs only, own conversations
 - role: portfolio-agent
   rules:
     - resources: [wiki, embedding]
@@ -126,17 +150,34 @@ Fine-grained access control integrated with Authentik OIDC:
       scope:
         projects: [homelab, portfolio]
         visibility: public
+    - resources: [conversation]
+      verbs: [read, write]
+      scope:
+        owner: self  # Can only access own conversations
 
-# Team member: full project access
-- role: homelab-team
+# Authenticated user: all docs, own conversations
+- role: authenticated-user
   rules:
     - resources: [wiki, embedding, skill]
-      verbs: [read, write, query]
+      verbs: [read, query]
+      # No visibility restriction → sees public + private
+    - resources: [conversation]
+      verbs: [read, write, delete]
       scope:
-        projects: [homelab]
+        owner: self
 ```
 
-Agents only retrieve knowledge they're authorized to access. Prevents cross-project data leakage.
+**JWT Claims → RBAC:**
+```json
+{
+  "sub": "alice",
+  "roles": ["authenticated-user", "homelab-team"],
+  "groups": ["engineering"],
+  "permissions": ["memory:read", "memory:write"]
+}
+```
+
+Agents only retrieve knowledge they're authorized to access. Results are filtered post-retrieval by `AccessGuard`.
 
 ### 5. Budget-Aware Context Assembly