fix grammar

pages/spicedb/concepts/consistency.mdx

@@ -48,7 +48,7 @@ Consistency is provided via the [Consistency message][msg] on supported API call
 
 #### Minimize Latency
 
-`minimize_latency` will attempt to minimize the latency of the API call by selecting data that is most likely exist in the cache.
+`minimize_latency` will attempt to minimize the latency of the API call by selecting data that is most likely to exist in the cache.
 
 <Callout type="warning">
   If used exclusively, this can lead to a window of time where the [New Enemy Problem] can occur.
@@ -130,13 +130,13 @@ SpiceDB returns ZedTokens from the APIs that perform permission checks or modify
 
 ### Storing ZedTokens
 
-There are scenarios where it makes sense to store ZedTokens in an applications primary database.
+There are scenarios where it makes sense to store ZedTokens in an application's primary database.
 The goal of this workflow is to ensure the application can query SpiceDB with consistency that is causally tied to the content of the protected resource.
 
 Stored ZedTokens should be updated under these events:
 
 - The resource is created or deleted
-- The contents of the resource changes
+- The contents of the resource change
 - Adding or removing access to the resource (e.g. writing a relationship)
 
 When these events happen, a new ZedToken is either returned or it should be requested by performing a check with full consistency.

pages/spicedb/concepts/datastore-migrations.mdx

@@ -31,7 +31,9 @@ For all software that maintains data, there can be updates to code that rely on
 The process of updating data to use new versions of software is called _migrating_.
 
 SpiceDB users will see migrations crop up in two places: when they update versions of SpiceDB and when they write backwards incompatible changes to their schema.
-This document's focus is on the former.
+This document's focus is on the former; the latter is documented [here].
+
+[here]: ../modeling/migrating-schema
 
 ### SpiceDB migration tooling
 

pages/spicedb/concepts/datastores.mdx

@@ -149,7 +149,8 @@ Since the relationship integrity feature signs each individual relationship, it
 Schema is also currently unverified, so an untrusted party could change it as well.
 Support for schema changes will likely come in a future version.
 
-**Setting up relationship integrity**
+##### Setting up relationship integrity
+
 To run with relationship integrity, new flags must be given to SpiceDB:
 
 ```zed
@@ -161,7 +162,7 @@ spicedb serve ...existing flags...
 
 Place the generated key contents (which must support an HMAC key) in `some.key`
 
-Deployment Process
+##### Deployment Process
 
 1. Start with a **clean** datastore for SpiceDB. **At this time, migrating an existing SpiceDB installation is not supported.**
 2. Run the standard `migrate` command but with relationship integrity flags included.

pages/spicedb/getting-started/coming-from/cancancan.mdx

@@ -33,7 +33,7 @@ A quick recap on the components and their purpose:
 
 CanCanCan is a *library* (gem) designed to help model authorization in Ruby on Rails projects.
 The fundamental idea behind most authorization libraries is that access control can be modeled by reusing as much as possible from within your existing web framework.
-For cancancan, developers defines their models from within an `Ability` class.
+For cancancan, developers define their models from within an `Ability` class.
 Engine logic is implemented within the library such that developers can simply load the `Ability` class within their `Controller` classes to enforce their models.
 Data outside of the request context is left open ended, but most often is fetched from the primary database using ActiveRecord.
 

pages/spicedb/getting-started/coming-from/opa.mdx

@@ -65,5 +65,5 @@ Adopting SpiceDB can be a powerful tool for enabling a shift towards centralizin
 
 ## When to use OPA instead of SpiceDB
 
-OPA excels where in scenarios where it can be easily embedded or ran alongside an existing workload.
+OPA excels in scenarios where it can be easily embedded or ran alongside an existing workload.
 Because it is a fairly open-ended how one deals with data in OPA deployments, it shines best as a solution when access control decisions don't require much data.

pages/spicedb/getting-started/protecting-a-blog.mdx

@@ -31,7 +31,7 @@ docker run --rm -p 50051:50051 authzed/spicedb serve --grpc-preshared-key "t_you
 
 The first step to integrating any software is ensuring you have an API client.
 
-Each tool is installed with its ecosystem's package management tools:
+Each client is installed with its ecosystem's package management tools:
 
 <Tabs items={['zed', 'Node', 'Go', 'Python', 'Ruby', 'Java']}>
 <Tabs.Tab>
@@ -113,11 +113,11 @@ This example defines two types of objects that will be used in the permissions s
 Each post can have two kinds of relations to users: `reader` and `writer`.
 Each post can have two permissions checked: `read` and `write`.
 The `read` permission unions together both readers and writers, so that any writer is implicitly granted read, as well.
-Feel free to start with design to modify and test your own experiments in the [playground].
+Feel free to modify and test your own experiments in the [playground].
 
 [playground]: https://play.authzed.com/s/mVBBpf5poNd8/schema
 
-With a schema designed, we can now move on using our client to apply that schema to the Permission System.
+With a schema designed, we can now move on to using our client to apply that schema to the Permission System.
 
 <Callout type="info">
 Similar to applying schema changes for relational databases, all changes to a schema must be backwards compatible.
@@ -314,7 +314,7 @@ public class App {
 
 ## Storing Relationships
 
-After a permission system has its schema applied, it is ready to have its relationships be created, touched, or deleted.
+After a permission system has its schema applied, it is ready to have its relationships created, touched, or deleted.
 Relationships are live instances of relations between objects.
 Because the relationships stored in the system can change at runtime, this is a powerful primitive for dynamically granting or revoking access to the resources you've modeled.
 When applications modify or create rows in their database, they will also typically create or update relationships.
@@ -639,17 +639,17 @@ public class App {
 ## Checking Permissions
 
 Permissions Systems that have stored relationships are capable of performing permission checks.
-Checks do not only test for the existence of direct relationships, but will also compute and traverse transitive relationships.
-For example, in our example schema, writers have both write and read, so there's no need to create a read relationship for a subject that is already a writer.
+Checks not only test for the existence of direct relationships, but also compute and traverse transitive relationships.
+For example, in our example schema, writers have both write and read permissions, so there's no need to create a read relationship for a subject that is already a writer.
 
 <Callout type="info">
 In addition to checking _permissions_, it is also possible to perform checks on _relations_ to determine membership.
 
-However, this goes against best practice: permissions can be redefined in backwards compatible ways by changing schema, so it's ideal to rely on permissions as the contract between SpiceDB and applications querying SpiceDB.
+However, this goes against best practice: permissions can be redefined in backwards compatible ways by changing the schema, so it's ideal to rely on permissions as the contract between SpiceDB and applications querying SpiceDB.
 </Callout>
 
 <Callout type="warning">
-In order to get read-after-write consistency, you must provide a [ZedToken] from the WriteRelationships response or request [full consistency].
+When doing a permission check, in order to get read-after-write consistency, you must provide a [ZedToken] from the WriteRelationships response or request [full consistency].
 
 [ZedToken]: /spicedb/concepts/consistency#zedtokens
 [full consistency]: /spicedb/concepts/consistency#fully-consistent

pages/spicedb/modeling/attributes.mdx

@@ -22,10 +22,9 @@ Feature flag authorization can be enabled with boolean attributes.
 [Wildcards](/spicedb/concepts/schema#wildcards) are a way to implement boolean attributes.
 Wildcards modify a type so that a relationship can be written to all objects of a resource type but not individual objects.
 
-In the example below, the schema enforces the following authorization logic: a user can only view a document if the user is related to the document as viewer and editing is enabled for the document.
-To enable document editing in the example below, you need to establish a wildcard relationship that connects all users to the document using the ```edit_enabled``` wildcard relation.
-A user will have ```edit``` permission on the document if they are related to the document as an ```editor``` and they relate to the document through ```edit_enabled```.
+In the example below, the schema enforces the following authorization logic: a user will have ```edit``` permission on the document if they are related to the document as an ```editor``` and they relate to the document through ```edit_enabled```.
 Both are required because ```editor``` and ```edit_enabled``` are [intersected](/spicedb/concepts/schema#-intersection) at the ```edit``` permission definition.
+To enable document editing, you need to establish a relationship that connects all users to the document using the ```edit_enabled``` relation: `document:somedocument#edit_enabled@user:*`.
 
 <InlinePlayground reference="p6ltnJZ2Zso7" />
 

pages/spicedb/modeling/developing-a-schema.mdx

@@ -70,7 +70,7 @@ relation reader: user | anotherobjecttype
 
 ## Validating our schema
 
-To validate that our schema is correct, both [zed] and [Playground] supports the writing of _test relationships_ as data writing tests against our schema.
+To validate that our schema is correct, both [zed] and [Playground] support the writing of _test relationships_ as data writing tests against our schema.
 Once we've [created test relationships][understanding-rels], we can define tests in three ways:
 
 - **Check Watches**: live checks performed as we edit the schema
@@ -108,7 +108,7 @@ assertFalse:
   - "document:specificdocument#reader@user:anotheruser"
 ```
 
-Validation can be run by clicking the `Validate` button in the Playground or using the `zed validate` command.
+Validations can be run by clicking the `Validate` button in the Playground or by using the `zed validate` command.
 
 ### Expected Relations
 
@@ -190,9 +190,9 @@ As a naive solution, we could create a `reader` relationship for every user when
 
 Instead, we'd ideally like a user with role `writer` to be **implicitly** allowed to a read a document, such that we only ever need to write _one_ relationship representing the user's **actual** relation/role to the document.
 
-The solution to this problem is the second concept available within the Schema Language: **permissions**
+The solution to this problem is the second concept available within the Schema Language: **permissions**.
 
-A `permission` in schema defines a permission _computed_ from one or more other relations or permissions.
+A `permission` in a schema defines a permission _computed_ from one or more other relations or permissions.
 
 Let's take our schema again from above:
 
@@ -281,9 +281,9 @@ Note that the contents of the angled brackets for `differentuser` and `specificu
 ### Preparing to inherit permissions
 
 As we've seen above, we can use `permission` to define _implicit_ permissions, such as a `view` permission consisting of users either the `reader` or `writer` role.
-Implicit permissions on a specific object type, however, are often insufficient: Sometimes permissions need to be **inherited** between object types.
+Implicit permissions on a specific object type, however, are often insufficient: sometimes permissions need to be **inherited** between object types.
 
-As an example: Imagine that we add the concept of an `organization` to our permissions system, where any user that is an administrator of an organization automatically gains the ability to `view` any `document` within that organization; how would we define such a permissions schema?
+As an example: imagine that we add the concept of an `organization` to our permissions system, where any user that is an administrator of an organization automatically gains the ability to `view` any `document` within that organization; how would we define such a permissions schema?
 
 ### Defining the organization type
 
@@ -347,7 +347,7 @@ Here we've chosen to call this relation `docorg`, but it could be called anythin
 
 ### Adding the relationship
 
-Now that we've defined the `relation` to hold our new relationship, we can add a test relationship in our test relationships:
+Now that we've defined the `relation` to hold our new relationship, we can add a test relationship:
 
 ```relationship filename="Test Relationships"
 document:specificdocument#docorg@organization:someorg

pages/spicedb/modeling/recursion-and-max-depth.mdx

@@ -48,7 +48,7 @@ group:secondgroup#member@group:thirdgroup#member
 group:thirdgroup#member@group:firstgroup#member
 ```
 
-Attempts by SpiceDB to compute a permission answer will walk from `resource:someresource#viewer`
+When computing a permission answer for `resource:someresource`, SpiceDB will attempt this walk: `resource:someresource#viewer`
 -> `group:firstgroup#member` -> `group:secondgroup#member` -> `group:thirdgroup#member` ->
 `group:firstgroup#member` -> ..., causing a cycle.
 
@@ -103,7 +103,7 @@ as SpiceDB assume the permissions graph is a [tree].
 
 #### Overhead
 
-From a practical perspective, tracking of visiting objects when computing `CheckPermission` and
+From a practical perspective, tracking of visited objects when computing `CheckPermission` and
 other permissions queries results in having significant amount of overhead over the wire and in
 memory to track the full set of encountered objects and check for duplicates.
 

pages/spicedb/modeling/representing-users.mdx

@@ -4,8 +4,6 @@ import { Callout } from 'nextra/components'
 
 Within a Permissions System, a [CheckPermission] call is always made between an object representing the *resource* and an object representing a *subject*: The API call returns whether the *subject* has the specified permission on the *resource*.
 
-The choice of how to represent subjects can have large downstream effects on the design of a permissions system.
-
 [CheckPermission]: https://buf.build/authzed/api/docs/main:authzed.api.v1#CheckPermission
 
 ## Representing users as subjects
@@ -34,7 +32,7 @@ As the `sub` field is **guaranteed** to be stable for that particular user (if a
 
 <Callout type="info">
 
-If you have *multiple* authentication provides, then the recommendation is to define a subject type for *each* provider, to ensure a clean namespace:
+If you have *multiple* authentication providers, then the recommendation is to define a subject type for *each* provider, to ensure a clean namespace:
 
 ```zed
 /** githubuser represents a user from GitHub */
@@ -67,7 +65,7 @@ Some databases allow various sequences to reuse IDs.
 
 <Callout type="warning">
 
-It is typically **not recommended** to use an e-mail address to represent a user as as a subject in SpiceDB.
+It is typically **not recommended** to use an e-mail address to represent a user as a subject in SpiceDB.
 
 </Callout>
 

pages/spicedb/modeling/validation-testing-debugging.mdx

@@ -60,7 +60,7 @@ assertFalse: []
 #### Caveat Context In Assertions
 
 <Callout type="info">
-    In order to escape JSON representation of the caveat context in an assertion you should use single-quotes
+    In order to escape JSON representation of the caveat context in an assertion you should use single-quotes.
 </Callout>
 
 You can provide caveat context as part of an assertion:
@@ -155,9 +155,7 @@ Request tracing information by setting `with_tracing: true` in the request messa
 
 <Callout type="warning">
   **Warning:**
-  Versions older than v1.31.0
-
-  Request tracing information via a header and the information will be found in the response footer as JSON.
+  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.
 </Callout>
 
 ## Zed
@@ -242,7 +240,9 @@ true
    └── user:fred 
 ```
 
-This command will also highlight which parts of the traversal were cached and if a cycle is detected.
+This command will also highlight which parts of the traversal were cached and if a [cycle] is detected.
+
+[cycle]: ./recursion-and-max-depth#recursion-in-relationships
 
 [tracing header]: #checkpermission-tracing-header
 

pages/spicedb/ops/load-testing.mdx

@@ -53,7 +53,7 @@ If more groups were related, to `document:somedocument`, it's likely that more s
 
 Notable exceptions to short-circuiting (thus negatively impacting overall performance) are usages of [Intersections (&)] and [Exclusions (-)].
 
-While fanout is mostly unavoidable, it can result in an exponential increase to the the number of sub-problems that must be computed.
+While fanout is mostly unavoidable, it can result in an exponential increase to the number of sub-problems that must be computed.
 Therefore, when performing a load test it's critical to have a SpiceDB instance seeded with relationship data that closely mimics real world data.
 
 [Intersections (&)]: ../concepts/schema#-intersection
@@ -197,7 +197,7 @@ We highly recommend that you [get in touch][call] for a schema review session be
 
 ### SpiceDB Caveats Performance
 
-In general, we only recommend using caveats when when you’re evaluating dynamic data (e.g. users can only access the document between 9-5 or users can only access the document when you are in the EU).
+In general, we only recommend using caveats when you’re evaluating dynamic data (e.g. users can only access the document between 9-5 or users can only access the document when you are in the EU).
 Almost all other scenarios can be represented in the graph.
 Caveats add computational cost to checks because their evaluations can't be cached.