1 files changed, 152 insertions, 0 deletions
diff --git a/share/man/spicedb/README.md b/share/man/spicedb/README.md
new file mode 100644
index 00000000..f5e2e968
--- /dev/null
+++ b/share/man/spicedb/README.md
@@ -0,0 +1,152 @@
+# SpiceDB Integration Guide
+
+SpiceDB provides relation-based authorization using the Google Zanzibar model.
+This service handles complex permission hierarchies through relationship graphs.
+
+## Architecture
+
+```
++---------------------------------------------------------------------+
+|                      Client Request                                 |
++---------------------------------------------------------------------+
+                          |
+                          V
++---------------------------------------------------------------------+
+|                     Envoy Proxy (:20000)                            |
+|                                                                     |
+|  Routes /authzed.api.v1.* directly to SpiceDB                       |
+|---------------------------------------------------------------------+
+                          | SpiceDB APIs
+                          V
+              +---------------------+
+              |  SpiceDB (:50051)   |
+              |                     |
+              | +-----------------+ |
+              | |   Relations     | |
+              | | * user:mokhax   | |
+              | | * project:1     | |
+              | | * maintainer    | |
+              | | * developer     | |
+              | +-----------------+ |
+              +---------------------+
+```
+
+## Authorization Flow
+
+```
+     Client                    Envoy                   SpiceDB
+        |                       |                        |
+        | gRPC PermissionCheck  |                        |
+        |---------------------->|                        |
+        |                       | Route by gRPC service  |
+        |                       |----------------------->|
+        |                       |                        |
+        |                       |                        | Query
+        |                       |                        | relations
+        |                       |                        | graph
+        |                       |   Permission result    |
+        |                       |<-----------------------|
+        |                       |                        |
+        | Permission response   |                        |
+        |<----------------------|                        |
+```
+
+## Quick Start
+
+### 1. Start All Services
+
+```bash
+# Start authzd, envoy, and spicedb
+make run
+```
+
+### 2. Setup SpiceDB Schema & Data
+
+```bash
+# Initialize schema and test data
+make run-spicedb-setup
+
+# Test permissions
+make run-spicedb-permission-check
+```
+
+### 3. Test SpiceDB Permissions
+
+```bash
+# Check permissions via zed CLI
+zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:mokhax
+```
+
+## SpiceDB Configuration
+
+### Schema Development
+
+1. Update schema in `etc/authzd/spice.schema`
+2. Apply with `zed schema write`
+3. Add relationships with `zed relationship create`
+
+### Schema Example
+
+```zed
+definition user {}
+definition project {
+  relation developer: user
+  relation maintainer: user
+  permission read = developer + maintainer
+  permission write = maintainer
+}
+```
+
+### Creating Relationships
+
+```bash
+# Add user to project as maintainer
+zed relationship create project:1 maintainer user:mokhax
+
+# Add user to project as developer
+zed relationship create project:1 developer user:tanuki
+```
+
+## zed CLI Commands
+
+### Schema Management
+
+```bash
+# Write schema to SpiceDB
+zed --endpoint "localhost:20000" --token "secret" --insecure schema write etc/authzd/spice.schema
+
+# Read current schema
+zed --endpoint "localhost:20000" --token "secret" --insecure schema read
+```
+
+### Relationship Management
+
+```bash
+# Create relationships
+zed --endpoint "localhost:20000" --token "secret" --insecure relationship create project:1 maintainer user:mokhax
+
+# Delete relationships
+zed --endpoint "localhost:20000" --token "secret" --insecure relationship delete project:1 developer user:tanuki
+```
+
+### Permission Checks
+
+```bash
+# Check specific permissions
+zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 write user:mokhax
+
+# Bulk permission checks
+zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:tanuki
+```
+
+## Make Targets
+
+- `make run-spicedb-setup` - Initialize schema and test data
+- `make run-spicedb-permission-check` - Test permission queries
+
+## References
+
+- [SpiceDB Documentation](https://authzed.com/docs)
+- [Google Zanzibar Paper](https://authzed.com/blog/what-is-google-zanzibar)
+- [Cedar Policy Language](https://docs.cedarpolicy.com/)
+- [Envoy External Authorization](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter)