From 0182f1cac67231ae2a3ff7e6f72f69d1f364d24c Mon Sep 17 00:00:00 2001
From: Scott Trinh <scott@scotttrinh.com>
Date: Thu, 13 Feb 2025 16:15:20 -0500
Subject: [PATCH] wip

---
 docs/intro/quickstart/access.rst      | 423 ---------------
 docs/intro/quickstart/dynamic.rst     | 136 -----
 docs/intro/quickstart/index.rst       |   5 +-
 docs/intro/quickstart/inheritance.rst |  89 ++--
 docs/intro/quickstart/modeling.rst    |  40 +-
 docs/intro/quickstart/setup.rst       |  10 +-
 docs/intro/quickstart/workflow.rst    | 111 ----
 docs/intro/quickstart/working.rst     | 717 +++++++++++++-------------
 8 files changed, 447 insertions(+), 1084 deletions(-)
 delete mode 100644 docs/intro/quickstart/access.rst
 delete mode 100644 docs/intro/quickstart/dynamic.rst
 delete mode 100644 docs/intro/quickstart/workflow.rst

diff --git a/docs/intro/quickstart/access.rst b/docs/intro/quickstart/access.rst
deleted file mode 100644
index a41e946534e..00000000000
--- a/docs/intro/quickstart/access.rst
+++ /dev/null
@@ -1,423 +0,0 @@
-.. _ref_quickstart_access:
-
-=====================
-Adding Access Control
-=====================
-
-.. edb:split-section::
-
-  In this section, you will add a concept of a user to your application, and update your data model to limit access to the decks and cards to only the user's own decks. The ``User`` type will be very simple, and for authentication, use a simple ``AccessToken`` type that gets returned from the user creation endpoint when you make a new user. Gel has some really powerful tools available in our authentication extension, but for now, just use a simple token that you will store in the database.
-
-  Along with this user type, add some ``global`` values that will use the access token provided by the client to set a global ``current_user`` variable that you can use in your queries to limit access to the decks and cards to only the user's own decks.
-
-  .. note::
-
-    Deck creators should be required, but since you are adding this to an existing dataset, set the new ``creator`` property to optional. That will effectively make the existing cards and decks invisible since they don't have a creator. You can update the existing data in the database to set the ``creator`` property for all of the existing decks and cards after making the first user, or reinsert the deck and the creator will be set in your updated query.
-
-  .. code-block:: sdl-diff
-    :caption: dbschema/default.gel
-
-      module default {
-    +   single optional global access_token: uuid;
-    +   single optional global current_user := (
-    +     select AccessToken filter .id = global access_token
-    +   ).user;
-    +
-    +   type User {
-    +     required name: str;
-    +   }
-    +
-    +   type AccessToken {
-    +     required user: User;
-    +   }
-    +
-        type Deck {
-          required name: str;
-          description: str;
-    +
-    +     creator: User;
-
-          cards := (select .<deck[is Card] order by .order);
-    +
-    +     access policy creator_has_full_access
-    +       allow all
-    +       using (
-    +         .creator ?= global current_user
-    +       );
-        };
-
-        type Card {
-          required order: int64;
-          required front: str;
-          required back: str;
-
-          required deck: Deck;
-    +
-    +     access policy deck_creator_has_full_access
-    +       allow all
-    +       using (
-    +         .deck.creator ?= global current_user
-    +       );
-        }
-      }
-
-.. edb:split-section::
-
-  Create this migration which will also trigger the query builder to be regenerated.
-
-  .. code-block:: sh
-
-    $ npx gel migration create
-    did you create global 'default::access_token'? [y,n,l,c,b,s,q,?]
-    > y
-    did you create object type 'default::User'? [y,n,l,c,b,s,q,?]
-    > y
-    did you create object type 'default::AccessToken'? [y,n,l,c,b,s,q,?]
-    > y
-    did you create global 'default::current_user'? [y,n,l,c,b,s,q,?]
-    > y
-    did you alter object type 'default::Deck'? [y,n,l,c,b,s,q,?]
-    > y
-    did you create access policy 'deck_creator_has_full_access' of object type 'default::Card'? [y,n,l,c,b,s,q,?]
-    > y
-    Created /home/strinh/projects/flashcards/dbschema/migrations/00003-m1solvt.edgeql, id: m1solvta35uzsbs4axzqmkwfx7zatjtkozpr43cjs56fp75qzbrg5q
-
-    $ npx gel migrate
-    Applying m1solvta35uzsbs4axzqmkwfx7zatjtkozpr43cjs56fp75qzbrg5q (00003-m1solvt.edgeql)
-    ... parsed
-    ... applied
-    Generating query builder...
-    Detected tsconfig.json, generating TypeScript files.
-    To override this, use the --target flag.
-    Run `npx @gel/generate --help` for full options.
-    Introspecting database schema...
-    Generating runtime spec...
-    Generating cast maps...
-    Generating scalars...
-    Generating object types...
-    Generating function types...
-    Generating operators...
-    Generating set impl...
-    Generating globals...
-    Generating index...
-    Writing files to ./dbschema/edgeql-js
-    Generation complete! 🤘
-
-.. edb:split-section::
-
-  Create a page for creating a new user and getting an access token. Start by creating the query to create a new user which will return the ``AccessToken.id`` which you will use as the access token itself. Save this access token in a cookie so that you can authenticate requests in other server actions and route handlers.
-
-  .. tabs::
-
-    .. code-tab:: typescript
-      :caption: app/signup/actions.ts
-
-        "use server";
-
-        import { redirect } from "next/navigation";
-        import { cookies } from "next/headers";
-
-        import { client } from "@/lib/gel";
-        import e from "@/dbschema/edgeql-js";
-
-        const createUser = e.params(
-          {
-            name: e.str,
-          },
-          (params) =>
-            e.insert(e.AccessToken, {
-              user: e.insert(e.User, { name: params.name }),
-            })
-        );
-
-        export async function signUp(formData: FormData) {
-          const name = formData.get("name");
-          if (typeof name !== "string") {
-            console.error("Name is required");
-            return;
-          }
-
-          const access_token = await createUser(client, { name });
-          (await cookies()).set("flashcards_access_token", access_token.id);
-          redirect("/");
-        }
-
-
-    .. code-tab:: typescript
-      :caption: app/signup/page.tsx
-
-        import { Button } from "@/components/ui/button";
-        import {
-          Card,
-          CardContent,
-          CardDescription,
-          CardHeader,
-          CardTitle,
-        } from "@/components/ui/card";
-        import { Input } from "@/components/ui/input";
-        import { Label } from "@/components/ui/label";
-
-        import { signUp } from "./actions";
-
-        export default function SignUpPage() {
-          return (
-            <div className="flex flex-col items-center justify-center gap-6">
-              <Card className="w-full max-w-md">
-                <CardHeader>
-                  <CardTitle className="text-2xl">Sign Up</CardTitle>
-                  <CardDescription>
-                    Enter your name below to create an account
-                  </CardDescription>
-                </CardHeader>
-                <CardContent>
-                  <form action={signUp}>
-                    <div className="flex flex-col gap-6">
-                      <div className="grid gap-2">
-                        <Label htmlFor="name">Name</Label>
-                        <Input
-                          id="name"
-                          name="name"
-                          type="text"
-                          placeholder="John Doe"
-                          required
-                        />
-                      </div>
-                      <Button type="submit" className="w-full">
-                        Sign Up
-                      </Button>
-                    </div>
-                  </form>
-                </CardContent>
-              </Card>
-            </div>
-          );
-        }
-
-.. edb:split-section::
-
-  You should see this page when you navigate to the signup page.
-
-  .. code-block:: sh
-
-    $ echo
-
-Limiting access
-===============
-
-.. edb:split-section::
-
-  Now that you have your access token in a cookie, create a helper function to extract it and add it as a global to your client.
-
-  .. code-block:: typescript-diff
-    :caption: app/lib/gel.ts
-
-    + import { createClient, type Client } from "gel";
-    - import { createClient } from "gel";
-    + import { cookies } from "next/headers";
-
-      export const client = createClient();
-
-    + export async function getAuthenticatedClient(): Promise<Client | null> {
-    +   const access_token = (await cookies()).get("flashcards_access_token")?.value;
-    +   if (!access_token) {
-    +     return null;
-    +   }
-    +   return client.withGlobals({ access_token });
-    + }
-
-.. edb:split-section::
-
-  Along with allowing you to take advantage of your access policies in your queries, this will also allow you to redirect unauthenticated users to the signup page from any of your pages which should require authentication. Update your ``page.tsx`` file to redirect to the signup page if the user is not authenticated. Also, show the list of decks on this page.
-
-  .. tabs::
-
-    .. code-tab:: typescript-diff
-      :caption: app/actions.ts
-
-        "use server";
-      - import { client } from "@/lib/gel";
-      + import { getAuthenticatedClient } from "@/lib/gel";
-        import { createDeck } from "./create-deck.query";
-      + import e from "@/dbschema/edgeql-js";
-
-        export async function importDeck(formData: FormData) {
-          const deck = formData.get("deck");
-          if (typeof deck !== "string") {
-            return;
-          }
-      +
-      +   const client = await getAuthenticatedClient();
-      +   if (!client) {
-      +     return;
-      +   }
-
-          await createDeck(client, JSON.parse(deck));
-        }
-      +
-      + export async function getDecks() {
-      +   const client = await getAuthenticatedClient();
-      +   if (!client) {
-      +     return [];
-      +   }
-      +
-      +   return e.select(e.Deck, (d) => ({
-      +     id: true,
-      +     name: true,
-      +   })).run(client);
-      + }
-
-    .. code-tab:: typescript-diff
-      :caption: app/page.tsx
-
-        import { ImportForm } from "./form";
-      + import { getAuthenticatedClient } from "@/lib/gel";
-      + import { redirect } from "next/navigation";
-      + import { getDecks } from "./actions";
-
-        export default async function Page() {
-      +   const client = await getAuthenticatedClient();
-      +   if (!client) {
-      +     redirect("/signup");
-      +   }
-      +
-      +   const decks = await getDecks(client);
-      +
-      -   return <ImportForm />;
-      +   return (
-      +     <div>
-      +       <h1>Decks</h1>
-      +       <ul>
-      +         {decks.map((deck) => (
-      +           <li key={deck.id}>{deck.name}</li>
-      +         ))}
-      +       </ul>
-      +       <ImportForm />
-      +     </div>
-      +   );
-        }
-
-.. edb:split-section::
-
-  Next update the create deck query and server action with the authentication logic and ``creator`` property.
-
-  .. tabs::
-
-    .. code-tab:: typescript-diff
-      :caption: app/actions.ts
-
-        "use server";
-        import { redirect } from "next/navigation";
-      - import { client } from "@/lib/gel";
-      + import { getAuthenticatedClient } from "@/lib/gel";
-        import { createDeck } from "./create-deck.query";
-
-        export async function createDeck(formData: FormData) {
-          const deck = formData.get("deck");
-          if (typeof deck !== "string") {
-            return;
-          }
-
-          const client = await getAuthenticatedClient();
-          if (!client) {
-            return;
-          }
-
-          const { id } = await createDeck(client, JSON.parse(deck));
-          redirect(`/deck/${id}`);
-        }
-
-    .. code-tab:: typescript-diff
-      :caption: app/create-deck.query.ts (query builder)
-
-        // Run `npm generate edgeql-js` to generate the `e` query builder module.
-        import e from "@/dbschema/edgeql-js";
-
-        const createDeckQuery = e.params(
-          {
-            name: e.str,
-            description: e.optional(e.str),
-            cards: e.array(e.tuple({ order: e.int64, front: e.str, back: e.str })),
-          },
-          ({
-            cards,
-            ...deckData
-          }) => {
-      -     const newDeck = e.insert(e.Deck, deckData);
-      +     const newDeck = e.insert(e.Deck, {
-      +       ...deckData,
-      +       creator: e.assert_exists(e.global.current_user),
-      +     });
-            const newCards = e.for(e.array_unpack(cards), (card) =>
-              e.insert(e.Card, {
-                ...card,
-                deck: newDeck,
-              })
-            );
-            return e.with([newCards], e.select(newDeck));
-          }
-        );
-
-        export const createDeck = createDeckQuery.run.bind(createDeckQuery);
-
-.. edb:split-section::
-
-  Finally, update the deck page to require an authenticated user, and to return the deck's creator.
-
-  .. code-block:: typescript-diff
-    :caption: app/deck/[id]/page.tsx
-
-      import { notFound } from "next/navigation";
-    - import { client } from "@/lib/gel";
-    + import { getAuthenticatedClient } from "@/lib/gel";
-      import e from "@/dbschema/edgeql-js";
-      import { Fragment } from "react";
-
-      const getDeckQuery = e.params({ id: e.uuid }, (params) =>
-        e.select(e.Deck, (d) => ({
-          filter_single: e.op(d.id, "=", params.id),
-          id: true,
-          name: true,
-          description: true,
-          cards: {
-            id: true,
-            front: true,
-            back: true,
-            order: true,
-          },
-    +     creator: {
-    +       id: true,
-    +       name: true,
-    +     },
-        }))
-      );
-
-      export default async function DeckPage(
-        { params }: { params: Promise<{ id: string }> }
-      ) {
-        const { id } = await params;
-    +   const client = await getAuthenticatedClient();
-    +   if (!client) {
-    +     notFound();
-    +   }
-    +
-        const deck = await getDeckQuery.run(client, { id });
-
-        if (!deck) {
-          notFound();
-        }
-
-        return (
-          <div>
-            <h1>{deck.name}</h1>
-            <p>{deck.description}</p>
-            <dl>
-              {deck.cards.map((card) => (
-                <Fragment key={card.id}>
-                  <dt>{card.front}</dt>
-                  <dd>{card.back}</dd>
-                </Fragment>
-              ))}
-            </dl>
-          </div>
-        )
-      }
diff --git a/docs/intro/quickstart/dynamic.rst b/docs/intro/quickstart/dynamic.rst
deleted file mode 100644
index eed1a985d5d..00000000000
--- a/docs/intro/quickstart/dynamic.rst
+++ /dev/null
@@ -1,136 +0,0 @@
-.. _ref_quickstart_dynamic:
-
-===============
-Dynamic Queries
-===============
-
-When updating data, you often want to modify only specific fields while leaving others unchanged. For example, you might want to update just the front text of a flashcard or only the description of a deck. There are two main approaches to handle these partial updates:
-
-1. Write a single complex query that conditionally handles optional parameters
-2. Build the query dynamically in the application code based on which fields need updating
-
-The second approach using dynamic queries tends to be more performant and maintainable. EdgeDB's TypeScript query builder excels at this use case. It allows you to construct queries dynamically while maintaining full type safety. Let's see how to implement this pattern.
-
-.. edb:split-section::
-
-  Create a server action that updates a deck's ``name`` and/or ``description``. Since the description is optional, treat clearing the ``description`` form field as unsetting the ``description`` property.
-
-  Update the deck page to allow updating a deck's ``name`` and/or ``description``. Treat the request body as a partial update, and only update the fields that are provided. Since the description is optional, treat clearing the ``description`` form field as unsetting the ``description`` property.
-
-  .. tabs::
-
-    .. code-tab:: typescript
-      :caption: app/deck/[id]/actions.ts
-
-        "use server";
-
-        import { revalidatePath } from "next/cache";
-        import e from "@/dbschema/edgeql-js";
-        import { getAuthenticatedClient } from "@/lib/gel";
-
-        export async function updateDeck(data: FormData) {
-          const id = data.get("id");
-          if (!id) {
-            throw new Error("Missing deck ID");
-          }
-
-          const client = await getAuthenticatedClient();
-          if (!client) {
-            throw new Error("Unauthorized");
-          }
-
-          const name = data.get("name");
-          const description = data.get("description");
-
-          const nameSet = typeof name === "string" ? { name } : {};
-          const descriptionSet =
-            typeof description === "string"
-              ? { description: description || null }
-              : {};
-
-          await e
-            .update(e.Deck, (d) => ({
-              filter_single: e.op(d.id, "=", e.uuid(id)),
-              set: {
-                ...nameSet,
-                ...descriptionSet,
-              },
-            }))
-            .run(client);
-
-          revalidatePath(`/deck/${id}`);
-        }
-
-    .. code-tab:: typescript-diff
-      :caption: app/deck/[id]/page.tsx
-
-        import { redirect } from "next/navigation";
-        import { getAuthenticatedClient } from "@/lib/gel";
-        import e from "@/dbschema/edgeql-js";
-      + import { updateDeck } from "./actions";
-
-        const getDeckQuery = e.params({ deckId: e.uuid }, (params) =>
-          e.select(e.Deck, (d) => ({
-            filter_single: e.op(d.id, "=", params.deckId),
-            id: true,
-            name: true,
-            description: true,
-            cards: {
-              id: true,
-              front: true,
-              back: true,
-              order: true,
-            },
-            creator: {
-              id: true,
-              name: true,
-            },
-          }))
-        );
-
-        export default async function DeckPage(
-          { params }: { params: Promise<{ id: string }> }
-        ) {
-          const { id: deckId } = await params;
-          const client = await getAuthenticatedClient();
-          if (!client) {
-            redirect("/signup");
-          }
-
-          const deck = await getDeckQuery.run(client, { deckId });
-
-          if (!deck) {
-            redirect("/");
-          }
-
-          return (
-            <div>
-      -       <h1>{deck.name}</h1>
-      -       <p>{deck.description}</p>
-      +       <form action={updateDeck}>
-      +         <input
-      +           type="hidden"
-      +           name="id"
-      +           value={deck.id}
-      +         />
-      +         <input
-      +           name="name"
-      +           defaultValue={deck.name}
-      +         />
-      +         <textarea
-      +           name="description"
-      +           defaultValue={deck.description}
-      +         />
-      +         <button type="submit">Update</button>
-      +       </form>
-              <ul>
-                {deck.cards.map((card) => (
-                  <dl key={card.id}>
-                    <dt>{card.front}</dt>
-                    <dd>{card.back}</dd>
-                  </dl>
-                ))}
-              </ul>
-            </div>
-          )
-        }
diff --git a/docs/intro/quickstart/index.rst b/docs/intro/quickstart/index.rst
index 640a5b46fc0..23ac0a9dc5a 100644
--- a/docs/intro/quickstart/index.rst
+++ b/docs/intro/quickstart/index.rst
@@ -11,13 +11,10 @@ Quickstart
   setup
   modeling
   working
-  workflow
-  access
   inheritance
-  dynamic
 
 
-Welcome to the quickstart tutorial! You will create a simple Flashcards application using Next.js and Gel. The application will let users build and manage their own study decks, with each flashcard featuring customizable text on both sides - making it perfect for studying, memorization practice, or creating educational games.
+Welcome to the quickstart tutorial! In this tutorial, you will update a simple Next.js application to use Gel as your data layer. The application will let users build and manage their own study decks, with each flashcard featuring customizable text on both sides - making it perfect for studying, memorization practice, or creating educational games.
 
 Don't worry if you're new to Gel - you will be up and running with a working Next.js application and a local Gel database in just about **5 minutes**. From there, you will replace the static mock data with a Gel powered data layer in roughly 30-45 minutes.
 
diff --git a/docs/intro/quickstart/inheritance.rst b/docs/intro/quickstart/inheritance.rst
index 1a0b0bbc57a..75cbb5c19ae 100644
--- a/docs/intro/quickstart/inheritance.rst
+++ b/docs/intro/quickstart/inheritance.rst
@@ -12,11 +12,6 @@ Adding Shared Properties
     :caption: dbschema/default.gel
 
       module default {
-        single optional global access_token: str;
-        single optional global current_user := (
-          select AccessToken filter .token = access_token
-        ).user;
-
     +   abstract type Timestamped {
     +     required created_at: datetime {
     +       default := datetime_of_statement();
@@ -26,33 +21,15 @@ Adding Shared Properties
     +     };
     +   }
     +
-    -   type User {
-    +   type User extending Timestamped {
-          required name: str;
-        }
-
-    -   type AccessToken {
-    +   type AccessToken extending Timestamped {
-          required user: User;
-          required token: str {
-            constraint exclusive;
-          };
-        }
-
     -   type Deck {
     +   type Deck extending Timestamped {
           required name: str;
           description: str;
 
-          creator: User;
-
-          cards := (select .<deck[is Card] order by .order);
-
-          access policy creator_has_full_access
-            allow all
-            using (
-              .creator ?= global current_user
-            );
+          cards := (
+            select .<deck[is Card]
+            order by .order
+          );
         };
 
     -   type Card {
@@ -62,12 +39,6 @@ Adding Shared Properties
           required back: str;
 
           required deck: Deck;
-
-          access policy deck_creator_has_full_access
-            allow all
-            using (
-              .deck.creator ?= global current_user
-            );
         }
       }
 
@@ -80,10 +51,6 @@ Adding Shared Properties
     $ npx gel migration create
     did you create object type 'default::Timestamped'? [y,n,l,c,b,s,q,?]
     > y
-    did you alter object type 'default::AccessToken'? [y,n,l,c,b,s,q,?]
-    > y
-    did you alter object type 'default::User'? [y,n,l,c,b,s,q,?]
-    > y
     did you alter object type 'default::Card'? [y,n,l,c,b,s,q,?]
     > y
     did you alter object type 'default::Deck'? [y,n,l,c,b,s,q,?]
@@ -94,6 +61,54 @@ Adding Shared Properties
     Applying m1d2m5n5ajkalyijrxdliioyginonqbtfzihvwdfdmfwodunszstya (00004-m1d2m5n.edgeql)
     ... parsed
     ... applied
+    Generating query builder...
+    Detected tsconfig.json, generating TypeScript files.
+      To override this, use the --target flag.
+      Run `npx @gel/generate --help` for full options.
+    Introspecting database schema...
+    Generating runtime spec...
+    Generating cast maps...
+    Generating scalars...
+    Generating object types...
+    Generating function types...
+    Generating operators...
+    Generating set impl...
+    Generating globals...
+    Generating index...
+    Writing files to ./dbschema/edgeql-js
+    Generation complete! 🤘
+
+.. edb:split-section::
+
+  Update the ``getDecks`` query to sort the decks by ``updated_at`` in descending order.
+
+  .. code-block:: typescript-diff
+      :caption: app/queries.ts
+
+        import { client } from "@/lib/gel";
+        import e from "@/dbschema/edgeql-js";
+
+      - const getDecksQuery = e.select(e.Deck, () => ({
+      + const getDecksQuery = e.select(e.Deck, (deck) => ({
+          id: true,
+          name: true,
+          description: true,
+          cards: {
+            id: true,
+            front: true,
+            back: true,
+          },
+      +   order_by: {
+      +     expression: deck.updated_at,
+      +     direction: e.DESC,
+      +   },
+        }));
+
+        export async function getDecks() {
+          const decks = await getDecksQuery.run(client);
+
+          return decks;
+        }
 
 .. edb:split-section::
 
diff --git a/docs/intro/quickstart/modeling.rst b/docs/intro/quickstart/modeling.rst
index 970524e2162..51cb2aa273e 100644
--- a/docs/intro/quickstart/modeling.rst
+++ b/docs/intro/quickstart/modeling.rst
@@ -1,31 +1,51 @@
 .. _ref_quickstart_modeling:
 
 =================
-Modeling your data
+Modeling the data
 =================
 
 .. edb:split-section::
 
   The flashcards application has a simple data model, but it's interesting enough to get a taste of many of the features of the Gel schema language. You have a ``Card`` type that describes a single flashcard, which for now contains two required string properties: ``front`` and ``back``. Each ``Card`` belongs to a ``Deck``, and there is an explicit ordering to the cards in a given deck.
 
-  Starting with this simple model, express these types in the ``default.gel`` schema file.
+  Looking at the mock data, you can see this structure in the JSON.
+
+  .. code-block:: typescript
+
+    interface Card {
+      front: string;
+      back: string;
+    }
+
+    interface Deck {
+      name: string;
+      description: string | null;
+      cards: Card[];
+    }
+
+.. edb:split-section::
+
+  Starting with this simple model, add these types to the ``default.gel`` schema file. As you can see, the types closely mirror the JSON mock data.
+
+  Also of note, the link between ``Card`` and ``Deck`` objects creates a "1-to-n" relationship, where each ``Deck`` object has a link to zero or more ``Card`` objects. When you query the ``Deck.cards`` link, the cards will be unordered, so the ``Card`` type needs an explicit ``order`` property to allow sorting them at query time.
 
   .. code-block:: sdl-diff
     :caption: dbschema/default.gel
 
       module default {
-    +   type Deck {
-    +     required name: str;
-    +     description: str;
-    +   };
-
     +   type Card {
     +     required order: int64;
     +     required front: str;
     +     required back: str;
-
-    +     required deck: Deck;
-    +   }
+    +   };
+    +
+    +   type Deck {
+    +     required name: str;
+    +     description: str;
+    +     multi cards: Card {
+    +       constraint exclusive;
+    +     };
+    +   };
       };
 
 .. edb:split-section::
diff --git a/docs/intro/quickstart/setup.rst b/docs/intro/quickstart/setup.rst
index f8556401a2c..f11466baec9 100644
--- a/docs/intro/quickstart/setup.rst
+++ b/docs/intro/quickstart/setup.rst
@@ -20,7 +20,7 @@ Setting up your environment
 
 .. edb:split-section::
 
-  Quickly take a poke around the empty database with the CLI REPL.
+  Explore the empty database by starting our REPL from the project root.
 
   .. code-block:: sh
 
@@ -56,12 +56,12 @@ Setting up your environment
 
 .. edb:split-section::
 
-  Fun! You will create a proper data model for the application in the next step, but for now, take a look around the project you've just created. Most of the project files will be familiar if you've worked with Next.js before. Focus on the new files that integrate Gel.
+  Fun! You will create a proper data model for the application in the next step, but for now, take a look around the project you've just created. Most of the project files will be familiar if you've worked with Next.js before. Here are the new files that integrate Gel:
 
-  - ``gel.toml``: This is the configuration file for the Gel project instance.
+  - ``gel.toml``: The configuration file for the Gel project instance.
   - ``dbschema/``: This directory contains the schema for the database, and later supporting files like migrations, and generated code.
-  - ``dbschema/default.gel``: This is the default schema file that you'll use to define your data model. It is empty for now, but you'll add your data model to this file in the next step.
-  - ``lib/gel.ts``: This file contains the Gel client, which you'll use to interact with the database.
+  - ``dbschema/default.gel``: The default schema file that you'll use to define your data model. It is empty for now, but you'll add your data model to this file in the next step.
+  - ``lib/gel.ts``: A utility module that exports the Gel client, which you'll use to interact with the database.
 
   .. code-block:: sh
 
diff --git a/docs/intro/quickstart/workflow.rst b/docs/intro/quickstart/workflow.rst
deleted file mode 100644
index 41184939e01..00000000000
--- a/docs/intro/quickstart/workflow.rst
+++ /dev/null
@@ -1,111 +0,0 @@
-.. _ref_quickstart_workflow:
-
-===============================
-A Smoother Development Workflow
-===============================
-
-Part of building an application involves making changes to the schema, so take some time to make a comfortable development workflow for yourself. Spending a bit of time now will make it easier to stay in the flow of development.
-
-Staying in sync
-===============
-
-.. edb:split-section::
-
-  When your schema changes, the query builder files need to be regenerated to pick up the new changes. This can slow you down a bit, so the next workflow improvement is to add a hook script that will regenerate the query builder files after the migration is applied.
-
-  .. code-block:: toml-diff
-    :caption: gel.toml
-
-      [gel]
-      server-version = 6.0
-    +
-    + [hooks]
-    + schema.update.after = "npx @gel/generate edgeql-js"
-
-.. edb:split-section::
-
-  Make some changes to your schema and update your code. The first change will be to add a property to the ``Deck`` type that stores the link to all of the cards in the deck ordered by the ``order`` property on the ``Card`` type. Create a computed property, and use a back link from the ``Card`` type to the ``Deck`` type.
-
-  .. code-block:: sdl-diff
-    :caption: dbschema/default.gel
-
-      module default {
-        type Deck {
-          required name: str;
-          description: str;
-    +
-    +     cards := (select .<deck[is Card] order by .order);
-        };
-
-        type Card {
-          required order: int64;
-          required front: str;
-          required back: str;
-
-          required deck: Deck;
-        }
-      };
-
-.. edb:split-section::
-
-  Now that you've made your changes, create a migration to apply the changes to the database, and you will see that it also regenerates the query builder files.
-
-  .. code-block:: sh
-
-      $ npx gel migration create
-      $ npx gel migrate
-
-.. edb:split-section::
-
-  At the moment, in the ``getDeck`` query, you are defining this ``cards`` property explicitly. Now that you've added the computed property, remove the explicit definition.
-
-  .. code-block:: typescript-diff
-    :caption: app/deck/[id]/page.tsx
-
-      import { redirect } from "next/navigation";
-      import { client } from "@/lib/gel";
-      import e from "@/dbschema/edgeql-js";
-
-      const getDeckQuery = e.params({ deckId: e.uuid }, (params) =>
-        e.select(e.Deck, (d) => ({
-          filter_single: e.op(d.id, "=", params.deckId),
-          id: true,
-          name: true,
-          description: true,
-    -     cards: e.select(d["<deck[is Card]"], (c) => ({
-    +     cards: {
-            id: true,
-            front: true,
-            back: true,
-            order: true,
-    -       order_by: c.order,
-    -     })),
-          },
-        }))
-      );
-
-      export default async function DeckPage(
-        { params }: { params: Promise<{ id: string }> }
-      ) {
-        const { id: deckId } = await params;
-        const deck = await getDeckQuery.run(client, { deckId });
-
-        if (!deck) {
-          redirect("/");
-        }
-
-        return (
-          <div>
-            <h1>{deck.name}</h1>
-            <p>{deck.description}</p>
-            <ul>
-              {deck.cards.map((card) => (
-                <dl key={card.id}>
-                  <dt>{card.front}</dt>
-                  <dd>{card.back}</dd>
-                </dl>
-              ))}
-            </ul>
-          </div>
-        )
-      }
diff --git a/docs/intro/quickstart/working.rst b/docs/intro/quickstart/working.rst
index 264ee3718e0..c93667d0925 100644
--- a/docs/intro/quickstart/working.rst
+++ b/docs/intro/quickstart/working.rst
@@ -6,407 +6,408 @@ Working with the data
 
 .. edb:split-section::
 
-  With TypeScript, there are three ways to run a query: use a string EdgeQL query, use the ``queries`` generator to turn a string of EdgeQL into a TypeScript function, or use the query builder API to build queries dynamically in a type-safe manner. In the next example, you will see each of these methods, but the rest of the tutorial will use the query builder API.
+  With TypeScript, there are three ways to run a query: use a string EdgeQL query, use the ``queries`` generator to turn a string of EdgeQL into a TypeScript function, or use the query builder API to build queries dynamically in a type-safe manner. In this tutorial, you will use the TypeScript query builder API.
 
-  .. tabs::
-
-    .. code-tab:: sh
-      :caption: Query builder
-
-      $ npx @gel/generate edgeql-js
+  This query builder must be generated any time the schema changes, so add a hook in your ``gel.toml`` file to generate the query builder when the schema is updated.
 
-    .. code-tab:: sh
-      :caption: Queries generator
+  .. code-block:: toml-diff
+    :caption: gel.toml
 
-      $ npx @gel/generate queries
+      [instance]
+      server-version = 6.0
+    +
+    + [hooks]
+    + schema.update.after = "npx @gel/generate edgeql-js"
 
 .. edb:split-section::
 
-  Now that you have a schema defined, create a simple page with a button that allows users to import a deck of cards from a JSON file. Use Next.js server actions to handle the file upload and insert the data into your database. The JSON file will contain the deck name, optional description, and an array of cards with front and back text.
-
-  .. note::
-      If you are seeing TypeScript or ESLint errors, you may need to restart the TypeScript language server, or the ESLint server. Sometimes when adding new files, the language server or ESLint will not pick up the new files until you restart the server. This will be true for the rest of the tutorial, but the majority of development is not creating new files, so after this initial onboarding pain, you will find that editor tooling works well. This is not a Gel-specific issue, but rather a general issue with starting a new project.
-
-  .. edb:split-point::
-
-  .. tabs::
-
-    .. code-tab:: typescript
-      :caption: app/page.tsx
-
-        import { ImportForm } from "./form";
-
-        export default function Page() {
-          return <ImportForm />;
-        }
-
-    .. code-tab:: typescript
-      :caption: app/form.tsx
-
-        "use client";
-        import { useTransition, useState } from "react";
-        import { importDeck } from "./actions";
-
-        export function ImportForm() {
-          const [isPending, startTransition] = useTransition();
-          const [importState, setImportState] = useState<
-            "idle" | "loading" | "success" | "error"
-          >("idle");
-
-          const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-            const file = event.target.files?.[0];
-            if (!file) return;
-
-            setImportState("loading");
-            startTransition(async () => {
-              const deck = await file.text();
-
-              const formData = new FormData();
-              formData.set("deck", deck);
-              try {
-                await importDeck(formData);
-                setImportState("success");
-                event.target.form?.reset();
-              } catch (error) {
-                console.error(error);
-                setImportState("error");
-              }
-            });
-          };
-
-          return (
-            <form>
-              <label htmlFor="file">Upload a deck of cards</label>
-              {importState === "loading" && <p>Importing...</p>}
-              {importState === "success" && <p>Imported successfully</p>}
-              {importState === "error" && <p>Error importing</p>}
-              <input
-                type="file"
-                id="file"
-                onChange={handleFileChange}
-                disabled={isPending}
-              />
-            </form>
-          );
-        }
-
-
-    .. code-tab:: typescript
-      :caption: app/actions.ts
-
-        "use server";
-        import { client } from "@/lib/gel";
-        import { createDeck } from "./create-deck.query";
-
-        export async function importDeck(formData: FormData) {
-          const deck = formData.get("deck");
-          if (typeof deck !== "string") {
-            return;
-          }
-
-          await createDeck(client, JSON.parse(deck));
-        }
+  Since our schema migration has already run, we will run the generator once now to generate the query builder files, but subsequent migrations will automatically generate the files as needed.
 
-    .. code-tab:: typescript
-      :caption: app/create-deck.query.ts (query builder)
-
-        // Run `npm generate edgeql-js` to generate the `e` query builder module.
-        import e from "@/dbschema/edgeql-js";
-
-        const createDeckQuery = e.params(
-          {
-            name: e.str,
-            description: e.optional(e.str),
-            cards: e.array(e.tuple({ order: e.int64, front: e.str, back: e.str })),
-          },
-          ({
-            cards,
-            ...deckData
-          }) => {
-            const newDeck = e.insert(e.Deck, deckData);
-            const newCards = e.for(e.array_unpack(cards), (card) =>
-              e.insert(e.Card, {
-                ...card,
-                deck: newDeck,
-              })
-            );
-            return e.with([newCards], e.select(newDeck));
-          }
-        );
-
-        export const createDeck = createDeckQuery.run.bind(createDeckQuery);
-
-    .. code-tab:: typescript
-      :caption: app/create-deck.query.ts (string query)
-
-        import { type Client } from "@/lib/gel";
-
-        const createDeckQuery = `
-          with
-            name := <str>$name,
-            description := <optional str>$description,
-            cards := array_unpack(<array<tuple<front: str, back: str>>>$cards),
-            new_deck := (
-              insert Deck {
-                name := name,
-                description := description,
-              }
-            ),
-            new_cards := (
-              for card in cards
-              insert Card {
-                order := card.order,
-                front := card.front,
-                back := card.back,
-                deck := new_deck,
-              }
-            ),
-          select new_deck;
-        `;
-
-        export async function createDeck(
-          client: Client,
-          args: {
-            name: string;
-            description?: string;
-            cards: { order: number; front: string; back: string }[];
-          }
-        ): Promise<{ id: string }> {
-          return client.queryRequiredSingle(createDeckQuery, args);
-        }
+  .. code-block:: sh
 
-    .. code-tab:: edgeql
-      :caption: app/create-deck.edgeql (queries)
-
-        # Run `npm generate queries` to generate the create-deck.query.ts file.
-        with
-          name := <str>$name,
-          description := <optional str>$description,
-          cards := array_unpack(<array<tuple<front: str, back: str>>>$cards),
-          new_deck := (
-            insert Deck {
-              name := name,
-              description := description,
-            }
-          ),
-          new_cards := (
-            for card in cards
-            insert Card {
-              order := card.order,
-              front := card.front,
-              back := card.back,
-              deck := new_deck,
-            }
-          ),
-        select new_deck;
+    $ npx @gel/generate edgeql-js
 
 .. edb:split-section::
 
-  Create a static JSON file to seed your database with a deck of trivia cards.
-
-  .. code-block:: json
-    :caption: deck-edgeql.json
-
-      {
-        "name": "Learning EdgeQL",
-        "description": "A progressive guide to learning EdgeQL and SDL from basics to advanced concepts",
-        "cards": [
-          {
-            "front": "What data structure is used as a container for all values in EdgeQL?",
-            "back": "Sets. Even single values are treated as sets with one element (singletons)."
-          },
-          {
-            "front": "Can EdgeQL sets contain the same value multiple times?",
-            "back": "Yes, EdgeQL sets are mutli-sets."
-          },
-          {
-            "front": "How does EdgeQL represent no value?",
-            "back": "A typed empty set."
-          },
-          {
-            "front": "What are the string scalar types in EdgeQL?",
-            "back": "str"
-          },
-          {
-            "front": "What are the numeric scalar types in EdgeQL?",
-            "back": "int16, int32, int64, float32, float64, bigint, decimal"
-          },
-          {
-            "front": "By default, are properties of an Object type required?",
-            "back": "No, unless marked as required, properties are optional."
-          },
-          {
-            "front": "How do you define a one-to-one relationship between two object types?",
-            "back": "You define a single, exclusive link from one of the types to the other."
-          },
-          {
-            "front": "How do you define a one-to-many relationship between two object types?",
-            "back": "You define a multi, exclusive link from the one-typed object to the many-typed object."
-          },
-          {
-            "front": "How do you define a many-to-one relationship between two object types?",
-            "back": "You define a single, non-exclusive link from the many-type to the one-type."
-          },
-          {
-            "front": "How do you define a many-to-many relationship between two object types?",
-            "back": "You define a multi, non-exclusive link from one of the types to the other."
-          }
-        ]
+  Now that the schema has been defined, and the query builder has been generated, update the server action for importing a deck with cards.
+
+  .. code-block:: typescript-diff
+    :caption: app/actions.ts
+
+      "use server";
+
+    - import { readFile, writeFile } from "node:fs/promises";
+    + import { client } from "@/lib/gel";
+    + import e from "@/dbschema/edgeql-js";
+      import { revalidatePath } from "next/cache";
+    - import { RawJSONDeck, Deck } from "@/lib/models";
+    + import { RawJSONDeck } from "@/lib/models";
+
+      export async function importDeck(formData: FormData) {
+        const file = formData.get("file") as File;
+        const rawDeck = JSON.parse(await file.text()) as RawJSONDeck;
+        const deck = {
+          ...rawDeck,
+    -     id: crypto.randomUUID(),
+    -     cards: rawDeck.cards.map((card) => ({
+    +     cards: rawDeck.cards.map((card, index) => ({
+            ...card,
+    -       id: crypto.randomUUID(),
+    +       order: index,
+          })),
+        };
+    -
+    -   const existingDecks = JSON.parse(
+    -     await readFile("./decks.json", "utf-8")
+    -   ) as Deck[];
+    -
+    -   await writeFile(
+    -     "./decks.json",
+    -     JSON.stringify([...existingDecks, deck], null, 2)
+    -   );
+    +   const cardIds: string[] = [];
+    +   for (const card of deck.cards) {
+    +     const createdCard = await e
+    +       .insert(e.Card, {
+    +         front: card.front,
+    +         back: card.back,
+    +         order: card.order,
+    +       })
+    +       .run(client);
+    +
+    +     cardIds.push(createdCard.id);
+    +   }
+    +
+    +   await e
+    +     .params({ cardIds: e.array(e.uuid) }, (params) =>
+    +       e.insert(e.Deck, {
+    +         name: deck.name,
+    +         description: deck.description,
+    +         cards: e.select(e.Card, (c) => ({
+    +           filter: e.contains(params.cardIds, c.id),
+    +         })),
+    +       })
+    +     )
+    +     .run(client, { cardIds });
+
+        revalidatePath("/");
       }
 
-
 .. edb:split-section::
 
-  In the terminal, we will run the Next.js development server.
+  This works, but you might notice that it is not atomic. If one of the ``Card`` objects fails to insert, the entire operation will fail and the ``Deck`` will not be inserted. To make this operation atomic, you can use a transaction.
+
+  .. code-block:: typescript-diff
+    :caption: app/actions.ts
+
+      "use server";
+
+      import { client } from "@/lib/gel";
+      import e from "@/dbschema/edgeql-js";
+      import { revalidatePath } from "next/cache";
+      import { RawJSONDeck } from "@/lib/models";
+
+      export async function importDeck(formData: FormData) {
+        const file = formData.get("file") as File;
+        const rawDeck = JSON.parse(await file.text()) as RawJSONDeck;
+        const deck = {
+          ...rawDeck,
+          cards: rawDeck.cards.map((card, index) => ({
+            ...card,
+            order: index,
+          })),
+        };
+    +   await client.transaction(async (tx) => {
+        const cardIds: string[] = [];
+        for (const card of deck.cards) {
+          const createdCard = await e
+            .insert(e.Card, {
+              front: card.front,
+              back: card.back,
+              order: card.order,
+            })
+    -       .run(client);
+    +       .run(tx);
+
+          cardIds.push(createdCard.id);
+        }
 
-  .. code-block:: sh
+        await e
+          .params({ cardIds: e.array(e.uuid) }, (params) =>
+            e.insert(e.Deck, {
+              name: deck.name,
+              description: deck.description,
+              cards: e.select(e.Card, (c) => ({
+                filter: e.contains(params.cardIds, c.id),
+              })),
+            })
+          )
+    -     .run(client, { cardIds });
+    +     .run(tx, { cardIds });
+    +   });
 
-    $ npm run dev
+        revalidatePath("/");
+      }
 
 .. edb:split-section::
 
-  We should see our app running at http://localhost:3000.
-
-  .. image:: https://placehold.co/600x400?text=Show+import+form+ui
+  You might think this is as good as it gets, and many ORMs will basically create exactly this set of queries. However, the query builder allows you to do even better by creating a single query that will insert the ``Deck`` and ``Card`` objects, and the link between them all as a single fast query.
+
+  .. code-block:: typescript-diff
+    :caption: app/actions.ts
+
+      "use server";
+
+      import { client } from "@/lib/gel";
+      import e from "@/dbschema/edgeql-js";
+      import { revalidatePath } from "next/cache";
+      import { RawJSONDeck } from "@/lib/models";
+
+      export async function importDeck(formData: FormData) {
+        const file = formData.get("file") as File;
+        const rawDeck = JSON.parse(await file.text()) as RawJSONDeck;
+        const deck = {
+          ...rawDeck,
+          cards: rawDeck.cards.map((card, index) => ({
+            ...card,
+            order: index,
+          })),
+        };
+    -   await client.transaction(async (tx) => {
+    -   const cardIds: string[] = [];
+    -   for (const card of deck.cards) {
+    -     const createdCard = await e
+    -       .insert(e.Card, {
+    -         front: card.front,
+    -         back: card.back,
+    -         order: card.order,
+    -       })
+    -       .run(tx);
+    -
+    -     cardIds.push(createdCard.id);
+    -   }
+    -
+    -   await e
+    -     .params({ cardIds: e.array(e.uuid) }, (params) =>
+    -       e.insert(e.Deck, {
+    -         name: deck.name,
+    -         description: deck.description,
+    -         cards: e.select(e.Card, (c) => ({
+    -           filter: e.contains(params.cardIds, c.id),
+    -         })),
+    -       })
+    -     )
+    -     .run(tx, { cardIds });
+    -   });
+    +   await e
+    +     .params(
+    +       {
+    +         name: e.str,
+    +         description: e.optional(e.str),
+    +         cards: e.array(e.tuple({ front: e.str, back: e.str, order: e.int64 })),
+    +       },
+    +       (params) =>
+    +         e.insert(e.Deck, {
+    +           name: params.name,
+    +           description: params.description,
+    +           cards: e.for(e.array_unpack(params.cards), (card) =>
+    +             e.insert(e.Card, {
+    +               front: card.front,
+    +               back: card.back,
+    +               order: card.order,
+    +             })
+    +           ),
+    +         })
+    +     )
+    +     .run(client, deck);
+
+        revalidatePath("/");
+      }
 
 .. edb:split-section::
 
-  Next, let's define a page for viewing a deck of cards, and update our import form to redirect to the deck page after importing.
+  Next, update the Server Actions associated with each ``Deck`` object, ``updateDeck``, ``addCard``, and ``deleteCard``. Starting with ``updateDeck``, which is the most complex since it is dynamic. You can set either the ``title`` or ``description`` fields in an update, so we will use the dynamic nature of the query builder to generate separate queries depending on which fields are present in the form data.
 
-  .. tabs::
+  This may look a little intimidating at first, but the part that is making this query dynamic is the ``nameSet`` and ``descriptionSet`` variables. These variables are used to conditionally add the ``name`` or ``description`` fields to the ``set`` parameter of the ``update`` call.
 
-    .. code-tab:: typescript-diff
-      :caption: app/actions.ts
+  .. code-block:: typescript-diff
+    :caption: app/(authenticated)/deck/[id]/actions.ts
+
+      "use server";
 
-        "use server";
-      + import { redirect } from "next/navigation";
-        import { client } from "@/lib/gel";
-        import { createDeck } from "./create-deck.query";
+      import { revalidatePath } from "next/cache";
+    - import { readFile, writeFile } from "node:fs/promises";
+    + import { client } from "@/lib/gel";
+    + import e from "@/dbschema/edgeql-js";
+      import { Deck } from "@/lib/models";
 
-        export async function importDeck(formData: FormData) {
-          const deck = formData.get("deck");
-          if (typeof deck !== "string") {
-            return;
-          }
+      export async function updateDeck(formData: FormData) {
+        const id = formData.get("id");
+        const name = formData.get("name");
+        const description = formData.get("description");
 
-          await createDeck(client, JSON.parse(deck));
-      +   redirect(`/deck/${id}`);
+        if (
+          typeof id !== "string" ||
+          (typeof name !== "string" &&
+          typeof description !== "string")
+        ) {
+          return;
         }
 
-    .. code-tab:: typescript
-      :caption: app/deck/[id]/page.tsx
-
-        import { notFound } from "next/navigation";
-        import { client } from "@/lib/gel";
-        import e from "@/dbschema/edgeql-js";
-        import { Fragment } from "react";
-
-        const getDeckQuery = e.params({ id: e.uuid }, (params) =>
-          e.select(e.Deck, (d) => ({
-            filter_single: e.op(d.id, "=", params.id),
-            id: true,
-            name: true,
-            description: true,
-            cards: e.select(d["<deck[is Card]"], (c) => ({
-              id: true,
-              front: true,
-              back: true,
-              order: true,
-              order_by: c.order,
-            }))
-          }))
-        );
-
-        export default async function DeckPage(
-          { params }: { params: Promise<{ id: string }> }
+    -   const decks = JSON.parse(
+    -     await readFile("./decks.json", "utf-8")
+    -   ) as Deck[];
+    -   decks[index].name = name ?? decks[index].name;
+    +   const nameSet = typeof name === "string" ? { name } : {};
+    -   decks[index].description = description ?? decks[index].description;
+    +   const descriptionSet =
+    +     typeof description === "string" ? { description: description || null } : {};
+
+    +   await e
+    +     .update(e.Deck, (d) => ({
+    +       filter_single: e.op(d.id, "=", id),
+    +       set: {
+    +         ...nameSet,
+    +         ...descriptionSet,
+    +       },
+    +     })).run(client);
+    -   await writeFile("./decks.json", JSON.stringify(decks, null, 2));
+        revalidatePath(`/deck/${id}`);
+      }
+
+    + const addCardQuery = e.params(
+    +   {
+    +     front: e.str,
+    +     back: e.str,
+    +     deckId: e.uuid,
+    +   },
+    +   (params) => {
+    +     const deck = e.assert_exists(
+    +       e.select(e.Deck, (d) => ({
+    +         filter_single: e.op(d.id, "=", params.deckId),
+    +       }))
+    +     );
+    +
+    +     const order = e.cast(e.int64, e.max(deck.cards.order));
+    +     return e.insert(e.Card, {
+    +       front: params.front,
+    +       back: params.back,
+    +       deck: e.cast(e.Deck, params.deckId),
+    +       order: e.op(order, "+", 1),
+    +     });
+    +   }
+    + );
+    +
+      export async function addCard(formData: FormData) {
+    +   const client = await getAuthenticatedClient();
+    +   if (!client) {
+    +     return;
+    +   }
+    +
+        const deckId = formData.get("deckId");
+        const front = formData.get("front");
+        const back = formData.get("back");
+
+        if (
+          typeof deckId !== "string" ||
+          typeof front !== "string" ||
+          typeof back !== "string"
         ) {
-          const { id } = await params;
-          const deck = await getDeckQuery.run(client, { id });
-
-          if (!deck) {
-            notFound();
-          }
-
-          return (
-            <div>
-              <h1>{deck.name}</h1>
-              <p>{deck.description}</p>
-              <dl>
-                {deck.cards.map((card) => (
-                  <Fragment key={card.id}>
-                    <dt>{card.front}</dt>
-                    <dd>{card.back}</dd>
-                  </Fragment>
-                ))}
-              </dl>
-            </div>
-          )
+          return;
         }
 
-    .. code-tab:: typescript-diff
-      :caption: app/form.tsx
-
-        "use client";
-      - import { useTransition, useState } from "react";
-      + import { useTransition } from "react";
-        import { importDeck } from "./actions";
-
-        export function ImportForm() {
-          const [isPending, startTransition] = useTransition();
-      -   const [importState, setImportState] = useState<
-      -     "idle" | "loading" | "success" | "error"
-      -   >("idle");
-
-          const handleFileChange = (event: React.ChangeEvent<HTMLInputElement>) => {
-            const file = event.target.files?.[0];
-            if (!file) return;
-
-      -     setImportState("loading");
-            startTransition(async () => {
-              const deck = await file.text();
-
-              const formData = new FormData();
-              formData.set("deck", deck);
-              try {
-                await importDeck(formData);
-      -         setImportState("success");
-                event.target.form?.reset();
-              } catch (error) {
-                console.error(error);
-      -         setImportState("error");
-              }
-            });
-          };
-
-          return (
-            <form>
-              <label htmlFor="file">Upload a deck of cards</label>
-      -       {importState === "loading" && <p>Importing...</p>}
-      +       {isPending && <p>Importing...</p>}
-      -       {importState === "success" && <p>Imported successfully</p>}
-      -       {importState === "error" && <p>Error importing</p>}
-              <input
-                type="file"
-                id="file"
-                onChange={handleFileChange}
-                disabled={isPending}
-              />
-            </form>
-          );
+    -   const decks = JSON.parse(await readFile("./decks.json", "utf-8")) as Deck[];
+    -
+    -   const deck = decks.find((deck) => deck.id === deckId);
+    -   if (!deck) {
+    -     return;
+    -   }
+    -
+    -   deck.cards.push({ front, back, id: crypto.randomUUID() });
+    -   await writeFile("./decks.json", JSON.stringify(decks, null, 2));
+    +   await addCardQuery.run(client, {
+    +     front,
+    +     back,
+    +     deckId,
+    +   });
+
+        revalidatePath(`/deck/${deckId}`);
+      }
+
+    + const deleteCardQuery = e.params({ id: e.uuid }, (params) =>
+    +   e.delete(e.Card, (c) => ({
+    +     filter_single: e.op(c.id, "=", params.id),
+    +   }))
+    + );
+    +
+      export async function deleteCard(formData: FormData) {
+    +   const client = await getAuthenticatedClient();
+    +   if (!client) {
+    +     return;
+    +   }
+    +
+        const cardId = formData.get("cardId");
+
+        if (typeof cardId !== "string") {
+          return;
         }
 
+    -   const decks = JSON.parse(await readFile("./decks.json", "utf-8")) as Deck[];
+    -   const deck = decks.find((deck) => deck.cards.some((card) => card.id === cardId));
+    -   if (!deck) {
+    -     return;
+    -   }
+    -
+    -   deck.cards = deck.cards.filter((card) => card.id !== cardId);
+    -   await writeFile("./decks.json", JSON.stringify(decks, null, 2));
+    +   await deleteCardQuery.run(client, { id: cardId });
+
+        revalidatePath(`/`);
+      }
 
 .. edb:split-section::
 
-  Which should look something like this:
+  Next, update the ``queries.ts`` module to get decks from the database. Notice that the cards are ordered by the ``order`` property.
+
+  .. tabs::
 
-  .. image:: https://placehold.co/600x400?text=Show+deck+page
+    .. code-tab:: typescript-diff
+      :caption: app/queries.ts
+
+      - import { readFile } from "node:fs/promises";
+      + import { client } from "@/lib/gel";
+      + import e from "@/dbschema/edgeql-js";
+
+      - import { Deck } from "@/lib/models";
+      + const getDecksQuery = e.select(e.Deck, (deck) => ({
+      +   id: true,
+      +   name: true,
+      +   description: true,
+      +   cards: e.select(deck.cards, (card) => ({
+      +     id: true,
+      +     front: true,
+      +     back: true,
+      +     order_by: card.order,
+      +   })),
+      + }));
+
+        export async function getDecks() {
+      -   const decks = JSON.parse(await readFile("./decks.json", "utf-8")) as Deck[];
+      +   const decks = await getDecksQuery.run(client);
+
+          return decks;
+        }
 
 .. edb:split-section::
 
-  Now that we have some data of various types in our database, let's explore that data in the UI. We can use the Data Explorer view to see the ``Deck`` and ``Card`` objects we've created and even directly mutate the data.
+  In a terminal, run the Next.js development server.
 
   .. code-block:: sh
 
-        $ npx gel ui
+    $ npm run dev
+
+.. edb:split-section::
+
+  A static JSON file to seed your database with a deck of trivia cards is included in the project. Open your browser and navigate to the app at <http://localhost:3000>_. Use the "Import JSON" button to import this JSON file into your database.
 
+  .. image:: https://placehold.co/600x400?text=Show+import+deck+ui