docs: add tracing examples and clarify legacy vs modern methods

app/spicedb/concepts/commands/page.mdx

@@ -27,14 +27,13 @@ A database that stores and computes permissions
 
 ### Children commands
 
-- [spicedb datastore](#reference-spicedb-datastore)	 - datastore operations
-- [spicedb lsp](#reference-spicedb-lsp)	 - serve language server protocol
-- [spicedb man](#reference-spicedb-man)	 - Generate man page
-- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw)	 - serve a Postgres Foreign Data Wrapper for SpiceDB (EXPERIMENTAL)
-- [spicedb serve](#reference-spicedb-serve)	 - serve the permissions database
-- [spicedb serve-testing](#reference-spicedb-serve-testing)	 - test server with an in-memory datastore
-- [spicedb version](#reference-spicedb-version)	 - displays the version of SpiceDB
-
+- [spicedb datastore](#reference-spicedb-datastore) - datastore operations
+- [spicedb lsp](#reference-spicedb-lsp) - serve language server protocol
+- [spicedb man](#reference-spicedb-man) - Generate man page
+- [spicedb postgres-fdw](#reference-spicedb-postgres-fdw) - serve a Postgres Foreign Data Wrapper for SpiceDB (EXPERIMENTAL)
+- [spicedb serve](#reference-spicedb-serve) - serve the permissions database
+- [spicedb serve-testing](#reference-spicedb-serve-testing) - test server with an in-memory datastore
+- [spicedb version](#reference-spicedb-version) - displays the version of SpiceDB
 
 ## Reference: `spicedb datastore`
 
@@ -50,11 +49,10 @@ Operations against the configured datastore
 
 ### Children commands
 
-- [spicedb datastore gc](#reference-spicedb-datastore-gc)	 - executes garbage collection
-- [spicedb datastore head](#reference-spicedb-datastore-head)	 - compute the head (latest) database migration revision available
-- [spicedb datastore migrate](#reference-spicedb-datastore-migrate)	 - execute datastore schema migrations
-- [spicedb datastore repair](#reference-spicedb-datastore-repair)	 - executes datastore repair
-
+- [spicedb datastore gc](#reference-spicedb-datastore-gc) - executes garbage collection
+- [spicedb datastore head](#reference-spicedb-datastore-head) - compute the head (latest) database migration revision available
+- [spicedb datastore migrate](#reference-spicedb-datastore-migrate) - execute datastore schema migrations
+- [spicedb datastore repair](#reference-spicedb-datastore-repair) - executes datastore repair
 
 ## Reference: `spicedb datastore gc`
 
@@ -145,8 +143,6 @@ spicedb datastore gc [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb datastore head`
 
 compute the head (latest) database migration revision available
@@ -178,8 +174,6 @@ spicedb datastore head [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb datastore migrate`
 
 Executes datastore schema migrations for the datastore.
@@ -219,8 +213,6 @@ spicedb datastore migrate [revision] [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb datastore repair`
 
 Executes a repair operation for the datastore
@@ -310,8 +302,6 @@ spicedb datastore repair [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb lsp`
 
 serve language server protocol
@@ -335,20 +325,17 @@ spicedb lsp [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb man`
 
 Generate a man page for SpiceDB.
- The output can be redirected to a file and installed to the system:
+The output can be redirected to a file and installed to the system:
 
 ```
   spicedb man > spicedb.1
   sudo mv spicedb.1 /usr/share/man/man1/
   sudo mandb  # Update man page database
 ```
 
-
 ```
 spicedb man
 ```
@@ -361,8 +348,6 @@ spicedb man
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb postgres-fdw`
 
 EXPERIMENTAL: Serves a Postgres-compatible interface for querying SpiceDB data using foreign data wrappers. This feature is experimental and subject to change.
@@ -391,8 +376,6 @@ spicedb postgres-fdw [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb serve`
 
 start a SpiceDB server
@@ -577,8 +560,6 @@ spicedb serve [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb serve-testing`
 
 An in-memory spicedb server which serves completely isolated datastores per client-supplied auth token used.
@@ -640,8 +621,6 @@ spicedb serve-testing [flags]
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
 
-
-
 ## Reference: `spicedb version`
 
 displays the version of SpiceDB
@@ -663,6 +642,3 @@ spicedb version [flags]
       --log-level string     verbosity of logging ("trace", "debug", "info", "warn", "error") (default "info")
       --skip-release-check   if true, skips checking for new SpiceDB releases
 ```
-
-
-

app/spicedb/modeling/validation-testing-debugging/page.mdx

@@ -25,7 +25,9 @@ You can run the integration test server by executing `spicedb serve-testing` or
 
 While it is recommended that SpiceDB schema be validated and tested before production deployment, there are many scenarios where being able to see the actual paths taken against production data is incredibly important.
 
-To support this, SpiceDB's v1 CheckPermission API supports a debug header that will cause SpiceDB to trace the full set of relations and permission traversed while computing the check.
+**This method is deprecated.** As of v1.30.0+, use the [Check Tracing](#check-tracing) method with `withTracing: true` instead, which returns trace data directly in the response body.
+
+In versions prior to v1.30.0, this method uses gRPC metadata headers to request debug trace information, with the trace data returned in the response trailer.
 
 <Callout type="warning">
   **Warning:**
@@ -38,9 +40,24 @@ Instead, we recommend using [zed's explain flag] for this purpose.
 
 </Callout>
 
-Configuring this header is done by setting the header `io.spicedb.requestdebuginfo` to the string `true`.
+To request debug information, set the header `io.spicedb.requestdebuginfo` to `1`.
+
+<Callout type="info">
+  **Note:** In SpiceDB v1.30.0+, this header still works but the trace data is
+  returned in the response body (`debugTrace` field) rather than the trailer.
+  The trailer `io.spicedb.respmeta.debuginfo` will contain a message indicating
+  to check the response body instead.
+</Callout>
+
+#### Example
+
+Using the `zed` CLI with the `--explain` flag (recommended):
 
-The response will include a trailer, `io.spicedb.respmeta.debuginfo`, with a JSON-encoded tree.
+```sh
+zed permission check --explain document:firstdoc view user:fred
+```
+
+This will print a visual tree of the permission check trace.
 
 ## Playground
 
@@ -150,15 +167,105 @@ project:docs#admin:
 
 ## Check Tracing
 
+**This is the modern, recommended method for collecting trace information** (available in SpiceDB v1.30.0+). Unlike the legacy [CheckPermission Tracing Header](#checkpermission-tracing-header) approach (which returned trace data in a response trailer in versions prior to v1.30.0), this method returns the trace as a structured field directly in the response message body.
+
 SpiceDB supports tracing of check requests to view the path(s) taken to compute the result, as well as timing information.
 
-Request tracing information by setting `with_tracing: true` in the request message and the information will be found in the response message.
+To request tracing information, set `withTracing: true` in the request message. The trace data will be returned in the response message.
+
+**Key differences from the header-based approach:**
+
+- More structured and easier to parse programmatically
+- Preferred for modern integrations
 
 <Callout type="warning">
-  **Warning:** In versions older than v1.31.0, request tracing information via a
-  header and the information will be found in the response footer as JSON.
+  **Warning:** In versions older than v1.30.0, you must request tracing
+  information via a header, and the trace data will be returned in the response
+  trailer as JSON.
 </Callout>
 
+#### Example Request/Response
+
+**Request** (using grpcurl):
+
+```sh
+grpcurl \
+  -H "Authorization: Bearer your-token-here" \
+  -d '{
+    "resource": {"objectType": "document", "objectId": "firstdoc"},
+    "permission": "view",
+    "subject": {"object": {"objectType": "user", "objectId": "fred"}},
+    "withTracing": true
+  }' \
+  your-spicedb-instance:443 \
+  authzed.api.v1.PermissionsService/CheckPermission
+```
+
+**Response**:
+
+```json
+{
+  "permissionship": "PERMISSIONSHIP_HAS_PERMISSION",
+  "checkedAt": {
+    "token": "GhUKEzE3MDYxMTIwMDAwMDAwMDAwMDA="
+  },
+  "debugTrace": {
+    "check": {
+      "resource": {
+        "objectType": "document",
+        "objectId": "firstdoc"
+      },
+      "permission": "view",
+      "permissionType": "PERMISSION_TYPE_PERMISSION",
+      "subject": {
+        "object": {
+          "objectType": "user",
+          "objectId": "fred"
+        }
+      },
+      "result": "PERMISSIONSHIP_HAS_PERMISSION",
+      "duration": "0.000125s",
+      "subProblems": {
+        "traces": [
+          {
+            "resource": {
+              "objectType": "document",
+              "objectId": "firstdoc"
+            },
+            "permission": "reader",
+            "permissionType": "PERMISSION_TYPE_RELATION",
+            "subject": {
+              "object": {
+                "objectType": "user",
+                "objectId": "fred"
+              }
+            },
+            "result": "PERMISSIONSHIP_HAS_PERMISSION",
+            "duration": "0.000045s"
+          }
+        ]
+      }
+    },
+    "schemaUsed": "definition document {\n  relation reader: user\n  permission view = reader\n}\n\ndefinition user {}"
+  }
+}
+```
+
+The `debugTrace` field contains a `DebugInformation` object with:
+
+- `check`: A `CheckDebugTrace` object containing the trace tree
+- `schemaUsed`: The schema that was used for the check
+
+Each `CheckDebugTrace` includes:
+
+- `resource`: The resource being checked
+- `permission`: The permission or relation name
+- `permissionType`: Whether it's a `PERMISSION_TYPE_PERMISSION` or `PERMISSION_TYPE_RELATION`
+- `subject`: The subject of the check
+- `result`: The permissionship result
+- `duration`: Time spent on this check (as a Duration string, e.g., "0.000125s")
+- `subProblems`: Contains `traces` array with nested `CheckDebugTrace` objects, or `wasCachedResult: true` if cached
+
 ## Zed
 
 ### Zed Validate

wordlist.txt

@@ -1,4 +1,4 @@
-personal_ws-1.1 en 654
+personal_ws-1.1 en 655
 ABAC
 ACKing
 ACL
@@ -440,6 +440,7 @@ goroutines
 governance
 gpg
 grpc
+grpcurl
 grpcutil
 hashlib
 heredoc