docs: add guide for rewrites

docs/keto/guides/userset-rewrites.mdx

@@ -0,0 +1,117 @@
+---
+title: Userset Rewrites
+---
+
+import Tabs from "@theme/Tabs"
+import TabItem from "@theme/TabItem"
+import CodeFromRemote from "@theme/CodeFromRemote"
+const sha = "fc39b65f8be9b23bbb4e19480706964d61505c5e"
+const file = (path) => `https://github.com/ory/keto/blob/${sha}/contrib/rewrites-example/${path}`
+
+This guide will explain how to configure your your namespaces and relations using the
+[Ory Permission Language](../reference/ory-permission-language).
+
+The example describes a file store. Individual files are organized in a folder hierarchy, and can be accessed by users or groups
+of users. Through the Ory Permission Language we can specify that if a user has access to a folder, the user also has access to
+all files in that folder.
+
+## Setup and Configuration
+
+First, [install Keto](../install.mdx). Next, you need the following `keto.yaml` (at `contrib/rewrites-example/keto.yaml`):
+
+<CodeFromRemote src={file("keto.yaml")} />
+
+In the _namespaces_ key, you see the line `config: file://./namespaces.keto.ts`. This needs to point to your namespace
+configuration in the Ory Permission Language.
+
+:::info Backwards compatibility
+
+Namespace configurations without the Ory Permission Language are still supported by either specifying the namespaces directly or a
+"naked" URI, e.g. `namespaces: file://.namespaces.yaml`.
+
+:::
+
+Next, we create a file with our namespace configuration as follows:
+
+<CodeFromRemote src={file("namespaces.keto.ts")} />
+
+:::tip Editor support
+
+If you are using a text editor with TypeScript support, you can get extra help when using the Ory Permission Language. Just make
+sure that the file `contrib/rewrites-examples/lib.ts` is in the same folder as the file you are editing. It contains all
+definitions to type-check the config.
+
+In the future, we will make the lib file available at an easy-to-import location.
+
+:::
+
+### Starting Ory Keto
+
+After you created both configuration files (keto.yaml and namespaces.keto.ts), you can start Ory Keto with:
+
+```sh
+$ keto serve --config ./path/to/keto.yaml
+```
+
+## Creating the tuples
+
+Now that Ory Keto is running, we can create the tuples either through the Keto CLI.
+
+We use the following relation tuples to showcase the namespace configuration. In short, it sets up a "developer" group with two
+members, and a folder hierarchy. Through the rules in the Ory Permission Language, every member of the "developer" group can
+access the files in the hierarchy.
+
+As usual, it is still possible to create additional fine-grained permission rules for certain objects, as is done for the
+"private" file.
+
+<CodeFromRemote src={file("relation-tuples/tuples.json")} />
+
+You can load the file into keto as such:
+
+```sh
+$ keto relation-tuple create ./contrib/rewrites-example/relation-tuples/tuples.json
+
+NAMESPACE       OBJECT                  RELATION NAME   SUBJECT
+Group           developer               members         patrik
+Group           developer               members         User:Patrik
+Group           developer               members         User:Henning
+Folder          keto/                   viewers         Group:developer#members
+File            keto/README.md          parents         Folder:keto/
+Folder          keto/src/               parents         Folder:keto/
+File            keto/src/main.go        parents         Folder:keto/src/
+File            private                 owners          User:Henning
+```
+
+## Checking for permissions
+
+Now, let's check some permissions! Some queries to try:
+
+```
+$ keto check User:Patrik view File keto/src/main.go
+Allowed
+```
+
+Patrik can view "keto/src/main.go", because it is in the folder "keto/src", which is in the folder "keto", which has as "viewers"
+the group "developer", of which Patrik is a member of.
+
+```
+$ keto check User:Patrik view File private
+Denied
+```
+
+Patrik cannot view the private file, since that file is not part of any folder hierarchy Patrik has access to.
+
+```
+$ keto check User:Henning view File private
+Allowed
+
+$ keto check User:Henning edit File private
+Allowed
+```
+
+Henning can both edit and view the private file, since he is an "owner" of it.
+
+## Further reading
+
+If you want to dig furhter into the Ory Permission Language, be sure to check out the
+[specification](../reference/ory-permission-language).