docs: update documentation on spicedb and cedar

2 files changed, 264 insertions, 78 deletions

diff --git a/share/man/cedar/README.md b/share/man/cedar/README.md
new file mode 100644
index 00000000..ec665d69
--- /dev/null
+++ b/share/man/cedar/README.md
@@ -0,0 +1,125 @@
+# Cedar Authorization Guide
+
+Cedar provides policy-based authorization using Amazon's Cedar policy
+language. This service handles request authorization through Envoy's
+`ext_authz` filter.
+
+## Architecture
+
+```
++---------------------------------------------------------------------+
+|                     Client Request                                  |
++---------------------------------------------------------------------+
+                          │
+                          V
++---------------------------------------------------------------------+
+│                     Envoy Proxy (:20000)                            |
+│                                                                     |
+│  * JWT Filter extracts x-jwt-claim-sub header                       |
+│  * ext_authz sends CheckRequest to authzd                           |
++---------------------------------------------------------------------+
+                          | ext_authz
+                          V
+              +---------------------+
+              |   authzd (:50052)   |
+              |                     |
+              | +-----------------+ |
+              | | Cedar Policies  | |
+              | | * Static Assets | |
+              | | * JWT Claims    | |
+              | | * Path Rules    | |
+              | +-----------------+ |
+              +---------------------+
+```
+
+## Authorization Flow
+
+```
+     Client                    Envoy                     authzd
+        |                       |                        |
+        | HTTP Request + JWT    |                        |
+        |---------------------->|                        |
+        |                       | Extract JWT claims     |
+        |                       | Add x-jwt-claim-sub    |
+        |                       |                        |
+        |                       | ext_authz CheckRequest |
+        |                       |----------------------->|
+        |                       |                        |
+        |                       |                        | Evaluate
+        |                       |                        | Cedar
+        |                       |                        | policies
+        |                       |      Allow/Deny        |
+        |                       |<-----------------------|
+        |                       |                        |
+        | Forward request       |                        |
+        | or 403 Forbidden      |                        |
+        |<----------------------|                        |
+```
+
+## Cedar Policies
+
+### Policy Structure
+
+Policies are stored in `etc/authzd/*.cedar` files using Cedar's policy language:
+
+```cedar
+permit (
+  principal == User::"1",
+  action == Action::"GET",
+  resource == Resource::"/sparkle/"
+)
+when
+{
+  context has host &&
+  context.host == "sparkle.staging.runway.gitlab.net" &&
+  principal has username
+};
+```
+
+## JWT Integration
+
+### JWT Header Extraction
+
+Envoy's JWT filter extracts claims and adds them as headers:
+
+- `x-jwt-claim-sub` - User ID (subject)
+
+## Policy Development
+
+### Adding New Policies
+
+1. Create or edit `.cedar` files in `etc/authzd/`
+2. Use Cedar policy syntax for rules
+3. Test with `make test`
+4. Validate with `make lint`
+
+### Policy Validation
+
+```bash
+# Check policy syntax
+cedar check-parse --policies etc/authzd/policy1.cedar
+
+# Format policies
+cedar format --policies etc/authzd/policy1.cedar --check
+```
+
+### Testing Policies
+
+```bash
+# Run Cedar authorization tests
+cargo test authorization::cedar_authorizer_test
+
+# Test specific scenarios
+cargo test test_sparkle_homepage
+```
+
+## Make Targets
+
+- `make test` - Run all tests including Cedar policy tests
+- `make lint` - Validate Cedar policy syntax and formatting
+
+## References
+
+- [Cedar Policy Language](https://docs.cedarpolicy.com/)
+- [Cedar Language Guide](https://docs.cedarpolicy.com/policies/syntax.html)
+- [Envoy JWT Authentication](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/jwt_authn_filter)
diff --git a/share/man/spicedb/README.md b/share/man/spicedb/README.md
index bd6d7798..f5e2e968 100644
--- a/share/man/spicedb/README.md
+++ b/share/man/spicedb/README.md
@@ -1,91 +1,152 @@
-# Spice DB
+# SpiceDB Integration Guide
 
-SpiceDB is a re-implementation of the [Google Zanzibar][1].
+SpiceDB provides relation-based authorization using the Google Zanzibar model.
+This service handles complex permission hierarchies through relationship graphs.
 
-## Components
+## Architecture
 
-* `zed`: Command line client
-* `spicedb`: The Server
+```
++---------------------------------------------------------------------+
+|                      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   |                        |
+        |<----------------------|                        |
+```
 
-### zed
+## Quick Start
+
+### 1. Start All Services
 
 ```bash
-モ zed --help
-A command-line client for managing SpiceDB clusters.
-
-Usage:
-  zed [command]
-
-Available Commands:
-  backup       Create, restore, and inspect permissions system backups
-  completion   Generate the autocompletion script for the specified shell
-  context      Manage configurations for connecting to SpiceDB deployments
-  help         Help about any command
-  import       Imports schema and relationships from a file or url
-  permission   Query the permissions in a permissions system
-  preview      Experimental commands that have been made available for preview
-  relationship Query and mutate the relationships in a permissions system
-  schema       Manage schema for a permissions system
-  use          Alias for `zed context use`
-  validate     Validates the given validation file (.yaml, .zaml) or schema file (.zed)
-  version      Display zed and SpiceDB version information
-
-Flags:
-      --certificate-path string     path to certificate authority used to verify secure connections
-      --endpoint string             spicedb gRPC API endpoint
-  -h, --help                        help for zed
-      --hostname-override string    override the hostname used in the connection to the endpoint
-      --insecure                    connect over a plaintext connection
-      --log-format string           format of logs ("auto", "console", "json") (default "auto")
-      --log-level string            verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")
-      --max-message-size int        maximum size *in bytes* (defaults to 4_194_304 bytes ~= 4MB) of a gRPC message that can be sent or received by zed
-      --max-retries uint            maximum number of sequential retries to attempt when a request fails (default 10)
-      --no-verify-ca                do not attempt to verify the server's certificate chain and host name
-      --permissions-system string   permissions system to query
-      --proxy string                specify a SOCKS5 proxy address
-      --request-id string           optional id to send along with SpiceDB requests for tracing
-      --skip-version-check          if true, no version check is performed against the server
-      --token string                token used to authenticate to SpiceDB
-
-Use "zed [command] --help" for more information about a command.
+# 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
+```
 
-### server
+### 3. Test SpiceDB Permissions
 
 ```bash
-モ spicedb --help
-A database that stores, computes, and validates application permissions
-
-Usage:
-  spicedb [command]
-
-Examples:
-        No TLS and in-memory:
-                spicedb serve --grpc-preshared-key "somerandomkeyhere"
-
-        TLS and a real datastore:
-                spicedb serve --grpc-preshared-key "realkeyhere" --grpc-tls-cert-path path/to/tls/cert --grpc-tls-key-path path/to/tls/key \
-                        --http-tls-cert-path path/to/tls/cert --http-tls-key-path path/to/tls/key \
-                        --datastore-engine postgres --datastore-conn-uri "postgres-connection-string-here"
-
-
-Available Commands:
-  completion    Generate the autocompletion script for the specified shell
-  datastore     datastore operations
-  help          Help about any command
-  lsp           serve language server protocol
-  serve         serve the permissions database
-  serve-testing test server with an in-memory datastore
-  version       displays the version of SpiceDB
-
-Flags:
-  -h, --help                 help for spicedb
-      --log-format string    format of logs ("auto", "console", "json") (default "auto")
-      --log-level string     verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")
-      --skip-release-check   if true, skips checking for new SpiceDB releases
-
-Use "spicedb [command] --help" for more information about a command.
+# Check permissions via zed CLI
+zed --endpoint "localhost:20000" --token "secret" --insecure permission check project:1 read user:mokhax
 ```
 
-[1]:  https://authzed.com/blog/what-is-google-zanzibar
+## 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)