add docs titles for llms.txt, fixup referential variable docs

Author: wernst

packages/docs/src/pages/client/web-worker-client.mdx

@@ -1,3 +1,7 @@
+---
+description: How to run Triplit in a Web Worker - useful for multi-tab offline support and reducing main thread workload.
+---
+
 # Web Worker Client
 
 Triplit supports running the client in a Web Worker (specifically, a [`SharedWorker`](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker), which can connect to multiple tabs running a script from the same domain). While running a Web Worker, data syncs between browser tabs without having to sync with server. This reduces network traffic for Triplit apps running in the multiple tabs, move Triplit local database computation to a separate thread, and allow for robust multi-tab offline support.

packages/docs/src/pages/frameworks/react-native.mdx

@@ -27,30 +27,36 @@ For more information on setting up an Expo project with typescript see the [Expo
 
 Next, install Triplit's packages:
 
+<Callout type="warning">
+  There is currently a bug in how Triplit handles optional dependencies in
+  Metro, so you will need to install `uuidv7` as a dependency in your project.
+  This is a temporary workaround until the bug is fixed.
+</Callout>
+
 <Tabs items={['npm', 'pnpm', 'yarn', 'bun']}>
   <Tab>
     ```bash copy
-    npm i @triplit/client @triplit/react-native
+    npm i @triplit/client @triplit/react-native uuidv7
     npm i @triplit/cli --save-dev
     ```
   </Tab>
   <Tab>
     ```bash copy
-    pnpm add @triplit/client @triplit/react-native
+    pnpm add @triplit/client @triplit/react-native uuidv7
     pnpm add @triplit/cli --save-dev
     ```
 
   </Tab>
   <Tab>
     ```bash copy
-    yarn add @triplit/client @triplit/react-native
+    yarn add @triplit/client @triplit/react-native uuidv7
     yarn add @triplit/cli --dev
     ```
 
   </Tab>
   <Tab>
     ```bash copy
-    bun add @triplit/client @triplit/react-native
+    bun add @triplit/client @triplit/react-native uuidv7
     bun add @triplit/cli --dev
     ```
 

packages/docs/src/pages/query/subquery.mdx

@@ -80,3 +80,25 @@ A given entity in the result will look like this:
 }
 */
 ```
+
+## Use with relational queries
+
+The examples above are hardcoded to a specific user ID, however you can use [referential variables](/query/variables#referential-variables) to make the subquery dynamic. For example:
+
+```typescript
+// Fetch all 747 planes that have a flight to an airport newer than the plane
+const query = client.query('planes').Where([
+  ['model', '=', '747']
+  {
+    exists: client.query('flights').Where([
+      ['plane_id', '=', '$1.id'],
+      {
+        exists: client.query('airports').Where([
+          ['id', '=', '$1.destination_id']
+          ['created_at', '>', '$2.created_at'],
+        ]),
+      },
+    ]),
+  },
+]);
+```

packages/docs/src/pages/query/variables.mdx

@@ -43,6 +43,39 @@ Token variables are prefixed with the `token` scope and are accessible to all qu
 
 When determining access control rules with [roles](/schemas/permissions#roles), you can use role variables to reference values from a client's token in your permission definitions. Role variables are prefixed with the `role` scope.
 
+### Referential variables
+
+When issuing a subquery to load related data, you can use a referential variable in your query to reference ancestral data in the query. Referential variables are prefixed with a number (e.g. `$1`, `$2`, etc.) and correspond to higher levels of the query. If you are coming from a SQL background, you can think of these variables referencing the join keys of the parent.
+
+For example, you may fetch all posts and include the author of each post in the result:
+
+```typescript
+const query = client.query('posts').SubqueryMany(
+  'postAuthors',
+  client.query('users').Where(['id', '=', '$1.authorId']) // $1.authorId refers to posts.authorId
+);
+```
+
+By default, `$1` will actually be applied automatically if you do not specify a variable prefix `$authorId` in the filter. However, you would be required to use the referential prefix if you wanted to reference a grandparent or higher in the query:
+
+```typescript
+// Fetch all 747 planes that have a flight to an airport newer than the plane
+const query = client.query('planes').Where([
+  ['model', '=', '747']
+  {
+    exists: client.query('flights').Where([
+      ['plane_id', '=', '$1.id'],
+      {
+        exists: client.query('airports').Where([
+          ['id', '=', '$1.destination_id']
+          ['created_at', '>', '$2.created_at'],
+        ]),
+      },
+    ]),
+  },
+]);
+```
+
 ## Accessing variables
 
 `$global` and `$token` variables are accessible on the client instance through the `vars` property.

packages/docs/src/pages/schemas/relations.mdx

@@ -124,4 +124,22 @@ const departmentsQuery = client.query('departments').Include('classes');
 
 ## Defining relations with referential variables
 
-TODO
+You can also define relations ad-hoc in a query using referential variables. This allows you to define relations that are not part of the schema and is equivalent to a `JOIN` you might see in SQL. Under the hood, this is actually what your `RelationMany`, `RelationOne`, and `RelationById` attributes are doing. See usage of referential variables in the [Variables](/query/variables#referential-variables) documentation. For example:
+
+```typescript
+// Fetch all 747 planes that have a flight to an airport newer than the plane
+const query = client.query('planes').Where([
+  ['model', '=', '747']
+  {
+    exists: client.query('flights').Where([
+      ['plane_id', '=', '$1.id'],
+      {
+        exists: client.query('airports').Where([
+          ['id', '=', '$1.destination_id']
+          ['created_at', '>', '$2.created_at'],
+        ]),
+      },
+    ]),
+  },
+]);
+```

packages/docs/src/pages/self-hosting/docker.mdx

@@ -1,3 +1,7 @@
+---
+description: Learn how to run Triplit in a Docker container.
+---
+
 # Docker
 
 Triplit publishes the following Docker images that run in the following environments:

packages/docs/src/pages/self-hosting/key-gen.mdx

@@ -1,3 +1,7 @@
+---
+description: Learn how to generate keys and tokens for Triplit authentication.
+---
+
 # Key and Token Generation
 
 This page will help you generate the keys needed to run a self-hosted Triplit server. You will need to generate a signing key and a public key, which are used to sign and verify tokens for authentication. This is unopinionated on where you store your keys.

packages/docs/src/pages/self-hosting/platform-guides/fly.mdx

@@ -1,3 +1,7 @@
+---
+description: Learn how to deploy Triplit on Fly.io.
+---
+
 import { Steps } from 'nextra/components';
 
 # Deploying to Fly.io

packages/docs/src/pages/self-hosting/platform-guides/railway.mdx

@@ -1,3 +1,7 @@
+---
+description: Learn how to deploy Triplit on Railway.
+---
+
 import { Steps, Callout } from 'nextra/components';
 
 # Deploying to Railway

packages/docs/src/pages/ssr.mdx

@@ -1,3 +1,7 @@
+---
+description: Learn how to use Triplit in a server-side rendering environment, like SvelteKit, Next.js, or Remix.
+---
+
 # Server-side rendering
 
 Triplit is designed to work in a client-side environment, but it can work in a server-side rendering (SSR) environment as well.