diff --git a/drizzle-postgres/0004_charming_doomsday.sql b/drizzle-postgres/0004_charming_doomsday.sql
new file mode 100644
index 000000000..dfc9e4681
--- /dev/null
+++ b/drizzle-postgres/0004_charming_doomsday.sql
@@ -0,0 +1,2 @@
+ALTER TABLE "workspace_items" DROP CONSTRAINT "workspace_items_type_check";--> statement-breakpoint
+ALTER TABLE "workspace_items" ADD CONSTRAINT "workspace_items_type_check" CHECK ("workspace_items"."type" in ('folder', 'document', 'flashcard', 'quiz', 'file'));
\ No newline at end of file
diff --git a/drizzle-postgres/0005_dashing_masked_marvel.sql b/drizzle-postgres/0005_dashing_masked_marvel.sql
new file mode 100644
index 000000000..8abf0f064
--- /dev/null
+++ b/drizzle-postgres/0005_dashing_masked_marvel.sql
@@ -0,0 +1,7 @@
+ALTER TABLE "workspace_items" ADD COLUMN "ref_key" text DEFAULT substr(translate(encode(decode(md5(gen_random_uuid()::text), 'hex'), 'base64'), '+/', 'Aa'), 1, 8) NOT NULL;--> statement-breakpoint
+UPDATE "workspace_items" w SET "ref_key" = substr(translate(encode(decode(md5(gen_random_uuid()::text || w.id), 'hex'), 'base64'), '+/', 'Aa'), 1, 8)
+WHERE EXISTS (
+	SELECT 1 FROM "workspace_items" d
+	WHERE d."workspace_id" = w."workspace_id" AND d."ref_key" = w."ref_key" AND d."id" <> w."id"
+);--> statement-breakpoint
+CREATE UNIQUE INDEX "workspace_items_ref_key_unique" ON "workspace_items" USING btree ("workspace_id","ref_key");
\ No newline at end of file
diff --git a/drizzle-postgres/meta/0004_snapshot.json b/drizzle-postgres/meta/0004_snapshot.json
new file mode 100644
index 000000000..3b9dbe680
--- /dev/null
+++ b/drizzle-postgres/meta/0004_snapshot.json
@@ -0,0 +1,2478 @@
+{
+  "id": "cff9bd5b-3d3d-4cc3-86d9-7236e8cef04d",
+  "prevId": "25aa9ff5-8b2a-4423-8d78-053fd64107c5",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.account": {
+      "name": "account",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "account_id": {
+          "name": "account_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_token": {
+          "name": "access_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token": {
+          "name": "refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token": {
+          "name": "id_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "access_token_expires_at": {
+          "name": "access_token_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token_expires_at": {
+          "name": "refresh_token_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "account_userId_idx": {
+          "name": "account_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "account_user_id_user_id_fk": {
+          "name": "account_user_id_user_id_fk",
+          "tableFrom": "account",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.jwks": {
+      "name": "jwks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "public_key": {
+          "name": "public_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "private_key": {
+          "name": "private_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_access_token": {
+      "name": "oauth_access_token",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_id": {
+          "name": "refresh_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oauth_access_token_client_id_idx": {
+          "name": "oauth_access_token_client_id_idx",
+          "columns": [
+            {
+              "expression": "client_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_access_token_session_id_idx": {
+          "name": "oauth_access_token_session_id_idx",
+          "columns": [
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_access_token_user_id_idx": {
+          "name": "oauth_access_token_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_access_token_refresh_id_idx": {
+          "name": "oauth_access_token_refresh_id_idx",
+          "columns": [
+            {
+              "expression": "refresh_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_access_token_client_id_oauth_client_client_id_fk": {
+          "name": "oauth_access_token_client_id_oauth_client_client_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "oauth_client",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "client_id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_access_token_session_id_session_id_fk": {
+          "name": "oauth_access_token_session_id_session_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "session",
+          "columnsFrom": [
+            "session_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "oauth_access_token_user_id_user_id_fk": {
+          "name": "oauth_access_token_user_id_user_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_access_token_refresh_id_oauth_refresh_token_id_fk": {
+          "name": "oauth_access_token_refresh_id_oauth_refresh_token_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "oauth_refresh_token",
+          "columnsFrom": [
+            "refresh_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oauth_access_token_token_unique": {
+          "name": "oauth_access_token_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_client": {
+      "name": "oauth_client",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "disabled": {
+          "name": "disabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false,
+          "default": false
+        },
+        "skip_consent": {
+          "name": "skip_consent",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "enable_end_session": {
+          "name": "enable_end_session",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject_type": {
+          "name": "subject_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uri": {
+          "name": "uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "contacts": {
+          "name": "contacts",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tos": {
+          "name": "tos",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "policy": {
+          "name": "policy",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "software_id": {
+          "name": "software_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "software_version": {
+          "name": "software_version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "software_statement": {
+          "name": "software_statement",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "redirect_uris": {
+          "name": "redirect_uris",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "post_logout_redirect_uris": {
+          "name": "post_logout_redirect_uris",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "token_endpoint_auth_method": {
+          "name": "token_endpoint_auth_method",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "grant_types": {
+          "name": "grant_types",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "response_types": {
+          "name": "response_types",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "public": {
+          "name": "public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "require_pkce": {
+          "name": "require_pkce",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oauth_client_user_id_idx": {
+          "name": "oauth_client_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_client_user_id_user_id_fk": {
+          "name": "oauth_client_user_id_user_id_fk",
+          "tableFrom": "oauth_client",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oauth_client_client_id_unique": {
+          "name": "oauth_client_client_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "client_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_consent": {
+      "name": "oauth_consent",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oauth_consent_client_id_idx": {
+          "name": "oauth_consent_client_id_idx",
+          "columns": [
+            {
+              "expression": "client_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_consent_user_id_idx": {
+          "name": "oauth_consent_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_consent_client_id_oauth_client_client_id_fk": {
+          "name": "oauth_consent_client_id_oauth_client_client_id_fk",
+          "tableFrom": "oauth_consent",
+          "tableTo": "oauth_client",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "client_id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_consent_user_id_user_id_fk": {
+          "name": "oauth_consent_user_id_user_id_fk",
+          "tableFrom": "oauth_consent",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_refresh_token": {
+      "name": "oauth_refresh_token",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth_time": {
+          "name": "auth_time",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oauth_refresh_token_client_id_idx": {
+          "name": "oauth_refresh_token_client_id_idx",
+          "columns": [
+            {
+              "expression": "client_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_refresh_token_session_id_idx": {
+          "name": "oauth_refresh_token_session_id_idx",
+          "columns": [
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_refresh_token_user_id_idx": {
+          "name": "oauth_refresh_token_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_refresh_token_client_id_oauth_client_client_id_fk": {
+          "name": "oauth_refresh_token_client_id_oauth_client_client_id_fk",
+          "tableFrom": "oauth_refresh_token",
+          "tableTo": "oauth_client",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "client_id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_refresh_token_session_id_session_id_fk": {
+          "name": "oauth_refresh_token_session_id_session_id_fk",
+          "tableFrom": "oauth_refresh_token",
+          "tableTo": "session",
+          "columnsFrom": [
+            "session_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "oauth_refresh_token_user_id_user_id_fk": {
+          "name": "oauth_refresh_token_user_id_user_id_fk",
+          "tableFrom": "oauth_refresh_token",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oauth_refresh_token_token_unique": {
+          "name": "oauth_refresh_token_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.rate_limit": {
+      "name": "rate_limit",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "count": {
+          "name": "count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_request": {
+          "name": "last_request",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "rate_limit_key_unique": {
+          "name": "rate_limit_key_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "key"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.session": {
+      "name": "session",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "ip_address": {
+          "name": "ip_address",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_agent": {
+          "name": "user_agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "session_userId_idx": {
+          "name": "session_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "session_user_id_user_id_fk": {
+          "name": "session_user_id_user_id_fk",
+          "tableFrom": "session",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "session_token_unique": {
+          "name": "session_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user": {
+      "name": "user",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email_verified": {
+          "name": "email_verified",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "is_anonymous": {
+          "name": "is_anonymous",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "user_email_unique": {
+          "name": "user_email_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "email"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.verification": {
+      "name": "verification",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "identifier": {
+          "name": "identifier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "verification_identifier_idx": {
+          "name": "verification_identifier_idx",
+          "columns": [
+            {
+              "expression": "identifier",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_file_assets": {
+      "name": "workspace_file_assets",
+      "schema": "",
+      "columns": {
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_object_key": {
+          "name": "source_object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_hash": {
+          "name": "source_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_name": {
+          "name": "original_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "preview_object_key": {
+          "name": "preview_object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "preview_size_bytes": {
+          "name": "preview_size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "workspace_file_assets_item_id_workspace_items_id_fk": {
+          "name": "workspace_file_assets_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_file_assets",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "workspace_file_assets_source_object_key_unique": {
+          "name": "workspace_file_assets_source_object_key_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "source_object_key"
+          ]
+        },
+        "workspace_file_assets_preview_object_key_unique": {
+          "name": "workspace_file_assets_preview_object_key_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "preview_object_key"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_invites": {
+      "name": "workspace_invites",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_invites_token_unique": {
+          "name": "workspace_invites_token_unique",
+          "columns": [
+            {
+              "expression": "token",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_pending_link_per_role": {
+          "name": "workspace_invites_pending_link_per_role",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "role",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_invites\".\"type\" = 'link' and \"workspace_invites\".\"status\" = 'pending'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_pending_email_per_workspace": {
+          "name": "workspace_invites_pending_email_per_workspace",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "email",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_invites\".\"type\" = 'email' and \"workspace_invites\".\"status\" = 'pending'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_workspace_id_idx": {
+          "name": "workspace_invites_workspace_id_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_created_by_user_id_idx": {
+          "name": "workspace_invites_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_invites_workspace_id_workspaces_id_fk": {
+          "name": "workspace_invites_workspace_id_workspaces_id_fk",
+          "tableFrom": "workspace_invites",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_invites_created_by_user_id_user_id_fk": {
+          "name": "workspace_invites_created_by_user_id_user_id_fk",
+          "tableFrom": "workspace_invites",
+          "tableTo": "user",
+          "columnsFrom": [
+            "created_by_user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_invites_role_check": {
+          "name": "workspace_invites_role_check",
+          "value": "\"workspace_invites\".\"role\" in ('owner', 'admin', 'editor', 'viewer')"
+        },
+        "workspace_invites_type_check": {
+          "name": "workspace_invites_type_check",
+          "value": "\"workspace_invites\".\"type\" in ('email', 'link')"
+        },
+        "workspace_invites_status_check": {
+          "name": "workspace_invites_status_check",
+          "value": "\"workspace_invites\".\"status\" in ('pending', 'accepted', 'revoked', 'expired')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_contents": {
+      "name": "workspace_item_contents",
+      "schema": "",
+      "columns": {
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "workspace_item_contents_item_id_workspace_items_id_fk": {
+          "name": "workspace_item_contents_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_item_contents",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_extractions": {
+      "name": "workspace_item_extractions",
+      "schema": "",
+      "columns": {
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider": {
+          "name": "provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_mode": {
+          "name": "provider_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "source_hash": {
+          "name": "source_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_item_extractions_status_idx": {
+          "name": "workspace_item_extractions_status_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_item_extractions_item_fk": {
+          "name": "workspace_item_extractions_item_fk",
+          "tableFrom": "workspace_item_extractions",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "item_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_item_extractions_status_check": {
+          "name": "workspace_item_extractions_status_check",
+          "value": "\"workspace_item_extractions\".\"status\" in ('processing', 'ready', 'failed')"
+        },
+        "workspace_item_extractions_tier_check": {
+          "name": "workspace_item_extractions_tier_check",
+          "value": "\"workspace_item_extractions\".\"tier\" is null or \"workspace_item_extractions\".\"tier\" in ('fast', 'enhanced')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_pages": {
+      "name": "workspace_item_pages",
+      "schema": "",
+      "columns": {
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "markdown": {
+          "name": "markdown",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "markdown_bytes": {
+          "name": "markdown_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "workspace_item_pages_item_id_workspace_items_id_fk": {
+          "name": "workspace_item_pages_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_item_pages",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "workspace_item_pages_item_id_page_number_pk": {
+          "name": "workspace_item_pages_item_id_page_number_pk",
+          "columns": [
+            "item_id",
+            "page_number"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_item_pages_number_check": {
+          "name": "workspace_item_pages_number_check",
+          "value": "\"workspace_item_pages\".\"page_number\" > 0"
+        },
+        "workspace_item_pages_bytes_check": {
+          "name": "workspace_item_pages_bytes_check",
+          "value": "\"workspace_item_pages\".\"markdown_bytes\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_relations": {
+      "name": "workspace_item_relations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "from_item_id": {
+          "name": "from_item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_item_id": {
+          "name": "to_item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_item_relations_unique": {
+          "name": "workspace_item_relations_unique",
+          "columns": [
+            {
+              "expression": "from_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "to_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "kind",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "note",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_item_relations_from_idx": {
+          "name": "workspace_item_relations_from_idx",
+          "columns": [
+            {
+              "expression": "from_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_item_relations_to_idx": {
+          "name": "workspace_item_relations_to_idx",
+          "columns": [
+            {
+              "expression": "to_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_item_relations_from_fk": {
+          "name": "workspace_item_relations_from_fk",
+          "tableFrom": "workspace_item_relations",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "from_item_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_item_relations_to_fk": {
+          "name": "workspace_item_relations_to_fk",
+          "tableFrom": "workspace_item_relations",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "to_item_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_item_relations_kind_check": {
+          "name": "workspace_item_relations_kind_check",
+          "value": "\"workspace_item_relations\".\"kind\" in ('derived_from', 'references')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_user_states": {
+      "name": "workspace_item_user_states",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "state": {
+          "name": "state",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_item_user_states_item_id_idx": {
+          "name": "workspace_item_user_states_item_id_idx",
+          "columns": [
+            {
+              "expression": "item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_item_user_states_user_id_user_id_fk": {
+          "name": "workspace_item_user_states_user_id_user_id_fk",
+          "tableFrom": "workspace_item_user_states",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_item_user_states_item_id_workspace_items_id_fk": {
+          "name": "workspace_item_user_states_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_item_user_states",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "workspace_item_user_states_user_id_item_id_pk": {
+          "name": "workspace_item_user_states_user_id_item_id_pk",
+          "columns": [
+            "user_id",
+            "item_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_items": {
+      "name": "workspace_items",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parent_id": {
+          "name": "parent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name_key": {
+          "name": "name_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "color": {
+          "name": "color",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_items_tree_idx": {
+          "name": "workspace_items_tree_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_type_idx": {
+          "name": "workspace_items_type_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_root_name_unique": {
+          "name": "workspace_items_root_name_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_items\".\"parent_id\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_parent_name_unique": {
+          "name": "workspace_items_parent_name_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_items\".\"parent_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_items_workspace_id_workspaces_id_fk": {
+          "name": "workspace_items_workspace_id_workspaces_id_fk",
+          "tableFrom": "workspace_items",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_items_parent_fk": {
+          "name": "workspace_items_parent_fk",
+          "tableFrom": "workspace_items",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "parent_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "workspace_items_workspace_id_id_unique": {
+          "name": "workspace_items_workspace_id_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "workspace_id",
+            "id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "workspace_items_type_check": {
+          "name": "workspace_items_type_check",
+          "value": "\"workspace_items\".\"type\" in ('folder', 'document', 'flashcard', 'quiz', 'file')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_members": {
+      "name": "workspace_members",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        },
+        "last_opened_at": {
+          "name": "last_opened_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_members_workspace_user_unique": {
+          "name": "workspace_members_workspace_user_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_members_user_id_idx": {
+          "name": "workspace_members_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_members_user_last_opened_at_idx": {
+          "name": "workspace_members_user_last_opened_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "last_opened_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_members_workspace_id_workspaces_id_fk": {
+          "name": "workspace_members_workspace_id_workspaces_id_fk",
+          "tableFrom": "workspace_members",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_members_user_id_user_id_fk": {
+          "name": "workspace_members_user_id_user_id_fk",
+          "tableFrom": "workspace_members",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_members_role_check": {
+          "name": "workspace_members_role_check",
+          "value": "\"workspace_members\".\"role\" in ('owner', 'admin', 'editor', 'viewer')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspaces": {
+      "name": "workspaces",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "color": {
+          "name": "color",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "theme": {
+          "name": "theme",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revision": {
+          "name": "revision",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "owner_id": {
+          "name": "owner_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "workspaces_owner_id_idx": {
+          "name": "workspaces_owner_id_idx",
+          "columns": [
+            {
+              "expression": "owner_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspaces_archived_at_idx": {
+          "name": "workspaces_archived_at_idx",
+          "columns": [
+            {
+              "expression": "archived_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspaces_owner_id_user_id_fk": {
+          "name": "workspaces_owner_id_user_id_fk",
+          "tableFrom": "workspaces",
+          "tableTo": "user",
+          "columnsFrom": [
+            "owner_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
\ No newline at end of file
diff --git a/drizzle-postgres/meta/0005_snapshot.json b/drizzle-postgres/meta/0005_snapshot.json
new file mode 100644
index 000000000..08ed1fab4
--- /dev/null
+++ b/drizzle-postgres/meta/0005_snapshot.json
@@ -0,0 +1,2506 @@
+{
+  "id": "d97ba543-c09c-4540-9682-a823520ae2c7",
+  "prevId": "cff9bd5b-3d3d-4cc3-86d9-7236e8cef04d",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.account": {
+      "name": "account",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "account_id": {
+          "name": "account_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider_id": {
+          "name": "provider_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "access_token": {
+          "name": "access_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token": {
+          "name": "refresh_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "id_token": {
+          "name": "id_token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "access_token_expires_at": {
+          "name": "access_token_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_token_expires_at": {
+          "name": "refresh_token_expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scope": {
+          "name": "scope",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "password": {
+          "name": "password",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "account_userId_idx": {
+          "name": "account_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "account_user_id_user_id_fk": {
+          "name": "account_user_id_user_id_fk",
+          "tableFrom": "account",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.jwks": {
+      "name": "jwks",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "public_key": {
+          "name": "public_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "private_key": {
+          "name": "private_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_access_token": {
+      "name": "oauth_access_token",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "refresh_id": {
+          "name": "refresh_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oauth_access_token_client_id_idx": {
+          "name": "oauth_access_token_client_id_idx",
+          "columns": [
+            {
+              "expression": "client_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_access_token_session_id_idx": {
+          "name": "oauth_access_token_session_id_idx",
+          "columns": [
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_access_token_user_id_idx": {
+          "name": "oauth_access_token_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_access_token_refresh_id_idx": {
+          "name": "oauth_access_token_refresh_id_idx",
+          "columns": [
+            {
+              "expression": "refresh_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_access_token_client_id_oauth_client_client_id_fk": {
+          "name": "oauth_access_token_client_id_oauth_client_client_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "oauth_client",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "client_id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_access_token_session_id_session_id_fk": {
+          "name": "oauth_access_token_session_id_session_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "session",
+          "columnsFrom": [
+            "session_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "oauth_access_token_user_id_user_id_fk": {
+          "name": "oauth_access_token_user_id_user_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_access_token_refresh_id_oauth_refresh_token_id_fk": {
+          "name": "oauth_access_token_refresh_id_oauth_refresh_token_id_fk",
+          "tableFrom": "oauth_access_token",
+          "tableTo": "oauth_refresh_token",
+          "columnsFrom": [
+            "refresh_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oauth_access_token_token_unique": {
+          "name": "oauth_access_token_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_client": {
+      "name": "oauth_client",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_secret": {
+          "name": "client_secret",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "disabled": {
+          "name": "disabled",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false,
+          "default": false
+        },
+        "skip_consent": {
+          "name": "skip_consent",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "enable_end_session": {
+          "name": "enable_end_session",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subject_type": {
+          "name": "subject_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "uri": {
+          "name": "uri",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "contacts": {
+          "name": "contacts",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tos": {
+          "name": "tos",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "policy": {
+          "name": "policy",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "software_id": {
+          "name": "software_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "software_version": {
+          "name": "software_version",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "software_statement": {
+          "name": "software_statement",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "redirect_uris": {
+          "name": "redirect_uris",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "post_logout_redirect_uris": {
+          "name": "post_logout_redirect_uris",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "token_endpoint_auth_method": {
+          "name": "token_endpoint_auth_method",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "grant_types": {
+          "name": "grant_types",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "response_types": {
+          "name": "response_types",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "public": {
+          "name": "public",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "require_pkce": {
+          "name": "require_pkce",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "oauth_client_user_id_idx": {
+          "name": "oauth_client_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_client_user_id_user_id_fk": {
+          "name": "oauth_client_user_id_user_id_fk",
+          "tableFrom": "oauth_client",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oauth_client_client_id_unique": {
+          "name": "oauth_client_client_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "client_id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_consent": {
+      "name": "oauth_consent",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oauth_consent_client_id_idx": {
+          "name": "oauth_consent_client_id_idx",
+          "columns": [
+            {
+              "expression": "client_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_consent_user_id_idx": {
+          "name": "oauth_consent_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_consent_client_id_oauth_client_client_id_fk": {
+          "name": "oauth_consent_client_id_oauth_client_client_id_fk",
+          "tableFrom": "oauth_consent",
+          "tableTo": "oauth_client",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "client_id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_consent_user_id_user_id_fk": {
+          "name": "oauth_consent_user_id_user_id_fk",
+          "tableFrom": "oauth_consent",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.oauth_refresh_token": {
+      "name": "oauth_refresh_token",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "client_id": {
+          "name": "client_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "session_id": {
+          "name": "session_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "reference_id": {
+          "name": "reference_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "revoked": {
+          "name": "revoked",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "auth_time": {
+          "name": "auth_time",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "scopes": {
+          "name": "scopes",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "oauth_refresh_token_client_id_idx": {
+          "name": "oauth_refresh_token_client_id_idx",
+          "columns": [
+            {
+              "expression": "client_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_refresh_token_session_id_idx": {
+          "name": "oauth_refresh_token_session_id_idx",
+          "columns": [
+            {
+              "expression": "session_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "oauth_refresh_token_user_id_idx": {
+          "name": "oauth_refresh_token_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "oauth_refresh_token_client_id_oauth_client_client_id_fk": {
+          "name": "oauth_refresh_token_client_id_oauth_client_client_id_fk",
+          "tableFrom": "oauth_refresh_token",
+          "tableTo": "oauth_client",
+          "columnsFrom": [
+            "client_id"
+          ],
+          "columnsTo": [
+            "client_id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "oauth_refresh_token_session_id_session_id_fk": {
+          "name": "oauth_refresh_token_session_id_session_id_fk",
+          "tableFrom": "oauth_refresh_token",
+          "tableTo": "session",
+          "columnsFrom": [
+            "session_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "set null",
+          "onUpdate": "no action"
+        },
+        "oauth_refresh_token_user_id_user_id_fk": {
+          "name": "oauth_refresh_token_user_id_user_id_fk",
+          "tableFrom": "oauth_refresh_token",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "oauth_refresh_token_token_unique": {
+          "name": "oauth_refresh_token_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.rate_limit": {
+      "name": "rate_limit",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "key": {
+          "name": "key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "count": {
+          "name": "count",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "last_request": {
+          "name": "last_request",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "rate_limit_key_unique": {
+          "name": "rate_limit_key_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "key"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.session": {
+      "name": "session",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "ip_address": {
+          "name": "ip_address",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_agent": {
+          "name": "user_agent",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {
+        "session_userId_idx": {
+          "name": "session_userId_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "session_user_id_user_id_fk": {
+          "name": "session_user_id_user_id_fk",
+          "tableFrom": "session",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "session_token_unique": {
+          "name": "session_token_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "token"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.user": {
+      "name": "user",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "email_verified": {
+          "name": "email_verified",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "image": {
+          "name": "image",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "is_anonymous": {
+          "name": "is_anonymous",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": false,
+          "default": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "user_email_unique": {
+          "name": "user_email_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "email"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.verification": {
+      "name": "verification",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "identifier": {
+          "name": "identifier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "value": {
+          "name": "value",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "verification_identifier_idx": {
+          "name": "verification_identifier_idx",
+          "columns": [
+            {
+              "expression": "identifier",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_file_assets": {
+      "name": "workspace_file_assets",
+      "schema": "",
+      "columns": {
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "source_object_key": {
+          "name": "source_object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "source_hash": {
+          "name": "source_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "original_name": {
+          "name": "original_name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "mime_type": {
+          "name": "mime_type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "size_bytes": {
+          "name": "size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "preview_object_key": {
+          "name": "preview_object_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "preview_size_bytes": {
+          "name": "preview_size_bytes",
+          "type": "bigint",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "workspace_file_assets_item_id_workspace_items_id_fk": {
+          "name": "workspace_file_assets_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_file_assets",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "workspace_file_assets_source_object_key_unique": {
+          "name": "workspace_file_assets_source_object_key_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "source_object_key"
+          ]
+        },
+        "workspace_file_assets_preview_object_key_unique": {
+          "name": "workspace_file_assets_preview_object_key_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "preview_object_key"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_invites": {
+      "name": "workspace_invites",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'pending'"
+        },
+        "email": {
+          "name": "email",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "token": {
+          "name": "token",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_by_user_id": {
+          "name": "created_by_user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "expires_at": {
+          "name": "expires_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_invites_token_unique": {
+          "name": "workspace_invites_token_unique",
+          "columns": [
+            {
+              "expression": "token",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_pending_link_per_role": {
+          "name": "workspace_invites_pending_link_per_role",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "role",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_invites\".\"type\" = 'link' and \"workspace_invites\".\"status\" = 'pending'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_pending_email_per_workspace": {
+          "name": "workspace_invites_pending_email_per_workspace",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "email",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_invites\".\"type\" = 'email' and \"workspace_invites\".\"status\" = 'pending'",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_workspace_id_idx": {
+          "name": "workspace_invites_workspace_id_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_invites_created_by_user_id_idx": {
+          "name": "workspace_invites_created_by_user_id_idx",
+          "columns": [
+            {
+              "expression": "created_by_user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_invites_workspace_id_workspaces_id_fk": {
+          "name": "workspace_invites_workspace_id_workspaces_id_fk",
+          "tableFrom": "workspace_invites",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_invites_created_by_user_id_user_id_fk": {
+          "name": "workspace_invites_created_by_user_id_user_id_fk",
+          "tableFrom": "workspace_invites",
+          "tableTo": "user",
+          "columnsFrom": [
+            "created_by_user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_invites_role_check": {
+          "name": "workspace_invites_role_check",
+          "value": "\"workspace_invites\".\"role\" in ('owner', 'admin', 'editor', 'viewer')"
+        },
+        "workspace_invites_type_check": {
+          "name": "workspace_invites_type_check",
+          "value": "\"workspace_invites\".\"type\" in ('email', 'link')"
+        },
+        "workspace_invites_status_check": {
+          "name": "workspace_invites_status_check",
+          "value": "\"workspace_invites\".\"status\" in ('pending', 'accepted', 'revoked', 'expired')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_contents": {
+      "name": "workspace_item_contents",
+      "schema": "",
+      "columns": {
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "content": {
+          "name": "content",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "workspace_item_contents_item_id_workspace_items_id_fk": {
+          "name": "workspace_item_contents_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_item_contents",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_extractions": {
+      "name": "workspace_item_extractions",
+      "schema": "",
+      "columns": {
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "status": {
+          "name": "status",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "provider": {
+          "name": "provider",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "provider_mode": {
+          "name": "provider_mode",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "tier": {
+          "name": "tier",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "error_message": {
+          "name": "error_message",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "source_hash": {
+          "name": "source_hash",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_item_extractions_status_idx": {
+          "name": "workspace_item_extractions_status_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "status",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "updated_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_item_extractions_item_fk": {
+          "name": "workspace_item_extractions_item_fk",
+          "tableFrom": "workspace_item_extractions",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "item_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_item_extractions_status_check": {
+          "name": "workspace_item_extractions_status_check",
+          "value": "\"workspace_item_extractions\".\"status\" in ('processing', 'ready', 'failed')"
+        },
+        "workspace_item_extractions_tier_check": {
+          "name": "workspace_item_extractions_tier_check",
+          "value": "\"workspace_item_extractions\".\"tier\" is null or \"workspace_item_extractions\".\"tier\" in ('fast', 'enhanced')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_pages": {
+      "name": "workspace_item_pages",
+      "schema": "",
+      "columns": {
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "page_number": {
+          "name": "page_number",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "markdown": {
+          "name": "markdown",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "markdown_bytes": {
+          "name": "markdown_bytes",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "workspace_item_pages_item_id_workspace_items_id_fk": {
+          "name": "workspace_item_pages_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_item_pages",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "workspace_item_pages_item_id_page_number_pk": {
+          "name": "workspace_item_pages_item_id_page_number_pk",
+          "columns": [
+            "item_id",
+            "page_number"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_item_pages_number_check": {
+          "name": "workspace_item_pages_number_check",
+          "value": "\"workspace_item_pages\".\"page_number\" > 0"
+        },
+        "workspace_item_pages_bytes_check": {
+          "name": "workspace_item_pages_bytes_check",
+          "value": "\"workspace_item_pages\".\"markdown_bytes\" >= 0"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_relations": {
+      "name": "workspace_item_relations",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "from_item_id": {
+          "name": "from_item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "to_item_id": {
+          "name": "to_item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "kind": {
+          "name": "kind",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "note": {
+          "name": "note",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "''"
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_item_relations_unique": {
+          "name": "workspace_item_relations_unique",
+          "columns": [
+            {
+              "expression": "from_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "to_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "kind",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "note",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_item_relations_from_idx": {
+          "name": "workspace_item_relations_from_idx",
+          "columns": [
+            {
+              "expression": "from_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_item_relations_to_idx": {
+          "name": "workspace_item_relations_to_idx",
+          "columns": [
+            {
+              "expression": "to_item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_item_relations_from_fk": {
+          "name": "workspace_item_relations_from_fk",
+          "tableFrom": "workspace_item_relations",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "from_item_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_item_relations_to_fk": {
+          "name": "workspace_item_relations_to_fk",
+          "tableFrom": "workspace_item_relations",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "to_item_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_item_relations_kind_check": {
+          "name": "workspace_item_relations_kind_check",
+          "value": "\"workspace_item_relations\".\"kind\" in ('derived_from', 'references')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_item_user_states": {
+      "name": "workspace_item_user_states",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "item_id": {
+          "name": "item_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "state": {
+          "name": "state",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_item_user_states_item_id_idx": {
+          "name": "workspace_item_user_states_item_id_idx",
+          "columns": [
+            {
+              "expression": "item_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_item_user_states_user_id_user_id_fk": {
+          "name": "workspace_item_user_states_user_id_user_id_fk",
+          "tableFrom": "workspace_item_user_states",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_item_user_states_item_id_workspace_items_id_fk": {
+          "name": "workspace_item_user_states_item_id_workspace_items_id_fk",
+          "tableFrom": "workspace_item_user_states",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "item_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "workspace_item_user_states_user_id_item_id_pk": {
+          "name": "workspace_item_user_states_user_id_item_id_pk",
+          "columns": [
+            "user_id",
+            "item_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.workspace_items": {
+      "name": "workspace_items",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "parent_id": {
+          "name": "parent_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "type": {
+          "name": "type",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "name_key": {
+          "name": "name_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "ref_key": {
+          "name": "ref_key",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "substr(translate(encode(decode(md5(gen_random_uuid()::text), 'hex'), 'base64'), '+/', 'Aa'), 1, 8)"
+        },
+        "color": {
+          "name": "color",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "metadata": {
+          "name": "metadata",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'{}'::jsonb"
+        },
+        "sort_order": {
+          "name": "sort_order",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_items_tree_idx": {
+          "name": "workspace_items_tree_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "sort_order",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_type_idx": {
+          "name": "workspace_items_type_idx",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "type",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_ref_key_unique": {
+          "name": "workspace_items_ref_key_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "ref_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_root_name_unique": {
+          "name": "workspace_items_root_name_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_items\".\"parent_id\" is null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_items_parent_name_unique": {
+          "name": "workspace_items_parent_name_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "parent_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "name_key",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "where": "\"workspace_items\".\"parent_id\" is not null",
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_items_workspace_id_workspaces_id_fk": {
+          "name": "workspace_items_workspace_id_workspaces_id_fk",
+          "tableFrom": "workspace_items",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_items_parent_fk": {
+          "name": "workspace_items_parent_fk",
+          "tableFrom": "workspace_items",
+          "tableTo": "workspace_items",
+          "columnsFrom": [
+            "workspace_id",
+            "parent_id"
+          ],
+          "columnsTo": [
+            "workspace_id",
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {
+        "workspace_items_workspace_id_id_unique": {
+          "name": "workspace_items_workspace_id_id_unique",
+          "nullsNotDistinct": false,
+          "columns": [
+            "workspace_id",
+            "id"
+          ]
+        }
+      },
+      "policies": {},
+      "checkConstraints": {
+        "workspace_items_type_check": {
+          "name": "workspace_items_type_check",
+          "value": "\"workspace_items\".\"type\" in ('folder', 'document', 'flashcard', 'quiz', 'file')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspace_members": {
+      "name": "workspace_members",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "workspace_id": {
+          "name": "workspace_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "role": {
+          "name": "role",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'viewer'"
+        },
+        "last_opened_at": {
+          "name": "last_opened_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "workspace_members_workspace_user_unique": {
+          "name": "workspace_members_workspace_user_unique",
+          "columns": [
+            {
+              "expression": "workspace_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": true,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_members_user_id_idx": {
+          "name": "workspace_members_user_id_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspace_members_user_last_opened_at_idx": {
+          "name": "workspace_members_user_last_opened_at_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "last_opened_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspace_members_workspace_id_workspaces_id_fk": {
+          "name": "workspace_members_workspace_id_workspaces_id_fk",
+          "tableFrom": "workspace_members",
+          "tableTo": "workspaces",
+          "columnsFrom": [
+            "workspace_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        },
+        "workspace_members_user_id_user_id_fk": {
+          "name": "workspace_members_user_id_user_id_fk",
+          "tableFrom": "workspace_members",
+          "tableTo": "user",
+          "columnsFrom": [
+            "user_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {
+        "workspace_members_role_check": {
+          "name": "workspace_members_role_check",
+          "value": "\"workspace_members\".\"role\" in ('owner', 'admin', 'editor', 'viewer')"
+        }
+      },
+      "isRLSEnabled": false
+    },
+    "public.workspaces": {
+      "name": "workspaces",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "icon": {
+          "name": "icon",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "color": {
+          "name": "color",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "theme": {
+          "name": "theme",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "revision": {
+          "name": "revision",
+          "type": "integer",
+          "primaryKey": false,
+          "notNull": true,
+          "default": 0
+        },
+        "owner_id": {
+          "name": "owner_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "updated_at": {
+          "name": "updated_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        },
+        "archived_at": {
+          "name": "archived_at",
+          "type": "timestamp with time zone",
+          "primaryKey": false,
+          "notNull": false
+        }
+      },
+      "indexes": {
+        "workspaces_owner_id_idx": {
+          "name": "workspaces_owner_id_idx",
+          "columns": [
+            {
+              "expression": "owner_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "workspaces_archived_at_idx": {
+          "name": "workspaces_archived_at_idx",
+          "columns": [
+            {
+              "expression": "archived_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {
+        "workspaces_owner_id_user_id_fk": {
+          "name": "workspaces_owner_id_user_id_fk",
+          "tableFrom": "workspaces",
+          "tableTo": "user",
+          "columnsFrom": [
+            "owner_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}
\ No newline at end of file
diff --git a/drizzle-postgres/meta/_journal.json b/drizzle-postgres/meta/_journal.json
index a7d5371d6..64ec43925 100644
--- a/drizzle-postgres/meta/_journal.json
+++ b/drizzle-postgres/meta/_journal.json
@@ -29,6 +29,20 @@
       "when": 1786643511996,
       "tag": "0003_glorious_wolf_cub",
       "breakpoints": true
+    },
+    {
+      "idx": 4,
+      "version": "7",
+      "when": 1786760670175,
+      "tag": "0004_charming_doomsday",
+      "breakpoints": true
+    },
+    {
+      "idx": 5,
+      "version": "7",
+      "when": 1786767401526,
+      "tag": "0005_dashing_masked_marvel",
+      "breakpoints": true
     }
   ]
 }
\ No newline at end of file
diff --git a/eval/datasets/workspace-tools.cases.ts b/eval/datasets/workspace-tools.cases.ts
index 678b84dc6..b09f5e2a5 100644
--- a/eval/datasets/workspace-tools.cases.ts
+++ b/eval/datasets/workspace-tools.cases.ts
@@ -37,6 +37,15 @@ export const workspaceToolCases: WorkspaceToolCase[] = [
 		expectedTools: ["workspace_read_items", "workspace_edit_item"],
 		requiresTargetedEditFromRead: true,
 	},
+	{
+		name: "create a quiz without leaking the answer key into the stems",
+		input: {
+			prompt:
+				"Create a quiz at /Study/Photosynthesis Quiz with 3 multiple-choice questions about photosynthesis basics.",
+		},
+		expectedTools: ["workspace_create_items"],
+		forbiddenTools: ["workspace_delete_items"],
+	},
 	{
 		name: "respects a read-only turn",
 		input: {
diff --git a/eval/support/harness.ts b/eval/support/harness.ts
index 25a08c606..c832baf52 100644
--- a/eval/support/harness.ts
+++ b/eval/support/harness.ts
@@ -26,7 +26,7 @@ import {
 } from "#/features/workspaces/documents/document-ai-html";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
 import type { WorkspaceContentReadResult } from "#/features/workspaces/content/workspace-content-contract";
-import { createWorkspaceReadReferences } from "#/features/workspaces/content/workspace-read-references";
+import { parseWorkspaceAddress } from "#/features/workspaces/locations/workspace-location";
 
 /** A single tool call the model emitted, graded against the real zod schema. */
 export interface WorkspaceAgentToolCall {
@@ -55,11 +55,11 @@ export interface WorkspaceAgentInput {
 }
 
 const STANDUP_PATH = "/Notes/Standup.md";
+const STANDUP_REF_KEY = "standup1";
 
 type EvalStandupFixture = {
 	blocks: Map<string, string>;
 	content: string;
-	references: ReturnType<typeof createWorkspaceReadReferences>;
 };
 
 let evalStandupFixture: Promise<EvalStandupFixture> | undefined;
@@ -86,16 +86,7 @@ async function createEvalStandupFixture(): Promise<EvalStandupFixture> {
 		content.push(await serializeTiptapNodeToAiHtml(node));
 	}
 
-	const result = {
-		content: content.join(""),
-		format: "html" as const,
-		itemId: "standup-document",
-		location: { endBlock: 2, kind: "blocks" as const, startBlock: 1, totalBlocks: 2 },
-		path: STANDUP_PATH,
-		status: "ready" as const,
-		type: "document" as const,
-	};
-	return { blocks, content: result.content, references: createWorkspaceReadReferences([result]) };
+	return { blocks, content: content.join("") };
 }
 
 // Per-tool stubbed outputs. Reads return the realistic item for the requested
@@ -107,18 +98,15 @@ async function evalToolFixture(toolName: string, input: unknown): Promise<unknow
 		const requests = (input as { requests?: Array<{ ref?: string; mode?: string; path?: string }> })
 			?.requests;
 		const results: WorkspaceContentReadResult[] = (requests ?? []).map((request) => {
-			if (request.path !== STANDUP_PATH) {
-				return { code: "path_not_found", path: request.path ?? "", status: "failed" };
-			}
 			if (request.mode === "ref") {
-				const record = fixture.references.find(({ ref }) => ref === request.ref);
+				const address = request.ref ? parseWorkspaceAddress(request.ref) : undefined;
 				const contentRef =
-					record?.location.kind === "document-block" && record.revision
-						? `${record.location.blockId}.r_${record.revision}`
-						: "";
-				const content = fixture.blocks.get(contentRef);
-				if (!content) {
-					return { code: "ref_not_found", path: STANDUP_PATH, status: "failed" };
+					address?.refKey === STANDUP_REF_KEY && address.unit
+						? [...fixture.blocks.keys()].find((key) => key.startsWith(`${address.unit}.`))
+						: undefined;
+				const content = contentRef ? fixture.blocks.get(contentRef) : undefined;
+				if (!contentRef || !content) {
+					return { code: "ref_not_found", ref: request.ref ?? "", status: "failed" };
 				}
 
 				return {
@@ -127,10 +115,14 @@ async function evalToolFixture(toolName: string, input: unknown): Promise<unknow
 					format: "html",
 					itemId: "standup-document",
 					path: STANDUP_PATH,
+					ref: STANDUP_REF_KEY,
 					status: "ready",
 					type: "block",
 				};
 			}
+			if (request.path !== STANDUP_PATH) {
+				return { code: "path_not_found", path: request.path ?? "", status: "failed" };
+			}
 			if (request.mode !== "start") {
 				return { code: "invalid_selection", path: STANDUP_PATH, status: "failed" };
 			}
@@ -141,12 +133,13 @@ async function evalToolFixture(toolName: string, input: unknown): Promise<unknow
 				itemId: "standup-document",
 				location: { endBlock: 2, kind: "blocks", startBlock: 1, totalBlocks: 2 },
 				path: STANDUP_PATH,
+				ref: STANDUP_REF_KEY,
 				status: "ready",
 				type: "document",
 			};
 		});
 
-		return { references: fixture.references, results };
+		return { results };
 	}
 	return { ok: true, note: "eval stub — no real mutation" };
 }
diff --git a/eval/workspace-tools.eval.ts b/eval/workspace-tools.eval.ts
index be147293d..b2e44d47d 100644
--- a/eval/workspace-tools.eval.ts
+++ b/eval/workspace-tools.eval.ts
@@ -10,7 +10,7 @@ import {
 	scoreToolInputsValid,
 } from "./support/scorers";
 
-const STANDUP_LIST_REF = "wr_AAAAAAAA";
+const STANDUP_LIST_REF = "b_standupList1.r_4f2a1b";
 const STANDUP_PATH = "/Notes/Standup.md";
 
 describe("workspace eval scorers", () => {
diff --git a/src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx b/src/components/code-block/mermaid-diagram.tsx
similarity index 80%
rename from src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx
rename to src/components/code-block/mermaid-diagram.tsx
index 9519beb48..21a9723ac 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMermaidDiagram.tsx
+++ b/src/components/code-block/mermaid-diagram.tsx
@@ -1,6 +1,5 @@
 import { Check, Copy, GitBranch, Maximize2, Minimize2, Minus, Plus } from "lucide-react";
 import { useEffect, useId, useRef, useState } from "react";
-import { useIsCodeFenceIncomplete } from "streamdown";
 
 import { useTheme } from "#/components/theme-provider";
 import {
@@ -28,6 +27,24 @@ type MermaidRenderResult =
 
 let mermaidRenderQueue = Promise.resolve();
 
+/**
+ * Rendered SVGs keyed by theme and source. Study surfaces mount the same
+ * diagram over and over — flipping a card back and forth, stepping through
+ * questions, or any edit that rebuilds the editor — and re-running mermaid
+ * each time would flash a placeholder over artwork the reader just saw.
+ * Cleared wholesale past a generous ceiling: an eviction policy would cost
+ * more than the few kilobytes it saves.
+ */
+const mermaidImageCache = new Map<string, MermaidImage>();
+const MAX_CACHED_DIAGRAMS = 64;
+
+function cacheMermaidImage(requestKey: string, image: MermaidImage) {
+	if (mermaidImageCache.size >= MAX_CACHED_DIAGRAMS) {
+		mermaidImageCache.clear();
+	}
+	mermaidImageCache.set(requestKey, image);
+}
+
 function enqueueMermaidRender(input: { darkMode: boolean; id: string; source: string }) {
 	const render = mermaidRenderQueue.then(async () => {
 		const { default: mermaid } = await import("mermaid");
@@ -146,17 +163,30 @@ function useNearViewport() {
 	return { containerRef, isNearViewport };
 }
 
-export function AiChatMermaidDiagram({ source }: { source: string }) {
-	const isIncomplete = useIsCodeFenceIncomplete();
+/**
+ * Renders one mermaid source block as a diagram. Shared by chat, where the
+ * source streams in, and by document code blocks, where it arrives whole —
+ * hence `isIncomplete` as a prop rather than a hook: only chat can observe a
+ * half-written fence, and a document must not wait for a stream that has
+ * already ended.
+ */
+export function MermaidDiagram({
+	isIncomplete = false,
+	source,
+}: {
+	isIncomplete?: boolean;
+	source: string;
+}) {
 	const { resolvedTheme } = useTheme();
 	const reactId = useId();
 	const { containerRef, isNearViewport } = useNearViewport();
 	const requestKey = `${resolvedTheme}:${source}`;
 	const sourceIsTooLarge = source.length > MAX_MERMAID_SOURCE_LENGTH;
+	const cachedImage = mermaidImageCache.get(requestKey);
 	const [result, setResult] = useState<MermaidRenderResult | null>(null);
 
 	useEffect(() => {
-		if (!isNearViewport || isIncomplete || sourceIsTooLarge) {
+		if (!isNearViewport || isIncomplete || sourceIsTooLarge || cachedImage) {
 			return;
 		}
 
@@ -174,13 +204,15 @@ export function AiChatMermaidDiagram({ source }: { source: string }) {
 					return;
 				}
 
-				setResult({ image: prepareMermaidImage(svg), requestKey, status: "ready" });
+				const image = prepareMermaidImage(svg);
+				cacheMermaidImage(requestKey, image);
+				setResult({ image, requestKey, status: "ready" });
 			} catch (error: unknown) {
 				if (cancelled) {
 					return;
 				}
 
-				console.warn("[AiChatMermaidDiagram] Failed to render diagram", error);
+				console.warn("[MermaidDiagram] Failed to render diagram", error);
 				setResult({ requestKey, status: "error" });
 			}
 		})();
@@ -188,16 +220,39 @@ export function AiChatMermaidDiagram({ source }: { source: string }) {
 		return () => {
 			cancelled = true;
 		};
-	}, [isIncomplete, isNearViewport, reactId, requestKey, resolvedTheme, source, sourceIsTooLarge]);
-
-	const state: MermaidRenderResult | { status: "loading" } = sourceIsTooLarge
-		? { requestKey, status: "error" }
-		: isIncomplete || result?.requestKey !== requestKey
-			? { status: "loading" }
-			: result;
+	}, [
+		cachedImage,
+		isIncomplete,
+		isNearViewport,
+		reactId,
+		requestKey,
+		resolvedTheme,
+		source,
+		sourceIsTooLarge,
+	]);
+
+	// A cache hit is read straight through to the render rather than copied
+	// into state, so a remount paints finished artwork on the first frame.
+	// This render's own result still outranks it: an <img> that failed to
+	// decode must not be answered with the cached image that just failed.
+	const state = ((): MermaidRenderResult | { status: "loading" } => {
+		if (sourceIsTooLarge) {
+			return { requestKey, status: "error" };
+		}
+		if (isIncomplete) {
+			return { status: "loading" };
+		}
+		if (result?.requestKey === requestKey) {
+			return result;
+		}
+		if (cachedImage) {
+			return { image: cachedImage, requestKey, status: "ready" };
+		}
+		return { status: "loading" };
+	})();
 
 	return (
-		<div className="my-4" data-ai-chat-mermaid={state.status} ref={containerRef}>
+		<div className="my-4" data-mermaid={state.status} ref={containerRef}>
 			{state.status === "loading" ? <MermaidLoading /> : null}
 			{state.status === "error" ? <MermaidError source={source} /> : null}
 			{state.status === "ready" ? (
@@ -233,7 +288,7 @@ function MermaidError({ source }: { source: string }) {
 				<span className="font-medium">Diagram unavailable</span>
 			</div>
 			<div className="px-3 py-3 text-muted-foreground text-sm">
-				<p>This diagram couldn’t be displayed, but the rest of the response is unaffected.</p>
+				<p>This diagram couldn’t be displayed. Its source is unchanged.</p>
 				<details className="mt-2">
 					<summary className="w-fit cursor-pointer text-xs underline-offset-4 hover:underline">
 						View diagram source
@@ -260,7 +315,7 @@ function MermaidDiagramCard({
 	const [zoom, setZoom] = useState(1);
 	const { copied, copy } = useCopyToClipboard({
 		onError: (error) => {
-			console.warn("[AiChatMermaidDiagram] Failed to copy source", error);
+			console.warn("[MermaidDiagram] Failed to copy source", error);
 		},
 	});
 
diff --git a/src/db/schema.ts b/src/db/schema.ts
index ffc550e61..c84a5db63 100644
--- a/src/db/schema.ts
+++ b/src/db/schema.ts
@@ -262,6 +262,16 @@ export const workspaceItems = pgTable(
 		type: text("type", { enum: WORKSPACE_ITEM_TYPES }).notNull(),
 		name: text("name").notNull(),
 		nameKey: text("name_key").notNull(),
+		// Short, stable, model-facing handle. The volatile default backfills
+		// existing rows from a ~47-bit alphanumeric space (base64 of random
+		// bytes, +/ mapped to letters) so the unique index cannot trip over
+		// hex-only birthday collisions; application code supplies 62^8 nanoid
+		// values on insert.
+		refKey: text("ref_key")
+			.notNull()
+			.default(
+				sql`substr(translate(encode(decode(md5(gen_random_uuid()::text), 'hex'), 'base64'), '+/', 'Aa'), 1, 8)`,
+			),
 		color: text("color"),
 		metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}).notNull(),
 		sortOrder: integer("sort_order").notNull(),
@@ -281,6 +291,7 @@ export const workspaceItems = pgTable(
 		unique("workspace_items_workspace_id_id_unique").on(table.workspaceId, table.id),
 		index("workspace_items_tree_idx").on(table.workspaceId, table.parentId, table.sortOrder),
 		index("workspace_items_type_idx").on(table.workspaceId, table.type),
+		uniqueIndex("workspace_items_ref_key_unique").on(table.workspaceId, table.refKey),
 		uniqueIndex("workspace_items_root_name_unique")
 			.on(table.workspaceId, table.nameKey)
 			.where(sql`${table.parentId} is null`),
diff --git a/src/features/workspaces/ai/ai-thread-runtime.ts b/src/features/workspaces/ai/ai-thread-runtime.ts
index 21e2fdc38..aaf2dff61 100644
--- a/src/features/workspaces/ai/ai-thread-runtime.ts
+++ b/src/features/workspaces/ai/ai-thread-runtime.ts
@@ -15,7 +15,6 @@ import type {
 	AIThreadContext,
 	AIThreadPromptScope,
 } from "#/features/workspaces/ai/ai-thread-metadata";
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
 import {
 	requireAiToolDefinition,
 	type AiToolModelPolicy,
@@ -52,11 +51,11 @@ const AI_THREAD_VIEW_ONLY_WORKSPACE_LINE =
 	"- Workspace access: view-only. Do not create, rename, edit, move, or delete workspace items.";
 const AI_THREAD_WORKSPACE_CITATION_PROMPT = [
 	"# Workspace Citations",
-	"- Workspace reads may include short refs such as `wr_7Kp2Qa9x`.",
-	'- After a quote or important claim supported by a ref, place an empty `<citation ref="wr_7Kp2Qa9x"></citation>` immediately after that text.',
-	"- Copy refs exactly. Never invent, alter, reuse a ref for different material, or cite web/unsupported claims with workspace tags. Omit the tag when no ref was provided.",
+	"- Every workspace read returns the item's durable ref (like `Xk7p2Qa9`), and units inside it — pages, blocks, cards, questions — have unit refs.",
+	'- After a quote or important claim supported by workspace content, place an empty citation immediately after that text: `<citation ref="Xk7p2Qa9"></citation>` for the item, or `<citation ref="Xk7p2Qa9/p5"></citation>` for a unit (join the item ref and the unit with a slash, dropping any `.r_` suffix).',
+	"- Copy refs exactly. Never invent or alter one, and never cite web/unsupported claims with workspace tags. Omit the tag when you did not read the content.",
 	"- Cite selectively: important claims, conclusions, summaries, and direct quotes, not every sentence or common knowledge.",
-	"- When you mention a newly created workspace item and creation returned a ref, cite the item name with that ref.",
+	"- When you mention a newly created workspace item, cite its name with the ref creation returned.",
 	"- Workspace names and paths are not URLs. Never build Markdown links to workspace items from a name, path, or app origin.",
 ].join("\n");
 const WORKSPACE_FS_METHOD_NAMES = [
@@ -83,8 +82,6 @@ export function createAIThreadTools(input: {
 	threadId: string;
 	workspace: WorkspaceLike;
 	getThreadContext: () => Promise<AIThreadContext | null>;
-	onWorkspaceReferences?: (records: readonly WorkspaceReferenceRecord[]) => void;
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 	timeZone?: string;
 }): ToolSet {
 	return createAIThreadToolCatalog(input).tools;
@@ -98,8 +95,6 @@ export function createAIThreadTurnToolConfig(input: {
 	getThreadContext: () => Promise<AIThreadContext | null>;
 	canMutate: boolean;
 	onOrchestrationRuntime?: Parameters<typeof createAIThreadOrchestrationTool>[0]["onRuntime"];
-	onWorkspaceReferences?: (records: readonly WorkspaceReferenceRecord[]) => void;
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 	timeZone?: string;
 }) {
 	const toolCatalog = createAIThreadToolCatalog(input);
@@ -135,8 +130,6 @@ function createAIThreadToolCatalog(input: {
 	threadId: string;
 	workspace: WorkspaceLike;
 	getThreadContext: () => Promise<AIThreadContext | null>;
-	onWorkspaceReferences?: (records: readonly WorkspaceReferenceRecord[]) => void;
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 	timeZone?: string;
 }) {
 	const sandboxTools = createSandboxTools(input.workspace);
@@ -152,8 +145,6 @@ function createAIThreadToolCatalog(input: {
 	const workspaceTools = createAIThreadWorkspaceTools({
 		env: input.env,
 		getThreadContext: input.getThreadContext,
-		onWorkspaceReferences: input.onWorkspaceReferences,
-		resolveWorkspaceReferences: input.resolveWorkspaceReferences,
 	});
 	const entries: AIThreadToolEntry[] = [];
 
diff --git a/src/features/workspaces/ai/ai-thread.ts b/src/features/workspaces/ai/ai-thread.ts
index 1cc070ed5..41b66c231 100644
--- a/src/features/workspaces/ai/ai-thread.ts
+++ b/src/features/workspaces/ai/ai-thread.ts
@@ -24,10 +24,6 @@ import {
 	AI_THREAD_COMPACTION_TOKEN_THRESHOLD,
 	createAIThreadCompactFunction,
 } from "#/features/workspaces/ai/ai-compaction";
-import {
-	collectWorkspaceReferenceRecords,
-	reconcileWorkspaceMessageReferences,
-} from "#/features/workspaces/ai/workspace-references";
 import { resolveChatAttachmentModelMessages } from "#/features/workspaces/ai/chat-attachment-model";
 import { classifyAIThreadChatError } from "#/features/workspaces/ai/chat-error-classification";
 import type { AIThreadContext } from "#/features/workspaces/ai/ai-thread-metadata";
@@ -48,7 +44,6 @@ import {
 	type WorkspaceAiChatModelId,
 } from "#/features/workspaces/ai/models";
 import type { UserAIStore } from "#/features/workspaces/ai/user-ai-agents";
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
 import {
 	checkWorkspaceAiMessageAccess,
 	trackWorkspaceAiMessageUsage,
@@ -103,7 +98,6 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 		private shouldRefreshSessionPrompt = false;
 		private activeRunStartedAt: number | undefined;
 		private activeUsageContext: AIThreadUsageContext | undefined;
-		private activeWorkspaceReferences: WorkspaceReferenceRecord[] = [];
 		private readonly telemetry = new AIThreadTelemetryRecorder({
 			env: this.env,
 			schedule: (task) => {
@@ -164,10 +158,6 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 				threadId: this.name,
 				workspace: this.workspace,
 				getThreadContext: () => this._getThreadContext(),
-				onWorkspaceReferences: (records) => {
-					this._recordWorkspaceReferences(records);
-				},
-				resolveWorkspaceReferences: (refs) => this._resolveWorkspaceReferences(refs),
 			});
 		}
 
@@ -186,7 +176,6 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 			}
 
 			if (!ctx.continuation) {
-				this.activeWorkspaceReferences = [];
 				this.activeRunStartedAt = await directory.recordThreadRunStarted(this.name, {
 					isUserMessage: true,
 				});
@@ -295,9 +284,6 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 		override async onChatResponse(result: ChatResponseResult) {
 			this.telemetry.recordTurnFinished(result);
 			this._trackCompletedMessageUsage(result);
-			if (result.status === "completed") {
-				await this._reconcileWorkspaceReferences(result.message);
-			}
 			if (!this._shouldSettleRunAfterResponse(result)) {
 				await this._refreshSessionPromptIfNeeded();
 				return;
@@ -352,10 +338,6 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 				onOrchestrationRuntime: (runtime) => {
 					this.codemode = runtime;
 				},
-				onWorkspaceReferences: (records) => {
-					this._recordWorkspaceReferences(records);
-				},
-				resolveWorkspaceReferences: (refs) => this._resolveWorkspaceReferences(refs),
 				timeZone,
 			});
 		}
@@ -420,57 +402,10 @@ export function createAIThreadClass(getUserAIStore: () => typeof UserAIStore) {
 			} finally {
 				this.activeRunStartedAt = undefined;
 				this.activeUsageContext = undefined;
-				this.activeWorkspaceReferences = [];
 				await this._refreshSessionPromptIfNeeded();
 			}
 		}
 
-		private _recordWorkspaceReferences(records: readonly WorkspaceReferenceRecord[]) {
-			this.activeWorkspaceReferences.push(...records);
-		}
-
-		/**
-		 * Looks up the refs a read handed the assistant, so a tool can turn one
-		 * into the location it stands for. Reads from this turn are not in the
-		 * transcript yet, which is exactly when a document usually cites them.
-		 */
-		private async _resolveWorkspaceReferences(refs: readonly string[]) {
-			const wanted = new Set(refs);
-			const records = [
-				...collectWorkspaceReferenceRecords(await this.getMessages()),
-				...this.activeWorkspaceReferences,
-			];
-
-			return records.filter((record) => wanted.has(record.ref));
-		}
-
-		private async _reconcileWorkspaceReferences(message: ChatResponseResult["message"]) {
-			try {
-				const transcriptReferences = collectWorkspaceReferenceRecords(await this.getMessages());
-				const reconciled = reconcileWorkspaceMessageReferences(
-					message,
-					[...transcriptReferences, ...this.activeWorkspaceReferences],
-					this.activeWorkspaceReferences,
-				);
-
-				if (reconciled !== message) {
-					await this.addMessages([reconciled], { mode: "upsert" });
-				}
-			} catch (error) {
-				const thread = this.activeUsageContext?.thread;
-				recordOperationalFailure({
-					distinctId: thread?.userId,
-					error,
-					event: "ai_citation_finalization",
-					fields: {
-						thread_id: this.name,
-						user_id: thread?.userId,
-						workspace_id: thread?.workspaceId,
-					},
-				});
-			}
-		}
-
 		private _trackCompletedMessageUsage(result: ChatResponseResult) {
 			if (result.continuation || result.status !== "completed") {
 				return;
diff --git a/src/features/workspaces/ai/workspace-read-file-fallback.ts b/src/features/workspaces/ai/workspace-read-file-fallback.ts
index 01d974584..e1ed20586 100644
--- a/src/features/workspaces/ai/workspace-read-file-fallback.ts
+++ b/src/features/workspaces/ai/workspace-read-file-fallback.ts
@@ -4,7 +4,7 @@ import {
 	workspaceReadItemsInputSchema,
 	workspaceReadItemsOutputSchema,
 } from "#/features/workspaces/content/workspace-content-contract";
-import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-references";
+import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
 import { getWorkspaceFileSourceObject } from "#/features/workspaces/extraction/workspace-file-source";
 
 const maxPendingPdfBytes = 3.5 * 1024 * 1024;
diff --git a/src/features/workspaces/ai/workspace-references.test.ts b/src/features/workspaces/ai/workspace-references.test.ts
deleted file mode 100644
index a834bc936..000000000
--- a/src/features/workspaces/ai/workspace-references.test.ts
+++ /dev/null
@@ -1,199 +0,0 @@
-import type { UIMessage } from "ai";
-import { describe, expect, it } from "vitest";
-
-import {
-	collectWorkspaceReferenceRecords,
-	reconcileWorkspaceMessageReferences,
-	stripWorkspaceCitationTags,
-} from "#/features/workspaces/ai/workspace-references";
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
-
-const first = reference("wr_AAAAAAAA", "item-1");
-const second = reference("wr_BBBBBBBB", "item-2");
-
-describe("workspace references", () => {
-	it("persists only known refs used by assistant text in first-use order", () => {
-		const message = assistantMessage(
-			`Alpha <citation ref="wr_BBBBBBBB"></citation> beta ` +
-				`<citation ref="wr_UNKNOWN0"></citation> gamma ` +
-				`<citation ref="wr_AAAAAAAA"/> again <citation ref="wr_BBBBBBBB"></citation>`,
-		);
-		const reconciled = reconcileWorkspaceMessageReferences(message, [first, second]);
-
-		expect(collectWorkspaceReferenceRecords([reconciled])).toEqual([second, first]);
-	});
-
-	it("rejects a ref that maps to different durable locations", () => {
-		const collision = reference("wr_AAAAAAAA", "item-2");
-		const message = assistantMessage(`Alpha <citation ref="wr_AAAAAAAA"></citation>`);
-
-		expect(
-			collectWorkspaceReferenceRecords([
-				reconcileWorkspaceMessageReferences(message, [first, collision]),
-			]),
-		).toEqual([]);
-	});
-
-	it("is idempotent and removes stale normalized records", () => {
-		const message = assistantMessage(`Alpha <citation ref="wr_AAAAAAAA"></citation>`);
-		const reconciled = reconcileWorkspaceMessageReferences(message, [first]);
-
-		expect(reconcileWorkspaceMessageReferences(reconciled, [first])).toBe(reconciled);
-		expect(
-			collectWorkspaceReferenceRecords([
-				reconcileWorkspaceMessageReferences(
-					{ ...reconciled, parts: [{ type: "text", text: "No citation" }, reconciled.parts[1]] },
-					[first],
-				),
-			]),
-		).toEqual([]);
-	});
-
-	it("collapses duplicate citation data parts to one canonical part", () => {
-		const message = assistantMessage(`Alpha <citation ref="wr_AAAAAAAA"></citation>`);
-		const reconciled = reconcileWorkspaceMessageReferences(message, [first]);
-		const duplicated = {
-			...reconciled,
-			parts: [...reconciled.parts, reconciled.parts[1]],
-		};
-		const repaired = reconcileWorkspaceMessageReferences(duplicated, [first]);
-
-		expect(repaired.parts.filter((part) => part.type === "data-workspace-references")).toHaveLength(
-			1,
-		);
-	});
-
-	it("retains Code Mode refs that are not present in a direct tool result", () => {
-		const reconciled = reconcileWorkspaceMessageReferences(assistantMessage("Done"), [], [first]);
-
-		expect(collectWorkspaceReferenceRecords([reconciled])).toEqual([first]);
-	});
-
-	it("does not duplicate refs already persisted by a direct tool result", () => {
-		const readOutput = { references: [first], results: [] };
-		const message: UIMessage = {
-			id: "assistant-1",
-			role: "assistant",
-			parts: [
-				{
-					type: "tool-workspace_read_items",
-					toolCallId: "call-1",
-					state: "output-available",
-					input: { requests: [] },
-					output: readOutput,
-				},
-			],
-		};
-		const reconciled = reconcileWorkspaceMessageReferences(message, [first], [first]);
-
-		expect(reconciled.parts).toHaveLength(1);
-		expect(collectWorkspaceReferenceRecords([reconciled])).toEqual([first]);
-	});
-
-	it("collects references from direct workspace reads", () => {
-		const readOutput = {
-			references: [first],
-			results: [
-				{
-					content: '<h1 data-ref="b_abcdefghijkl.r_0123456789">Notes</h1>',
-					format: "html",
-					itemId: "item-1",
-					location: {
-						endBlock: 1,
-						kind: "blocks",
-						startBlock: 1,
-						totalBlocks: 1,
-					},
-					path: "/Notes",
-					status: "ready",
-					type: "document",
-				},
-			],
-		};
-		const messages: UIMessage[] = [
-			{
-				id: "assistant-1",
-				role: "assistant",
-				parts: [
-					{
-						type: "tool-workspace_read_items",
-						toolCallId: "call-1",
-						state: "output-available",
-						input: { requests: [] },
-						output: readOutput,
-					},
-				],
-			},
-		];
-
-		expect(collectWorkspaceReferenceRecords(messages)).toEqual([first]);
-	});
-
-	it("does not trust references inside model-authored Code Mode results", () => {
-		const messages: UIMessage[] = [
-			{
-				id: "assistant-1",
-				role: "assistant",
-				parts: [
-					{
-						type: "dynamic-tool",
-						toolName: "orchestrate",
-						toolCallId: "call-1",
-						state: "output-available",
-						input: {},
-						output: {
-							status: "completed",
-							result: {
-								references: [first],
-								results: [],
-							},
-						},
-					},
-				],
-			},
-		];
-
-		expect(collectWorkspaceReferenceRecords(messages)).toEqual([]);
-	});
-
-	it("ignores citation records supplied by a user message", () => {
-		const messages: UIMessage[] = [
-			{
-				id: "user-1",
-				role: "user",
-				parts: [
-					{
-						type: "data-workspace-references",
-						id: "workspace-references",
-						data: { references: [first], version: 1 },
-					},
-				],
-			},
-		];
-
-		expect(collectWorkspaceReferenceRecords(messages)).toEqual([]);
-	});
-
-	it("strips valid citation protocol tags from copied Markdown", () => {
-		expect(
-			stripWorkspaceCitationTags(
-				`Alpha <citation ref="wr_AAAAAAAA"></citation> beta <citation bad="value">label</citation>`,
-			),
-		).toBe("Alpha  beta label");
-	});
-});
-
-function assistantMessage(text: string): UIMessage {
-	return {
-		id: "assistant-1",
-		role: "assistant",
-		parts: [{ type: "text", text }],
-	};
-}
-
-function reference(ref: string, itemId: string): WorkspaceReferenceRecord {
-	return {
-		location: { itemId, kind: "item", version: 1 },
-		ref: ref as WorkspaceReferenceRecord["ref"],
-	};
-}
diff --git a/src/features/workspaces/ai/workspace-references.ts b/src/features/workspaces/ai/workspace-references.ts
index 7981016cb..db1ce82c3 100644
--- a/src/features/workspaces/ai/workspace-references.ts
+++ b/src/features/workspaces/ai/workspace-references.ts
@@ -1,140 +1,14 @@
-import { isToolUIPart, type UIMessage } from "ai";
-import { z } from "zod";
-
-import { getWorkspaceToolResultAdapter } from "#/features/workspaces/ai/workspace-tool-result-adapters";
-import {
-	getWorkspaceLocationKey,
-	indexWorkspaceReferenceRecords,
-	parseWorkspaceReference,
-	type WorkspaceReference,
-	type WorkspaceReferenceRecord,
-	type WorkspaceLocation,
-	workspaceReferenceRecordSchema,
-} from "#/features/workspaces/locations/workspace-location";
-
-export const WORKSPACE_REFERENCES_DATA_PART_TYPE = "data-workspace-references";
-const MAX_WORKSPACE_CITATIONS_PER_MESSAGE = 50;
-const workspaceCitationTagPattern =
-	/<citation\s+ref=(["'])([^"']+)\1\s*(?:\/>|>\s*<\/citation\s*>)/g;
-const anyCompleteWorkspaceCitationTagPattern = /<\/?citation\b[^>]*>/gi;
-
-const workspaceReferencesDataSchema = z.strictObject({
-	references: z.array(workspaceReferenceRecordSchema),
-	version: z.literal(1),
-});
-
 /**
- * Reconciles one hidden reference data part onto an assistant message.
- *
- * It retains valid cited refs plus refs produced inside Code Mode that do not
- * already live in a direct tool result. Unknown or colliding citations stay inert.
- *
- * @param message - Finalized assistant message.
- * @param candidates - App-issued refs available to this response.
- * @returns The original message when already normalized, otherwise an updated copy.
+ * Chat citations are self-describing workspace addresses: the assistant copies
+ * `refKey` or `refKey/unit` from a read into `<citation ref="…">`, and the
+ * client resolves them against the live workspace when a message is drawn.
+ * Nothing is minted or persisted per turn.
  */
-export function reconcileWorkspaceMessageReferences(
-	message: UIMessage,
-	candidates: readonly WorkspaceReferenceRecord[],
-	retain: readonly WorkspaceReferenceRecord[] = [],
-): UIMessage {
-	const directRecords = collectWorkspaceToolReferenceRecords(message);
-	const directKeys = new Set(directRecords.map(getWorkspaceReferenceRecordKey));
-	const references = dedupeWorkspaceReferenceRecords([
-		...resolveUsedWorkspaceCitations(message, candidates),
-		...retain.filter((record) => !directKeys.has(getWorkspaceReferenceRecordKey(record))),
-	]);
 
-	if (hasCanonicalWorkspaceReferencePart(message, references)) {
-		return message;
-	}
-
-	const parts = message.parts.filter((part) => part.type !== WORKSPACE_REFERENCES_DATA_PART_TYPE);
-	if (references.length > 0) {
-		parts.push({
-			type: WORKSPACE_REFERENCES_DATA_PART_TYPE,
-			data: {
-				references,
-				version: 1,
-			},
-		});
-	}
-
-	return { ...message, parts };
-}
-
-/**
- * Returns validated durable reference records persisted on a UI message.
- *
- * @param message - Any persisted or streaming UI message.
- * @returns The first valid normalized reference list, or an empty list.
- */
-function getWorkspaceMessageReferenceRecords(
-	message: UIMessage,
-): readonly WorkspaceReferenceRecord[] {
-	for (const part of message.parts) {
-		if (part.type !== WORKSPACE_REFERENCES_DATA_PART_TYPE || !("data" in part)) {
-			continue;
-		}
-
-		const parsed = workspaceReferencesDataSchema.safeParse(part.data);
-		if (parsed.success) {
-			return parsed.data.references;
-		}
-	}
-
-	return [];
-}
-
-/**
- * Collects app-issued reference records from direct workspace tools and
- * normalized hidden reference data in a persisted transcript.
- *
- * Code Mode's final result is model-authored, so genuine nested reads are
- * captured during execution instead of trusted from the orchestration output.
- *
- * @param messages - UI messages on the active thread path.
- * @returns Candidate records in transcript order.
- */
-export function collectWorkspaceReferenceRecords(
-	messages: readonly UIMessage[],
-): WorkspaceReferenceRecord[] {
-	const records: WorkspaceReferenceRecord[] = [];
-
-	for (const message of messages) {
-		if (message.role !== "assistant") {
-			continue;
-		}
-
-		records.push(...getWorkspaceMessageReferenceRecords(message));
-		records.push(...collectWorkspaceToolReferenceRecords(message));
-	}
-
-	return records;
-}
-
-/**
- * Builds the unambiguous ref-to-location map available while rendering a message.
- *
- * Persisted references and completed direct workspace-tool outputs both
- * contribute, so direct tool citations can appear before post-response
- * reconciliation arrives.
- *
- * @param message - Streaming or persisted UI message.
- * @returns Unambiguous locations keyed by their exact model-facing refs.
- */
-export function getWorkspaceCitationLocations(
-	message: UIMessage,
-): ReadonlyMap<WorkspaceReference, WorkspaceLocation> {
-	const index = indexWorkspaceReferenceRecords(collectWorkspaceReferenceRecords([message]));
-	const locations = new Map<WorkspaceReference, WorkspaceLocation>();
-
-	for (const [ref, record] of index) {
-		if (record) locations.set(ref, record.location);
-	}
+/** Hidden data part written by earlier versions; recognized only to keep it hidden. */
+export const WORKSPACE_REFERENCES_DATA_PART_TYPE = "data-workspace-references";
 
-	return locations;
-}
+const anyCompleteWorkspaceCitationTagPattern = /<\/?citation\b[^>]*>/gi;
 
 /**
  * Removes model-only citation markers from text copied to the clipboard.
@@ -145,106 +19,3 @@ export function getWorkspaceCitationLocations(
 export function stripWorkspaceCitationTags(text: string) {
 	return text.replace(anyCompleteWorkspaceCitationTagPattern, "");
 }
-
-function resolveUsedWorkspaceCitations(
-	message: UIMessage,
-	candidates: readonly WorkspaceReferenceRecord[],
-) {
-	const candidateIndex = indexWorkspaceReferenceRecords(candidates);
-	const citations: WorkspaceReferenceRecord[] = [];
-	const usedRefs = new Set<WorkspaceReference>();
-
-	for (const part of message.parts) {
-		if (part.type !== "text") {
-			continue;
-		}
-
-		for (const match of part.text.matchAll(workspaceCitationTagPattern)) {
-			const ref = parseWorkspaceReference(match[2]);
-			if (!ref || usedRefs.has(ref)) {
-				continue;
-			}
-
-			const candidate = candidateIndex.get(ref);
-			if (!candidate) {
-				continue;
-			}
-
-			usedRefs.add(ref);
-			citations.push(candidate);
-			if (citations.length === MAX_WORKSPACE_CITATIONS_PER_MESSAGE) {
-				return citations;
-			}
-		}
-	}
-
-	return citations;
-}
-
-function haveSameWorkspaceReferences(
-	left: readonly WorkspaceReferenceRecord[],
-	right: readonly WorkspaceReferenceRecord[],
-) {
-	return (
-		left.length === right.length &&
-		left.every(
-			(record, index) =>
-				record.ref === right[index]?.ref &&
-				getWorkspaceLocationKey(record.location) ===
-					getWorkspaceLocationKey(right[index].location) &&
-				record.revision === right[index].revision,
-		)
-	);
-}
-
-function hasCanonicalWorkspaceReferencePart(
-	message: UIMessage,
-	references: readonly WorkspaceReferenceRecord[],
-) {
-	const referenceParts = message.parts.filter(
-		(part) => part.type === WORKSPACE_REFERENCES_DATA_PART_TYPE,
-	);
-
-	if (references.length === 0) {
-		return referenceParts.length === 0;
-	}
-
-	if (referenceParts.length !== 1) {
-		return false;
-	}
-
-	const [part] = referenceParts;
-	if (!part || !("data" in part)) {
-		return false;
-	}
-
-	const parsed = workspaceReferencesDataSchema.safeParse(part.data);
-	return parsed.success && haveSameWorkspaceReferences(parsed.data.references, references);
-}
-
-function collectWorkspaceToolReferenceRecords(message: UIMessage) {
-	const records: WorkspaceReferenceRecord[] = [];
-	for (const part of message.parts) {
-		if (!isToolUIPart(part) || part.state !== "output-available") continue;
-		const toolName =
-			part.type === "dynamic-tool" ? part.toolName : part.type.split("-").slice(1).join("-");
-		records.push(
-			...(getWorkspaceToolResultAdapter(toolName)?.collectReferences(part.output) ?? []),
-		);
-	}
-	return records;
-}
-
-function dedupeWorkspaceReferenceRecords(records: readonly WorkspaceReferenceRecord[]) {
-	const seen = new Set<string>();
-	return records.filter((record) => {
-		const key = getWorkspaceReferenceRecordKey(record);
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
-	});
-}
-
-function getWorkspaceReferenceRecordKey(record: WorkspaceReferenceRecord) {
-	return `${record.ref}:${getWorkspaceLocationKey(record.location)}:${record.revision ?? ""}`;
-}
diff --git a/src/features/workspaces/ai/workspace-tool-result-adapters.test.ts b/src/features/workspaces/ai/workspace-tool-result-adapters.test.ts
index 254ccb821..411a045c6 100644
--- a/src/features/workspaces/ai/workspace-tool-result-adapters.test.ts
+++ b/src/features/workspaces/ai/workspace-tool-result-adapters.test.ts
@@ -6,13 +6,12 @@ describe("workspace tool result adapters", () => {
 	it("projects current results onto the model-facing shape", () => {
 		const output = {
 			failed: [],
-			items: [{ itemId: "itm_1", path: "/Notes/A", type: "document" }],
-			references: [{ location: { itemId: "itm_1", kind: "item", version: 1 }, ref: "wr_7Kp2Qa9x" }],
+			items: [{ itemId: "itm_1", path: "/Notes/A", ref: "Xk7p2Qa9", type: "document" }],
 		};
 
 		expect(getWorkspaceToolResultAdapter("workspace_create_items")?.projectOutput(output)).toEqual({
 			failed: [],
-			items: [{ path: "/Notes/A", ref: "wr_7Kp2Qa9x", type: "document" }],
+			items: [{ path: "/Notes/A", ref: "Xk7p2Qa9", type: "document" }],
 		});
 	});
 
@@ -27,7 +26,6 @@ describe("workspace tool result adapters", () => {
 				},
 			],
 			items: [],
-			references: [],
 		};
 
 		expect(getWorkspaceToolResultAdapter("workspace_create_items")?.projectOutput(output)).toEqual({
@@ -39,18 +37,12 @@ describe("workspace tool result adapters", () => {
 	it("projects create failures without exposing internal references", () => {
 		const output = {
 			failed: [{ code: "path_already_exists", index: 0, path: "/Old" }],
-			items: [{ itemId: "itm_internal", path: "/Old", type: "document" }],
-			references: [
-				{
-					location: { itemId: "itm_internal", kind: "item", version: 1 },
-					ref: "wr_7Kp2Qa9x",
-				},
-			],
+			items: [{ itemId: "itm_internal", path: "/Old", ref: "Xk7p2Qa9", type: "document" }],
 		};
 
 		expect(getWorkspaceToolResultAdapter("workspace_create_items")?.projectOutput(output)).toEqual({
 			failed: output.failed,
-			items: [{ path: "/Old", ref: "wr_7Kp2Qa9x", type: "document" }],
+			items: [{ path: "/Old", ref: "Xk7p2Qa9", type: "document" }],
 		});
 	});
 
diff --git a/src/features/workspaces/ai/workspace-tool-result-adapters.ts b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
index d7ac9a4c5..043426a88 100644
--- a/src/features/workspaces/ai/workspace-tool-result-adapters.ts
+++ b/src/features/workspaces/ai/workspace-tool-result-adapters.ts
@@ -1,68 +1,38 @@
 import type { JSONValue } from "ai";
-import { z } from "zod";
 
 import { workspaceReadItemsOutputSchema } from "#/features/workspaces/content/workspace-content-contract";
-import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-references";
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
+import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
 import {
 	workspaceCreateItemsOutputSchema,
 	workspaceEditItemOutputSchema,
 } from "#/features/workspaces/operations/workspace-tool-schemas";
 
-function defineWorkspaceToolResultAdapter<TSchema extends z.ZodTypeAny>(input: {
-	collectReferences?: (output: z.output<TSchema>) => readonly WorkspaceReferenceRecord[];
-	outputSchema: TSchema;
-	projectOutput: (output: z.output<TSchema>) => unknown;
-}) {
-	return {
-		collectReferences: (output: unknown) => {
-			const parsed = input.outputSchema.safeParse(output);
-			return parsed.success ? (input.collectReferences?.(parsed.data) ?? []) : [];
+/**
+ * Model-facing projections for tool outputs whose rich form carries more than
+ * the model needs. Addresses are already self-describing, so projection is
+ * only ever subtraction: internal item ids and app-side bookkeeping.
+ */
+const workspaceToolResultAdapters = {
+	workspace_create_items: {
+		projectOutput: (output: unknown): JSONValue => {
+			const { failed, items } = workspaceCreateItemsOutputSchema.parse(output);
+			return { failed, items: items.map(({ itemId: _itemId, ...item }) => item) } as JSONValue;
 		},
-		projectOutput: (output: unknown) => {
-			return input.projectOutput(input.outputSchema.parse(output)) as JSONValue;
+	},
+	// The operation output also carries the durable item id used by the app's
+	// review controls. Keep the model-facing receipt limited to actionable counts.
+	workspace_edit_item: {
+		projectOutput: (output: unknown): JSONValue => {
+			const { applied, failed, path } = workspaceEditItemOutputSchema.parse(output);
+			return { applied, failed, path } as JSONValue;
 		},
-	};
-}
-
-const workspaceReadItemsResultAdapter = defineWorkspaceToolResultAdapter({
-	collectReferences: (output) => output.references,
-	outputSchema: workspaceReadItemsOutputSchema,
-	projectOutput: createWorkspaceReadItemsModelOutput,
-});
-
-const workspaceCreateItemsResultAdapter = defineWorkspaceToolResultAdapter({
-	collectReferences: (output) => output.references,
-	outputSchema: workspaceCreateItemsOutputSchema,
-	projectOutput: (output) => {
-		const refsByItemId = new Map(
-			output.references.flatMap((record) =>
-				record.location.kind === "item" ? [[record.location.itemId, record.ref] as const] : [],
-			),
-		);
-
-		return {
-			failed: output.failed,
-			items: output.items.map(({ itemId, path, type }) => {
-				const ref = refsByItemId.get(itemId);
-
-				return { path, ...(ref ? { ref } : {}), type };
-			}),
-		};
 	},
-});
-
-// The operation output also carries the durable item id used by the app's
-// review controls. Keep the model-facing receipt limited to actionable counts.
-const workspaceEditItemResultAdapter = defineWorkspaceToolResultAdapter({
-	outputSchema: workspaceEditItemOutputSchema,
-	projectOutput: ({ applied, failed, path }) => ({ applied, failed, path }),
-});
-
-const workspaceToolResultAdapters = {
-	workspace_create_items: workspaceCreateItemsResultAdapter,
-	workspace_edit_item: workspaceEditItemResultAdapter,
-	workspace_read_items: workspaceReadItemsResultAdapter,
+	workspace_read_items: {
+		projectOutput: (output: unknown): JSONValue =>
+			createWorkspaceReadItemsModelOutput(
+				workspaceReadItemsOutputSchema.parse(output),
+			) as JSONValue,
+	},
 } as const;
 
 export function getWorkspaceToolResultAdapter(name: string) {
diff --git a/src/features/workspaces/ai/workspace-tools.ts b/src/features/workspaces/ai/workspace-tools.ts
index 0ad155bf9..050e958c4 100644
--- a/src/features/workspaces/ai/workspace-tools.ts
+++ b/src/features/workspaces/ai/workspace-tools.ts
@@ -7,23 +7,16 @@ import {
 	isPendingPdfFallbackInput,
 } from "#/features/workspaces/ai/workspace-read-file-fallback";
 import { getWorkspaceToolResultAdapter } from "#/features/workspaces/ai/workspace-tool-result-adapters";
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
 import {
 	workspaceToolDefinitions,
 	getWorkspaceToolScopes,
 } from "#/features/workspaces/operations/workspace-tool-definitions";
-import {
-	createWorkspaceAccessContext,
-	type WorkspaceAccessContext,
-	type WorkspaceAccessScope,
-} from "#/features/workspaces/operations/workspace-access-context";
+import { createWorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
 
 type WorkspaceThreadToolConfig = {
 	definition: (typeof workspaceToolDefinitions)[number];
 	env: Cloudflare.Env;
 	getThreadContext: () => Promise<AIThreadContext | null>;
-	onWorkspaceReferences?: (records: readonly WorkspaceReferenceRecord[]) => void;
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 };
 
 function createWorkspaceThreadTool(input: WorkspaceThreadToolConfig) {
@@ -65,18 +58,14 @@ function createWorkspaceThreadTool(input: WorkspaceThreadToolConfig) {
 
 			const output = await definition.executeUnknown(
 				args,
-				createThreadWorkspaceAccessContext(
-					thread,
-					getWorkspaceToolScopes(definition.access),
-					context.invocationId,
-					input.resolveWorkspaceReferences,
-				),
+				createWorkspaceAccessContext({
+					operationId: context.invocationId,
+					scopes: getWorkspaceToolScopes(definition.access),
+					userId: thread.userId,
+					workspaceId: thread.workspaceId,
+				}),
 			);
 
-			const references = resultAdapter?.collectReferences(output) ?? [];
-			if (references.length > 0 && input.onWorkspaceReferences) {
-				input.onWorkspaceReferences(references);
-			}
 			if (freshWorkspaceIds && isPendingPdfFallbackInput(args)) {
 				freshWorkspaceIds.set(context.invocationId, thread.workspaceId);
 			}
@@ -89,8 +78,6 @@ function createWorkspaceThreadTool(input: WorkspaceThreadToolConfig) {
 export function createAIThreadWorkspaceTools(input: {
 	env: Cloudflare.Env;
 	getThreadContext: () => Promise<AIThreadContext | null>;
-	onWorkspaceReferences?: (records: readonly WorkspaceReferenceRecord[]) => void;
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 }): ToolSet {
 	return Object.fromEntries(
 		workspaceToolDefinitions.map((definition) => [
@@ -99,8 +86,6 @@ export function createAIThreadWorkspaceTools(input: {
 				definition,
 				env: input.env,
 				getThreadContext: input.getThreadContext,
-				onWorkspaceReferences: input.onWorkspaceReferences,
-				resolveWorkspaceReferences: input.resolveWorkspaceReferences,
 			}),
 		]),
 	) as ToolSet;
@@ -115,18 +100,3 @@ async function requireThreadContext(getThreadContext: () => Promise<AIThreadCont
 
 	return thread;
 }
-
-function createThreadWorkspaceAccessContext(
-	thread: AIThreadContext,
-	scopes: readonly WorkspaceAccessScope[],
-	operationId: string,
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>,
-): WorkspaceAccessContext {
-	return createWorkspaceAccessContext({
-		operationId,
-		...(resolveWorkspaceReferences ? { resolveWorkspaceReferences } : {}),
-		scopes,
-		userId: thread.userId,
-		workspaceId: thread.workspaceId,
-	});
-}
diff --git a/src/features/workspaces/cache-page.test.ts b/src/features/workspaces/cache-page.test.ts
index df650432a..933613b61 100644
--- a/src/features/workspaces/cache-page.test.ts
+++ b/src/features/workspaces/cache-page.test.ts
@@ -75,6 +75,7 @@ function createItem(input: Partial<WorkspaceItem> = {}): WorkspaceItem {
 	return {
 		color: input.color ?? null,
 		createdAt: "2026-01-01T00:00:00.000Z",
+		refKey: "ref-item-1",
 		id: "folder-1",
 		metadataJson: {},
 		name: input.name ?? "Folder",
diff --git a/src/features/workspaces/components/WorkspaceCitation.tsx b/src/features/workspaces/components/WorkspaceCitation.tsx
index aa252dfa1..33aa2755a 100644
--- a/src/features/workspaces/components/WorkspaceCitation.tsx
+++ b/src/features/workspaces/components/WorkspaceCitation.tsx
@@ -5,16 +5,19 @@ import type { WorkspaceItem } from "#/features/workspaces/contracts";
 import { flashcardViewerQueryOptions } from "#/features/workspaces/flashcards/flashcard-queries";
 import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
 import { useWorkspaceLocationActions } from "#/features/workspaces/locations/workspace-location-context";
+import { quizViewerQueryOptions } from "#/features/workspaces/quizzes/quiz-queries";
 import { cn } from "#/lib/utils";
 
 export function WorkspaceCitation({ location }: { readonly location: WorkspaceLocation }) {
 	const item = useWorkspaceLocationActions().getItem(location.itemId);
 
-	return location.kind === "flashcard" && item?.type === "flashcard" ? (
-		<FlashcardCitation item={item} location={location} />
-	) : (
-		<CitationButton location={location} />
-	);
+	if (location.kind === "flashcard" && item?.type === "flashcard") {
+		return <FlashcardCitation item={item} location={location} />;
+	}
+	if (location.kind === "quiz-question" && item?.type === "quiz") {
+		return <QuizCitation item={item} location={location} />;
+	}
+	return <CitationButton location={location} />;
 }
 
 function FlashcardCitation({
@@ -41,6 +44,31 @@ function FlashcardCitation({
 	);
 }
 
+function QuizCitation({
+	item,
+	location,
+}: {
+	item: WorkspaceItem;
+	location: Extract<WorkspaceLocation, { kind: "quiz-question" }>;
+}) {
+	const { data: questionNumber } = useQuery({
+		...quizViewerQueryOptions({
+			itemId: item.id,
+			updatedAt: item.updatedAt,
+			workspaceId: item.workspaceId,
+		}),
+		select: ({ questions }) =>
+			questions.findIndex((question) => question.id === location.questionId) + 1,
+	});
+
+	return (
+		<CitationButton
+			location={location}
+			locatorLabel={questionNumber ? `Question ${questionNumber}` : undefined}
+		/>
+	);
+}
+
 function CitationButton({
 	location,
 	locatorLabel,
diff --git a/src/features/workspaces/components/WorkspaceContent.tsx b/src/features/workspaces/components/WorkspaceContent.tsx
index 7fbfc8f79..7baecb4a1 100644
--- a/src/features/workspaces/components/WorkspaceContent.tsx
+++ b/src/features/workspaces/components/WorkspaceContent.tsx
@@ -11,6 +11,7 @@ import {
 } from "#/components/ui/empty";
 import { DocumentEditorSurface } from "#/features/workspaces/components/document-editor/DocumentEditorSurface";
 import { FlashcardViewer } from "#/features/workspaces/components/flashcards/FlashcardViewer";
+import { QuizViewer } from "#/features/workspaces/components/quizzes/QuizViewer";
 import { WorkspaceClipboardIntakeDialog } from "#/features/workspaces/components/WorkspaceClipboardIntakeDialog";
 import WorkspaceClickableEmptyState from "#/features/workspaces/components/WorkspaceClickableEmptyState";
 import { useWorkspaceClipboardIntake } from "#/features/workspaces/components/useWorkspaceClipboardIntake";
@@ -525,6 +526,10 @@ function WorkspaceItemView({
 		return <FlashcardViewer itemPath={itemPath} item={item} viewInstanceId={viewInstanceId} />;
 	}
 
+	if (item.type === "quiz") {
+		return <QuizViewer itemPath={itemPath} item={item} viewInstanceId={viewInstanceId} />;
+	}
+
 	const { Icon: ItemIcon, iconClassName, surfaceClassName } = getWorkspaceItemDisplay(item);
 	const itemViewContent = (
 		<div className="flex flex-col items-center gap-3 text-center">
diff --git a/src/features/workspaces/components/WorkspaceLayout.tsx b/src/features/workspaces/components/WorkspaceLayout.tsx
index dfc6f5fe3..bd7238d31 100644
--- a/src/features/workspaces/components/WorkspaceLayout.tsx
+++ b/src/features/workspaces/components/WorkspaceLayout.tsx
@@ -4,7 +4,10 @@ import { workspacePageQueryKey } from "#/features/workspaces/cache-keys";
 import { applyWorkspacePageDeltaToCache } from "#/features/workspaces/cache-page";
 import AiChatPanel from "#/features/workspaces/components/AiChatPanel";
 import WorkspaceChatLayout from "#/features/workspaces/components/WorkspaceChatLayout";
-import { CreateFlashcardsDialog } from "#/features/workspaces/components/flashcards/CreateFlashcardsDialog";
+import {
+	CreateStudyItemDialog,
+	type StudyItemDialogType,
+} from "#/features/workspaces/components/study/CreateStudyItemDialog";
 import WorkspaceContextBar from "#/features/workspaces/components/WorkspaceContextBar";
 import { hasActiveWorkspaceCapture } from "#/features/workspaces/components/WorkspaceCaptureChrome";
 import WorkspaceDragProvider from "#/features/workspaces/components/WorkspaceDragProvider";
@@ -70,7 +73,10 @@ export function WorkspaceShell({
 	const queryClient = useQueryClient();
 	const createWorkspaceItemMutation = useCreateWorkspaceItemMutation();
 	const moveWorkspaceItemsMutation = useMoveWorkspaceItemsMutation();
-	const [flashcardParentId, setFlashcardParentId] = useState<string | null | undefined>();
+	const [studyDraft, setStudyDraft] = useState<{
+		type: StudyItemDialogType;
+		parentId: string | null;
+	}>();
 	const persistedStoresHydrated = useWorkspacePersistedStoresHydrated();
 	const ensureWorkspaceUiSession = useWorkspaceUiStore((state) => state.ensureWorkspaceSession);
 	const itemViewStatesByViewInstanceId = useWorkspaceItemViewStatesByViewInstance(workspace.id);
@@ -135,8 +141,8 @@ export function WorkspaceShell({
 			return;
 		}
 
-		if (input.type === "flashcard") {
-			setFlashcardParentId(input.parentId);
+		if (input.type === "flashcard" || input.type === "quiz") {
+			setStudyDraft({ type: input.type, parentId: input.parentId });
 			return;
 		}
 		createWorkspaceItemMutation.mutate({
@@ -297,11 +303,10 @@ export function WorkspaceShell({
 			</WorkspaceFileIntakeProvider>
 		</WorkspaceFileUploadProvider>
 	);
-	const flashcardParent = flashcardParentId ? itemsById.get(flashcardParentId) : undefined;
-	const flashcardDialogOpen = flashcardParentId === null || flashcardParent !== undefined;
-	const flashcardParentPath = flashcardParent
-		? getWorkspaceItemPath(flashcardParent, itemsById)
-		: "/";
+	const studyParent = studyDraft?.parentId ? itemsById.get(studyDraft.parentId) : undefined;
+	const studyDialogOpen =
+		studyDraft !== undefined && (studyDraft.parentId === null || studyParent !== undefined);
+	const studyParentPath = studyParent ? getWorkspaceItemPath(studyParent, itemsById) : "/";
 
 	return (
 		<WorkspaceMutationAccessProvider membershipRole={workspace.membershipRole}>
@@ -310,12 +315,13 @@ export function WorkspaceShell({
 					<WorkspacePdfEngineProvider active={hasHeavyViewerRuntimeItems}>
 						{workspaceInteractionContent}
 					</WorkspacePdfEngineProvider>
-					<CreateFlashcardsDialog
-						open={flashcardDialogOpen}
-						parentPath={flashcardParentPath}
+					<CreateStudyItemDialog
+						type={studyDraft?.type ?? "flashcard"}
+						open={studyDialogOpen}
+						parentPath={studyParentPath}
 						workspaceId={workspace.id}
 						onOpenChange={(open) => {
-							if (!open) setFlashcardParentId(undefined);
+							if (!open) setStudyDraft(undefined);
 						}}
 					/>
 				</DocumentEditReviewProvider>
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessagePartView.tsx b/src/features/workspaces/components/ai-chat/AiChatMessagePartView.tsx
index 06b6522b9..21a90a213 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessagePartView.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessagePartView.tsx
@@ -16,30 +16,23 @@ import {
 import { AiChatMessageResponse } from "#/features/workspaces/components/ai-chat/AiChatMessageResponse";
 import { AiChatToolActivityRow } from "#/features/workspaces/components/ai-chat/AiChatToolActivityRow";
 import type { AiChatMessagePart } from "#/features/workspaces/components/ai-chat/types";
-import type {
-	WorkspaceLocation,
-	WorkspaceReference,
-} from "#/features/workspaces/locations/workspace-location";
 
 export function AiChatMessagePartView({
 	interruptUnfinishedTools = false,
 	isStreaming = false,
 	part,
 	preserveWhitespace = false,
-	workspaceCitationLocations,
 }: {
 	interruptUnfinishedTools?: boolean;
 	isStreaming?: boolean;
 	part: AiChatMessagePart | AiChatToolGroupPart;
 	preserveWhitespace?: boolean;
-	workspaceCitationLocations?: ReadonlyMap<WorkspaceReference, WorkspaceLocation>;
 }) {
 	if (part.type === "text") {
 		return (
 			<AiChatMessageResponse
 				className={preserveWhitespace ? "whitespace-pre-wrap" : undefined}
 				isStreaming={isStreaming}
-				workspaceCitationLocations={workspaceCitationLocations}
 			>
 				{part.text}
 			</AiChatMessageResponse>
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
index 7e593de6d..d896a15b1 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.test.tsx
@@ -6,10 +6,6 @@ import { AiChatMessageResponse } from "#/features/workspaces/components/ai-chat/
 import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
 import { flashcardViewerQueryOptions } from "#/features/workspaces/flashcards/flashcard-queries";
 import { createEmptyFlashcardStudyState } from "#/features/workspaces/flashcards/flashcard-study-state";
-import type {
-	WorkspaceLocation,
-	WorkspaceReference,
-} from "#/features/workspaces/locations/workspace-location";
 import { WorkspaceLocationProvider } from "#/features/workspaces/locations/workspace-location-context";
 import type { WorkspaceItem } from "#/features/workspaces/contracts";
 
@@ -18,9 +14,15 @@ vi.mock("#/features/workspaces/flashcards/flashcard-functions", () => ({
 	recordFlashcardStudyRatingFn: vi.fn(),
 	resetFlashcardStudyProgressFn: vi.fn(),
 }));
+vi.mock("#/features/workspaces/quizzes/quiz-functions", () => ({
+	getQuizViewerFn: vi.fn(),
+	recordQuizAnswerFn: vi.fn(),
+	resetQuizStudyProgressFn: vi.fn(),
+}));
 
 const documentItem: WorkspaceItem = {
 	color: null,
+	refKey: "refdoc01",
 	createdAt: "2026-01-01T00:00:00.000Z",
 	id: "document-1",
 	metadataJson: {},
@@ -35,6 +37,7 @@ const documentItem: WorkspaceItem = {
 const flashcardItem: WorkspaceItem = {
 	...documentItem,
 	id: "flashcard-1",
+	refKey: "refcard1",
 	name: "Biology",
 	type: "flashcard",
 };
@@ -44,7 +47,6 @@ function renderMessage(
 	options: {
 		isStreaming?: boolean;
 		items?: WorkspaceItem[];
-		locations?: ReadonlyMap<WorkspaceReference, WorkspaceLocation>;
 		queryClient?: QueryClient;
 	} = {},
 ) {
@@ -54,38 +56,42 @@ function renderMessage(
 				itemsById={new Map(options.items?.map((item) => [item.id, item]))}
 				navigate={() => "tab-1"}
 			>
-				<AiChatMessageResponse
-					isStreaming={options.isStreaming}
-					workspaceCitationLocations={options.locations}
-				>
-					{children}
-				</AiChatMessageResponse>
+				<AiChatMessageResponse isStreaming={options.isStreaming}>{children}</AiChatMessageResponse>
 			</WorkspaceLocationProvider>
 		</QueryClientProvider>,
 	);
 }
 
 describe("AI chat message response citations", () => {
-	it("renders a validated citation as an app-owned source button", () => {
-		const ref = "wr_AAAAAAAA" as WorkspaceReference;
-		const html = renderMessage(`Claim <citation ref="${ref}"></citation>`, {
-			locations: new Map([
-				[ref, { itemId: "missing-pdf", kind: "pdf-page", pageNumber: 12, version: 1 }],
-			]),
+	it("renders a resolvable page citation as an app-owned source button", () => {
+		const fileItem: WorkspaceItem = {
+			...documentItem,
+			id: "file-1",
+			refKey: "reffile1",
+			name: "Book.pdf",
+			type: "file",
+		};
+		const html = renderMessage(`Claim <citation ref="reffile1/p12"></citation>`, {
+			items: [fileItem],
 		});
 
 		expect(html).toContain("<button");
-		expect(html).toContain("Open Source unavailable · p. 12");
-		expect(html).toContain(">Source unavailable</span>");
 		expect(html).toContain(">· p. 12</span>");
 		expect(html).not.toContain("<citation");
 	});
 
+	it("renders nothing for an address no live item answers to", () => {
+		const html = renderMessage(`Claim <citation ref="zzZZzzZZ/p12"></citation>`, {
+			items: [documentItem],
+		});
+
+		expect(html).not.toContain("<button");
+		expect(html).not.toContain("<citation");
+	});
+
 	it("reuses the workspace item's icon and color", () => {
-		const ref = "wr_BBBBBBBB" as WorkspaceReference;
-		const html = renderMessage(`Claim <citation ref="${ref}"></citation>`, {
+		const html = renderMessage(`Claim <citation ref="refdoc01"></citation>`, {
 			items: [documentItem],
-			locations: new Map([[ref, { itemId: documentItem.id, kind: "item", version: 1 }]]),
 		});
 
 		expect(html).toContain("<svg");
@@ -94,7 +100,6 @@ describe("AI chat message response citations", () => {
 	});
 
 	it("shows a flashcard's authored position", () => {
-		const ref = "wr_CCCCCCCC" as WorkspaceReference;
 		const cardId = "f67080f9-0158-4565-86a9-4c90ed6809d2";
 		const queryClient = new QueryClient();
 		const query = flashcardViewerQueryOptions({
@@ -110,11 +115,8 @@ describe("AI chat message response citations", () => {
 			],
 			studyState: createEmptyFlashcardStudyState(),
 		});
-		const html = renderMessage(`Claim <citation ref="${ref}"></citation>`, {
+		const html = renderMessage(`Claim <citation ref="refcard1/${cardId}"></citation>`, {
 			items: [flashcardItem],
-			locations: new Map([
-				[ref, { cardId, itemId: flashcardItem.id, kind: "flashcard", version: 1 }],
-			]),
 			queryClient,
 		});
 
@@ -123,17 +125,18 @@ describe("AI chat message response citations", () => {
 	});
 
 	it("does not expose an incomplete streamed citation tag", () => {
-		const html = renderMessage('Claim <citation ref="wr_AAAAAAAA', { isStreaming: true });
+		const html = renderMessage('Claim <citation ref="refdoc01/b_x7Kp2Qa9x8L', {
+			isStreaming: true,
+		});
 
 		expect(html).toContain("Claim");
 		expect(html).not.toContain("citation");
-		expect(html).not.toContain("wr_AAAAAAAA");
+		expect(html).not.toContain("refdoc01");
 	});
 
 	it("renders non-empty citation markup as inert text", () => {
-		const ref = "wr_AAAAAAAA" as WorkspaceReference;
-		const html = renderMessage(`Claim <citation ref="${ref}">not a citation</citation>`, {
-			locations: new Map([[ref, { itemId: "document-1", kind: "item", version: 1 }]]),
+		const html = renderMessage(`Claim <citation ref="refdoc01">not a citation</citation>`, {
+			items: [documentItem],
 		});
 
 		expect(html).toContain("not a citation");
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx
index a463da156..0b1ca8283 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessageResponse.tsx
@@ -1,15 +1,11 @@
 import { cjk } from "@streamdown/cjk";
 import { createMathPlugin } from "@streamdown/math";
-import { createContext, type ComponentProps, use, useEffect } from "react";
+import { type ComponentProps, useEffect } from "react";
 import { Streamdown, type StreamdownProps } from "streamdown";
 import "katex/dist/katex.min.css";
 // Extends the shared KaTeX instance with \ce{} chemistry and \pu{} units.
 import "katex/contrib/mhchem";
-import {
-	parseWorkspaceReference,
-	type WorkspaceLocation,
-	type WorkspaceReference,
-} from "#/features/workspaces/locations/workspace-location";
+import { useWorkspaceLocationActions } from "#/features/workspaces/locations/workspace-location-context";
 import { MarkdownCodeBlock } from "#/features/workspaces/components/ai-chat/ai-chat-code-block";
 import { normalizeLlmMarkdown } from "#/features/workspaces/components/ai-chat/normalize-llm-markdown";
 import { WorkspaceCitation } from "#/features/workspaces/components/WorkspaceCitation";
@@ -20,7 +16,6 @@ type AiChatMessageResponseProps = Omit<
 	"allowedTags" | "literalTagContent"
 > & {
 	isStreaming?: boolean;
-	workspaceCitationLocations?: ReadonlyMap<WorkspaceReference, WorkspaceLocation>;
 };
 
 const math = createMathPlugin({
@@ -31,10 +26,6 @@ const streamdownPlugins = { cjk, math };
 const streamdownComponents = { code: MarkdownCodeBlock };
 const streamdownAllowedTags = { citation: ["ref"] };
 const streamdownLiteralTagContent = ["citation"];
-const emptyWorkspaceCitationLocations = new Map<WorkspaceReference, WorkspaceLocation>();
-const WorkspaceCitationLocationsContext = createContext<
-	ReadonlyMap<WorkspaceReference, WorkspaceLocation>
->(emptyWorkspaceCitationLocations);
 const streamdownAnimation = {
 	animation: "fadeIn",
 	duration: 160,
@@ -50,6 +41,7 @@ type StreamdownCitationProps = Record<string, unknown> & {
 };
 
 function StreamdownWorkspaceCitation(citationProps: StreamdownCitationProps) {
+	const { resolveAddress } = useWorkspaceLocationActions();
 	const children = citationProps.children;
 	if (typeof children === "string" && children.trim().length > 0) {
 		return children;
@@ -58,13 +50,7 @@ function StreamdownWorkspaceCitation(citationProps: StreamdownCitationProps) {
 		return null;
 	}
 
-	const ref = parseWorkspaceReference(citationProps.node?.properties?.ref);
-	if (!ref) {
-		return null;
-	}
-
-	const locations = use(WorkspaceCitationLocationsContext);
-	const location = locations.get(ref);
+	const location = resolveAddress(citationProps.node?.properties?.ref);
 	return location ? <WorkspaceCitation location={location} /> : null;
 }
 
@@ -73,7 +59,6 @@ export function AiChatMessageResponse({
 	className,
 	components,
 	isStreaming = false,
-	workspaceCitationLocations = emptyWorkspaceCitationLocations,
 	...props
 }: AiChatMessageResponseProps) {
 	useEffect(() => {
@@ -90,21 +75,19 @@ export function AiChatMessageResponse({
 		typeof children === "string" ? normalizeLlmMarkdown(children) : children;
 
 	return (
-		<WorkspaceCitationLocationsContext value={workspaceCitationLocations}>
-			<Streamdown
-				animated={streamdownAnimation}
-				className={cn("[&>ol]:pl-2 [&>ul]:pl-2", className)}
-				components={mergedComponents}
-				isAnimating={isStreaming}
-				linkSafety={{ enabled: false }}
-				mode="streaming"
-				plugins={streamdownPlugins}
-				{...props}
-				allowedTags={streamdownAllowedTags}
-				literalTagContent={streamdownLiteralTagContent}
-			>
-				{normalizedChildren}
-			</Streamdown>
-		</WorkspaceCitationLocationsContext>
+		<Streamdown
+			animated={streamdownAnimation}
+			className={cn("[&>ol]:pl-2 [&>ul]:pl-2", className)}
+			components={mergedComponents}
+			isAnimating={isStreaming}
+			linkSafety={{ enabled: false }}
+			mode="streaming"
+			plugins={streamdownPlugins}
+			{...props}
+			allowedTags={streamdownAllowedTags}
+			literalTagContent={streamdownLiteralTagContent}
+		>
+			{normalizedChildren}
+		</Streamdown>
 	);
 }
diff --git a/src/features/workspaces/components/ai-chat/AiChatMessageRow.tsx b/src/features/workspaces/components/ai-chat/AiChatMessageRow.tsx
index 11974dfae..3d6e052a4 100644
--- a/src/features/workspaces/components/ai-chat/AiChatMessageRow.tsx
+++ b/src/features/workspaces/components/ai-chat/AiChatMessageRow.tsx
@@ -11,10 +11,7 @@ import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from "#/comp
 import { AiChatMessagePartView } from "#/features/workspaces/components/ai-chat/AiChatMessagePartView";
 import { AiChatDocumentEditActions } from "#/features/workspaces/components/ai-chat/AiChatDocumentEditActions";
 import { getAiChatDocumentEditGroups } from "#/features/workspaces/components/ai-chat/ai-chat-document-edit-actions";
-import {
-	getWorkspaceCitationLocations,
-	stripWorkspaceCitationTags,
-} from "#/features/workspaces/ai/workspace-references";
+import { stripWorkspaceCitationTags } from "#/features/workspaces/ai/workspace-references";
 import {
 	type AiChatRenderablePart,
 	type AssistantRowDisplay,
@@ -49,8 +46,6 @@ export default function AiChatMessageRow({
 	message: AiChatMessage;
 	onRegenerate?: () => void;
 }) {
-	const workspaceCitationLocations = getWorkspaceCitationLocations(message);
-
 	if (message.role === "assistant" && display?.kind === "hidden") {
 		return null;
 	}
@@ -86,7 +81,6 @@ export default function AiChatMessageRow({
 									isStreaming={isStreaming}
 									message={message}
 									onRegenerate={onRegenerate}
-									workspaceCitationLocations={workspaceCitationLocations}
 								/>
 							) : (
 								<UserMessageBody message={message} parts={userBodyParts} />
@@ -209,13 +203,11 @@ function AssistantMessageBody({
 	isStreaming,
 	message,
 	onRegenerate,
-	workspaceCitationLocations,
 }: {
 	display: AssistantRowDisplay;
 	isStreaming: boolean;
 	message: AiChatMessage;
 	onRegenerate?: () => void;
-	workspaceCitationLocations: ReturnType<typeof getWorkspaceCitationLocations>;
 }) {
 	if (display.kind === "content") {
 		return (
@@ -226,7 +218,6 @@ function AssistantMessageBody({
 						interruptUnfinishedTools={display.interruptUnfinishedTools}
 						isStreaming={isStreaming}
 						part={part}
-						workspaceCitationLocations={workspaceCitationLocations}
 					/>
 				))}
 			</div>
diff --git a/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx b/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
index fad3fcd15..4a8d30e81 100644
--- a/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
+++ b/src/features/workspaces/components/ai-chat/ai-chat-code-block.tsx
@@ -2,6 +2,7 @@ import type { CSSProperties, HTMLAttributes, ReactNode } from "react";
 import { isValidElement, useEffect, useState } from "react";
 import type { ThemedToken } from "shiki/core";
 import { ClientOnly } from "@tanstack/react-router";
+import { useIsCodeFenceIncomplete } from "streamdown";
 import {
 	CodeBlockActions,
 	CodeBlockCopyButton,
@@ -13,10 +14,11 @@ import {
 import {
 	getCodeLanguageLabel,
 	highlightCodeTokens,
+	isMermaidCodeLanguage,
 	normalizeCodeLanguage,
 	type SupportedCodeLanguage,
 } from "#/features/workspaces/documents/code-block-shiki/highlighter";
-import { AiChatMermaidDiagram } from "#/features/workspaces/components/ai-chat/AiChatMermaidDiagram";
+import { MermaidDiagram } from "#/components/code-block/mermaid-diagram";
 import { cn } from "#/lib/utils.ts";
 
 // Shiki uses bitflags for font styles: 1=italic, 2=bold, 4=underline
@@ -358,6 +360,9 @@ export const MarkdownCodeBlock = ({
 	"data-block": dataBlock,
 	...props
 }: MarkdownCodeBlockProps) => {
+	// Only chat can see a half-written fence, so the streaming state is read
+	// here and handed to the shared diagram rather than looked up inside it.
+	const isFenceIncomplete = useIsCodeFenceIncomplete();
 	const isBlock = dataBlock !== undefined;
 
 	if (!isBlock) {
@@ -375,10 +380,10 @@ export const MarkdownCodeBlock = ({
 		getLanguageFromClassName(className) ?? getLanguageFromClassName(node?.properties?.className);
 	const code = getTextContent(children).replace(/\n$/, "");
 
-	if (rawLanguage?.toLowerCase() === "mermaid") {
+	if (isMermaidCodeLanguage(rawLanguage)) {
 		return (
 			<ClientOnly>
-				<AiChatMermaidDiagram source={code} />
+				<MermaidDiagram isIncomplete={isFenceIncomplete} source={code} />
 			</ClientOnly>
 		);
 	}
diff --git a/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts b/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
index 6cd3e183d..285a9eb49 100644
--- a/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
+++ b/src/features/workspaces/components/ai-chat/ai-chat-tool-receipts.ts
@@ -166,7 +166,13 @@ export function getFinishedToolReceipt(input: {
 				successVerb: "Created",
 				typeFromItem: (item) => {
 					const type = getString(asRecord(item).type);
-					return type === "folder" ? "folder" : type === "flashcard" ? "flashcard set" : "document";
+					return type === "folder"
+						? "folder"
+						: type === "flashcard"
+							? "flashcard set"
+							: type === "quiz"
+								? "quiz"
+								: "document";
 				},
 			});
 		case "workspace_delete_items":
diff --git a/src/features/workspaces/components/flashcards/FlashcardViewer.tsx b/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
index 81edcf8ce..4782c1e8c 100644
--- a/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
+++ b/src/features/workspaces/components/flashcards/FlashcardViewer.tsx
@@ -1,16 +1,23 @@
 import { useQuery } from "@tanstack/react-query";
-import type { JSONContent } from "@tiptap/core";
-import { EditorContent, useEditor } from "@tiptap/react";
-import { Check, ChevronLeft, ChevronRight, Lightbulb, X } from "lucide-react";
+import { Check, X } from "lucide-react";
 import { domAnimation, LazyMotion, m, MotionConfig } from "motion/react";
 import { type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
 
 import { Button } from "#/components/ui/button";
 import { Skeleton } from "#/components/ui/skeleton";
 import { sendComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
-import { FlashcardToolbar } from "#/features/workspaces/components/flashcards/FlashcardToolbar";
+import {
+	StudyProgressStrip,
+	type StudyProgressTone,
+} from "#/features/workspaces/components/study/StudyProgressStrip";
+import { StudyRichText } from "#/features/workspaces/components/study/StudyRichText";
+import {
+	StudyAiActionButton,
+	StudyNavButton,
+	useStudySessionFocus,
+} from "#/features/workspaces/components/study/StudySessionControls";
+import { StudyToolbar } from "#/features/workspaces/components/study/StudyToolbar";
 import { useWorkspaceItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
-import { getTiptapDocumentBaseExtensions } from "#/features/workspaces/documents/tiptap-extensions";
 import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
 import {
 	flashcardViewerQueryOptions,
@@ -178,9 +185,17 @@ function FlashcardStudySession({
 	}, [resetProgress, startSession]);
 	const toolbar = useMemo(
 		() => (
-			<FlashcardToolbar
+			<StudyToolbar
 				canReset={studyProgress.reviewedCount > 0}
 				isResetting={isResetting}
+				labels={{
+					allLabel: "All cards",
+					mobileLabel: "Flashcard study options",
+					resetAriaLabel: "Reset flashcard progress",
+					resetDescription:
+						"This clears every saved response for this set. The cards themselves will not change.",
+					resetTitle: "Reset flashcard progress?",
+				}}
 				missedCount={studyProgress.missedCount}
 				mode={mode}
 				shuffled={shuffled}
@@ -407,6 +422,7 @@ function FlashcardStudySurface({
 	studyCards: Flashcard[];
 	studyState: FlashcardStudyState;
 }) {
+	const sectionRef = useStudySessionFocus(currentCard.id);
 	const settling = ratingFeedback !== null;
 	const nextCard = ratingFeedback ? studyCards[currentIndex + 1] : undefined;
 	const isLastCardRating = ratingFeedback !== null && !nextCard;
@@ -441,6 +457,7 @@ function FlashcardStudySurface({
 		<LazyMotion features={domAnimation}>
 			<MotionConfig reducedMotion="user">
 				<section
+					ref={sectionRef}
 					className="flex h-full min-h-0 flex-col bg-background px-4 py-5 sm:px-8 sm:py-7"
 					aria-label={`${item.name} study session`}
 					onKeyDown={(event) => {
@@ -565,7 +582,8 @@ function FlashcardStudySurface({
 											label="Front"
 											content={currentCard.front}
 											action={
-												<FlashcardAiAction
+												<StudyAiActionButton
+													className="absolute top-4 right-4 z-10"
 													label="Hint"
 													onSend={() =>
 														sendComposerPrompt(
@@ -582,7 +600,8 @@ function FlashcardStudySurface({
 											label="Back"
 											content={currentCard.back}
 											action={
-												<FlashcardAiAction
+												<StudyAiActionButton
+													className="absolute top-4 right-4 z-10"
 													label="Explain"
 													onSend={() =>
 														sendComposerPrompt(
@@ -599,30 +618,28 @@ function FlashcardStudySurface({
 						</div>
 
 						<div className="space-y-3">
-							<FlashcardStatusStrip
-								cards={studyCards}
+							<StudyProgressStrip
+								ariaLabel={`${gotItCount} got it, ${missedCount} missed, ${studyCards.length - gotItCount - missedCount} not reviewed`}
 								currentIndex={currentIndex}
-								gotItCount={gotItCount}
-								missedCount={missedCount}
 								onSelect={onGoTo}
-								reviewsByCardId={studyState.cards}
+								segments={studyCards.map((card, index) => {
+									const { label, tone } = describeFlashcardRating(
+										studyState.cards[card.id]?.lastRating,
+									);
+									return { id: card.id, label: `Card ${index + 1}: ${label}`, tone };
+								})}
 							/>
 							<div className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-2">
 								<span className="justify-self-start text-xs text-muted-foreground tabular-nums sm:text-sm">
 									{gotItCount + missedCount} reviewed
 								</span>
 								<div className="col-start-2 flex items-center justify-center gap-1 sm:gap-2">
-									<Button
-										variant="ghost"
-										size="icon-lg"
-										aria-label="Previous card"
-										title="Previous card (Left arrow)"
+									<StudyNavButton
+										direction="previous"
+										noun="card"
 										disabled={settling || currentIndex === 0}
-										className="size-11 rounded-xl [&_svg]:size-4.5 sm:size-12 sm:[&_svg]:size-5"
 										onClick={() => onGoTo(currentIndex - 1)}
-									>
-										<ChevronLeft />
-									</Button>
+									/>
 									<Button
 										variant="outline"
 										aria-label="Review again"
@@ -655,17 +672,12 @@ function FlashcardStudySurface({
 									>
 										<Check /> Yes
 									</Button>
-									<Button
-										variant="ghost"
-										size="icon-lg"
-										aria-label="Next card"
-										title="Next card (Right arrow)"
+									<StudyNavButton
+										direction="next"
+										noun="card"
 										disabled={settling || currentIndex === studyCards.length - 1}
-										className="size-11 rounded-xl [&_svg]:size-4.5 sm:size-12 sm:[&_svg]:size-5"
 										onClick={() => onGoTo(currentIndex + 1)}
-									>
-										<ChevronRight />
-									</Button>
+									/>
 								</div>
 								<span className="col-start-3 justify-self-end text-xs text-muted-foreground tabular-nums sm:text-sm">
 									{currentIndex + 1} of {studyCards.length}
@@ -679,66 +691,6 @@ function FlashcardStudySurface({
 	);
 }
 
-function FlashcardStatusStrip({
-	cards,
-	currentIndex,
-	gotItCount,
-	missedCount,
-	onSelect,
-	reviewsByCardId,
-}: {
-	cards: Flashcard[];
-	currentIndex: number;
-	gotItCount: number;
-	missedCount: number;
-	onSelect: (index: number) => void;
-	reviewsByCardId: FlashcardStudyState["cards"];
-}) {
-	const unseenCount = cards.length - gotItCount - missedCount;
-	const gap = cards.length <= 50 ? 3 : cards.length <= 120 ? 2 : cards.length <= 300 ? 1 : 0;
-
-	return (
-		<div
-			role="group"
-			aria-label={`${gotItCount} got it, ${missedCount} missed, ${unseenCount} not reviewed`}
-			className="mx-auto grid h-4 w-full items-center"
-			style={{
-				columnGap: gap,
-				gridTemplateColumns: `repeat(${cards.length}, minmax(0, 1fr))`,
-				maxWidth: `${cards.length * 64}px`,
-			}}
-		>
-			{cards.map((card, index) => {
-				const rating = reviewsByCardId[card.id]?.lastRating;
-				const status = getFlashcardRatingLabel(rating);
-				return (
-					<button
-						key={card.id}
-						type="button"
-						aria-current={index === currentIndex ? "step" : undefined}
-						aria-label={`Card ${index + 1}: ${status}`}
-						tabIndex={index === currentIndex ? 0 : -1}
-						onClick={() => onSelect(index)}
-						className="group flex h-4 min-w-0 cursor-pointer items-center focus-visible:outline-none"
-					>
-						<span
-							aria-hidden="true"
-							className={cn(
-								"h-1.5 w-full min-w-0 rounded-full bg-border transition-[height,background-color,box-shadow,filter] duration-150 group-hover:h-2.5 group-hover:brightness-125",
-								rating === "again" && "bg-red-500/75",
-								rating === "hard" && "bg-amber-500/75",
-								(rating === "good" || rating === "easy") && "bg-emerald-500/75",
-								index === currentIndex &&
-									"h-2.5 ring-1 ring-foreground/70 ring-offset-1 ring-offset-background",
-							)}
-						/>
-					</button>
-				);
-			})}
-		</div>
-	);
-}
-
 function getStudyCards(cardIds: string[], cardsById: ReadonlyMap<string, Flashcard>): Flashcard[] {
 	const cards: Flashcard[] = [];
 	for (const cardId of cardIds) {
@@ -748,18 +700,21 @@ function getStudyCards(cardIds: string[], cardsById: ReadonlyMap<string, Flashca
 	return cards;
 }
 
-function getFlashcardRatingLabel(rating: FlashcardStudyRating | undefined): string {
+function describeFlashcardRating(rating: FlashcardStudyRating | undefined): {
+	label: string;
+	tone: StudyProgressTone;
+} {
 	switch (rating) {
 		case "again":
-			return "Missed";
+			return { label: "Missed", tone: "missed" };
 		case "hard":
-			return "Hard";
+			return { label: "Hard", tone: "hard" };
 		case "good":
-			return "Got it";
+			return { label: "Got it", tone: "correct" };
 		case "easy":
-			return "Easy";
+			return { label: "Easy", tone: "correct" };
 		default:
-			return "Not reviewed";
+			return { label: "Not reviewed", tone: "unseen" };
 	}
 }
 
@@ -779,23 +734,6 @@ function FlashcardFace({
 	const textLength = countFlashcardText(content);
 	const densityClass =
 		textLength > 500 ? "is-very-dense" : textLength > 220 ? "is-dense" : undefined;
-	const editor = useEditor(
-		{
-			content: content as unknown as JSONContent,
-			editable: false,
-			immediatelyRender: false,
-			extensions: getTiptapDocumentBaseExtensions(),
-			editorProps: {
-				attributes: {
-					class: cn(
-						"workspace-document-prose workspace-flashcard-prose outline-none",
-						densityClass,
-					),
-				},
-			},
-		},
-		[content],
-	);
 
 	return (
 		<div
@@ -807,29 +745,15 @@ function FlashcardFace({
 				{label}
 			</span>
 			{action}
-			<EditorContent editor={editor} />
+			<StudyRichText
+				className="w-full"
+				content={content}
+				proseClassName={cn("workspace-flashcard-prose", densityClass)}
+			/>
 		</div>
 	);
 }
 
-function FlashcardAiAction({ label, onSend }: { label: string; onSend: () => void }) {
-	return (
-		<Button
-			variant="ghost"
-			size="sm"
-			className="absolute top-4 right-4 z-10 text-amber-600 hover:bg-amber-500/10 hover:text-amber-700 dark:text-amber-400 dark:hover:text-amber-300"
-			onClick={(event) => {
-				event.stopPropagation();
-				onSend();
-			}}
-			onKeyDown={(event) => event.stopPropagation()}
-		>
-			<Lightbulb />
-			{label}
-		</Button>
-	);
-}
-
 function countFlashcardText(value: unknown): number {
 	if (Array.isArray(value)) {
 		return value.reduce((length, entry) => length + countFlashcardText(entry), 0);
diff --git a/src/features/workspaces/components/flashcards/flashcard-viewer.css b/src/features/workspaces/components/flashcards/flashcard-viewer.css
index 3174b99bf..1faed71e3 100644
--- a/src/features/workspaces/components/flashcards/flashcard-viewer.css
+++ b/src/features/workspaces/components/flashcards/flashcard-viewer.css
@@ -47,9 +47,11 @@
 	}
 
 	.workspace-flashcard-prose {
+		width: 100%;
 		max-width: 42rem;
+		margin-inline: auto;
 		font-size: clamp(1.4rem, 3vw, 2rem);
-		text-align: center;
+		text-align: left;
 	}
 
 	.workspace-flashcard-prose.is-dense {
@@ -60,12 +62,6 @@
 		font-size: clamp(0.95rem, 1.7vw, 1.2rem);
 	}
 
-	.workspace-flashcard-prose ul,
-	.workspace-flashcard-prose ol {
-		display: inline-block;
-		text-align: left;
-	}
-
 	@media (prefers-reduced-motion: reduce) {
 		.workspace-flashcard-face {
 			transition-duration: 1ms;
diff --git a/src/features/workspaces/components/quizzes/QuizViewer.tsx b/src/features/workspaces/components/quizzes/QuizViewer.tsx
new file mode 100644
index 000000000..3ac924e8b
--- /dev/null
+++ b/src/features/workspaces/components/quizzes/QuizViewer.tsx
@@ -0,0 +1,560 @@
+import { useQuery } from "@tanstack/react-query";
+import { Check, X } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+import { Button } from "#/components/ui/button";
+import { Skeleton } from "#/components/ui/skeleton";
+import { sendComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
+import { StudyProgressStrip } from "#/features/workspaces/components/study/StudyProgressStrip";
+import { StudyRichText } from "#/features/workspaces/components/study/StudyRichText";
+import {
+	StudyAiActionButton,
+	StudyNavButton,
+	useStudySessionFocus,
+} from "#/features/workspaces/components/study/StudySessionControls";
+import { StudyToolbar } from "#/features/workspaces/components/study/StudyToolbar";
+import { useWorkspaceItemToolbar } from "#/features/workspaces/components/WorkspaceItemToolbarSlot";
+import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
+import type { WorkspaceItem } from "#/features/workspaces/contracts";
+import { useWorkspaceRevealRequest } from "#/features/workspaces/locations/workspace-location-context";
+import type { QuizQuestion } from "#/features/workspaces/quizzes/quiz-content";
+import {
+	quizViewerQueryOptions,
+	useRecordQuizAnswer,
+	useResetQuizStudyProgress,
+} from "#/features/workspaces/quizzes/quiz-queries";
+import {
+	createQuizStudyQueue,
+	getQuizStudyViewState,
+	type QuizStudyMode,
+} from "#/features/workspaces/quizzes/quiz-study-session";
+import {
+	getQuizAnswer,
+	summarizeQuizStudyProgress,
+	type QuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
+import { useWorkspaceUiStore } from "#/features/workspaces/state/workspace-ui-store";
+import { cn } from "#/lib/utils";
+
+interface QuizSessionState {
+	questionIds: string[];
+	currentIndex: number;
+	mode: QuizStudyMode;
+	/** The option picked but not yet submitted for the current question. */
+	pendingOptionId: string | null;
+	shuffled: boolean;
+}
+
+export function QuizViewer({
+	itemPath,
+	item,
+	viewInstanceId,
+}: {
+	itemPath: string;
+	item: WorkspaceItem;
+	viewInstanceId: string;
+}) {
+	const { data, error, isPending } = useQuery(
+		quizViewerQueryOptions({
+			itemId: item.id,
+			updatedAt: item.updatedAt,
+			workspaceId: item.workspaceId,
+		}),
+	);
+
+	if (isPending) return <QuizViewerSkeleton />;
+	if (error || !data) {
+		return (
+			<div className="flex h-full items-center justify-center p-6 text-center text-muted-foreground">
+				Could not load this quiz.
+			</div>
+		);
+	}
+	return (
+		<QuizStudySession
+			key={`${item.id}:${item.updatedAt}`}
+			questions={data.questions}
+			itemPath={itemPath}
+			studyState={data.studyState}
+			item={item}
+			viewInstanceId={viewInstanceId}
+		/>
+	);
+}
+
+function QuizStudySession({
+	questions,
+	itemPath,
+	studyState,
+	item,
+	viewInstanceId,
+}: {
+	questions: QuizQuestion[];
+	itemPath: string;
+	studyState: QuizStudyState;
+	item: WorkspaceItem;
+	viewInstanceId: string;
+}) {
+	const [session, setSession] = useState<QuizSessionState>(() => ({
+		questionIds: createQuizStudyQueue({ questions, mode: "all", shuffled: false, studyState }),
+		currentIndex: 0,
+		mode: "all",
+		pendingOptionId: null,
+		shuffled: false,
+	}));
+	const { questionIds, currentIndex, mode, pendingOptionId, shuffled } = session;
+	const questionsById = useMemo(
+		() => new Map(questions.map((question) => [question.id, question])),
+		[questions],
+	);
+	const studyQuestions = useMemo(
+		() =>
+			questionIds.flatMap((questionId) => {
+				const question = questionsById.get(questionId);
+				return question ? [question] : [];
+			}),
+		[questionIds, questionsById],
+	);
+	const currentQuestion = studyQuestions[currentIndex];
+	const sourceQuestionNumber = currentQuestion
+		? questions.findIndex((question) => question.id === currentQuestion.id) + 1
+		: 0;
+	const answer = currentQuestion ? getQuizAnswer(currentQuestion, studyState) : undefined;
+	const sectionRef = useStudySessionFocus(currentQuestion?.id);
+	const quizProgress = useMemo(
+		() => summarizeQuizStudyProgress(questions, studyState),
+		[questions, studyState],
+	);
+	const clearItemViewState = useWorkspaceUiStore((state) => state.clearItemViewState);
+	const setItemViewState = useWorkspaceUiStore((state) => state.setItemViewState);
+	const { complete: completeRevealRequest, request: revealRequest } = useWorkspaceRevealRequest(
+		viewInstanceId,
+		"quiz-question",
+	);
+	const queryInput = {
+		itemId: item.id,
+		updatedAt: item.updatedAt,
+		workspaceId: item.workspaceId,
+	};
+	const recordAnswer = useRecordQuizAnswer(queryInput);
+	const { isPending: isResetting, mutate: resetProgress } = useResetQuizStudyProgress(queryInput);
+	const startSession = useCallback(
+		(nextMode: QuizStudyMode, nextShuffled: boolean) => {
+			setSession({
+				questionIds: createQuizStudyQueue({
+					questions,
+					mode: nextMode,
+					shuffled: nextShuffled,
+					studyState,
+				}),
+				currentIndex: 0,
+				mode: nextMode,
+				pendingOptionId: null,
+				shuffled: nextShuffled,
+			});
+		},
+		[questions, studyState],
+	);
+	const goTo = useCallback((index: number) => {
+		setSession((current) => ({
+			...current,
+			currentIndex: Math.min(Math.max(index, 0), current.questionIds.length - 1),
+			pendingOptionId: null,
+		}));
+	}, []);
+	const resetStudyProgress = useCallback(() => {
+		startSession("all", false);
+		resetProgress();
+	}, [resetProgress, startSession]);
+	const toolbar = useMemo(
+		() => (
+			<StudyToolbar
+				canReset={quizProgress.answeredCount > 0}
+				isResetting={isResetting}
+				labels={{
+					allLabel: "All questions",
+					mobileLabel: "Quiz options",
+					resetAriaLabel: "Reset quiz progress",
+					resetDescription:
+						"This clears every saved answer for this quiz. The questions themselves will not change.",
+					resetTitle: "Reset quiz progress?",
+				}}
+				missedCount={quizProgress.incorrectCount}
+				mode={mode}
+				shuffled={shuffled}
+				onModeChange={(nextMode) => startSession(nextMode, shuffled)}
+				onReset={resetStudyProgress}
+				onShuffleToggle={() => startSession(mode, !shuffled)}
+			/>
+		),
+		[isResetting, mode, quizProgress, resetStudyProgress, shuffled, startSession],
+	);
+	useWorkspaceItemToolbar(viewInstanceId, toolbar);
+	useEffect(() => {
+		if (!currentQuestion) return;
+		setItemViewState(item.workspaceId, viewInstanceId, {
+			itemId: item.id,
+			...getQuizStudyViewState({
+				answered: answer !== undefined,
+				...(answer ? { correct: answer.selectedOptionId === currentQuestion.correctOptionId } : {}),
+				mode,
+				progress: quizProgress,
+				sessionPosition: currentIndex + 1,
+				sessionTotal: studyQuestions.length,
+				shuffled,
+				sourceQuestionNumber,
+			}),
+		});
+	}, [
+		answer,
+		currentIndex,
+		currentQuestion,
+		item.id,
+		item.workspaceId,
+		mode,
+		quizProgress,
+		setItemViewState,
+		shuffled,
+		sourceQuestionNumber,
+		studyQuestions.length,
+		viewInstanceId,
+	]);
+	useEffect(
+		() => () => clearItemViewState(item.workspaceId, viewInstanceId),
+		[clearItemViewState, item.workspaceId, viewInstanceId],
+	);
+	useEffect(() => {
+		if (!revealRequest) return;
+		let nextQuestionIds = questionIds;
+		let questionIndex = nextQuestionIds.indexOf(revealRequest.location.questionId);
+		if (questionIndex < 0 && questionsById.has(revealRequest.location.questionId)) {
+			nextQuestionIds = createQuizStudyQueue({ questions, mode: "all", shuffled, studyState });
+			questionIndex = nextQuestionIds.indexOf(revealRequest.location.questionId);
+		}
+		let cancelled = false;
+		queueMicrotask(() => {
+			if (cancelled) return;
+			if (questionIndex >= 0) {
+				setSession((current) => ({
+					...current,
+					questionIds: nextQuestionIds,
+					currentIndex: questionIndex,
+					mode: nextQuestionIds === questionIds ? current.mode : "all",
+					pendingOptionId: null,
+				}));
+			}
+			completeRevealRequest(revealRequest, questionIndex >= 0);
+		});
+		return () => {
+			cancelled = true;
+		};
+	}, [
+		completeRevealRequest,
+		questionIds,
+		questions,
+		questionsById,
+		revealRequest,
+		shuffled,
+		studyState,
+	]);
+
+	if (questions.length === 0) {
+		return (
+			<div className="flex h-full items-center justify-center p-6 text-center">
+				<div className="space-y-1">
+					<h2 className="font-medium">No questions yet</h2>
+					<p className="text-sm text-muted-foreground">Ask AI to add questions to this quiz.</p>
+				</div>
+			</div>
+		);
+	}
+	if (studyQuestions.length === 0) {
+		return (
+			<div className="flex h-full items-center justify-center p-6 text-center">
+				<div className="space-y-3">
+					<div className="space-y-1">
+						<h2 className="font-medium">No missed questions</h2>
+						<p className="text-sm text-muted-foreground">Nothing needs another try right now.</p>
+					</div>
+					<Button variant="outline" onClick={() => startSession("all", shuffled)}>
+						Take the whole quiz
+					</Button>
+				</div>
+			</div>
+		);
+	}
+	if (!currentQuestion) return null;
+
+	const graded = answer !== undefined;
+	const isCorrect = answer?.selectedOptionId === currentQuestion.correctOptionId;
+	const selectedOptionId = graded ? answer.selectedOptionId : pendingOptionId;
+	const isLastQuestion = currentIndex >= studyQuestions.length - 1;
+	// Khan-style: the pending pick, and the correct option once graded, get an
+	// outline. Wrong picks keep only the filled X — no row chrome — so they
+	// stay in the hairline list.
+	const outlinedOptionIds = new Set(
+		[!graded ? selectedOptionId : null, graded ? currentQuestion.correctOptionId : null].filter(
+			Boolean,
+		),
+	);
+	const lastOption = currentQuestion.options.at(-1);
+
+	return (
+		<section
+			ref={sectionRef}
+			className="flex h-full min-h-0 flex-col bg-background px-4 py-5 sm:px-8 sm:py-7"
+			aria-label={`${item.name} quiz session`}
+			tabIndex={0}
+			onKeyDown={(event) => {
+				if ((event.target as HTMLElement).closest("input, textarea, select")) return;
+				if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+					event.preventDefault();
+					goTo(currentIndex + (event.key === "ArrowLeft" ? -1 : 1));
+				}
+			}}
+		>
+			<div className="mx-auto flex min-h-0 w-full max-w-4xl flex-1 flex-col gap-4">
+				{/* Keyed by question so a scrolled-down long question does not leave the
+				    next one scrolled past its stem. pt-1 leaves the Hint button's focus
+				    ring room inside the scroller, which clips both axes once
+				    overflow-y is set. */}
+				<div key={currentQuestion.id} className="min-h-0 flex-1 overflow-y-auto pt-1">
+					<div className="flex items-start justify-between gap-3 pb-5">
+						<QuizRichText content={currentQuestion.question} />
+						{/* The slot keeps its height once grading removes the Hint, so the
+						    options below do not jump up. */}
+						<div className="flex h-8 shrink-0 items-center">
+							{!graded ? (
+								<StudyAiActionButton
+									label="Hint"
+									onSend={() =>
+										sendComposerPrompt(
+											item.workspaceId,
+											`Give me a helpful hint for question ${sourceQuestionNumber} in “${itemPath}” without revealing the answer.`,
+										)
+									}
+								/>
+							) : null}
+						</div>
+					</div>
+
+					<div role="radiogroup" aria-label="Answer options">
+						{currentQuestion.options.map((option, optionIndex) => {
+							const isSelected = option.id === selectedOptionId;
+							const isCorrectOption = option.id === currentQuestion.correctOptionId;
+							const previousOption = currentQuestion.options[optionIndex - 1];
+							return (
+								<div key={option.id}>
+									<QuizOptionRule
+										visible={
+											!outlinedOptionIds.has(option.id) &&
+											!(previousOption && outlinedOptionIds.has(previousOption.id))
+										}
+									/>
+									<button
+										type="button"
+										role="radio"
+										aria-checked={isSelected}
+										disabled={graded || recordAnswer.isPending}
+										className={cn(
+											"flex w-full items-center gap-3 rounded-xl border border-transparent px-3 py-4 text-left transition-colors",
+											!graded && "cursor-pointer hover:bg-accent/40",
+											!graded && isSelected && "border-primary/60 bg-primary/5",
+											graded && isCorrectOption && "border-emerald-500/60 bg-emerald-500/10",
+											graded && !isSelected && !isCorrectOption && "opacity-60",
+										)}
+										onClick={() =>
+											setSession((current) => ({ ...current, pendingOptionId: option.id }))
+										}
+									>
+										<span
+											className={cn(
+												"flex size-6 shrink-0 items-center justify-center rounded-full border text-xs font-semibold text-muted-foreground",
+												!graded &&
+													isSelected &&
+													"border-primary bg-primary text-primary-foreground",
+												graded &&
+													isCorrectOption &&
+													"border-emerald-600 bg-emerald-600 text-white dark:border-emerald-500 dark:bg-emerald-500",
+												graded &&
+													isSelected &&
+													!isCorrectOption &&
+													"border-red-600 bg-red-600 text-white dark:border-red-500 dark:bg-red-500",
+											)}
+										>
+											{graded && isCorrectOption ? (
+												<Check className="size-3.5" />
+											) : graded && isSelected ? (
+												<X className="size-3.5" />
+											) : (
+												String.fromCharCode(65 + optionIndex)
+											)}
+										</span>
+										<QuizRichText content={option.text} compact />
+									</button>
+								</div>
+							);
+						})}
+						<QuizOptionRule visible={!lastOption || !outlinedOptionIds.has(lastOption.id)} />
+					</div>
+
+					{graded ? (
+						<div
+							className={cn(
+								"mt-4 mb-3 rounded-xl border p-4",
+								isCorrect
+									? "border-emerald-500/40 bg-emerald-500/5"
+									: "border-red-500/40 bg-red-500/5",
+							)}
+						>
+							<div className="mb-1 flex items-center justify-between gap-2">
+								<span
+									className={cn(
+										"text-sm font-medium",
+										isCorrect
+											? "text-emerald-700 dark:text-emerald-400"
+											: "text-red-700 dark:text-red-400",
+									)}
+								>
+									{isCorrect ? "Correct" : "Incorrect"}
+								</span>
+								<StudyAiActionButton
+									label="Explain more"
+									onSend={() =>
+										sendComposerPrompt(
+											item.workspaceId,
+											`Explain the answer to question ${sourceQuestionNumber} in “${itemPath}” in more depth.`,
+										)
+									}
+								/>
+							</div>
+							<QuizRichText content={currentQuestion.explanation} compact />
+						</div>
+					) : null}
+				</div>
+
+				<div className="space-y-3">
+					<StudyProgressStrip
+						ariaLabel={`${quizProgress.correctCount} correct, ${quizProgress.incorrectCount} missed, ${quizProgress.unansweredCount} unanswered`}
+						currentIndex={currentIndex}
+						onSelect={goTo}
+						segments={studyQuestions.map((question, index) => {
+							const questionAnswer = getQuizAnswer(question, studyState);
+							const questionCorrect = questionAnswer?.selectedOptionId === question.correctOptionId;
+							return {
+								id: question.id,
+								label: `Question ${index + 1}: ${
+									!questionAnswer ? "Unanswered" : questionCorrect ? "Correct" : "Missed"
+								}`,
+								tone: !questionAnswer ? "unseen" : questionCorrect ? "correct" : "missed",
+							};
+						})}
+					/>
+					<div className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-2">
+						<span className="justify-self-start text-xs text-muted-foreground tabular-nums sm:text-sm">
+							{quizProgress.answeredCount} answered
+						</span>
+						<div className="col-start-2 flex items-center justify-center gap-1 sm:gap-2">
+							<StudyNavButton
+								direction="previous"
+								noun="question"
+								disabled={currentIndex === 0}
+								onClick={() => goTo(currentIndex - 1)}
+							/>
+							<span className="text-sm text-muted-foreground tabular-nums">
+								{currentIndex + 1} of {studyQuestions.length}
+							</span>
+							<StudyNavButton
+								direction="next"
+								noun="question"
+								disabled={isLastQuestion}
+								onClick={() => goTo(currentIndex + 1)}
+							/>
+						</div>
+						{graded ? (
+							<Button
+								variant="outline"
+								className="col-start-3 h-11 justify-self-end rounded-xl px-5 text-sm font-medium sm:h-12 sm:px-6 sm:text-base"
+								disabled={isLastQuestion}
+								onClick={() => goTo(currentIndex + 1)}
+							>
+								Next question
+							</Button>
+						) : (
+							<Button
+								className="col-start-3 h-11 justify-self-end rounded-xl px-5 text-sm font-medium sm:h-12 sm:px-6 sm:text-base"
+								disabled={!pendingOptionId || recordAnswer.isPending}
+								onClick={() => {
+									if (!pendingOptionId) return;
+									recordAnswer.mutate({
+										questionId: currentQuestion.id,
+										selectedOptionId: pendingOptionId,
+									});
+								}}
+							>
+								Submit
+							</Button>
+						)}
+					</div>
+				</div>
+			</div>
+		</section>
+	);
+}
+
+function QuizRichText({ content, compact }: { content: TiptapDocumentJson; compact?: boolean }) {
+	return (
+		<StudyRichText
+			className="min-w-0 flex-1"
+			content={content}
+			proseClassName={cn("is-flush", compact && "text-sm")}
+		/>
+	);
+}
+
+/**
+ * Hairline between answer rows. Always in the flow and hidden by colour rather
+ * than by unmounting, so rows never shift as the outline moves between them.
+ */
+function QuizOptionRule({ visible }: { visible: boolean }) {
+	return <div className={cn("border-t", !visible && "border-transparent")} />;
+}
+
+function QuizViewerSkeleton() {
+	return (
+		<div className="flex h-full min-h-0 flex-col px-4 py-5 sm:px-8 sm:py-7">
+			<div className="mx-auto flex min-h-0 w-full max-w-4xl flex-1 flex-col gap-4">
+				<div className="min-h-0 flex-1 pt-1">
+					<div className="flex items-start justify-between gap-3 pb-5">
+						<Skeleton className="h-6 w-2/3" />
+						<Skeleton className="h-8 w-16 rounded-lg" />
+					</div>
+					{/* Widths vary so the rows read as answers rather than a block. */}
+					{["w-3/5", "w-2/5", "w-1/2", "w-4/6"].map((width) => (
+						<div key={width} className="border-t">
+							<div className="flex items-center gap-3 px-3 py-4">
+								<Skeleton className="size-6 shrink-0 rounded-full" />
+								<Skeleton className={cn("h-4", width)} />
+							</div>
+						</div>
+					))}
+					<div className="border-t" />
+				</div>
+				<div className="space-y-3">
+					<div className="flex h-4 items-center">
+						<Skeleton className="h-1.5 w-full rounded-full" />
+					</div>
+					<div className="grid min-h-10 grid-cols-[minmax(0,1fr)_auto_minmax(0,1fr)] items-center gap-2">
+						<Skeleton className="h-4 w-24 justify-self-start" />
+						<div className="col-start-2 flex items-center justify-center gap-1 sm:gap-2">
+							<Skeleton className="size-11 rounded-xl sm:size-12" />
+							<Skeleton className="h-4 w-14" />
+							<Skeleton className="size-11 rounded-xl sm:size-12" />
+						</div>
+						<Skeleton className="col-start-3 h-11 w-24 justify-self-end rounded-xl sm:h-12" />
+					</div>
+				</div>
+			</div>
+		</div>
+	);
+}
diff --git a/src/features/workspaces/components/flashcards/CreateFlashcardsDialog.tsx b/src/features/workspaces/components/study/CreateStudyItemDialog.tsx
similarity index 63%
rename from src/features/workspaces/components/flashcards/CreateFlashcardsDialog.tsx
rename to src/features/workspaces/components/study/CreateStudyItemDialog.tsx
index 37d7db68e..549d21a92 100644
--- a/src/features/workspaces/components/flashcards/CreateFlashcardsDialog.tsx
+++ b/src/features/workspaces/components/study/CreateStudyItemDialog.tsx
@@ -1,4 +1,4 @@
-import { Layers3 } from "lucide-react";
+import { Layers3, ListChecks } from "lucide-react";
 import { useId } from "react";
 
 import { Button } from "#/components/ui/button";
@@ -15,12 +15,36 @@ import { NativeSelect, NativeSelectOption } from "#/components/ui/native-select"
 import { Textarea } from "#/components/ui/textarea";
 import { sendComposerPrompt } from "#/features/workspaces/composer/workspace-composer-actions";
 
-export function CreateFlashcardsDialog({
+export type StudyItemDialogType = "flashcard" | "quiz";
+
+const studyItemDialogConfigs = {
+	flashcard: {
+		Icon: Layers3,
+		iconClassName: "text-violet-500",
+		title: "Create flashcards",
+		countLabel: "Number of cards",
+		prompt: (count: number, locationPhrase: string, topic: string) =>
+			`Create a flashcard set with exactly ${count} cards ${locationPhrase}. Cover: ${topic}`,
+	},
+	quiz: {
+		Icon: ListChecks,
+		iconClassName: "text-emerald-500",
+		title: "Create a quiz",
+		countLabel: "Number of questions",
+		prompt: (count: number, locationPhrase: string, topic: string) =>
+			`Create a quiz with exactly ${count} multiple-choice questions ${locationPhrase}. Cover: ${topic}`,
+	},
+} as const satisfies Record<StudyItemDialogType, unknown>;
+
+/** Collects a topic and size, then hands the AI composer the create request. */
+export function CreateStudyItemDialog({
+	type,
 	open,
 	parentPath,
 	workspaceId,
 	onOpenChange,
 }: {
+	type: StudyItemDialogType;
 	open: boolean;
 	parentPath: string;
 	workspaceId: string;
@@ -28,6 +52,7 @@ export function CreateFlashcardsDialog({
 }) {
 	const topicId = useId();
 	const countId = useId();
+	const config = studyItemDialogConfigs[type];
 
 	return (
 		<Dialog open={open} onOpenChange={onOpenChange}>
@@ -43,7 +68,7 @@ export function CreateFlashcardsDialog({
 							if (
 								!sendComposerPrompt(
 									workspaceId,
-									`Create a flashcard set with exactly ${count} cards ${describeFlashcardLocation(parentPath)}. Cover: ${topic}`,
+									config.prompt(count, describeStudyItemLocation(parentPath), topic),
 								)
 							)
 								return;
@@ -52,14 +77,14 @@ export function CreateFlashcardsDialog({
 					>
 						<DialogHeader>
 							<DialogTitle className="flex items-center gap-2">
-								<Layers3 className="size-5 text-violet-500" aria-hidden="true" />
-								Create flashcards
+								<config.Icon className={`size-5 ${config.iconClassName}`} aria-hidden="true" />
+								{config.title}
 							</DialogTitle>
-							<DialogDescription>AI will create the set in your current chat.</DialogDescription>
+							<DialogDescription>AI will create it in your current chat.</DialogDescription>
 						</DialogHeader>
 						<FieldGroup>
 							<Field>
-								<FieldLabel htmlFor={topicId}>What should the cards cover?</FieldLabel>
+								<FieldLabel htmlFor={topicId}>What should it cover?</FieldLabel>
 								<Textarea
 									id={topicId}
 									name="topic"
@@ -70,7 +95,7 @@ export function CreateFlashcardsDialog({
 								/>
 							</Field>
 							<Field orientation="horizontal" className="items-center justify-between">
-								<FieldLabel htmlFor={countId}>Number of cards</FieldLabel>
+								<FieldLabel htmlFor={countId}>{config.countLabel}</FieldLabel>
 								<NativeSelect id={countId} name="count" defaultValue="10" size="sm">
 									<NativeSelectOption value="5">5</NativeSelectOption>
 									<NativeSelectOption value="10">10</NativeSelectOption>
@@ -92,7 +117,7 @@ export function CreateFlashcardsDialog({
 	);
 }
 
-function describeFlashcardLocation(parentPath: string) {
+function describeStudyItemLocation(parentPath: string) {
 	if (parentPath === "/") return "in this workspace";
 	return `in the “${parentPath.slice(1).replaceAll("/", " › ")}” folder`;
 }
diff --git a/src/features/workspaces/components/study/StudyProgressStrip.tsx b/src/features/workspaces/components/study/StudyProgressStrip.tsx
new file mode 100644
index 000000000..28b1b52e3
--- /dev/null
+++ b/src/features/workspaces/components/study/StudyProgressStrip.tsx
@@ -0,0 +1,68 @@
+import { cn } from "#/lib/utils";
+
+/** Outcome colour for one segment. Each study type maps its own state onto these. */
+export type StudyProgressTone = "correct" | "hard" | "missed" | "unseen";
+
+export interface StudyProgressSegment {
+	id: string;
+	/** Announced for the segment's button, e.g. "Card 3: Got it". */
+	label: string;
+	tone: StudyProgressTone;
+}
+
+/**
+ * One tick per item in the current session, coloured by outcome and clickable
+ * to jump. Shared by every study viewer so progress reads the same whichever
+ * item type you are working through.
+ */
+export function StudyProgressStrip({
+	ariaLabel,
+	currentIndex,
+	onSelect,
+	segments,
+}: {
+	ariaLabel: string;
+	currentIndex: number;
+	onSelect: (index: number) => void;
+	segments: StudyProgressSegment[];
+}) {
+	const gap =
+		segments.length <= 50 ? 3 : segments.length <= 120 ? 2 : segments.length <= 300 ? 1 : 0;
+
+	return (
+		<div
+			role="group"
+			aria-label={ariaLabel}
+			className="mx-auto grid h-4 w-full items-center"
+			style={{
+				columnGap: gap,
+				gridTemplateColumns: `repeat(${segments.length}, minmax(0, 1fr))`,
+				maxWidth: `${segments.length * 64}px`,
+			}}
+		>
+			{segments.map((segment, index) => (
+				<button
+					key={segment.id}
+					type="button"
+					aria-current={index === currentIndex ? "step" : undefined}
+					aria-label={segment.label}
+					tabIndex={index === currentIndex ? 0 : -1}
+					onClick={() => onSelect(index)}
+					className="group flex h-4 min-w-0 cursor-pointer items-center focus-visible:outline-none"
+				>
+					<span
+						aria-hidden="true"
+						className={cn(
+							"h-1.5 w-full min-w-0 rounded-full bg-border transition-[height,background-color,box-shadow,filter] duration-150 group-hover:h-2.5 group-hover:brightness-125",
+							segment.tone === "missed" && "bg-red-500/75",
+							segment.tone === "hard" && "bg-amber-500/75",
+							segment.tone === "correct" && "bg-emerald-500/75",
+							index === currentIndex &&
+								"h-2.5 ring-1 ring-foreground/70 ring-offset-1 ring-offset-background",
+						)}
+					/>
+				</button>
+			))}
+		</div>
+	);
+}
diff --git a/src/features/workspaces/components/study/StudyRichText.tsx b/src/features/workspaces/components/study/StudyRichText.tsx
new file mode 100644
index 000000000..fee7b091f
--- /dev/null
+++ b/src/features/workspaces/components/study/StudyRichText.tsx
@@ -0,0 +1,36 @@
+import type { JSONContent } from "@tiptap/core";
+import { EditorContent, useEditor } from "@tiptap/react";
+
+import { getTiptapDocumentBaseExtensions } from "#/features/workspaces/documents/tiptap-extensions";
+import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
+import { cn } from "#/lib/utils";
+
+/**
+ * Read-only rendering of a study item's rich text — a card face, a quiz stem,
+ * an answer option. `className` styles the wrapper for layout, `proseClassName`
+ * the text itself (measure, size, alignment).
+ */
+export function StudyRichText({
+	className,
+	content,
+	proseClassName,
+}: {
+	className?: string;
+	content: TiptapDocumentJson;
+	proseClassName?: string;
+}) {
+	const editor = useEditor(
+		{
+			content: content as unknown as JSONContent,
+			editable: false,
+			immediatelyRender: false,
+			extensions: getTiptapDocumentBaseExtensions(),
+			editorProps: {
+				attributes: { class: cn("workspace-document-prose outline-none", proseClassName) },
+			},
+		},
+		[content],
+	);
+
+	return <EditorContent editor={editor} className={className} />;
+}
diff --git a/src/features/workspaces/components/study/StudySessionControls.tsx b/src/features/workspaces/components/study/StudySessionControls.tsx
new file mode 100644
index 000000000..387899fba
--- /dev/null
+++ b/src/features/workspaces/components/study/StudySessionControls.tsx
@@ -0,0 +1,85 @@
+import { ChevronLeft, ChevronRight, Lightbulb } from "lucide-react";
+import { useEffect, useRef } from "react";
+
+import { Button } from "#/components/ui/button";
+import { cn } from "#/lib/utils";
+
+/**
+ * Keeps the session's arrow keys alive across navigation. Both viewers key the
+ * current entry's subtree so it remounts on navigation, and a remount that held
+ * the focused element drops focus to <body> — out of reach of the section's
+ * keydown handler. Attach the returned ref to the section; when an entry change
+ * strands focus on <body>, the section takes it back.
+ */
+export function useStudySessionFocus(entryKey: string | undefined) {
+	const sectionRef = useRef<HTMLElement>(null);
+	const previousKey = useRef(entryKey);
+	useEffect(() => {
+		if (previousKey.current === entryKey) return;
+		previousKey.current = entryKey;
+		if (document.activeElement === document.body) sectionRef.current?.focus();
+	}, [entryKey]);
+	return sectionRef;
+}
+
+/**
+ * Asks the AI for help with the item on screen — a hint before answering, a
+ * fuller explanation after. Amber everywhere so "ask AI" reads the same in
+ * every study viewer.
+ */
+export function StudyAiActionButton({
+	className,
+	label,
+	onSend,
+}: {
+	className?: string;
+	label: string;
+	onSend: () => void;
+}) {
+	return (
+		<Button
+			variant="ghost"
+			size="sm"
+			className={cn(
+				"text-amber-600 hover:bg-amber-500/10 hover:text-amber-700 dark:text-amber-400 dark:hover:text-amber-300",
+				className,
+			)}
+			onClick={(event) => {
+				event.stopPropagation();
+				onSend();
+			}}
+			onKeyDown={(event) => event.stopPropagation()}
+		>
+			<Lightbulb />
+			{label}
+		</Button>
+	);
+}
+
+/** Previous/next step in a study session. `noun` names the step: "card", "question". */
+export function StudyNavButton({
+	direction,
+	disabled,
+	noun,
+	onClick,
+}: {
+	direction: "next" | "previous";
+	disabled: boolean;
+	noun: string;
+	onClick: () => void;
+}) {
+	const label = `${direction === "next" ? "Next" : "Previous"} ${noun}`;
+	return (
+		<Button
+			variant="ghost"
+			size="icon-lg"
+			aria-label={label}
+			title={`${label} (${direction === "next" ? "Right" : "Left"} arrow)`}
+			className="size-11 rounded-xl [&_svg]:size-4.5 sm:size-12 sm:[&_svg]:size-5"
+			disabled={disabled}
+			onClick={onClick}
+		>
+			{direction === "next" ? <ChevronRight /> : <ChevronLeft />}
+		</Button>
+	);
+}
diff --git a/src/features/workspaces/components/flashcards/FlashcardToolbar.tsx b/src/features/workspaces/components/study/StudyToolbar.tsx
similarity index 51%
rename from src/features/workspaces/components/flashcards/FlashcardToolbar.tsx
rename to src/features/workspaces/components/study/StudyToolbar.tsx
index 25bb33b44..a580bb16f 100644
--- a/src/features/workspaces/components/flashcards/FlashcardToolbar.tsx
+++ b/src/features/workspaces/components/study/StudyToolbar.tsx
@@ -27,12 +27,23 @@ import {
 	WorkspaceToolbarIconButton,
 	WorkspaceToolbarTextButton,
 } from "#/features/workspaces/components/WorkspaceToolbar";
-import type { FlashcardStudyMode } from "#/features/workspaces/flashcards/flashcard-study-session";
 import { cn } from "#/lib/utils";
 
-export function FlashcardToolbar({
+export type StudyMode = "all" | "missed";
+
+/** The per-type copy on an otherwise identical study toolbar. */
+export interface StudyToolbarLabels {
+	allLabel: string;
+	mobileLabel: string;
+	resetAriaLabel: string;
+	resetDescription: string;
+	resetTitle: string;
+}
+
+export function StudyToolbar({
 	canReset,
 	isResetting,
+	labels,
 	missedCount,
 	mode,
 	shuffled,
@@ -42,10 +53,11 @@ export function FlashcardToolbar({
 }: {
 	canReset: boolean;
 	isResetting: boolean;
+	labels: StudyToolbarLabels;
 	missedCount: number;
-	mode: FlashcardStudyMode;
+	mode: StudyMode;
 	shuffled: boolean;
-	onModeChange: (mode: FlashcardStudyMode) => void;
+	onModeChange: (mode: StudyMode) => void;
 	onReset: () => void;
 	onShuffleToggle: () => void;
 }) {
@@ -53,22 +65,50 @@ export function FlashcardToolbar({
 	return (
 		<>
 			<WorkspaceResponsiveToolbar
-				mobileLabel="Flashcard study options"
+				mobileLabel={labels.mobileLabel}
 				scrollable
 				mobileContent={
-					<FlashcardActionsMenuContent
-						canReset={canReset}
-						isResetting={isResetting}
-						missedCount={missedCount}
-						mode={mode}
-						shuffled={shuffled}
-						onModeChange={onModeChange}
-						onReset={() => setIsConfirmingReset(true)}
-						onShuffleToggle={onShuffleToggle}
-					/>
+					<>
+						<StudyModeItems
+							allLabel={labels.allLabel}
+							missedCount={missedCount}
+							mode={mode}
+							onModeChange={onModeChange}
+						/>
+						<DropdownMenuSeparator />
+						<DropdownMenuGroup>
+							<DropdownMenuItem onClick={onShuffleToggle}>
+								<Shuffle />
+								Shuffle
+								{shuffled ? (
+									<span className="ml-auto text-xs text-muted-foreground">On</span>
+								) : null}
+							</DropdownMenuItem>
+							<DropdownMenuItem
+								disabled={!canReset || isResetting}
+								onClick={() => setIsConfirmingReset(true)}
+							>
+								{isResetting ? <LoaderCircle className="animate-spin" /> : <RotateCcw />}
+								Reset progress…
+							</DropdownMenuItem>
+						</DropdownMenuGroup>
+					</>
 				}
 			>
-				<FlashcardModeMenu missedCount={missedCount} mode={mode} onModeChange={onModeChange} />
+				<DropdownMenu>
+					<DropdownMenuTrigger render={<WorkspaceToolbarTextButton />}>
+						{mode === "all" ? <List /> : <XCircle />}
+						{mode === "all" ? labels.allLabel : "Missed"}
+					</DropdownMenuTrigger>
+					<DropdownMenuContent className="w-48" align="end">
+						<StudyModeItems
+							allLabel={labels.allLabel}
+							missedCount={missedCount}
+							mode={mode}
+							onModeChange={onModeChange}
+						/>
+					</DropdownMenuContent>
+				</DropdownMenu>
 				<WorkspaceToolbarTextButton
 					aria-pressed={shuffled}
 					className={cn(shuffled && "bg-accent text-foreground")}
@@ -78,7 +118,7 @@ export function FlashcardToolbar({
 					Shuffle
 				</WorkspaceToolbarTextButton>
 				<WorkspaceToolbarIconButton
-					aria-label="Reset flashcard progress"
+					aria-label={labels.resetAriaLabel}
 					title="Reset progress"
 					disabled={!canReset || isResetting}
 					onClick={() => setIsConfirmingReset(true)}
@@ -89,10 +129,8 @@ export function FlashcardToolbar({
 			<AlertDialog open={isConfirmingReset} onOpenChange={setIsConfirmingReset}>
 				<AlertDialogContent>
 					<AlertDialogHeader>
-						<AlertDialogTitle>Reset flashcard progress?</AlertDialogTitle>
-						<AlertDialogDescription>
-							This clears every saved response for this set. The cards themselves will not change.
-						</AlertDialogDescription>
+						<AlertDialogTitle>{labels.resetTitle}</AlertDialogTitle>
+						<AlertDialogDescription>{labels.resetDescription}</AlertDialogDescription>
 					</AlertDialogHeader>
 					<AlertDialogFooter>
 						<AlertDialogCancel disabled={isResetting}>Keep progress</AlertDialogCancel>
@@ -113,74 +151,16 @@ export function FlashcardToolbar({
 	);
 }
 
-function FlashcardModeMenu({
-	missedCount,
-	mode,
-	onModeChange,
-}: {
-	missedCount: number;
-	mode: FlashcardStudyMode;
-	onModeChange: (mode: FlashcardStudyMode) => void;
-}) {
-	return (
-		<DropdownMenu>
-			<DropdownMenuTrigger render={<WorkspaceToolbarTextButton />}>
-				{mode === "all" ? <List /> : <XCircle />}
-				{mode === "all" ? "All cards" : "Missed"}
-			</DropdownMenuTrigger>
-			<DropdownMenuContent className="w-48" align="end">
-				<FlashcardModeItems missedCount={missedCount} mode={mode} onModeChange={onModeChange} />
-			</DropdownMenuContent>
-		</DropdownMenu>
-	);
-}
-
-function FlashcardActionsMenuContent({
-	canReset,
-	isResetting,
-	missedCount,
-	mode,
-	shuffled,
-	onModeChange,
-	onReset,
-	onShuffleToggle,
-}: {
-	canReset: boolean;
-	isResetting: boolean;
-	missedCount: number;
-	mode: FlashcardStudyMode;
-	shuffled: boolean;
-	onModeChange: (mode: FlashcardStudyMode) => void;
-	onReset: () => void;
-	onShuffleToggle: () => void;
-}) {
-	return (
-		<>
-			<FlashcardModeItems missedCount={missedCount} mode={mode} onModeChange={onModeChange} />
-			<DropdownMenuSeparator />
-			<DropdownMenuGroup>
-				<DropdownMenuItem onClick={onShuffleToggle}>
-					<Shuffle />
-					Shuffle
-					{shuffled ? <span className="ml-auto text-xs text-muted-foreground">On</span> : null}
-				</DropdownMenuItem>
-				<DropdownMenuItem disabled={!canReset || isResetting} onClick={onReset}>
-					{isResetting ? <LoaderCircle className="animate-spin" /> : <RotateCcw />}
-					Reset progress…
-				</DropdownMenuItem>
-			</DropdownMenuGroup>
-		</>
-	);
-}
-
-function FlashcardModeItems({
+function StudyModeItems({
+	allLabel,
 	missedCount,
 	mode,
 	onModeChange,
 }: {
+	allLabel: string;
 	missedCount: number;
-	mode: FlashcardStudyMode;
-	onModeChange: (mode: FlashcardStudyMode) => void;
+	mode: StudyMode;
+	onModeChange: (mode: StudyMode) => void;
 }) {
 	return (
 		<DropdownMenuGroup>
@@ -192,7 +172,7 @@ function FlashcardModeItems({
 			>
 				<DropdownMenuRadioItem value="all">
 					<List />
-					All cards
+					{allLabel}
 				</DropdownMenuRadioItem>
 				<DropdownMenuRadioItem value="missed" disabled={missedCount === 0}>
 					<XCircle />
diff --git a/src/features/workspaces/components/workspace-presentation-model.ts b/src/features/workspaces/components/workspace-presentation-model.ts
index 10d81fe9b..2ca7dc513 100644
--- a/src/features/workspaces/components/workspace-presentation-model.ts
+++ b/src/features/workspaces/components/workspace-presentation-model.ts
@@ -11,7 +11,7 @@ export interface WorkspacePresentationProps {
 }
 
 export interface WorkspaceCreateItemRequest {
-	type: "document" | "flashcard" | "folder";
+	type: "document" | "flashcard" | "folder" | "quiz";
 	parentId: string | null;
 }
 
diff --git a/src/features/workspaces/content/entry-rich-text.ts b/src/features/workspaces/content/entry-rich-text.ts
new file mode 100644
index 000000000..4393961fa
--- /dev/null
+++ b/src/features/workspaces/content/entry-rich-text.ts
@@ -0,0 +1,81 @@
+import { z } from "zod";
+
+import { parseDocumentAiHtml } from "#/features/workspaces/documents/document-ai-html";
+import {
+	coerceTiptapDocumentProjection,
+	type TiptapDocumentJson,
+} from "#/features/workspaces/documents/tiptap-document";
+import { isRecord } from "#/lib/record";
+
+/**
+ * Rich text for entries inside structured items: flashcard sides and quiz
+ * stems, options, and explanations. Deliberately smaller than a document —
+ * no headings, tables, images, widgets, task lists, or citations.
+ */
+export const entryRichTextHtmlSchema = z.string().trim().min(1).max(8_000);
+
+const allowedNodeTypes = new Set([
+	"doc",
+	"paragraph",
+	"text",
+	"bulletList",
+	"orderedList",
+	"listItem",
+	"codeBlock",
+	"hardBreak",
+	"inlineMath",
+	"blockMath",
+]);
+
+const allowedMarkTypes = new Set(["bold", "italic", "strike", "code", "link", "underline"]);
+
+/**
+ * Parses one HTML fragment the model authored for an entry. `itemLabel` names
+ * the item type in errors — "Flashcard", "Quiz".
+ *
+ * The allowlist is not cosmetic: study viewers render with the full document
+ * schema, so an unchecked widget or table really would embed itself inside a
+ * card face or an answer row. Rejecting costs the model one retry, which is
+ * cheaper than the alternatives — silently dropping the node loses content the
+ * model believed it wrote, and coercing it needs a rule per node type.
+ */
+export function parseEntryRichTextHtml(html: string, itemLabel: string): TiptapDocumentJson {
+	const document = parseDocumentAiHtml(html);
+	visitRichTextValue(document, itemLabel);
+	return document;
+}
+
+/**
+ * Reads back content this module wrote earlier. Structure still has to hold,
+ * but the allowlist is deliberately not re-applied: it guards what the model
+ * may author, and re-running it on storage would let one odd entry — written
+ * by an older build, or by a later one that allows more — make the whole item
+ * unopenable.
+ */
+export function parseStoredEntryRichText(value: unknown, itemLabel: string): TiptapDocumentJson {
+	const projection = coerceTiptapDocumentProjection(value);
+	if (projection.warnings.length > 0) {
+		throw new Error(`${itemLabel} content contains invalid rich text.`);
+	}
+	return projection.document;
+}
+
+function visitRichTextValue(value: unknown, itemLabel: string) {
+	if (Array.isArray(value)) {
+		for (const entry of value) visitRichTextValue(entry, itemLabel);
+		return;
+	}
+	if (!isRecord(value)) return;
+
+	if (typeof value.type === "string" && !allowedNodeTypes.has(value.type)) {
+		throw new Error(`${itemLabel} content cannot contain ${value.type} nodes.`);
+	}
+	if (Array.isArray(value.marks)) {
+		for (const mark of value.marks) {
+			if (!isRecord(mark) || typeof mark.type !== "string" || !allowedMarkTypes.has(mark.type)) {
+				throw new Error(`${itemLabel} content contains an unsupported text mark.`);
+			}
+		}
+	}
+	if ("content" in value) visitRichTextValue(value.content, itemLabel);
+}
diff --git a/src/features/workspaces/content/ordered-entry-edits.ts b/src/features/workspaces/content/ordered-entry-edits.ts
new file mode 100644
index 000000000..6d27d6ae2
--- /dev/null
+++ b/src/features/workspaces/content/ordered-entry-edits.ts
@@ -0,0 +1,131 @@
+import type { ReplaceUniqueTextFailureCode } from "#/features/workspaces/content/replace-unique-text";
+
+/**
+ * The shared edit engine for structured items that are ordered lists of
+ * entries — flashcard sets (cards) and quizzes (questions). It owns ref
+ * resolution, revision staleness, ordering mechanics, and per-edit failure
+ * collection; the item type supplies how one entry is built or revised.
+ */
+
+export type OrderedEntryEditOp =
+	| "insert_before"
+	| "insert_after"
+	| "update"
+	| "replace"
+	| "replace_text"
+	| "move"
+	| "delete";
+
+export interface OrderedEntryEditShape {
+	op: OrderedEntryEditOp;
+	ref: string;
+	beforeRef?: string;
+	afterRef?: string;
+}
+
+export interface OrderedEntryEditTarget {
+	entryId: string;
+	revision: string;
+}
+
+export type OrderedEntryEditFailureCode =
+	| "cannot_delete_last_entry"
+	| "ref_not_found"
+	| "ref_stale"
+	| "invalid_entry_content"
+	| "no_change"
+	| ReplaceUniqueTextFailureCode;
+
+export interface OrderedEntryEditFailure {
+	code: OrderedEntryEditFailureCode;
+	detail?: string;
+	index: number;
+}
+
+export class OrderedEntryEditError extends Error {
+	constructor(
+		readonly code: Exclude<OrderedEntryEditFailureCode, "invalid_entry_content">,
+		message?: string,
+	) {
+		super(message);
+	}
+}
+
+export async function applyOrderedEntryEdits<
+	TEntry extends { id: string },
+	TEdit extends OrderedEntryEditShape,
+>(input: {
+	entries: readonly TEntry[];
+	edits: readonly TEdit[];
+	targets: ReadonlyMap<string, OrderedEntryEditTarget>;
+	computeRevision: (entry: TEntry) => Promise<string>;
+	/** Builds the entry an insert op adds. Throw for invalid content. */
+	createEntry: (edit: TEdit) => TEntry;
+	/** Returns the revised entry for update, replace, and replace_text ops. */
+	reviseEntry: (entry: TEntry, edit: TEdit) => TEntry;
+	/** Shown when a delete would empty the item, e.g. "A quiz needs at least one question." */
+	lastEntryDetail: string;
+}): Promise<{ applied: number; failed: OrderedEntryEditFailure[]; entries: TEntry[] }> {
+	const entries = [...input.entries];
+	// Revisions are pinned to the pre-edit content so every ref a read handed
+	// out stays usable for the whole batch, even after an earlier edit touched
+	// the same entry.
+	const initialRevisions = new Map(
+		await Promise.all(
+			entries.map(async (entry) => [entry.id, await input.computeRevision(entry)] as const),
+		),
+	);
+	const failed: OrderedEntryEditFailure[] = [];
+	let applied = 0;
+
+	const findEntryIndex = (ref: string) => {
+		const target = input.targets.get(ref);
+		if (!target) throw new OrderedEntryEditError("ref_not_found");
+		const index = entries.findIndex((entry) => entry.id === target.entryId);
+		if (index < 0) throw new OrderedEntryEditError("ref_not_found");
+		if (initialRevisions.get(target.entryId) !== target.revision) {
+			throw new OrderedEntryEditError("ref_stale");
+		}
+		return index;
+	};
+
+	for (const [index, edit] of input.edits.entries()) {
+		try {
+			const before = JSON.stringify(entries);
+			const entryIndex = findEntryIndex(edit.ref);
+			if (edit.op === "insert_before" || edit.op === "insert_after") {
+				const insertionIndex = edit.op === "insert_before" ? entryIndex : entryIndex + 1;
+				entries.splice(insertionIndex, 0, input.createEntry(edit));
+			} else if (edit.op === "update" || edit.op === "replace" || edit.op === "replace_text") {
+				entries[entryIndex] = input.reviseEntry(entries[entryIndex]!, edit);
+			} else if (edit.op === "delete") {
+				if (entries.length === 1) {
+					throw new OrderedEntryEditError("cannot_delete_last_entry", input.lastEntryDetail);
+				}
+				entries.splice(entryIndex, 1);
+			} else if (edit.op === "move") {
+				const destinationRef = edit.beforeRef ?? edit.afterRef;
+				if (!destinationRef || destinationRef === edit.ref) {
+					throw new OrderedEntryEditError("no_change");
+				}
+				findEntryIndex(destinationRef);
+				const [entry] = entries.splice(entryIndex, 1);
+				const destinationIndex = findEntryIndex(destinationRef);
+				if (!entry) throw new OrderedEntryEditError("ref_not_found");
+				entries.splice(edit.beforeRef ? destinationIndex : destinationIndex + 1, 0, entry);
+			} else {
+				throw new Error("Unsupported edit.");
+			}
+			if (JSON.stringify(entries) === before) throw new OrderedEntryEditError("no_change");
+			applied += 1;
+		} catch (error) {
+			failed.push({
+				code: error instanceof OrderedEntryEditError ? error.code : "invalid_entry_content",
+				...(error instanceof Error && error.message ? { detail: error.message } : {}),
+				index,
+			});
+		}
+	}
+
+	return { applied, failed, entries };
+}
diff --git a/src/features/workspaces/content/workspace-content-contract.test.ts b/src/features/workspaces/content/workspace-content-contract.test.ts
index c8fe39ac0..f1e0e60e8 100644
--- a/src/features/workspaces/content/workspace-content-contract.test.ts
+++ b/src/features/workspaces/content/workspace-content-contract.test.ts
@@ -13,13 +13,9 @@ describe("workspace read tool schemas", () => {
 				requests: [
 					{ mode: "start", path: "/Notes" },
 					{ mode: "pages", path: "/Book.pdf", range: "1-3" },
-					{ mode: "cards", path: "/Biology", range: "1-3" },
-					{ cursor: "opaque", mode: "continue", path: "/Notes" },
-					{
-						ref: "wr_AAAAAAAA",
-						mode: "ref",
-						path: "/Notes",
-					},
+					{ mode: "entries", path: "/Biology", range: "1-3" },
+					{ mode: "ref", ref: "Xk7p2Qa9/b_x7Kp2Qa9x8Lm" },
+					{ mode: "ref", ref: "Xk7p2Qa9" },
 				],
 			}).success,
 		).toBe(true);
@@ -31,6 +27,11 @@ describe("workspace read tool schemas", () => {
 		expect(
 			workspaceReadItemsInputSchema.safeParse({ requests: [{ path: "/Notes" }] }).success,
 		).toBe(false);
+		expect(
+			workspaceReadItemsInputSchema.safeParse({
+				requests: [{ mode: "ref", ref: "not an address" }],
+			}).success,
+		).toBe(false);
 	});
 
 	it("emits a strict-provider-compatible JSON Schema", () => {
@@ -46,11 +47,10 @@ describe("workspace read tool schemas", () => {
 							{ additionalProperties: false, required: ["path", "mode", "range"] },
 							{
 								additionalProperties: false,
-								properties: { mode: { const: "cards" } },
+								properties: { mode: { const: "entries" } },
 								required: ["path", "mode", "range"],
 							},
-							{ additionalProperties: false, required: ["path", "cursor", "mode"] },
-							{ additionalProperties: false, required: ["path", "ref", "mode"] },
+							{ additionalProperties: false, required: ["mode", "ref"] },
 						],
 					},
 				},
@@ -63,14 +63,14 @@ describe("workspace read tool schemas", () => {
 	it("keeps document and file result shapes disjoint", () => {
 		expect(
 			workspaceReadItemsOutputSchema.safeParse({
-				references: [],
 				results: [
 					{
-						content: '<h1 data-ref="b_abcdefghijkl.r_0123456789">Notes</h1>',
+						content: '<h1 data-ref="b_abcdefghijkl.r_012345">Notes</h1>',
 						format: "html",
 						itemId: "notes",
 						location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
 						path: "/Notes",
+						ref: "Xk7p2Qa9",
 						status: "ready",
 						type: "document",
 					},
@@ -81,6 +81,7 @@ describe("workspace read tool schemas", () => {
 						itemId: "book",
 						location: { kind: "pages", requested: "1", returned: [1], total: 1 },
 						path: "/Book.pdf",
+						ref: "Yk7p2Qa9",
 						status: "ready",
 						type: "file",
 					},
@@ -89,7 +90,6 @@ describe("workspace read tool schemas", () => {
 		).toBe(true);
 		expect(
 			workspaceReadItemsOutputSchema.safeParse({
-				references: [],
 				results: [
 					{
 						content: "Page one",
@@ -97,6 +97,7 @@ describe("workspace read tool schemas", () => {
 						itemId: "notes",
 						location: { kind: "pages", requested: "1", returned: [1], total: 1 },
 						path: "/Notes",
+						ref: "Xk7p2Qa9",
 						status: "ready",
 						type: "document",
 					},
diff --git a/src/features/workspaces/content/workspace-content-contract.ts b/src/features/workspaces/content/workspace-content-contract.ts
index 163479217..e4f3afb68 100644
--- a/src/features/workspaces/content/workspace-content-contract.ts
+++ b/src/features/workspaces/content/workspace-content-contract.ts
@@ -5,27 +5,23 @@ import {
 	flashcardReviewSchema,
 	flashcardStudyProgressSchema,
 } from "#/features/workspaces/flashcards/flashcard-study-state";
-import {
-	workspaceReferenceInputSchema,
-	workspaceReferenceRecordSchema,
-} from "#/features/workspaces/locations/workspace-location";
+import { quizStudyProgressSchema } from "#/features/workspaces/quizzes/quiz-study-state";
+import { workspaceAddressInputSchema } from "#/features/workspaces/locations/workspace-location";
 import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
 
 const workspacePathSchema = z.string().min(1);
 
 const readWorkspaceItemsFailureCodes = [
-	"content_changed",
 	"extraction_failed",
 	"extraction_stalled",
-	"invalid_cursor",
 	"invalid_selection",
 	"page_range_out_of_range",
 	"page_selection_too_large",
-	"read_budget_exceeded",
 	"path_is_folder",
 	"path_not_absolute",
 	"path_not_found",
 	"projection_failed",
+	"read_budget_exceeded",
 	"ref_not_found",
 	"unsupported_item_type",
 ] as const;
@@ -36,42 +32,39 @@ const workspaceNumberRangeSchema = z
 	.min(1)
 	.regex(/^\d+(?:\s*-\s*\d+)?(?:\s*,\s*\d+(?:\s*-\s*\d+)?)*$/);
 const workspacePageRangeSchema = workspaceNumberRangeSchema.describe(
-	"Up to 20 physical pages from an extracted file, like 1, 3, 5-7, or 1,4-6. Defaults to page 1.",
+	"Up to 20 physical pages from an extracted file, like 1, 3, 5-7, or 1,4-6.",
 );
-const workspaceCardRangeSchema = workspaceNumberRangeSchema.describe(
-	"Up to 20 card numbers from a flashcard set, like 1, 3, 5-7, or 1,4-6.",
+const workspaceEntryRangeSchema = workspaceNumberRangeSchema.describe(
+	"Up to 20 entry numbers. Flashcards and quiz questions take lists like 1, 3, 5-7; document blocks take one contiguous range like 5-12.",
 );
 
-const workspaceContentReadRequestBase = {
-	path: workspacePathSchema.describe("Absolute path of the workspace item to read."),
-};
-
+/**
+ * One read request. `start` returns the first chunk of anything plus its
+ * total unit count; every result reports which numbered units it covered, so
+ * continuing is just another `entries` or `pages` request with the next range.
+ * `ref` reads the exact content an address identifies — one block in full,
+ * one card, one page — with a current revisioned ref beside it.
+ */
 const workspaceContentReadRequestSchema = z.union([
 	z.strictObject({
-		...workspaceContentReadRequestBase,
+		path: workspacePathSchema.describe("Absolute path of the workspace item to read."),
 		mode: z.literal("start"),
 	}),
 	z.strictObject({
-		...workspaceContentReadRequestBase,
+		path: workspacePathSchema.describe("Absolute path of the workspace item to read."),
 		mode: z.literal("pages"),
 		range: workspacePageRangeSchema,
 	}),
 	z.strictObject({
-		...workspaceContentReadRequestBase,
-		mode: z.literal("cards"),
-		range: workspaceCardRangeSchema,
-	}),
-	z.strictObject({
-		...workspaceContentReadRequestBase,
-		cursor: z.string().min(1).max(4_096).describe("Opaque cursor returned by a previous read."),
-		mode: z.literal("continue"),
+		path: workspacePathSchema.describe("Absolute path of the workspace item to read."),
+		mode: z.literal("entries"),
+		range: workspaceEntryRangeSchema,
 	}),
 	z.strictObject({
-		...workspaceContentReadRequestBase,
-		ref: workspaceReferenceInputSchema.describe(
-			"Ref from an earlier read. Returns the exact content it identifies with a current ref.",
-		),
 		mode: z.literal("ref"),
+		ref: workspaceAddressInputSchema.describe(
+			"Address from an earlier read or citation, like itemRef or itemRef/unit.",
+		),
 	}),
 ]);
 
@@ -98,48 +91,81 @@ const workspaceReadRelationsSchema = z.array(
 	}),
 );
 
+/** A unit ref with its current revision, like `c_9xKp2Qab.r_4f2a1b`. */
+const workspaceUnitRefSchema = z.string().regex(/^[A-Za-z0-9_-]{1,40}\.r_[A-Za-z0-9_-]{6}$/);
+
+/** Fields every ready read carries, whatever the item type. */
+const workspaceReadyResultBase = {
+	/** The item's durable address; cite units as `ref/unit`. */
+	ref: z.string().min(1),
+	itemId: z.string().min(1),
+	path: workspacePathSchema,
+	relations: workspaceReadRelationsSchema.optional(),
+	status: z.literal("ready"),
+};
+
+/** Which numbered entries of an item this read returned. */
+const workspaceEntriesLocationSchema = z.object({
+	kind: z.literal("entries"),
+	returned: z.array(z.number().int().positive()).min(1),
+	total: z.number().int().positive(),
+});
+
 const workspaceContentReadResultSchema = z.union([
 	z.object({
+		...workspaceReadyResultBase,
 		content: z.string(),
 		format: z.literal("html"),
-		itemId: z.string().min(1),
 		location: z.object({
 			endBlock: z.number().int().positive(),
 			kind: z.literal("blocks"),
 			startBlock: z.number().int().positive(),
 			totalBlocks: z.number().int().positive(),
 		}),
-		nextCursor: z.string().optional(),
-		path: workspacePathSchema,
-		relations: workspaceReadRelationsSchema.optional(),
-		status: z.literal("ready"),
 		type: z.literal("document"),
 	}),
 	z.object({
+		...workspaceReadyResultBase,
 		cards: z.array(
 			z.object({
-				cardId: z.uuid(),
-				revision: z.string().regex(/^[A-Za-z0-9_-]{10}$/),
+				ref: workspaceUnitRefSchema,
 				front: z.string(),
 				back: z.string(),
 				study: flashcardReviewSchema.optional(),
 			}),
 		),
 		format: z.literal("html"),
-		itemId: z.string().min(1),
-		location: z.object({
-			kind: z.literal("cards"),
-			returned: z.array(z.number().int().positive()).min(1),
-			total: z.number().int().positive(),
-		}),
-		nextCursor: z.string().optional(),
-		path: workspacePathSchema,
+		location: workspaceEntriesLocationSchema,
 		progress: flashcardStudyProgressSchema,
-		relations: workspaceReadRelationsSchema.optional(),
-		status: z.literal("ready"),
 		type: z.literal("flashcard"),
 	}),
 	z.object({
+		...workspaceReadyResultBase,
+		format: z.literal("html"),
+		location: workspaceEntriesLocationSchema,
+		progress: quizStudyProgressSchema,
+		questions: z.array(
+			z.object({
+				ref: workspaceUnitRefSchema,
+				question: z.string(),
+				options: z
+					.array(z.object({ text: z.string(), correct: z.boolean() }))
+					.min(2)
+					.describe("Options in the order users see them; exactly one is correct."),
+				explanation: z.string(),
+				answer: z
+					.object({
+						selected: z.number().int().positive().describe("1-based option position."),
+						correct: z.boolean(),
+					})
+					.optional()
+					.describe("The reading user's locked-in answer, when they have one."),
+			}),
+		),
+		type: z.literal("quiz"),
+	}),
+	z.object({
+		...workspaceReadyResultBase,
 		assetKind: workspaceFileAssetKindSchema,
 		content: z.string(),
 		emptyPages: z
@@ -149,18 +175,13 @@ const workspaceContentReadResultSchema = z.union([
 				"Returned pages that extracted no text. Expect these to fill in later while provisional is true.",
 			),
 		format: z.literal("markdown"),
-		itemId: z.string().min(1),
 		location: workspaceReadPagesSchema.extend({ kind: z.literal("pages") }),
-		nextCursor: z.string().optional(),
-		path: workspacePathSchema,
 		provisional: z
 			.boolean()
 			.optional()
 			.describe(
 				"True when this content came from the fast extraction pass and a higher-quality pass is still running.",
 			),
-		relations: workspaceReadRelationsSchema.optional(),
-		status: z.literal("ready"),
 		type: z.literal("file"),
 	}),
 	z.object({
@@ -183,26 +204,23 @@ const workspaceContentReadResultSchema = z.union([
 		type: z.literal("file"),
 	}),
 	z.object({
+		...workspaceReadyResultBase,
 		content: z.string(),
-		contentRef: z.string().min(1).max(64),
+		contentRef: workspaceUnitRefSchema,
 		format: z.literal("html"),
-		itemId: z.string().min(1),
-		path: workspacePathSchema,
-		relations: workspaceReadRelationsSchema.optional(),
-		status: z.literal("ready"),
 		type: z.literal("block"),
 	}),
 	z.object({
 		code: z.enum(readWorkspaceItemsFailureCodes),
-		message: z.string().optional().describe("Why extraction failed, when known."),
-		path: workspacePathSchema,
+		message: z.string().optional().describe("Why this read failed, when the reason is known."),
+		path: workspacePathSchema.optional(),
+		ref: z.string().optional(),
 		status: z.literal("failed"),
 		type: z.literal("file").optional(),
 	}),
 ]);
 
 export const workspaceReadItemsOutputSchema = z.object({
-	references: z.array(workspaceReferenceRecordSchema),
 	results: z.array(workspaceContentReadResultSchema),
 });
 
diff --git a/src/features/workspaces/content/workspace-content-cursor.ts b/src/features/workspaces/content/workspace-content-cursor.ts
deleted file mode 100644
index 143379483..000000000
--- a/src/features/workspaces/content/workspace-content-cursor.ts
+++ /dev/null
@@ -1,44 +0,0 @@
-import { z } from "zod";
-
-import { decodeBase64UrlText, encodeBase64UrlText } from "#/lib/binary";
-
-const workspaceContentCursorSchema = z.discriminatedUnion("kind", [
-	z.object({
-		kind: z.literal("document"),
-		offset: z.number().int().nonnegative(),
-		path: z.string().min(1),
-		revision: z.string().min(1),
-		version: z.literal(3),
-	}),
-	z.object({
-		kind: z.literal("file"),
-		nextPage: z.number().int().positive(),
-		path: z.string().min(1),
-		sourceHash: z.string().min(1),
-		version: z.literal(2),
-	}),
-	z.object({
-		kind: z.literal("flashcard"),
-		offset: z.number().int().nonnegative(),
-		path: z.string().min(1),
-		revision: z.string().min(1),
-		version: z.literal(1),
-	}),
-]);
-
-type WorkspaceContentCursor = z.infer<typeof workspaceContentCursorSchema>;
-
-export function encodeWorkspaceContentCursor(cursor: WorkspaceContentCursor) {
-	return encodeBase64UrlText(JSON.stringify(cursor));
-}
-
-export function decodeWorkspaceContentCursor(value: string): WorkspaceContentCursor | null {
-	if (value.length > 4_096) {
-		return null;
-	}
-	try {
-		return workspaceContentCursorSchema.parse(JSON.parse(decodeBase64UrlText(value)));
-	} catch {
-		return null;
-	}
-}
diff --git a/src/features/workspaces/content/workspace-content-reader.test.ts b/src/features/workspaces/content/workspace-content-reader.test.ts
index 323dd7fbc..7dc15aa7e 100644
--- a/src/features/workspaces/content/workspace-content-reader.test.ts
+++ b/src/features/workspaces/content/workspace-content-reader.test.ts
@@ -6,14 +6,12 @@ import {
 	createDocumentAiBlockSnapshot,
 	ensureTiptapDocumentBlockIds,
 	parseDocumentAiHtml,
-	parseDocumentAiRef,
 	readTiptapNodeBlockId,
 } from "#/features/workspaces/documents/document-ai-html";
 import { readDocumentHtmlChunk } from "#/features/workspaces/documents/document-html-chunk";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
 import type { WorkspacePathResolution } from "#/features/workspaces/persistence/workspace-persistence-types";
 import { readWorkspaceContent } from "#/features/workspaces/content/workspace-content-reader";
-import { encodeWorkspaceContentCursor } from "#/features/workspaces/content/workspace-content-cursor";
 import { createFlashcardSetFromHtml } from "#/features/workspaces/flashcards/flashcard-content";
 import type { FlashcardStudyState } from "#/features/workspaces/flashcards/flashcard-study-state";
 
@@ -31,6 +29,7 @@ vi.mock("#/features/workspaces/persistence/workspace-files", () => ({
 
 const documentItem: WorkspaceItem = {
 	id: "document-1",
+	refKey: "refdoc01",
 	workspaceId: "workspace-1",
 	parentId: null,
 	type: "document",
@@ -45,16 +44,19 @@ const documentItem: WorkspaceItem = {
 const flashcardItem: WorkspaceItem = {
 	...documentItem,
 	id: "flashcard-1",
+	refKey: "refcard1",
 	type: "flashcard",
 	name: "Biology cards",
 };
 
+const unitRefPattern = /^[A-Za-z0-9_-]+\.r_[A-Za-z0-9_-]{6}$/;
+
 describe("WorkspaceContentReader", () => {
-	it("reads a complete flashcard set with revision metadata", async () => {
+	it("reads a complete flashcard set with revisioned unit refs", async () => {
 		const set = createFlashcardSetFromHtml([{ front: "<p>Question</p>", back: "<p>Answer</p>" }]);
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "<p />", revision: "unused" }),
+			getDocumentSession: () => createDocumentSession({ html: "<p />" }),
 			item: flashcardItem,
 			readFlashcardItem: async () => ({
 				cards: set.cards,
@@ -75,15 +77,14 @@ describe("WorkspaceContentReader", () => {
 			{
 				cards: [
 					{
-						cardId: set.cards[0]!.id,
-						revision: expect.stringMatching(/^[A-Za-z0-9_-]{10}$/),
+						ref: expect.stringMatching(unitRefPattern),
 						front: "<p>Question</p>",
 						back: "<p>Answer</p>",
 						study: { lastRating: "good", reviewCount: 2 },
 					},
 				],
 				format: "html",
-				location: { kind: "cards", returned: [1], total: 1 },
+				location: { kind: "entries", returned: [1], total: 1 },
 				progress: {
 					gotItCount: 1,
 					missedCount: 0,
@@ -91,104 +92,85 @@ describe("WorkspaceContentReader", () => {
 					totalCards: 1,
 					unreviewedCount: 0,
 				},
+				ref: "refcard1",
 				status: "ready",
 				type: "flashcard",
 			},
 		]);
 	});
 
-	it("reads the current flashcard addressed by a ref", async () => {
+	it("reads the exact flashcard an address identifies", async () => {
 		const set = createFlashcardSetFromHtml([
 			{ front: "<p>One</p>", back: "<p>1</p>" },
 			{ front: "<p>Two</p>", back: "<p>2</p>" },
 		]);
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "<p />", revision: "unused" }),
+			getDocumentSession: () => createDocumentSession({ html: "<p />" }),
 			item: flashcardItem,
 			readFlashcardItem: async () => ({
 				cards: set.cards,
 				studyState: { kind: "flashcard", cards: {} },
 			}),
-			resolveReference: (_itemId, ref) =>
-				ref === "wr_AAAAAAAA"
-					? {
-							cardId: set.cards[1]!.id,
-							itemId: flashcardItem.id,
-							kind: "flashcard",
-							version: 1,
-						}
+			resolveRefKey: async (refKey) =>
+				refKey === flashcardItem.refKey
+					? { item: flashcardItem, path: "/Biology cards" }
 					: undefined,
 		});
 
 		await expect(
-			read([{ mode: "ref", path: "/Biology cards", ref: "wr_AAAAAAAA" }]),
+			read([{ mode: "ref", ref: `refcard1/${set.cards[1]!.id}` }]),
 		).resolves.toMatchObject([
 			{
-				cards: [{ cardId: set.cards[1]!.id, front: "<p>Two</p>" }],
-				location: { kind: "cards", returned: [2], total: 2 },
+				cards: [{ front: "<p>Two</p>" }],
+				location: { kind: "entries", returned: [2], total: 2 },
 				status: "ready",
 				type: "flashcard",
 			},
 		]);
 	});
 
-	it("continues a large flashcard set without repeating cards", async () => {
+	it("chunks a large flashcard set and continues by entry range", async () => {
 		const side = `<p>${"x".repeat(7_900)}</p>`;
 		const set = createFlashcardSetFromHtml(
 			Array.from({ length: 4 }, () => ({ front: side, back: side })),
 		);
-		let cards = set.cards;
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "<p />", revision: "unused" }),
+			getDocumentSession: () => createDocumentSession({ html: "<p />" }),
 			item: flashcardItem,
 			readFlashcardItem: async () => ({
-				cards,
+				cards: set.cards,
 				studyState: { kind: "flashcard", cards: {} },
 			}),
 		});
 
 		const [first] = await read([{ mode: "start", path: "/Biology cards" }]);
 		expect(first).toMatchObject({
-			cards: expect.any(Array),
-			location: { kind: "cards", returned: [1, 2, 3], total: 4 },
+			location: { kind: "entries", returned: [1, 2, 3], total: 4 },
 			status: "ready",
 			type: "flashcard",
 		});
-		if (!first || first.status !== "ready" || first.type !== "flashcard" || !first.nextCursor) {
-			throw new Error("Expected the first flashcard chunk to have a continuation cursor.");
-		}
-		expect(first.cards).toHaveLength(3);
-
-		cards = [...set.cards].reverse();
-		await expect(
-			read([{ cursor: first.nextCursor, mode: "continue", path: "/Biology cards" }]),
-		).resolves.toEqual([{ code: "content_changed", path: "/Biology cards", status: "failed" }]);
-		cards = set.cards;
 
-		const [second] = await read([
-			{ cursor: first.nextCursor, mode: "continue", path: "/Biology cards" },
-		]);
-		expect(second).toMatchObject({
-			cards: [{ cardId: set.cards[3]!.id, revision: expect.stringMatching(/^[A-Za-z0-9_-]{10}$/) }],
-			location: { kind: "cards", returned: [4], total: 4 },
+		const [rest] = await read([{ mode: "entries", path: "/Biology cards", range: "4" }]);
+		expect(rest).toMatchObject({
+			cards: [{ ref: expect.stringMatching(unitRefPattern) }],
+			location: { kind: "entries", returned: [4], total: 4 },
 			status: "ready",
 			type: "flashcard",
 		});
 
-		const [targeted] = await read([{ mode: "cards", path: "/Biology cards", range: "1, 4" }]);
+		const [targeted] = await read([{ mode: "entries", path: "/Biology cards", range: "1, 4" }]);
 		expect(targeted).toMatchObject({
-			cards: [{ cardId: set.cards[0]!.id }, { cardId: set.cards[3]!.id }],
-			location: { kind: "cards", returned: [1, 4], total: 4 },
+			location: { kind: "entries", returned: [1, 4], total: 4 },
 			status: "ready",
 			type: "flashcard",
 		});
 	});
 
-	it("continues a large live document with a revision-guarded cursor", async () => {
+	it("chunks a large document and continues by block range", async () => {
 		const html = Array.from({ length: 20_000 }, (_, index) => `<p>line ${index + 1}</p>`).join("");
-		const session = createDocumentSession({ html, revision: "revision-1" });
+		const session = createDocumentSession({ html });
 		const read = createReader({
 			bucket: {} as R2Bucket,
 			getDocumentSession: () => session,
@@ -199,6 +181,7 @@ describe("WorkspaceContentReader", () => {
 			format: "html",
 			location: { kind: "blocks", startBlock: 1, totalBlocks: 20_000 },
 			path: "/Notes",
+			ref: "refdoc01",
 			status: "ready",
 			type: "document",
 		});
@@ -206,55 +189,46 @@ describe("WorkspaceContentReader", () => {
 			!first ||
 			first.status !== "ready" ||
 			first.type !== "document" ||
-			first.location.kind !== "blocks" ||
-			!first.nextCursor
+			first.location.kind !== "blocks"
 		) {
-			throw new Error("Expected the first document chunk to have a continuation cursor.");
+			throw new Error("Expected a document chunk.");
 		}
+		expect(first.location.endBlock).toBeLessThan(20_000);
 
-		const [second] = await read([{ cursor: first.nextCursor, mode: "continue", path: "/Notes" }]);
+		const [second] = await read([
+			{
+				mode: "entries",
+				path: "/Notes",
+				range: `${first.location.endBlock + 1}-${first.location.endBlock + 3}`,
+			},
+		]);
 		expect(second).toMatchObject({
-			location: { kind: "blocks" },
-			path: "/Notes",
+			location: {
+				kind: "blocks",
+				startBlock: first.location.endBlock + 1,
+				endBlock: first.location.endBlock + 3,
+			},
 			status: "ready",
 			type: "document",
 		});
-		if (
-			!second ||
-			second.status !== "ready" ||
-			second.type !== "document" ||
-			second.location.kind !== "blocks"
-		) {
-			throw new Error("Expected a continued document chunk.");
-		}
-		expect(second.location.startBlock).toBeGreaterThan(first.location.startBlock);
 	});
 
-	it("rejects continuation when the live document revision changed", async () => {
-		const session = createDocumentSession({
-			html: "<p>a</p>".repeat(40_000),
-			revision: "revision-1",
-		});
+	it("rejects a scattered block range for documents", async () => {
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => session,
+			getDocumentSession: () => createDocumentSession({ html: "<p>a</p><p>b</p>" }),
 		});
-		const [first] = await read([{ mode: "start", path: "/Notes" }]);
-		if (!first || first.status !== "ready" || first.type !== "document" || !first.nextCursor) {
-			throw new Error("Expected a continuation cursor.");
-		}
 
-		session.readHtmlChunk = vi.fn(async () => ({ status: "content_changed" }));
-		await expect(
-			read([{ cursor: first.nextCursor, mode: "continue", path: "/Notes" }]),
-		).resolves.toEqual([{ code: "content_changed", path: "/Notes", status: "failed" }]);
-	}, 10_000);
+		await expect(read([{ mode: "entries", path: "/Notes", range: "1,3" }])).resolves.toMatchObject([
+			{ code: "invalid_selection", path: "/Notes", status: "failed" },
+		]);
+	});
 
 	it("keeps document HTML split on top-level block boundaries", async () => {
 		const html = `<h1>Heading</h1><pre><code>${"x".repeat(64_000)}</code></pre><p>Tail</p>`;
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html, revision: "revision-1" }),
+			getDocumentSession: () => createDocumentSession({ html }),
 		});
 
 		const contents: string[] = [];
@@ -262,77 +236,46 @@ describe("WorkspaceContentReader", () => {
 		for (;;) {
 			const [result] = await read([request]);
 			expect(result).toMatchObject({ status: "ready", type: "document" });
-			if (!result || result.status !== "ready" || result.type !== "document") {
+			if (
+				!result ||
+				result.status !== "ready" ||
+				result.type !== "document" ||
+				result.location.kind !== "blocks"
+			) {
 				throw new Error("Expected a document chunk.");
 			}
 			contents.push(result.content);
-			if (!result.nextCursor) {
+			if (result.location.endBlock >= result.location.totalBlocks) {
 				break;
 			}
-			request = { cursor: result.nextCursor, mode: "continue", path: "/Notes" };
+			request = {
+				mode: "entries",
+				path: "/Notes",
+				range: `${result.location.endBlock + 1}-${result.location.totalBlocks}`,
+			};
 		}
 		expect(contents).toHaveLength(3);
 		expect(contents[0]).toMatch(
-			/^<h1 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Heading<\/h1>$/,
+			/^<h1 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}">Heading<\/h1>$/,
 		);
 		expect(contents[1]).toContain("<pre data-ref=");
 		expect(contents[1]).toContain("</pre>");
 		expect(contents[2]).toContain(">Tail</p>");
 	});
 
-	it("rejects a nonzero continuation offset for an empty document", async () => {
-		const read = createReader({
-			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
-		});
-		const cursor = encodeWorkspaceContentCursor({
-			kind: "document",
-			offset: 1,
-			path: "/Notes",
-			revision: "revision-1",
-			version: 3,
-		});
-
-		await expect(read([{ cursor, mode: "continue", path: "/Notes" }])).resolves.toEqual([
-			{ code: "invalid_cursor", path: "/Notes", status: "failed" },
-		]);
-	});
-
-	it("rejects a continuation cursor issued for another path", async () => {
-		const read = createReader({
-			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
-		});
-		const cursor = encodeWorkspaceContentCursor({
-			kind: "document",
-			offset: 0,
-			path: "/Other",
-			revision: "revision-1",
-			version: 3,
-		});
-
-		await expect(read([{ cursor, mode: "continue", path: "/Notes" }])).resolves.toEqual([
-			{ code: "invalid_cursor", path: "/Notes", status: "failed" },
-		]);
-	});
-
 	it("bounds total content returned by a batch", async () => {
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () =>
-				createDocumentSession({
-					html: `<p>${"😀".repeat(300_000)}</p>`,
-					revision: "revision-1",
-				}),
+			getDocumentSession: () => createDocumentSession({ html: `<p>${"😀".repeat(300_000)}</p>` }),
 		});
-		const requests = Array.from({ length: 20 }, (_, index) => ({
+		const requests = Array.from({ length: 3 }, (_, index) => ({
 			mode: "start" as const,
 			path: `/Notes ${index + 1}`,
 		}));
 
 		const results = await read(requests);
 		expect(results.filter((result) => result.status === "ready")).toHaveLength(1);
-		expect(results.slice(1)).toEqual(
+		expect(results.slice(1)).toMatchObject(
 			requests.slice(1).map((request) => ({
 				code: "read_budget_exceeded",
 				path: request.path,
@@ -346,11 +289,12 @@ describe("WorkspaceContentReader", () => {
 		// One session across both reads: a fresh one would mint new refs.
 		const session = createDocumentSession({
 			html: `<p>Before</p><div data-type="widget" title="Sine">${source.replaceAll("<", "&lt;")}</div>`,
-			revision: "revision-1",
 		});
 		const read = createReader({
 			bucket: {} as R2Bucket,
 			getDocumentSession: () => session,
+			resolveRefKey: async (refKey) =>
+				refKey === documentItem.refKey ? { item: documentItem, path: "/Notes" } : undefined,
 		});
 
 		const [chunk] = await read([{ mode: "start", path: "/Notes" }]);
@@ -362,21 +306,9 @@ describe("WorkspaceContentReader", () => {
 		const widgetTag = /<div[^>]*data-type="widget"[^>]*>/.exec(chunk.content)?.[0] ?? "";
 		const contentRef = /data-ref="([^"]+)"/.exec(widgetTag)?.[1];
 		expect(contentRef).toBeTruthy();
+		const blockId = contentRef!.split(".")[0]!;
 
-		const readBlock = createReader({
-			bucket: {} as R2Bucket,
-			getDocumentSession: () => session,
-			resolveReference: (_itemId, ref) =>
-				ref === "wr_AAAAAAAA"
-					? {
-							blockId: parseDocumentAiRef(contentRef!)!,
-							itemId: documentItem.id,
-							kind: "document-block",
-							version: 1,
-						}
-					: undefined,
-		});
-		const [block] = await readBlock([{ ref: "wr_AAAAAAAA", mode: "ref", path: "/Notes" }]);
+		const [block] = await read([{ mode: "ref", ref: `refdoc01/${blockId}` }]);
 		expect(block).toMatchObject({ contentRef, status: "ready", type: "block" });
 		if (!block || block.status !== "ready" || block.type !== "block") {
 			throw new Error("Expected a block read.");
@@ -385,34 +317,34 @@ describe("WorkspaceContentReader", () => {
 		expect(block.content).not.toContain("data-ref");
 	});
 
-	it("rejects unknown exact refs", async () => {
-		const fileItem = {
-			...documentItem,
-			id: "file-1",
-			name: "Book.pdf",
-			type: "file",
-		} satisfies WorkspaceItem;
+	it("rejects unknown addresses", async () => {
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
-			item: fileItem,
+			getDocumentSession: () => createDocumentSession({ html: "" }),
 		});
 
-		await expect(
-			read([
-				{
-					ref: "wr_AAAAAAAA",
-					mode: "ref",
-					path: "/Book.pdf",
-				},
-			]),
-		).resolves.toEqual([{ code: "ref_not_found", path: "/Book.pdf", status: "failed" }]);
+		await expect(read([{ mode: "ref", ref: "zzZZzzZZ/p5" }])).resolves.toEqual([
+			{ code: "ref_not_found", ref: "zzZZzzZZ/p5", status: "failed" },
+		]);
+	});
+
+	it("rejects a unit that cannot belong to the item's type", async () => {
+		const read = createReader({
+			bucket: {} as R2Bucket,
+			getDocumentSession: () => createDocumentSession({ html: "<p>a</p>" }),
+			resolveRefKey: async (refKey) =>
+				refKey === documentItem.refKey ? { item: documentItem, path: "/Notes" } : undefined,
+		});
+
+		await expect(read([{ mode: "ref", ref: "refdoc01/p5" }])).resolves.toEqual([
+			{ code: "ref_not_found", ref: "refdoc01/p5", status: "failed" },
+		]);
 	});
 
 	it("keeps one ordered result for every requested path", async () => {
 		const read = createReader({
 			bucket: {} as R2Bucket,
-			getDocumentSession: () => createDocumentSession({ html: "", revision: "revision-1" }),
+			getDocumentSession: () => createDocumentSession({ html: "" }),
 			resolvePaths: vi.fn(
 				async () =>
 					[
@@ -437,18 +369,13 @@ describe("WorkspaceContentReader", () => {
 	});
 });
 
-function createDocumentSession(input: { html: string; revision: string }) {
+function createDocumentSession(input: { html: string }) {
 	const document = ensureTiptapDocumentBlockIds(parseDocumentAiHtml(input.html)).document;
 	const documentNode = getTiptapDocumentSchema().nodeFromJSON(document);
 	return {
-		readHtmlChunk: vi.fn(async ({ expectedRevision, offset }) => {
-			if (expectedRevision && expectedRevision !== input.revision) {
-				return { status: "content_changed" as const };
-			}
-			const chunk = await readDocumentHtmlChunk(documentNode, offset);
-			return chunk
-				? { ...chunk, revision: input.revision, status: "ready" as const }
-				: { status: "invalid_offset" as const };
+		readHtmlChunk: vi.fn(async ({ offset, maxBlocks }: { offset: number; maxBlocks?: number }) => {
+			const chunk = await readDocumentHtmlChunk(documentNode, offset, maxBlocks);
+			return chunk ? { ...chunk, status: "ready" as const } : { status: "invalid_offset" as const };
 		}),
 		readBlock: vi.fn(async ({ blockId }: { blockId: string }) => {
 			let found: ReturnType<typeof documentNode.child> | null = null;
@@ -480,7 +407,8 @@ function createReader(input: {
 				cards: ReturnType<typeof createFlashcardSetFromHtml>["cards"];
 				studyState: FlashcardStudyState;
 		  }>;
-	resolveReference?: Parameters<typeof readWorkspaceContent>[0]["resolveReference"];
+	readQuizItem?: Parameters<typeof readWorkspaceContent>[0]["readQuizItem"];
+	resolveRefKey?: Parameters<typeof readWorkspaceContent>[0]["resolveRefKey"];
 	resolvePaths?: typeof persistence.resolveWorkspacePaths;
 }) {
 	const item = input.item ?? documentItem;
@@ -499,7 +427,10 @@ function createReader(input: {
 			readFlashcardItem:
 				input.readFlashcardItem ??
 				(async () => ({ cards: [], studyState: { kind: "flashcard", cards: {} } })),
-			resolveReference: input.resolveReference,
+			readQuizItem:
+				input.readQuizItem ??
+				(async () => ({ questions: [], studyState: { kind: "quiz", answers: {} } })),
+			resolveRefKey: input.resolveRefKey ?? (async () => undefined),
 			requests,
 			workspaceId: "workspace-1",
 		});
diff --git a/src/features/workspaces/content/workspace-content-reader.ts b/src/features/workspaces/content/workspace-content-reader.ts
index 4349e2954..2f965bd5a 100644
--- a/src/features/workspaces/content/workspace-content-reader.ts
+++ b/src/features/workspaces/content/workspace-content-reader.ts
@@ -1,8 +1,4 @@
-import {
-	type WorkspaceItem,
-	getWorkspaceItemContentKind,
-	isWorkspaceItemContainer,
-} from "#/features/workspaces/contracts";
+import { type WorkspaceItem, isWorkspaceItemContainer } from "#/features/workspaces/contracts";
 import type {
 	WorkspaceContentReadRequest,
 	WorkspaceContentReadResult,
@@ -29,24 +25,35 @@ import {
 	parseWorkspacePageRange,
 	WorkspacePageSelectionError,
 } from "#/features/workspaces/read-page-selection";
-import {
-	decodeWorkspaceContentCursor,
-	encodeWorkspaceContentCursor,
-} from "#/features/workspaces/content/workspace-content-cursor";
 import {
 	createFlashcardRevision,
 	type Flashcard,
 	serializeFlashcardSetToHtml,
 } from "#/features/workspaces/flashcards/flashcard-content";
-import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import {
+	parseWorkspaceAddress,
+	resolveWorkspaceAddressLocation,
+} from "#/features/workspaces/locations/workspace-location";
 import {
 	summarizeFlashcardStudyProgress,
 	type FlashcardStudyState,
 } from "#/features/workspaces/flashcards/flashcard-study-state";
-import { sha256Base64UrlText } from "#/lib/binary";
+import {
+	createQuizQuestionRevision,
+	serializeQuizSetToHtml,
+	type QuizQuestion,
+} from "#/features/workspaces/quizzes/quiz-content";
+import {
+	getQuizAnswer,
+	summarizeQuizStudyProgress,
+	type QuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
 
-const maxWorkspaceContentBatchBytes = 2 * 1024 * 1024 + 64 * 1024;
-const targetFlashcardChunkCharacters = 48_000;
+// A context-sized ceiling for one whole read call, not a transport limit: once
+// a call has returned this much content, further requests in it fail fast and
+// say to read fewer units at a time.
+const maxWorkspaceReadCharacters = 200_000;
+const targetEntryChunkCharacters = 48_000;
 
 interface DocumentContentReader {
 	readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise<DocumentHtmlChunkReadResult>;
@@ -61,6 +68,12 @@ type FlashcardItemReader = (
 	| { cards: Flashcard[]; studyState: FlashcardStudyState }
 	| Promise<{ cards: Flashcard[]; studyState: FlashcardStudyState }>;
 
+type QuizItemReader = (
+	itemId: string,
+) =>
+	| { questions: QuizQuestion[]; studyState: QuizStudyState }
+	| Promise<{ questions: QuizQuestion[]; studyState: QuizStudyState }>;
+
 interface PendingReadyResult {
 	item: WorkspaceItem;
 	read: Extract<WorkspaceContentReadResult, { status: "ready" }>;
@@ -71,90 +84,71 @@ export async function readWorkspaceContent(input: {
 	bucket: R2Bucket;
 	getDocumentSession: (itemId: string) => DocumentContentReader | Promise<DocumentContentReader>;
 	readFlashcardItem: FlashcardItemReader;
-	resolveReference?: (itemId: string, ref: string) => WorkspaceLocation | undefined;
+	readQuizItem: QuizItemReader;
+	/** Resolves an item address's refKey to a live item and its path. */
+	resolveRefKey: (refKey: string) => Promise<{ item: WorkspaceItem; path: string } | undefined>;
 	requests: WorkspaceContentReadRequest[];
 	workspaceId: string;
 }): Promise<WorkspaceContentReadResult[]> {
 	const { requests } = input;
-	const encoder = new TextEncoder();
-	const resolutions = await resolveWorkspacePaths({
-		paths: requests.map((request) => request.path),
+	const pathResolutions = await resolveWorkspacePaths({
+		paths: requests.flatMap((request) => ("path" in request ? [request.path] : [])),
 		workspaceId: input.workspaceId,
 	});
 	const results: WorkspaceContentReadResult[] = [];
 	const readyResults: PendingReadyResult[] = [];
-	let returnedContentBytes = 0;
-	let readBudgetExhausted = false;
-
-	// Reads stay ordered so each body is consumed before the shared byte budget advances.
-	for (const [index, resolution] of resolutions.entries()) {
-		const request = requests[index];
-		if (!request) {
-			throw new Error("Workspace content resolution did not match its request.");
-		}
-		if (resolution.status === "invalid_path") {
-			results.push({ code: resolution.code, path: resolution.path, status: "failed" });
-			continue;
-		}
-		if (resolution.status === "root") {
-			results.push({ code: "path_is_folder", path: resolution.path, status: "failed" });
-			continue;
-		}
-		if (resolution.status === "not_found") {
-			results.push({ code: "path_not_found", path: resolution.path, status: "failed" });
-			continue;
-		}
-		if (isWorkspaceItemContainer(resolution.item.type)) {
-			results.push({ code: "path_is_folder", path: resolution.path, status: "failed" });
+	let returnedCharacters = 0;
+	let pathIndex = 0;
+
+	// Reads stay ordered so each body is consumed before the shared budget advances.
+	for (const request of requests) {
+		const resolved =
+			"path" in request
+				? resolvePathRequest(pathResolutions[pathIndex++], request.path)
+				: await resolveRefRequest(input.resolveRefKey, request.ref);
+		if ("failure" in resolved) {
+			results.push(resolved.failure);
 			continue;
 		}
-		const readBudgetFailure = {
-			code: "read_budget_exceeded" as const,
-			path: resolution.path,
-			status: "failed" as const,
-			...(getWorkspaceItemContentKind(resolution.item.type) === "file"
-				? { type: "file" as const }
-				: {}),
-		};
-		if (readBudgetExhausted) {
-			results.push(readBudgetFailure);
+
+		if (returnedCharacters >= maxWorkspaceReadCharacters) {
+			results.push({
+				code: "read_budget_exceeded",
+				message: "This call already returned as much as fits. Read fewer units per call.",
+				path: resolved.path,
+				status: "failed",
+			});
 			continue;
 		}
 
 		try {
 			const read = await readWorkspaceItem({
 				...input,
-				item: resolution.item,
+				item: resolved.item,
 				request,
-				path: resolution.path,
+				path: resolved.path,
 			});
 			if (read.status !== "ready") {
 				results.push(read);
 				continue;
 			}
-			const contentBytes = encoder.encode(
-				"content" in read ? read.content : JSON.stringify(read.cards),
-			).byteLength;
-			if (returnedContentBytes + contentBytes > maxWorkspaceContentBatchBytes) {
-				readBudgetExhausted = true;
-				results.push(readBudgetFailure);
-				continue;
-			}
-			returnedContentBytes += contentBytes;
+			returnedCharacters +=
+				"content" in read
+					? read.content.length
+					: JSON.stringify("cards" in read ? read.cards : read.questions).length;
 
-			const pending = {
-				item: resolution.item,
+			readyResults.push({
+				item: resolved.item,
 				read,
 				relations: listWorkspaceItemRelations({
-					itemId: resolution.item.id,
+					itemId: resolved.item.id,
 					workspaceId: input.workspaceId,
 				}),
-			};
-			readyResults.push(pending);
+			});
 			results.push(read);
 		} catch (error) {
 			if (error instanceof WorkspacePageSelectionError) {
-				results.push({ code: error.code, path: resolution.path, status: "failed" });
+				results.push({ code: error.code, path: resolved.path, status: "failed" });
 				continue;
 			}
 			throw error;
@@ -165,18 +159,52 @@ export async function readWorkspaceContent(input: {
 	return results;
 }
 
+function resolvePathRequest(
+	resolution: Awaited<ReturnType<typeof resolveWorkspacePaths>>[number] | undefined,
+	path: string,
+): { item: WorkspaceItem; path: string } | { failure: WorkspaceContentReadResult } {
+	if (!resolution) {
+		throw new Error("Workspace content resolution did not match its request.");
+	}
+	if (resolution.status === "invalid_path") {
+		return { failure: { code: resolution.code, path: resolution.path, status: "failed" } };
+	}
+	if (resolution.status === "root") {
+		return { failure: { code: "path_is_folder", path: resolution.path, status: "failed" } };
+	}
+	if (resolution.status === "not_found") {
+		return { failure: { code: "path_not_found", path: resolution.path, status: "failed" } };
+	}
+	if (isWorkspaceItemContainer(resolution.item.type)) {
+		return { failure: { code: "path_is_folder", path, status: "failed" } };
+	}
+	return { item: resolution.item, path: resolution.path };
+}
+
+async function resolveRefRequest(
+	resolveRefKey: (refKey: string) => Promise<{ item: WorkspaceItem; path: string } | undefined>,
+	ref: string,
+): Promise<{ item: WorkspaceItem; path: string } | { failure: WorkspaceContentReadResult }> {
+	const address = parseWorkspaceAddress(ref);
+	const resolved = address ? await resolveRefKey(address.refKey) : undefined;
+	if (!resolved || isWorkspaceItemContainer(resolved.item.type)) {
+		return { failure: { code: "ref_not_found", ref, status: "failed" } };
+	}
+	return resolved;
+}
+
 async function readWorkspaceItem(input: {
 	bucket: R2Bucket;
 	getDocumentSession: (itemId: string) => DocumentContentReader | Promise<DocumentContentReader>;
 	readFlashcardItem: FlashcardItemReader;
-	resolveReference?: (itemId: string, ref: string) => WorkspaceLocation | undefined;
+	readQuizItem: QuizItemReader;
 	item: WorkspaceItem;
 	path: string;
 	request: WorkspaceContentReadRequest;
 	workspaceId: string;
 }): Promise<WorkspaceContentReadResult> {
 	if (input.request.mode === "ref") {
-		return readWorkspaceReference(input, input.request.ref);
+		return readWorkspaceUnit(input, input.request.ref);
 	}
 	switch (input.item.type) {
 		case "document":
@@ -187,36 +215,36 @@ async function readWorkspaceItem(input: {
 			return { code: "unsupported_item_type", path: input.path, status: "failed" };
 		case "flashcard":
 			return readFlashcards(input);
+		case "quiz":
+			return readQuiz(input);
 	}
 }
 
-async function readWorkspaceReference(
+/** Reads the exact content an address identifies: one page, block, or entry. */
+async function readWorkspaceUnit(
 	input: Parameters<typeof readWorkspaceItem>[0],
 	ref: string,
 ): Promise<WorkspaceContentReadResult> {
-	const location = input.resolveReference?.(input.item.id, ref);
-	if (!location || location.itemId !== input.item.id) {
-		return { code: "ref_not_found", path: input.path, status: "failed" };
+	const address = parseWorkspaceAddress(ref);
+	const location = address ? resolveWorkspaceAddressLocation(input.item, address) : undefined;
+	if (!location) {
+		return { code: "ref_not_found", ref, status: "failed" };
 	}
 
 	switch (location.kind) {
 		case "item":
 			return readWorkspaceItem({ ...input, request: { mode: "start", path: input.path } });
 		case "pdf-page":
-			return input.item.type === "file"
-				? readFile({
-						...input,
-						request: { mode: "pages", path: input.path, range: String(location.pageNumber) },
-					})
-				: { code: "ref_not_found", path: input.path, status: "failed" };
+			return readFile({
+				...input,
+				request: { mode: "pages", path: input.path, range: String(location.pageNumber) },
+			});
 		case "document-block":
-			return input.item.type === "document"
-				? readDocumentBlock(input, location.blockId)
-				: { code: "ref_not_found", path: input.path, status: "failed" };
+			return readDocumentBlock(input, location.blockId);
 		case "flashcard":
-			return input.item.type === "flashcard"
-				? readFlashcards(input, location.cardId)
-				: { code: "ref_not_found", path: input.path, status: "failed" };
+			return readFlashcards(input, location.cardId);
+		case "quiz-question":
+			return readQuiz(input, location.questionId);
 	}
 }
 
@@ -230,73 +258,30 @@ async function readFlashcards(
 	},
 	targetCardId?: string,
 ): Promise<WorkspaceContentReadResult> {
-	if (
-		!targetCardId &&
-		input.request.mode !== "start" &&
-		input.request.mode !== "continue" &&
-		input.request.mode !== "cards"
-	) {
-		return { code: "invalid_selection", path: input.path, status: "failed" };
-	}
-
 	const { cards, studyState } = await input.readFlashcardItem(input.item.id);
 	const cardsById = new Map(cards.map((card) => [card.id, card]));
-	const serializedCards = serializeFlashcardSetToHtml({ cards, version: 1 });
-	let selectedCards: typeof serializedCards;
-	let returned: number[];
-	let nextCursor: string | undefined;
-
-	if (targetCardId) {
-		const cardIndex = serializedCards.findIndex((card) => card.id === targetCardId);
-		if (cardIndex < 0) return { code: "ref_not_found", path: input.path, status: "failed" };
-		selectedCards = [serializedCards[cardIndex]!];
-		returned = [cardIndex + 1];
-	} else if (input.request.mode === "cards") {
-		try {
-			returned = parseWorkspacePageRange(input.request.range, cards.length);
-		} catch (error) {
-			if (error instanceof WorkspacePageSelectionError) {
-				return { code: "invalid_selection", path: input.path, status: "failed" };
-			}
-			throw error;
-		}
-		selectedCards = returned.map((cardNumber) => serializedCards[cardNumber - 1]!);
-	} else {
-		const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
-		const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
-		if (encodedCursor && (!cursor || cursor.kind !== "flashcard" || cursor.path !== input.path)) {
-			return { code: "invalid_cursor", path: input.path, status: "failed" };
-		}
-
-		const revision = await sha256Base64UrlText(JSON.stringify(cards));
-		if (cursor?.kind === "flashcard" && cursor.revision !== revision) {
-			return { code: "content_changed", path: input.path, status: "failed" };
-		}
-
-		const offset = cursor?.kind === "flashcard" ? cursor.offset : 0;
-		const chunk = readFlashcardChunk(serializedCards, offset);
-		if (!chunk) return { code: "invalid_cursor", path: input.path, status: "failed" };
-		selectedCards = chunk.cards;
-		returned = Array.from({ length: chunk.endOffset - offset }, (_, index) => offset + index + 1);
-		if (chunk.endOffset < cards.length) {
-			nextCursor = encodeWorkspaceContentCursor({
-				kind: "flashcard",
-				offset: chunk.endOffset,
-				path: input.path,
-				revision,
-				version: 1,
-			});
-		}
+	const selection = selectOrderedEntries({
+		entries: serializeFlashcardSetToHtml({ cards, version: 1 }),
+		measure: (card) => card.front.length + card.back.length,
+		request: input.request,
+		targetEntryId: targetCardId,
+	});
+	if (!selection.ok) {
+		return {
+			code: selection.code,
+			...(selection.message ? { message: selection.message } : {}),
+			path: input.path,
+			status: "failed",
+		};
 	}
 
 	return {
 		cards: await Promise.all(
-			selectedCards.map(async (card) => {
+			selection.selected.map(async (card) => {
 				const source = cardsById.get(card.id);
 				if (!source) throw new Error("Serialized flashcard does not match its source set.");
 				return {
-					cardId: card.id,
-					revision: await createFlashcardRevision(source),
+					ref: `${card.id}.r_${await createFlashcardRevision(source)}`,
 					front: card.front,
 					back: card.back,
 					...(studyState.cards[card.id] ? { study: studyState.cards[card.id] } : {}),
@@ -306,35 +291,160 @@ async function readFlashcards(
 		format: "html",
 		itemId: input.item.id,
 		location: {
-			kind: "cards",
-			returned,
+			kind: "entries",
+			returned: selection.returned,
 			total: cards.length,
 		},
-		...(nextCursor ? { nextCursor } : {}),
 		path: input.path,
 		progress: summarizeFlashcardStudyProgress(
 			cards.map((card) => card.id),
 			studyState,
 		),
+		ref: input.item.refKey,
 		status: "ready",
 		type: "flashcard",
 	};
 }
 
-function readFlashcardChunk(cards: ReturnType<typeof serializeFlashcardSetToHtml>, offset: number) {
-	if (offset < 0 || offset >= cards.length) return null;
+async function readQuiz(
+	input: {
+		item: WorkspaceItem;
+		path: string;
+		readQuizItem: QuizItemReader;
+		request: WorkspaceContentReadRequest;
+		workspaceId: string;
+	},
+	targetQuestionId?: string,
+): Promise<WorkspaceContentReadResult> {
+	const { questions, studyState } = await input.readQuizItem(input.item.id);
+	const questionsById = new Map(questions.map((question) => [question.id, question]));
+	const selection = selectOrderedEntries({
+		entries: serializeQuizSetToHtml({ questions, version: 1 }),
+		measure: (question) =>
+			question.question.length +
+			question.explanation.length +
+			question.options.reduce((total, option) => total + option.text.length, 0),
+		request: input.request,
+		targetEntryId: targetQuestionId,
+	});
+	if (!selection.ok) {
+		return {
+			code: selection.code,
+			...(selection.message ? { message: selection.message } : {}),
+			path: input.path,
+			status: "failed",
+		};
+	}
+
+	return {
+		format: "html",
+		itemId: input.item.id,
+		location: {
+			kind: "entries",
+			returned: selection.returned,
+			total: questions.length,
+		},
+		path: input.path,
+		progress: summarizeQuizStudyProgress(questions, studyState),
+		questions: await Promise.all(
+			selection.selected.map(async (question) => {
+				const source = questionsById.get(question.id);
+				if (!source) throw new Error("Serialized quiz question does not match its source set.");
+				const answer = getQuizAnswer(source, studyState);
+				const selectedIndex = answer
+					? source.options.findIndex((option) => option.id === answer.selectedOptionId)
+					: -1;
+				return {
+					ref: `${question.id}.r_${await createQuizQuestionRevision(source)}`,
+					question: question.question,
+					options: question.options.map(({ text, correct }) => ({ text, correct })),
+					explanation: question.explanation,
+					...(answer && selectedIndex >= 0
+						? {
+								answer: {
+									selected: selectedIndex + 1,
+									correct: answer.selectedOptionId === source.correctOptionId,
+								},
+							}
+						: {}),
+				};
+			}),
+		),
+		ref: input.item.refKey,
+		status: "ready",
+		type: "quiz",
+	};
+}
+
+type OrderedEntrySelection<T> =
+	| { ok: true; selected: T[]; returned: number[] }
+	| {
+			ok: false;
+			code:
+				| "invalid_selection"
+				| "page_range_out_of_range"
+				| "page_selection_too_large"
+				| "ref_not_found";
+			message?: string;
+	  };
+
+/**
+ * Shared selection for structured items: one targeted entry from an address,
+ * an explicit entry range, or the first character-budgeted chunk on `start`.
+ * Every result names the entry numbers it covered, so continuing is just the
+ * next range — no cursor to carry.
+ */
+function selectOrderedEntries<T extends { id: string }>(input: {
+	entries: T[];
+	measure: (entry: T) => number;
+	request: WorkspaceContentReadRequest;
+	targetEntryId?: string;
+}): OrderedEntrySelection<T> {
+	const { entries, request, targetEntryId } = input;
+
+	if (targetEntryId) {
+		const entryIndex = entries.findIndex((entry) => entry.id === targetEntryId);
+		if (entryIndex < 0) return { ok: false, code: "ref_not_found" };
+		return { ok: true, selected: [entries[entryIndex]!], returned: [entryIndex + 1] };
+	}
+	if (request.mode === "entries") {
+		let returned: number[];
+		try {
+			returned = parseWorkspacePageRange(request.range, entries.length);
+		} catch (error) {
+			if (error instanceof WorkspacePageSelectionError) {
+				return {
+					ok: false,
+					code: error.code,
+					message: `The item has ${entries.length} entries; request up to 20 of them per read.`,
+				};
+			}
+			throw error;
+		}
+		return {
+			ok: true,
+			selected: returned.map((entryNumber) => entries[entryNumber - 1]!),
+			returned,
+		};
+	}
+	if (request.mode !== "start") {
+		return { ok: false, code: "invalid_selection" };
+	}
 
 	let characters = 0;
-	let endOffset = offset;
-	while (endOffset < cards.length) {
-		const card = cards[endOffset]!;
-		const cardCharacters = card.front.length + card.back.length;
-		if (endOffset > offset && characters + cardCharacters > targetFlashcardChunkCharacters) break;
-		characters += cardCharacters;
+	let endOffset = 0;
+	while (endOffset < entries.length) {
+		const entryCharacters = input.measure(entries[endOffset]!);
+		if (endOffset > 0 && characters + entryCharacters > targetEntryChunkCharacters) break;
+		characters += entryCharacters;
 		endOffset += 1;
 	}
 
-	return { cards: cards.slice(offset, endOffset), endOffset };
+	return {
+		ok: true,
+		selected: entries.slice(0, endOffset),
+		returned: Array.from({ length: endOffset }, (_, index) => index + 1),
+	};
 }
 
 /**
@@ -364,6 +474,7 @@ async function readDocumentBlock(
 		format: "html",
 		itemId: input.item.id,
 		path: input.path,
+		ref: input.item.refKey,
 		status: "ready",
 		type: "block",
 	};
@@ -376,26 +487,31 @@ async function readDocument(input: {
 	request: WorkspaceContentReadRequest;
 	workspaceId: string;
 }): Promise<WorkspaceContentReadResult> {
-	if (input.request.mode !== "start" && input.request.mode !== "continue") {
+	let chunkInput: DocumentHtmlChunkReadInput;
+	if (input.request.mode === "start") {
+		chunkInput = { offset: 0 };
+	} else if (input.request.mode === "entries") {
+		// Blocks are contiguous prose; a scattered range has no meaningful join.
+		const range = /^(\d+)(?:\s*-\s*(\d+))?$/.exec(input.request.range);
+		const startBlock = range ? Number(range[1]) : 0;
+		const endBlock = range?.[2] ? Number(range[2]) : startBlock;
+		if (!range || startBlock < 1 || endBlock < startBlock) {
+			return {
+				code: "invalid_selection",
+				message: "Document entries must be one block number or one contiguous range like 5-12.",
+				path: input.path,
+				status: "failed",
+			};
+		}
+		chunkInput = { offset: startBlock - 1, maxBlocks: endBlock - startBlock + 1 };
+	} else {
 		return { code: "invalid_selection", path: input.path, status: "failed" };
 	}
 
-	const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
-	const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
-	if (encodedCursor && (!cursor || cursor.kind !== "document" || cursor.path !== input.path)) {
-		return { code: "invalid_cursor", path: input.path, status: "failed" };
-	}
-
 	const documentSession = await input.getDocumentSession(input.item.id);
-	const chunk = await documentSession.readHtmlChunk({
-		expectedRevision: cursor?.kind === "document" ? cursor.revision : undefined,
-		offset: cursor?.kind === "document" ? cursor.offset : 0,
-	});
-	if (chunk.status === "content_changed") {
-		return { code: "content_changed", path: input.path, status: "failed" };
-	}
+	const chunk = await documentSession.readHtmlChunk(chunkInput);
 	if (chunk.status === "invalid_offset") {
-		return { code: "invalid_cursor", path: input.path, status: "failed" };
+		return { code: "invalid_selection", path: input.path, status: "failed" };
 	}
 
 	return {
@@ -403,18 +519,8 @@ async function readDocument(input: {
 		format: "html",
 		itemId: input.item.id,
 		location: { kind: "blocks", ...chunk.location },
-		...(chunk.nextOffset === undefined
-			? {}
-			: {
-					nextCursor: encodeWorkspaceContentCursor({
-						kind: "document",
-						offset: chunk.nextOffset,
-						path: input.path,
-						revision: chunk.revision,
-						version: 3,
-					}),
-				}),
 		path: input.path,
+		ref: input.item.refKey,
 		status: "ready",
 		type: "document",
 	};
@@ -427,11 +533,7 @@ async function readFile(input: {
 	request: WorkspaceContentReadRequest;
 	workspaceId: string;
 }): Promise<WorkspaceContentReadResult> {
-	if (
-		input.request.mode !== "start" &&
-		input.request.mode !== "continue" &&
-		input.request.mode !== "pages"
-	) {
+	if (input.request.mode !== "start" && input.request.mode !== "pages") {
 		return { code: "invalid_selection", path: input.path, status: "failed" };
 	}
 	const fileType = resolveWorkspaceFileTypeFromItem(input.item);
@@ -450,25 +552,12 @@ async function readFile(input: {
 		return describeUnreadableProjection(projection, input.path, input.item.id);
 	}
 
-	const encodedCursor = input.request.mode === "continue" ? input.request.cursor : undefined;
-	const cursor = encodedCursor ? decodeWorkspaceContentCursor(encodedCursor) : undefined;
-	if (encodedCursor && (!cursor || cursor.kind !== "file" || cursor.path !== input.path)) {
-		return { code: "invalid_cursor", path: input.path, status: "failed" };
-	}
-	if (cursor?.kind === "file" && cursor.sourceHash !== projection.sourceHash) {
-		return { code: "content_changed", path: input.path, status: "failed" };
-	}
 	let pageRead: Awaited<ReturnType<typeof readWorkspacePageProjection>>;
 	try {
 		pageRead = await readWorkspacePageProjection({
 			itemId: input.item.id,
 			pageCount: projection.pageCount,
-			pages:
-				cursor?.kind === "file"
-					? String(cursor.nextPage)
-					: input.request.mode === "pages"
-						? input.request.range
-						: undefined,
+			pages: input.request.mode === "pages" ? input.request.range : undefined,
 			workspaceId: input.workspaceId,
 		});
 	} catch (error) {
@@ -477,7 +566,6 @@ async function readFile(input: {
 		}
 		return { code: "projection_failed", path: input.path, status: "failed", type: "file" };
 	}
-	const nextPage = Math.max(...pageRead.pages.returned) + 1;
 	return {
 		assetKind: fileType.assetKind,
 		content: pageRead.content,
@@ -485,19 +573,9 @@ async function readFile(input: {
 		format: "markdown",
 		itemId: input.item.id,
 		location: { kind: "pages", ...pageRead.pages },
-		...(nextPage > pageRead.pages.total
-			? {}
-			: {
-					nextCursor: encodeWorkspaceContentCursor({
-						kind: "file",
-						nextPage,
-						path: input.path,
-						sourceHash: projection.sourceHash,
-						version: 2,
-					}),
-				}),
 		path: input.path,
 		...(projection.provisional ? { provisional: true } : {}),
+		ref: input.item.refKey,
 		status: "ready",
 		type: "file",
 	};
diff --git a/src/features/workspaces/content/workspace-read-model-output.test.ts b/src/features/workspaces/content/workspace-read-model-output.test.ts
new file mode 100644
index 000000000..47ffdbcda
--- /dev/null
+++ b/src/features/workspaces/content/workspace-read-model-output.test.ts
@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+
+import type { WorkspaceReadItemsOutput } from "#/features/workspaces/content/workspace-content-contract";
+import { createWorkspaceReadItemsModelOutput } from "#/features/workspaces/content/workspace-read-model-output";
+
+describe("workspace read model output", () => {
+	it("drops internal item ids and keeps self-describing refs", () => {
+		const output: WorkspaceReadItemsOutput = {
+			results: [
+				{
+					content: '<h1 data-ref="b_abcdefghijkl.r_012345">Notes</h1>',
+					format: "html",
+					itemId: "document-1",
+					location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
+					path: "/Notes",
+					ref: "Xk7p2Qa9",
+					status: "ready",
+					type: "document",
+				},
+			],
+		};
+
+		const modelOutput = createWorkspaceReadItemsModelOutput(output);
+		expect(modelOutput).not.toHaveProperty("guidance");
+		expect(modelOutput.results[0]).toMatchObject({
+			content: expect.stringContaining('data-ref="b_abcdefghijkl.r_012345"'),
+			path: "/Notes",
+			ref: "Xk7p2Qa9",
+			status: "ready",
+		});
+		expect(JSON.stringify(modelOutput)).not.toContain("document-1");
+	});
+
+	it("emits each handling guidance once per situation", () => {
+		const output: WorkspaceReadItemsOutput = {
+			results: [
+				{
+					elapsedSeconds: 5,
+					path: "/A.pdf",
+					phase: "extracting",
+					retryAfterSeconds: 10,
+					status: "pending",
+					type: "file",
+				},
+				{
+					elapsedSeconds: 9,
+					path: "/B.pdf",
+					phase: "queued",
+					retryAfterSeconds: 10,
+					status: "pending",
+					type: "file",
+				},
+				{ code: "extraction_failed", path: "/C.pdf", status: "failed", type: "file" },
+			],
+		};
+
+		const modelOutput = createWorkspaceReadItemsModelOutput(output);
+		expect(modelOutput.guidance).toHaveLength(2);
+		expect(modelOutput.guidance?.[0]).toContain("still extracting");
+		expect(modelOutput.guidance?.[1]).toContain("will not finish");
+	});
+
+	it("does not warn about empty pages once extraction is final", () => {
+		const output: WorkspaceReadItemsOutput = {
+			results: [
+				{
+					assetKind: "pdf",
+					content: "## Page 1",
+					emptyPages: [1],
+					format: "markdown",
+					itemId: "file-1",
+					location: { kind: "pages", requested: "1", returned: [1], total: 1 },
+					path: "/Book.pdf",
+					ref: "Yk7p2Qa9",
+					status: "ready",
+					type: "file",
+				},
+			],
+		};
+
+		expect(createWorkspaceReadItemsModelOutput(output)).not.toHaveProperty("guidance");
+	});
+});
diff --git a/src/features/workspaces/content/workspace-read-model-output.ts b/src/features/workspaces/content/workspace-read-model-output.ts
new file mode 100644
index 000000000..9bf100232
--- /dev/null
+++ b/src/features/workspaces/content/workspace-read-model-output.ts
@@ -0,0 +1,81 @@
+import type {
+	WorkspaceContentReadResult,
+	WorkspaceReadItemsOutput,
+} from "#/features/workspaces/content/workspace-content-contract";
+
+/**
+ * Guidance for read outcomes the model has to react to, keyed by situation.
+ *
+ * These live here rather than in the tool description because none of them
+ * change how a read is issued, and background extraction states are rare enough
+ * that every request should not carry the instructions for handling them.
+ */
+const workspaceReadGuidance = {
+	pending:
+		"Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. If an original file is attached, use it and do not read that path again in this reply. Otherwise, either do other work and read pending paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
+	unrecoverable:
+		"Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
+	transient:
+		"Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
+	provisional:
+		"Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
+} as const;
+
+/**
+ * Collects the handling guidance a set of read results calls for.
+ *
+ * Emitted once per situation rather than once per result so a batch of pending
+ * reads does not repeat the same paragraph for every path.
+ */
+function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
+	const situations = new Set<keyof typeof workspaceReadGuidance>();
+
+	for (const result of results) {
+		if (result.status === "pending") {
+			situations.add("pending");
+			continue;
+		}
+
+		if (result.status === "failed") {
+			if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
+				situations.add("unrecoverable");
+			} else if (result.code === "projection_failed") {
+				situations.add("transient");
+			}
+			continue;
+		}
+
+		// Gate on provisional only: emptyPages on a final (non-provisional) read
+		// describes genuinely blank pages, which must not be reported as still
+		// extracting or the model retries a completed read forever.
+		if (result.type === "file" && result.provisional) {
+			situations.add("provisional");
+		}
+	}
+
+	return (Object.keys(workspaceReadGuidance) as Array<keyof typeof workspaceReadGuidance>)
+		.filter((situation) => situations.has(situation))
+		.map((situation) => workspaceReadGuidance[situation]);
+}
+
+/**
+ * Projects a rich workspace read result into the model-visible JSON.
+ *
+ * The results already carry self-describing addresses, so the only work left
+ * is dropping the internal item id and attaching guidance for outcomes that
+ * need handling.
+ */
+export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOutput) {
+	const guidance = createWorkspaceReadGuidance(output.results);
+
+	return {
+		...(guidance.length > 0 ? { guidance } : {}),
+		results: output.results.map(omitWorkspaceReadItemId),
+	};
+}
+
+function omitWorkspaceReadItemId<T extends object>(result: T): Omit<T, "itemId"> {
+	const { itemId: _itemId, ...modelResult } = result as T & { itemId?: string };
+
+	return modelResult;
+}
diff --git a/src/features/workspaces/content/workspace-read-references.test.ts b/src/features/workspaces/content/workspace-read-references.test.ts
deleted file mode 100644
index 4fca8c2d8..000000000
--- a/src/features/workspaces/content/workspace-read-references.test.ts
+++ /dev/null
@@ -1,274 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import type {
-	WorkspaceContentReadResult,
-	WorkspaceReadItemsOutput,
-} from "#/features/workspaces/content/workspace-content-contract";
-import {
-	createWorkspaceReadItemsModelOutput,
-	createWorkspaceReadReferences,
-} from "#/features/workspaces/content/workspace-read-references";
-
-describe("workspace read references", () => {
-	it("gives document blocks and extracted pages one transcript-backed ref each", () => {
-		const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
-		const references = createWorkspaceReadReferences(results);
-
-		expect(references).toHaveLength(3);
-		expect(references.map(({ location }) => location)).toEqual([
-			{
-				blockId: "b_abcdefghijkl",
-				itemId: "document-1",
-				kind: "document-block",
-				version: 1,
-			},
-			{ itemId: "file-1", kind: "pdf-page", pageNumber: 12, version: 1 },
-			{ itemId: "file-1", kind: "pdf-page", pageNumber: 13, version: 1 },
-		]);
-		expect(references.every(({ ref }) => /^wr_[0-9A-Za-z]{8}$/.test(ref))).toBe(true);
-	});
-
-	it("projects refs beside content without exposing durable item IDs", () => {
-		const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
-		const output: WorkspaceReadItemsOutput = {
-			references: createWorkspaceReadReferences(results),
-			results,
-		};
-		const modelOutput = createWorkspaceReadItemsModelOutput(output);
-		const document = modelOutput.results[0];
-		const file = modelOutput.results[1];
-
-		expect(document).toMatchObject({
-			content: expect.stringMatching(/data-ref="wr_[0-9A-Za-z]{8}"/),
-			path: "/Notes",
-			status: "ready",
-			type: "document",
-		});
-		expect(file).toMatchObject({
-			status: "ready",
-			type: "file",
-		});
-		expect(file).not.toHaveProperty("pageReferences");
-		expect(file && "content" in file ? file.content : "").toMatch(
-			/^## Page 12 \[ref: wr_[0-9A-Za-z]{8}\]$/m,
-		);
-		expect(file && "content" in file ? file.content : "").toMatch(
-			/^## Page 13 \[ref: wr_[0-9A-Za-z]{8}\]$/m,
-		);
-		expect(JSON.stringify(modelOutput)).not.toContain("document-1");
-		expect(JSON.stringify(modelOutput)).not.toContain("file-1");
-	});
-
-	it("gives each flashcard one ref for editing, citation, and navigation", () => {
-		const results = [flashcardResult()] satisfies WorkspaceContentReadResult[];
-		const references = createWorkspaceReadReferences(results);
-		const modelOutput = createWorkspaceReadItemsModelOutput({ references, results });
-
-		expect(references.map(({ location }) => location)).toEqual([
-			{
-				cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
-				itemId: "flashcard-1",
-				kind: "flashcard",
-				version: 1,
-			},
-		]);
-		expect(modelOutput.results[0]).toMatchObject({
-			cards: [
-				{
-					back: "<p>Paris</p>",
-					front: "<p>Capital of France?</p>",
-					ref: expect.stringMatching(/^wr_[0-9A-Za-z]{8}$/),
-				},
-			],
-			path: "/Geography",
-			progress: { gotItCount: 1, missedCount: 0, reviewedCount: 1 },
-			type: "flashcard",
-		});
-		expect(JSON.stringify(modelOutput)).not.toContain("flashcard-1");
-	});
-
-	it("deduplicates repeated reads of the same durable location in one result", () => {
-		const references = createWorkspaceReadReferences([
-			documentResult(),
-			{ ...documentResult(), content: "continued" },
-		]);
-
-		expect(references).toHaveLength(1);
-	});
-
-	it("uses an item ref for extracted images that have no page-navigation surface", () => {
-		const image = {
-			...fileResult(),
-			assetKind: "image",
-			itemId: "image-1",
-			path: "/Diagram.png",
-		} satisfies Extract<WorkspaceContentReadResult, { status: "ready"; type: "file" }>;
-		const references = createWorkspaceReadReferences([image]);
-		const modelOutput = createWorkspaceReadItemsModelOutput({
-			references,
-			results: [image],
-		});
-
-		expect(references).toMatchObject([
-			{ location: { itemId: "image-1", kind: "item", version: 1 } },
-		]);
-		expect(modelOutput.results[0]).toMatchObject({
-			assetKind: "image",
-			ref: expect.stringMatching(/^wr_[0-9A-Za-z]{8}$/),
-		});
-		expect(modelOutput.results[0]).not.toHaveProperty("pageReferences");
-	});
-
-	it("stays silent when every read succeeded outright", () => {
-		const results = [documentResult(), fileResult()] satisfies WorkspaceContentReadResult[];
-
-		expect(
-			createWorkspaceReadItemsModelOutput({
-				references: createWorkspaceReadReferences(results),
-				results,
-			}),
-		).not.toHaveProperty("guidance");
-	});
-
-	it("explains a pending read once however many paths are waiting", () => {
-		const results = [
-			{
-				elapsedSeconds: 4,
-				itemId: "file-a",
-				path: "/A.pdf",
-				phase: "extracting",
-				retryAfterSeconds: 15,
-				status: "pending",
-				type: "file",
-			},
-			{
-				elapsedSeconds: 0,
-				path: "/B.pdf",
-				phase: "queued",
-				retryAfterSeconds: 15,
-				status: "pending",
-				type: "file",
-			},
-		] satisfies WorkspaceContentReadResult[];
-		const modelOutput = createWorkspaceReadItemsModelOutput({ references: [], results });
-		const { guidance } = modelOutput;
-
-		expect(guidance).toHaveLength(1);
-		expect(guidance?.[0]).toContain("Never sleep");
-		expect(JSON.stringify(modelOutput)).not.toContain("file-a");
-	});
-
-	it("separates failures that will never resolve from transient ones", () => {
-		const results = [
-			{ code: "extraction_failed", path: "/A.pdf", status: "failed", type: "file" },
-			{ code: "extraction_stalled", path: "/B.pdf", status: "failed", type: "file" },
-			{ code: "projection_failed", path: "/C.pdf", status: "failed", type: "file" },
-		] satisfies WorkspaceContentReadResult[];
-		const guidance = createWorkspaceReadItemsModelOutput({ references: [], results }).guidance;
-
-		expect(guidance).toHaveLength(2);
-		expect(guidance?.[0]).toContain("do not suggest re-uploading");
-		expect(guidance?.[1]).toContain("One repeat read is reasonable");
-	});
-
-	it("says nothing about failures that are the caller's own mistake", () => {
-		const results = [
-			{ code: "path_not_found", path: "/Missing.pdf", status: "failed" },
-		] satisfies WorkspaceContentReadResult[];
-
-		expect(createWorkspaceReadItemsModelOutput({ references: [], results })).not.toHaveProperty(
-			"guidance",
-		);
-	});
-
-	it("warns that blank pages from the fast pass are not final", () => {
-		const results = [
-			{ ...fileResult(), emptyPages: [13], provisional: true },
-		] satisfies WorkspaceContentReadResult[];
-		const guidance = createWorkspaceReadItemsModelOutput({
-			references: createWorkspaceReadReferences(results),
-			results,
-		}).guidance;
-
-		expect(guidance).toHaveLength(1);
-		expect(guidance?.[0]).toContain("still extracting");
-	});
-
-	it("stays silent about blank pages on a final, non-provisional read", () => {
-		const results = [{ ...fileResult(), emptyPages: [13] }] satisfies WorkspaceContentReadResult[];
-
-		expect(
-			createWorkspaceReadItemsModelOutput({
-				references: createWorkspaceReadReferences(results),
-				results,
-			}),
-		).not.toHaveProperty("guidance");
-	});
-});
-
-function documentResult(): Extract<
-	WorkspaceContentReadResult,
-	{ status: "ready"; type: "document" }
-> {
-	return {
-		content: '<h1 data-ref="b_abcdefghijkl.r_0123456789">Notes</h1>',
-		format: "html",
-		itemId: "document-1",
-		location: { endBlock: 1, kind: "blocks", startBlock: 1, totalBlocks: 1 },
-		path: "/Notes",
-		status: "ready",
-		type: "document",
-	};
-}
-
-function fileResult(): Extract<WorkspaceContentReadResult, { status: "ready"; type: "file" }> {
-	return {
-		assetKind: "pdf",
-		content: "## Page 12\n\nAlpha\n\n## Page 13\n\nBeta",
-		format: "markdown",
-		itemId: "file-1",
-		location: {
-			kind: "pages",
-			requested: "12-13",
-			returned: [12, 13],
-			total: 20,
-		},
-		path: "/Book.pdf",
-		status: "ready",
-		type: "file",
-	};
-}
-
-function flashcardResult(): Extract<
-	WorkspaceContentReadResult,
-	{ status: "ready"; type: "flashcard" }
-> {
-	return {
-		cards: [
-			{
-				back: "<p>Paris</p>",
-				cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
-				revision: "0123456789",
-				front: "<p>Capital of France?</p>",
-				study: {
-					lastRating: "good",
-					lastReviewedAt: "2026-08-13T12:00:00.000Z",
-					reviewCount: 1,
-				},
-			},
-		],
-		format: "html",
-		itemId: "flashcard-1",
-		location: { kind: "cards", returned: [1], total: 1 },
-		path: "/Geography",
-		progress: {
-			gotItCount: 1,
-			missedCount: 0,
-			reviewedCount: 1,
-			totalCards: 1,
-			unreviewedCount: 0,
-		},
-		status: "ready",
-		type: "flashcard",
-	};
-}
diff --git a/src/features/workspaces/content/workspace-read-references.ts b/src/features/workspaces/content/workspace-read-references.ts
deleted file mode 100644
index 29cf6ad9c..000000000
--- a/src/features/workspaces/content/workspace-read-references.ts
+++ /dev/null
@@ -1,268 +0,0 @@
-import {
-	createWorkspaceReferenceRecords,
-	getWorkspaceLocationKey,
-	type WorkspaceLocation,
-	type WorkspaceReference,
-	type WorkspaceReferenceRecord,
-} from "#/features/workspaces/locations/workspace-location";
-import {
-	parseDocumentAiRef,
-	readDocumentAiRefs,
-	readDocumentAiRefRevision,
-} from "#/features/workspaces/documents/document-ai-html";
-import type {
-	WorkspaceContentReadResult,
-	WorkspaceReadItemsOutput,
-} from "#/features/workspaces/content/workspace-content-contract";
-
-/**
- * Allocates durable-location records for every ready workspace read.
- *
- * Editable blocks and cards retain a revision with their durable location.
- * PDFs receive one location per physical page; other files use the item.
- *
- * @param results - Ordered workspace read results.
- * @returns Deduplicated reference records for the rich tool result.
- */
-export function createWorkspaceReadReferences(
-	results: readonly WorkspaceContentReadResult[],
-): WorkspaceReferenceRecord[] {
-	const targets: Array<WorkspaceLocation | { location: WorkspaceLocation; revision: string }> = [];
-
-	for (const result of results) {
-		if (result.status !== "ready") {
-			continue;
-		}
-		if (result.type === "flashcard") {
-			for (const card of result.cards) {
-				targets.push({
-					location: {
-						itemId: result.itemId,
-						kind: "flashcard",
-						cardId: card.cardId,
-						version: 1,
-					},
-					revision: card.revision,
-				});
-			}
-			continue;
-		}
-		if (result.type === "document" || result.type === "block") {
-			const contentRefs =
-				result.type === "block" ? [result.contentRef] : readDocumentAiRefs(result.content);
-			for (const contentRef of contentRefs) {
-				const blockId = parseDocumentAiRef(contentRef);
-				const revision = readDocumentAiRefRevision(contentRef);
-				if (!blockId || !revision)
-					throw new Error("Document read returned an invalid content ref.");
-				targets.push({
-					location: { blockId, itemId: result.itemId, kind: "document-block", version: 1 },
-					revision,
-				});
-			}
-			continue;
-		}
-
-		if (result.type !== "file" || result.assetKind !== "pdf") {
-			targets.push({
-				itemId: result.itemId,
-				kind: "item",
-				version: 1,
-			});
-			continue;
-		}
-
-		for (const pageNumber of result.location.returned) {
-			targets.push({
-				itemId: result.itemId,
-				kind: "pdf-page",
-				pageNumber,
-				version: 1,
-			});
-		}
-	}
-
-	return createWorkspaceReferenceRecords(targets);
-}
-
-/**
- * Guidance for read outcomes the model has to react to, keyed by situation.
- *
- * These live here rather than in the tool description because none of them
- * change how a read is issued, and background extraction states are rare enough
- * that every request should not carry the instructions for handling them.
- */
-const workspaceReadGuidance = {
-	pending:
-		"Some paths are still extracting. Never sleep, poll, or otherwise stall waiting for them, including inside compute, sandbox_bash, or orchestrate. If an original file is attached, use it and do not read that path again in this reply. Otherwise, either do other work and read pending paths again later in this reply, or tell the user they are still processing and to ask again in about retryAfterSeconds. Never read the same pending path more than twice in one reply.",
-	unrecoverable:
-		"Extraction will not finish for some paths. Report the code and any message to the user; do not retry those reads and do not suggest re-uploading the file.",
-	transient:
-		"Some paths failed on a transient storage problem. One repeat read is reasonable; if it fails again, tell the user.",
-	provisional:
-		"Some content came from a fast first pass. Pages listed in emptyPages are still extracting, so read them again later rather than reporting them as blank.",
-} as const;
-
-/**
- * Collects the handling guidance a set of read results calls for.
- *
- * Emitted once per situation rather than once per result so a batch of pending
- * reads does not repeat the same paragraph for every path.
- *
- * @param results - Ordered workspace read results.
- * @returns Guidance lines for the situations present, most actionable first.
- */
-function createWorkspaceReadGuidance(results: readonly WorkspaceContentReadResult[]): string[] {
-	const situations = new Set<keyof typeof workspaceReadGuidance>();
-
-	for (const result of results) {
-		if (result.status === "pending") {
-			situations.add("pending");
-			continue;
-		}
-
-		if (result.status === "failed") {
-			if (result.code === "extraction_failed" || result.code === "extraction_stalled") {
-				situations.add("unrecoverable");
-			} else if (result.code === "projection_failed") {
-				situations.add("transient");
-			}
-			continue;
-		}
-
-		// Gate on provisional only: emptyPages on a final (non-provisional) read
-		// describes genuinely blank pages, which must not be reported as still
-		// extracting or the model retries a completed read forever.
-		if (result.type === "file" && result.provisional) {
-			situations.add("provisional");
-		}
-	}
-
-	return (Object.keys(workspaceReadGuidance) as Array<keyof typeof workspaceReadGuidance>)
-		.filter((situation) => situations.has(situation))
-		.map((situation) => workspaceReadGuidance[situation]);
-}
-
-/**
- * Projects a rich workspace read result into compact model-visible JSON.
- *
- * Raw item IDs and durable locations remain in the persisted tool result.
- * Model-visible content receives only opaque refs next to the content they
- * identify, plus guidance for any outcome that needs handling.
- *
- * @param output - Validated rich workspace read output.
- * @returns JSON-safe results annotated with short workspace refs.
- */
-export function createWorkspaceReadItemsModelOutput(output: WorkspaceReadItemsOutput) {
-	const refsByLocation = new Map(
-		output.references.map((record) => [getWorkspaceLocationKey(record.location), record.ref]),
-	);
-	const refFor = (location: WorkspaceLocation) =>
-		refsByLocation.get(getWorkspaceLocationKey(location));
-	const guidance = createWorkspaceReadGuidance(output.results);
-
-	return {
-		...(guidance.length > 0 ? { guidance } : {}),
-		results: output.results.map((result) => {
-			if (result.status === "pending") {
-				return omitWorkspaceReadItemId(result);
-			}
-
-			if (result.status === "failed") {
-				return result;
-			}
-			if (result.type === "flashcard") {
-				return {
-					...omitWorkspaceReadItemId(result),
-					cards: result.cards.map(({ cardId, revision: _revision, ...card }) => ({
-						...card,
-						ref: refFor({ itemId: result.itemId, kind: "flashcard", cardId, version: 1 }),
-					})),
-				};
-			}
-			if (result.type === "document") {
-				return {
-					...omitWorkspaceReadItemId(result),
-					content: replaceDocumentContentRefs(result, refsByLocation),
-				};
-			}
-			if (result.type === "block") {
-				const blockId = parseDocumentAiRef(result.contentRef);
-				const ref = blockId
-					? refFor({ blockId, itemId: result.itemId, kind: "document-block", version: 1 })
-					: undefined;
-				const { contentRef: _contentRef, itemId: _itemId, ...modelResult } = result;
-				return { ...modelResult, ...(ref ? { ref } : {}) };
-			}
-
-			if (result.type !== "file" || result.assetKind !== "pdf") {
-				const ref = refFor({ itemId: result.itemId, kind: "item", version: 1 });
-
-				return {
-					...omitWorkspaceReadItemId(result),
-					...(ref ? { ref } : {}),
-				};
-			}
-
-			const references = result.location.returned.flatMap((pageNumber) => {
-				const ref = refFor({
-					itemId: result.itemId,
-					kind: "pdf-page",
-					pageNumber,
-					version: 1,
-				});
-
-				return ref ? [{ pageNumber, ref }] : [];
-			});
-
-			return {
-				...omitWorkspaceReadItemId(result),
-				content: annotateWorkspaceReadPageHeadings(result.content, references),
-			};
-		}),
-	};
-}
-
-function replaceDocumentContentRefs(
-	result: Extract<WorkspaceContentReadResult, { status: "ready"; type: "document" }>,
-	refsByLocation: ReadonlyMap<string, WorkspaceReference>,
-) {
-	return result.content.replace(/data-ref="([^"]+)"/g, (attribute, contentRef: string) => {
-		const blockId = parseDocumentAiRef(contentRef);
-		if (!blockId) return attribute;
-		const ref = refsByLocation.get(
-			getWorkspaceLocationKey({
-				blockId,
-				itemId: result.itemId,
-				kind: "document-block",
-				version: 1,
-			}),
-		);
-		return ref ? `data-ref="${ref}"` : attribute;
-	});
-}
-
-function omitWorkspaceReadItemId<T extends { readonly itemId?: string }>(
-	result: T,
-): Omit<T, "itemId"> {
-	const { itemId: _itemId, ...modelResult } = result;
-
-	return modelResult;
-}
-
-function annotateWorkspaceReadPageHeadings(
-	content: string,
-	references: readonly { readonly pageNumber: number; readonly ref: WorkspaceReference }[],
-) {
-	const refsByPage = new Map(references.map(({ pageNumber, ref }) => [pageNumber, ref]));
-
-	return content.replace(/^## Page (\d+)[ \t]*$/gm, (heading, pageNumberText: string) => {
-		const pageNumber = Number(pageNumberText);
-		const ref = refsByPage.get(pageNumber);
-		if (!ref) {
-			return heading;
-		}
-
-		return `${heading} [ref: ${ref}]`;
-	});
-}
diff --git a/src/features/workspaces/contracts.ts b/src/features/workspaces/contracts.ts
index eca9d943f..f0b357b73 100644
--- a/src/features/workspaces/contracts.ts
+++ b/src/features/workspaces/contracts.ts
@@ -364,6 +364,7 @@ export const workspaceItemSchema = z.object({
 	parentId: z.string().nullable(),
 	type: workspaceItemTypeSchema,
 	name: z.string(),
+	refKey: z.string(),
 	color: z.string().nullable(),
 	metadataJson: z.record(z.string(), jsonValueSchema),
 	sortOrder: z.number(),
diff --git a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
index 212ddfb74..07b7215dc 100644
--- a/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
+++ b/src/features/workspaces/documents/code-block-shiki/CodeBlockNodeView.tsx
@@ -13,18 +13,56 @@ import {
 	CodeBlockLanguageSelectorValue,
 	CodeBlockTitle,
 } from "#/components/code-block/code-block-chrome";
+import { MermaidDiagram } from "#/components/code-block/mermaid-diagram";
 import {
 	codeLanguageOptions,
 	getCodeLanguageLabel,
+	isMermaidCodeLanguage,
 	normalizeCodeLanguage,
 	type SupportedCodeLanguage,
 } from "#/features/workspaces/documents/code-block-shiki/highlighter";
 
-export function CodeBlockNodeView({ node, updateAttributes }: ReactNodeViewProps) {
+export function CodeBlockNodeView({
+	editor,
+	getPos,
+	node,
+	selected,
+	updateAttributes,
+}: ReactNodeViewProps) {
 	const language = normalizeCodeLanguage(node.attrs.language as string | null);
 	const code = node.textContent;
 	const codeLanguage = language ?? "text";
 
+	/**
+	 * A diagram is only ever the drawing, never the mermaid source that made
+	 * it. Nobody hand-writes that syntax — the assistant authors and edits it —
+	 * so a click selects the whole block to move or delete, the way an image
+	 * behaves. The content stays mounted but hidden because ProseMirror still
+	 * needs somewhere to keep the node's text.
+	 */
+	if (isMermaidCodeLanguage(node.attrs.language as string | null)) {
+		return (
+			<NodeViewWrapper
+				className="workspace-document-diagram"
+				contentEditable={false}
+				data-selected={selected ? "true" : undefined}
+				onClick={() => {
+					const position = getPos();
+					if (position !== undefined && editor.isEditable) {
+						// Focus first: a click on non-editable content leaves the
+						// editor blurred, and an unfocused selection ignores Backspace.
+						editor.chain().focus().setNodeSelection(position).run();
+					}
+				}}
+			>
+				<MermaidDiagram source={code} />
+				{/* Same bargain as a widget's source: ProseMirror has to render the
+				    node's text somewhere, and the drawing is its visible form. */}
+				<NodeViewContent className="workspace-document-diagram-source" />
+			</NodeViewWrapper>
+		);
+	}
+
 	return (
 		<NodeViewWrapper
 			className="workspace-document-code-block"
@@ -33,32 +71,38 @@ export function CodeBlockNodeView({ node, updateAttributes }: ReactNodeViewProps
 		>
 			<CodeBlockHeader className="workspace-document-code-block-header" contentEditable={false}>
 				<CodeBlockTitle>
-					<CodeBlockLanguageSelector
-						value={language ?? "plain"}
-						onValueChange={(value) => {
-							updateAttributes({
-								language: value === "plain" ? null : (value as SupportedCodeLanguage),
-							});
-						}}
-					>
-						<CodeBlockLanguageSelectorTrigger aria-label="Code language">
-							<CodeBlockLanguageSelectorValue>
-								{(value: string | null) =>
-									value === "plain" ? "Plain text" : getCodeLanguageLabel(value)
-								}
-							</CodeBlockLanguageSelectorValue>
-						</CodeBlockLanguageSelectorTrigger>
-						<CodeBlockLanguageSelectorContent className="min-w-44">
-							<CodeBlockLanguageSelectorItem value="plain">
-								Plain text
-							</CodeBlockLanguageSelectorItem>
-							{codeLanguageOptions.map((option) => (
-								<CodeBlockLanguageSelectorItem key={option.value} value={option.value}>
-									{option.label}
+					{/* Study viewers render this node view read-only, where the
+					    language is a fact to show, not a setting to change. */}
+					{editor.isEditable ? (
+						<CodeBlockLanguageSelector
+							value={language ?? "plain"}
+							onValueChange={(value) => {
+								updateAttributes({
+									language: value === "plain" ? null : (value as SupportedCodeLanguage),
+								});
+							}}
+						>
+							<CodeBlockLanguageSelectorTrigger aria-label="Code language">
+								<CodeBlockLanguageSelectorValue>
+									{(value: string | null) =>
+										value === "plain" ? "Plain text" : getCodeLanguageLabel(value)
+									}
+								</CodeBlockLanguageSelectorValue>
+							</CodeBlockLanguageSelectorTrigger>
+							<CodeBlockLanguageSelectorContent className="min-w-44">
+								<CodeBlockLanguageSelectorItem value="plain">
+									Plain text
 								</CodeBlockLanguageSelectorItem>
-							))}
-						</CodeBlockLanguageSelectorContent>
-					</CodeBlockLanguageSelector>
+								{codeLanguageOptions.map((option) => (
+									<CodeBlockLanguageSelectorItem key={option.value} value={option.value}>
+										{option.label}
+									</CodeBlockLanguageSelectorItem>
+								))}
+							</CodeBlockLanguageSelectorContent>
+						</CodeBlockLanguageSelector>
+					) : (
+						getCodeLanguageLabel(language)
+					)}
 				</CodeBlockTitle>
 				<CodeBlockActions>
 					<CodeBlockDownloadButton code={code} language={codeLanguage} />
diff --git a/src/features/workspaces/documents/code-block-shiki/code-languages.ts b/src/features/workspaces/documents/code-block-shiki/code-languages.ts
index c0cf0154d..a551c6161 100644
--- a/src/features/workspaces/documents/code-block-shiki/code-languages.ts
+++ b/src/features/workspaces/documents/code-block-shiki/code-languages.ts
@@ -118,6 +118,16 @@ export const codeLanguageOptions: CodeLanguageOption[] = codeLanguageDefinitions
 	({ label, value }) => ({ label, value }),
 );
 
+/**
+ * Mermaid is deliberately not one of the languages above. It is never syntax
+ * highlighted, never offered in the language picker, and never read as source
+ * — every surface draws it instead — so registering a grammar for it would
+ * only ship a parser nothing looks at.
+ */
+export function isMermaidCodeLanguage(language: string | null | undefined) {
+	return language?.trim().toLowerCase() === "mermaid";
+}
+
 export const supportedCodeFileExtensions = [
 	...new Set(codeLanguageDefinitionList.flatMap((definition) => definition.extensions ?? [])),
 ].sort((left, right) => left.localeCompare(right));
diff --git a/src/features/workspaces/documents/code-block-shiki/highlighter.ts b/src/features/workspaces/documents/code-block-shiki/highlighter.ts
index 26d4c3e72..4fe9a7a9f 100644
--- a/src/features/workspaces/documents/code-block-shiki/highlighter.ts
+++ b/src/features/workspaces/documents/code-block-shiki/highlighter.ts
@@ -13,6 +13,7 @@ import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
 export {
 	codeLanguageOptions,
 	getCodeLanguageLabel,
+	isMermaidCodeLanguage,
 	normalizeCodeLanguage,
 	type CodeLanguageOption,
 	type SupportedCodeLanguage,
diff --git a/src/features/workspaces/documents/document-ai-edits.test.ts b/src/features/workspaces/documents/document-ai-edits.test.ts
index b96e55cbe..ff169c92c 100644
--- a/src/features/workspaces/documents/document-ai-edits.test.ts
+++ b/src/features/workspaces/documents/document-ai-edits.test.ts
@@ -103,7 +103,7 @@ describe("document AI edits", () => {
 
 		expect(rewritten.document.content?.at(-1)).toMatchObject({ type: "paragraph" });
 		expect(await serializeTiptapDocumentToAiHtml(rewritten.document)).toMatch(
-			/<\/ul><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"><\/p>$/,
+			/<\/ul><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}"><\/p>$/,
 		);
 	});
 
diff --git a/src/features/workspaces/documents/document-ai-edits.ts b/src/features/workspaces/documents/document-ai-edits.ts
index ce6b67fa4..56dc7e6b1 100644
--- a/src/features/workspaces/documents/document-ai-edits.ts
+++ b/src/features/workspaces/documents/document-ai-edits.ts
@@ -19,9 +19,9 @@ import {
 	type TiptapDocumentJson,
 } from "#/features/workspaces/documents/tiptap-document";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
-import { workspaceReferenceInputSchema } from "#/features/workspaces/locations/workspace-location";
+import { workspaceUnitRefInputSchema } from "#/features/workspaces/locations/workspace-location";
 
-const documentRefSchema = workspaceReferenceInputSchema.describe(
+const documentRefSchema = workspaceUnitRefInputSchema.describe(
 	"Exact ref from a recent document or block read.",
 );
 export const documentAiHtmlSchema = z
diff --git a/src/features/workspaces/documents/document-ai-html.test.ts b/src/features/workspaces/documents/document-ai-html.test.ts
index ffa56fc44..06c3fc0ea 100644
--- a/src/features/workspaces/documents/document-ai-html.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.test.ts
@@ -19,7 +19,7 @@ describe("document AI HTML", () => {
 		).document;
 		const html = await serializeTiptapDocumentToAiHtml(document);
 
-		expect(html).toMatch(/^<h1 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Notes<\/h1>/);
+		expect(html).toMatch(/^<h1 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}">Notes<\/h1>/);
 		expect(html).toContain("<strong>bold</strong>");
 		expect(html).toContain('data-type="inline-math"');
 		expect(html).toContain('data-type="taskItem"');
@@ -47,7 +47,7 @@ describe("document AI HTML", () => {
 		);
 
 		expect(html).not.toContain("b_modelchosen1");
-		expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}"/);
+		expect(html).toMatch(/data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}"/);
 	});
 
 	it("normalizes malformed but recoverable HTML", () => {
diff --git a/src/features/workspaces/documents/document-ai-html.ts b/src/features/workspaces/documents/document-ai-html.ts
index cb22531a0..6eeafeffb 100644
--- a/src/features/workspaces/documents/document-ai-html.ts
+++ b/src/features/workspaces/documents/document-ai-html.ts
@@ -16,7 +16,7 @@ import { sha256Base64UrlText } from "#/lib/binary";
 
 const TEXT_NODE = 3;
 const documentBlockIdPattern = /^b_[A-Za-z0-9_-]{12}$/;
-const documentAiRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_([A-Za-z0-9_-]{10})$/;
+const documentAiRefPattern = /^(b_[A-Za-z0-9_-]{12})\.r_([A-Za-z0-9_-]{6})$/;
 export class DocumentAiHtmlError extends Error {}
 export class WidgetScriptSyntaxError extends DocumentAiHtmlError {}
 
@@ -108,7 +108,7 @@ export async function createDocumentAiRef(node: ProseMirrorNode) {
 	// second DOM pass per block per read, and the ref only has to change when
 	// the block's content does.
 	const content = JSON.stringify(withTiptapNodeAiRef(node, null).toJSON());
-	const revision = (await sha256Base64UrlText(content)).slice(0, 10);
+	const revision = (await sha256Base64UrlText(content)).slice(0, 6);
 	return `${blockId}.r_${revision}`;
 }
 
@@ -116,16 +116,6 @@ export function parseDocumentAiRef(ref: string) {
 	return documentAiRefPattern.exec(ref)?.[1] ?? null;
 }
 
-export function readDocumentAiRefRevision(ref: string) {
-	return documentAiRefPattern.exec(ref)?.[2] ?? null;
-}
-
-export function readDocumentAiRefs(html: string) {
-	return Array.from(html.matchAll(/\sdata-ref="([^"]+)"/g), (match) => match[1]!).filter((ref) =>
-		documentAiRefPattern.test(ref),
-	);
-}
-
 export function ensureTiptapDocumentBlockIds(document: TiptapDocumentJson): {
 	changed: boolean;
 	document: TiptapDocumentJson;
@@ -375,6 +365,9 @@ export function applyDocumentCitationLocations(
 			case "flashcard":
 				element.setAttribute("data-card-id", location.cardId);
 				break;
+			case "quiz-question":
+				element.setAttribute("data-question-id", location.questionId);
+				break;
 		}
 	}
 
diff --git a/src/features/workspaces/documents/document-ai-html.worker.test.ts b/src/features/workspaces/documents/document-ai-html.worker.test.ts
index 2741508f7..2b755a809 100644
--- a/src/features/workspaces/documents/document-ai-html.worker.test.ts
+++ b/src/features/workspaces/documents/document-ai-html.worker.test.ts
@@ -13,7 +13,7 @@ describe("document AI HTML in Workers", () => {
 		).document;
 
 		expect(await serializeTiptapDocumentToAiHtml(document)).toMatch(
-			/^<h2 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Worker<\/h2><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{10}">Schema-safe HTML<\/p>$/,
+			/^<h2 data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}">Worker<\/h2><p data-ref="b_[A-Za-z0-9_-]{12}\.r_[A-Za-z0-9_-]{6}">Schema-safe HTML<\/p>$/,
 		);
 	});
 });
diff --git a/src/features/workspaces/documents/document-html-chunk.ts b/src/features/workspaces/documents/document-html-chunk.ts
index 0810bda1d..9d1991cee 100644
--- a/src/features/workspaces/documents/document-html-chunk.ts
+++ b/src/features/workspaces/documents/document-html-chunk.ts
@@ -17,18 +17,19 @@ export interface DocumentHtmlChunk {
 }
 
 export interface DocumentHtmlChunkReadInput {
-	expectedRevision?: string;
 	offset: number;
+	/** Stop after this many blocks even if the character budget has room. */
+	maxBlocks?: number;
 }
 
 export type DocumentHtmlChunkReadResult =
-	| { status: "content_changed" }
 	| { status: "invalid_offset" }
-	| ({ revision: string; status: "ready" } & DocumentHtmlChunk);
+	| ({ status: "ready" } & DocumentHtmlChunk);
 
 export async function readDocumentHtmlChunk(
 	document: ProseMirrorNode,
 	offset: number,
+	maxBlocks?: number,
 ): Promise<DocumentHtmlChunk | undefined> {
 	if (offset < 0 || offset >= document.childCount) {
 		return undefined;
@@ -38,6 +39,7 @@ export async function readDocumentHtmlChunk(
 	let characters = 0;
 	let endOffset = offset;
 	while (endOffset < document.childCount) {
+		if (maxBlocks !== undefined && endOffset - offset >= maxBlocks) break;
 		const block = await serializeTiptapNodeToAiHtml(document.child(endOffset));
 		const separatorCharacters = content.length > 0 ? 1 : 0;
 		if (
diff --git a/src/features/workspaces/documents/document-session.ts b/src/features/workspaces/documents/document-session.ts
index 3b8c63c69..98049c238 100644
--- a/src/features/workspaces/documents/document-session.ts
+++ b/src/features/workspaces/documents/document-session.ts
@@ -51,7 +51,7 @@ import {
 	commitWorkspaceDocumentCheckpoint,
 	readWorkspaceDocumentCheckpoint,
 } from "#/features/workspaces/persistence/workspace-document-checkpoints";
-import { sha256Base64Url, sha256Base64UrlText } from "#/lib/binary";
+import { sha256Base64UrlText } from "#/lib/binary";
 
 const persistedYDocUpdateKey = "document-session:yjs-update";
 const latestDocumentEditReceiptKey = "document-session:ai-edit-receipt:latest";
@@ -354,14 +354,10 @@ export class DocumentSession extends YServer {
 
 	async readHtmlChunk(input: DocumentHtmlChunkReadInput): Promise<DocumentHtmlChunkReadResult> {
 		this.assertActive();
-		const { document, stateVector } = await this.getReferencedDocumentSnapshot();
-		const revision = await sha256Base64Url(stateVector);
-		if (input.expectedRevision && input.expectedRevision !== revision) {
-			return { status: "content_changed" };
-		}
+		const { document } = await this.getReferencedDocumentSnapshot();
 
-		const chunk = await readDocumentHtmlChunk(document, input.offset);
-		return chunk ? { ...chunk, revision, status: "ready" } : { status: "invalid_offset" };
+		const chunk = await readDocumentHtmlChunk(document, input.offset, input.maxBlocks);
+		return chunk ? { ...chunk, status: "ready" } : { status: "invalid_offset" };
 	}
 
 	/**
diff --git a/src/features/workspaces/documents/tiptap-schema.ts b/src/features/workspaces/documents/tiptap-schema.ts
index fe794b81e..fdf78a852 100644
--- a/src/features/workspaces/documents/tiptap-schema.ts
+++ b/src/features/workspaces/documents/tiptap-schema.ts
@@ -34,6 +34,7 @@ export const Citation = Node.create({
 			itemId: { default: null, parseHTML: (el) => el.getAttribute("data-item-id") },
 			blockId: { default: null, parseHTML: (el) => el.getAttribute("data-block-id") },
 			cardId: { default: null, parseHTML: (el) => el.getAttribute("data-card-id") },
+			questionId: { default: null, parseHTML: (el) => el.getAttribute("data-question-id") },
 			pageNumber: {
 				default: null,
 				parseHTML: (el) => {
@@ -55,6 +56,7 @@ export const Citation = Node.create({
 				"data-item-id": node.attrs.itemId,
 				...(node.attrs.blockId ? { "data-block-id": String(node.attrs.blockId) } : {}),
 				...(node.attrs.cardId ? { "data-card-id": String(node.attrs.cardId) } : {}),
+				...(node.attrs.questionId ? { "data-question-id": String(node.attrs.questionId) } : {}),
 				...(node.attrs.pageNumber ? { "data-page": String(node.attrs.pageNumber) } : {}),
 			},
 		];
@@ -67,13 +69,15 @@ export function getWorkspaceCitationLocation(
 	const itemId = typeof attrs.itemId === "string" ? attrs.itemId : null;
 	if (!itemId) return undefined;
 
-	const location = attrs.cardId
-		? { cardId: attrs.cardId, itemId, kind: "flashcard", version: 1 }
-		: attrs.blockId
-			? { blockId: attrs.blockId, itemId, kind: "document-block", version: 1 }
-			: attrs.pageNumber
-				? { itemId, kind: "pdf-page", pageNumber: attrs.pageNumber, version: 1 }
-				: { itemId, kind: "item", version: 1 };
+	const location = attrs.questionId
+		? { itemId, kind: "quiz-question", questionId: attrs.questionId, version: 1 }
+		: attrs.cardId
+			? { cardId: attrs.cardId, itemId, kind: "flashcard", version: 1 }
+			: attrs.blockId
+				? { blockId: attrs.blockId, itemId, kind: "document-block", version: 1 }
+				: attrs.pageNumber
+					? { itemId, kind: "pdf-page", pageNumber: attrs.pageNumber, version: 1 }
+					: { itemId, kind: "item", version: 1 };
 	const parsed = workspaceLocationSchema.safeParse(location);
 
 	return parsed.success ? parsed.data : undefined;
diff --git a/src/features/workspaces/export/workspace-document-pdf-html.test.ts b/src/features/workspaces/export/workspace-document-pdf-html.test.ts
index 34e8b2ee8..c26eb347f 100644
--- a/src/features/workspaces/export/workspace-document-pdf-html.test.ts
+++ b/src/features/workspaces/export/workspace-document-pdf-html.test.ts
@@ -70,4 +70,25 @@ describe("renderWorkspaceDocumentPdfHtml", () => {
 		expect(html).toContain("math-fallback");
 		expect(html).toContain("$\\definitelynotacommand{$");
 	});
+
+	// A PDF cannot draw the diagram, and its source is authoring material the
+	// reader never asked for, so the block leaves nothing behind.
+	it("drops a mermaid diagram rather than printing its source", async () => {
+		const html = await renderWorkspaceDocumentPdfHtml({
+			type: "doc",
+			content: [
+				{
+					type: "codeBlock",
+					attrs: { language: "mermaid" },
+					content: [{ type: "text", text: "flowchart TD; A[Start] --> B[End]" }],
+				},
+				{ type: "paragraph", content: [{ type: "text", text: "Prose survives." }] },
+			],
+		});
+
+		expect(html).toContain("Prose survives.");
+		expect(html).not.toContain("flowchart");
+		expect(html).not.toContain("Mermaid");
+		expect(html).not.toContain("language-mermaid");
+	});
 });
diff --git a/src/features/workspaces/export/workspace-document-pdf-html.ts b/src/features/workspaces/export/workspace-document-pdf-html.ts
index 262387d91..d5360c73a 100644
--- a/src/features/workspaces/export/workspace-document-pdf-html.ts
+++ b/src/features/workspaces/export/workspace-document-pdf-html.ts
@@ -5,6 +5,7 @@ import { parseHTML } from "linkedom";
 import {
 	getCodeLanguageLabel,
 	highlightCodeTokens,
+	isMermaidCodeLanguage,
 } from "#/features/workspaces/documents/code-block-shiki/highlighter";
 import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
 import { getTiptapDocumentSchema } from "#/features/workspaces/documents/tiptap-schema";
@@ -102,10 +103,28 @@ export async function renderWorkspaceDocumentPdfHtml(document: TiptapDocumentJso
 	return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><style>${pdfDocumentStyles}</style></head><body>${article.outerHTML}</body></html>`;
 }
 
+/**
+ * What a printed page cannot carry. A citation has nothing to link to; a
+ * widget is markup that has to run; a mermaid block is an instruction for
+ * drawing rather than the drawing. Falling back to source for the last two
+ * would put authoring material in front of a reader who asked for a document,
+ * so all three leave nothing behind.
+ */
 function removeUnexportedNodes(article: Element) {
 	for (const node of article.querySelectorAll('citation, [data-type="widget"]')) {
 		node.remove();
 	}
+	for (const code of article.querySelectorAll("pre > code")) {
+		if (isMermaidCodeLanguage(readCodeBlockLanguage(code))) {
+			code.parentElement?.remove();
+		}
+	}
+}
+
+/** The language a code block declares, exactly as it was written. */
+function readCodeBlockLanguage(element: Element) {
+	const languageClass = Array.from(element.classList).find((name) => name.startsWith("language-"));
+	return languageClass?.slice("language-".length) || null;
 }
 
 function renderMath(article: Element) {
@@ -133,11 +152,8 @@ async function renderCodeBlocks(htmlDocument: Document, article: Element) {
 	const codeBlocks = Array.from(article.querySelectorAll("pre > code"));
 	const rendered = await Promise.all(
 		codeBlocks.map(async (element) => {
-			const languageClass = Array.from(element.classList).find((name) =>
-				name.startsWith("language-"),
-			);
 			const code = element.textContent ?? "";
-			const language = languageClass?.slice("language-".length) || null;
+			const language = readCodeBlockLanguage(element);
 			return {
 				code,
 				element,
diff --git a/src/features/workspaces/export/workspace-export-archive.test.ts b/src/features/workspaces/export/workspace-export-archive.test.ts
index 01b138362..2ccf72595 100644
--- a/src/features/workspaces/export/workspace-export-archive.test.ts
+++ b/src/features/workspaces/export/workspace-export-archive.test.ts
@@ -3,10 +3,10 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { WorkspaceItem } from "#/features/workspaces/contracts";
 import { createWorkspaceExportStream } from "#/features/workspaces/export/workspace-export-archive";
-import { createFlashcardSetFromHtml } from "#/features/workspaces/flashcards/flashcard-content";
 
 const baseItem = {
 	workspaceId: "workspace-1",
+	refKey: "ref-item-1",
 	color: null,
 	metadataJson: {},
 	sortOrder: 0,
@@ -54,11 +54,9 @@ describe("workspace export archive", () => {
 					content: [{ type: "paragraph", content: [{ type: "text", text: "Hello" }] }],
 				}),
 				readFile: vi.fn().mockResolvedValue(new Blob(["PDF bytes"]).stream()),
-				readFlashcards: vi
+				readStructuredMarkdown: vi
 					.fn()
-					.mockReturnValue(
-						createFlashcardSetFromHtml([{ front: "<p>Term</p>", back: "<p>Definition</p>" }]),
-					),
+					.mockReturnValue("# Key terms\n\n## Card 1\n\nTerm\n\n**Answer**\n\nDefinition\n"),
 			}),
 		).arrayBuffer();
 		const files = unzipSync(new Uint8Array(archive));
@@ -103,7 +101,7 @@ describe("workspace export archive", () => {
 			createWorkspaceExportStream(items, {
 				readDocument: vi.fn().mockReturnValue({ type: "doc" }),
 				readFile: vi.fn().mockResolvedValue(new Blob(["file"]).stream()),
-				readFlashcards: vi.fn(),
+				readStructuredMarkdown: vi.fn(),
 			}),
 		).arrayBuffer();
 
diff --git a/src/features/workspaces/export/workspace-export-archive.ts b/src/features/workspaces/export/workspace-export-archive.ts
index 9c5620260..c59ced998 100644
--- a/src/features/workspaces/export/workspace-export-archive.ts
+++ b/src/features/workspaces/export/workspace-export-archive.ts
@@ -7,7 +7,6 @@ import {
 } from "#/features/workspaces/contracts";
 import { serializeTiptapDocumentToMarkdown } from "#/features/workspaces/documents/document-markdown";
 import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
-import type { FlashcardSetContent } from "#/features/workspaces/flashcards/flashcard-content";
 import { buildWorkspaceItemPathIndex } from "#/features/workspaces/model/workspace-paths";
 
 const emptyBytes = new Uint8Array();
@@ -15,7 +14,8 @@ const textEncoder = new TextEncoder();
 
 interface WorkspaceExportReaders {
 	readDocument: (item: WorkspaceItem) => TiptapDocumentJson;
-	readFlashcards: (item: WorkspaceItem) => FlashcardSetContent;
+	/** Pre-rendered Markdown for structured items (flashcard sets, quizzes). */
+	readStructuredMarkdown: (item: WorkspaceItem) => string;
 	readFile: (item: WorkspaceItem) => Promise<ReadableStream<Uint8Array>>;
 }
 
@@ -65,8 +65,8 @@ async function writeWorkspaceExport(
 				await addZipBytes(zip, path, textEncoder.encode(`${markdown}\n`), () => output);
 				continue;
 			}
-			if (item.type === "flashcard") {
-				const markdown = serializeFlashcardsToMarkdown(item, readers.readFlashcards(item));
+			if (getWorkspaceItemContentKind(item.type) === "structured") {
+				const markdown = readers.readStructuredMarkdown(item);
 				await addZipBytes(zip, path, textEncoder.encode(markdown), () => output);
 				continue;
 			}
@@ -102,7 +102,8 @@ function buildArchivePathIndex(
 	}
 
 	for (const item of items) {
-		if (getWorkspaceItemContentKind(item.type) !== "document" && item.type !== "flashcard") {
+		const contentKind = getWorkspaceItemContentKind(item.type);
+		if (contentKind !== "document" && contentKind !== "structured") {
 			continue;
 		}
 		const workspacePath = workspacePaths.get(item.id)?.slice(1);
@@ -121,15 +122,6 @@ function buildArchivePathIndex(
 	return archivePaths;
 }
 
-function serializeFlashcardsToMarkdown(item: WorkspaceItem, set: FlashcardSetContent) {
-	const cards = set.cards.map((card, index) => {
-		const front = serializeTiptapDocumentToMarkdown(card.front);
-		const back = serializeTiptapDocumentToMarkdown(card.back);
-		return `## Card ${index + 1}\n\n${front}\n\n**Answer**\n\n${back}`;
-	});
-	return `# ${item.name}\n\n${cards.join("\n\n---\n\n")}\n`;
-}
-
 function reserveArchivePath(path: string, reservedPaths: ReadonlySet<string>) {
 	if (!reservedPaths.has(path.toLowerCase())) {
 		return path;
diff --git a/src/features/workspaces/export/workspace-export.ts b/src/features/workspaces/export/workspace-export.ts
index ae5fe3153..1d3047508 100644
--- a/src/features/workspaces/export/workspace-export.ts
+++ b/src/features/workspaces/export/workspace-export.ts
@@ -8,9 +8,12 @@ import {
 } from "#/features/workspaces/documents/tiptap-document";
 import { createWorkspaceExportStream } from "#/features/workspaces/export/workspace-export-archive";
 import { type FlashcardSetContent } from "#/features/workspaces/flashcards/flashcard-content";
+import { serializeTiptapDocumentToMarkdown } from "#/features/workspaces/documents/document-markdown";
 import { canExportWorkspaceEstimate } from "#/features/workspaces/export/workspace-export-limit";
 import { readWorkspaceDocumentCheckpoint } from "#/features/workspaces/persistence/workspace-document-checkpoints";
 import { readFlashcardSet } from "#/features/workspaces/flashcards/flashcard-persistence";
+import { readQuizSet } from "#/features/workspaces/quizzes/quiz-persistence";
+import { type QuizSetContent } from "#/features/workspaces/quizzes/quiz-content";
 import { readWorkspaceFileSource } from "#/features/workspaces/persistence/workspace-files";
 import { WorkspaceForbiddenError } from "#/features/workspaces/server/permissions";
 import { getWorkspacePageForUser } from "#/features/workspaces/server/queries";
@@ -18,6 +21,32 @@ import { getMetadataNumber } from "#/features/workspaces/model/workspace-file";
 
 const textEncoder = new TextEncoder();
 
+function serializeFlashcardSetToMarkdown(item: WorkspaceItem, set: FlashcardSetContent) {
+	const cards = set.cards.map((card, index) => {
+		const front = serializeTiptapDocumentToMarkdown(card.front);
+		const back = serializeTiptapDocumentToMarkdown(card.back);
+		return `## Card ${index + 1}\n\n${front}\n\n**Answer**\n\n${back}`;
+	});
+	return `# ${item.name}\n\n${cards.join("\n\n---\n\n")}\n`;
+}
+
+function serializeQuizSetToMarkdown(item: WorkspaceItem, set: QuizSetContent) {
+	const questions = set.questions.map((question, index) => {
+		const stem = serializeTiptapDocumentToMarkdown(question.question);
+		const options = question.options
+			.map((option, optionIndex) => {
+				const letter = String.fromCharCode(65 + optionIndex);
+				const text = serializeTiptapDocumentToMarkdown(option.text);
+				const marker = option.id === question.correctOptionId ? " ✓" : "";
+				return `${letter}. ${text}${marker}`;
+			})
+			.join("\n");
+		const explanation = serializeTiptapDocumentToMarkdown(question.explanation);
+		return `## Question ${index + 1}\n\n${stem}\n\n${options}\n\n**Explanation**\n\n${explanation}`;
+	});
+	return `# ${item.name}\n\n${questions.join("\n\n---\n\n")}\n`;
+}
+
 export class WorkspaceExportTooLargeError extends Error {
 	constructor() {
 		super("Workspace is too large to export.");
@@ -27,7 +56,7 @@ export class WorkspaceExportTooLargeError extends Error {
 
 interface PreparedWorkspaceExport {
 	documents: Map<string, TiptapDocumentJson>;
-	flashcards: Map<string, FlashcardSetContent>;
+	structuredMarkdown: Map<string, string>;
 	fileName: string;
 	fileObjectKeys: Map<string, string>;
 	items: WorkspaceItem[];
@@ -46,10 +75,10 @@ export async function createWorkspaceExport(input: { workspaceId: string; userId
 				}
 				return document;
 			},
-			readFlashcards: (item) => {
-				const set = prepared.flashcards.get(item.id);
-				if (!set) throw new Error(`Workspace flashcards were not prepared for ${item.name}.`);
-				return set;
+			readStructuredMarkdown: (item) => {
+				const markdown = prepared.structuredMarkdown.get(item.id);
+				if (!markdown) throw new Error(`Workspace content was not prepared for ${item.name}.`);
+				return markdown;
 			},
 			readFile: async (item) => {
 				const objectKey = prepared.fileObjectKeys.get(item.id);
@@ -94,7 +123,7 @@ async function prepareWorkspaceExport(input: { workspaceId: string; userId: stri
 	}
 
 	const documents = new Map<string, TiptapDocumentJson>();
-	const flashcards = new Map<string, FlashcardSetContent>();
+	const structuredMarkdown = new Map<string, string>();
 	const fileObjectKeys = new Map<string, string>();
 	let estimatedBytes = page.items.length * 512;
 
@@ -123,11 +152,19 @@ async function prepareWorkspaceExport(input: { workspaceId: string; userId: stri
 			fileObjectKeys.set(item.id, source.objectKey);
 			continue;
 		}
-		if (item.type === "flashcard") {
-			const set = await readFlashcardSet({ itemId: item.id, workspaceId: input.workspaceId });
-			const serialized = JSON.stringify(set);
-			estimatedBytes += textEncoder.encode(serialized).byteLength;
-			flashcards.set(item.id, set);
+		if (getWorkspaceItemContentKind(item.type) === "structured") {
+			const markdown =
+				item.type === "flashcard"
+					? serializeFlashcardSetToMarkdown(
+							item,
+							await readFlashcardSet({ itemId: item.id, workspaceId: input.workspaceId }),
+						)
+					: serializeQuizSetToMarkdown(
+							item,
+							await readQuizSet({ itemId: item.id, workspaceId: input.workspaceId }),
+						);
+			estimatedBytes += textEncoder.encode(markdown).byteLength;
+			structuredMarkdown.set(item.id, markdown);
 		}
 	}
 
@@ -137,7 +174,7 @@ async function prepareWorkspaceExport(input: { workspaceId: string; userId: stri
 
 	return {
 		documents,
-		flashcards,
+		structuredMarkdown,
 		fileName: `${normalizeWorkspaceItemName(page.workspace.name, "Workspace")}-${new Date().toISOString().slice(0, 10)}.zip`,
 		fileObjectKeys,
 		items: page.items,
diff --git a/src/features/workspaces/flashcards/flashcard-content.test.ts b/src/features/workspaces/flashcards/flashcard-content.test.ts
index 8d0d9e8c8..e2f4fb1b9 100644
--- a/src/features/workspaces/flashcards/flashcard-content.test.ts
+++ b/src/features/workspaces/flashcards/flashcard-content.test.ts
@@ -25,7 +25,7 @@ describe("flashcard content", () => {
 	it("rejects document-only nodes", () => {
 		expect(() =>
 			createFlashcardSetFromHtml([{ front: "<h2>Heading</h2>", back: "<p>A</p>" }]),
-		).toThrow("Flashcards do not support heading content yet.");
+		).toThrow("Flashcard content cannot contain heading nodes.");
 	});
 
 	it("rejects empty sets and malformed stored rich text", () => {
diff --git a/src/features/workspaces/flashcards/flashcard-content.ts b/src/features/workspaces/flashcards/flashcard-content.ts
index 9be673295..baed067dc 100644
--- a/src/features/workspaces/flashcards/flashcard-content.ts
+++ b/src/features/workspaces/flashcards/flashcard-content.ts
@@ -1,19 +1,18 @@
-import { z } from "zod";
-
 import {
-	parseDocumentAiHtml,
-	serializeTiptapDocumentToHtml,
-} from "#/features/workspaces/documents/document-ai-html";
+	parseEntryRichTextHtml,
+	parseStoredEntryRichText,
+} from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
+import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
 import {
-	coerceTiptapDocumentProjection,
-	type TiptapDocumentJson,
-} from "#/features/workspaces/documents/tiptap-document";
+	createWorkspaceEntryId,
+	workspaceEntryIdSchema,
+} from "#/features/workspaces/locations/workspace-location";
 import { sha256Base64UrlText } from "#/lib/binary";
 import { isRecord } from "#/lib/record";
 
 export const FLASHCARD_SET_VERSION = 1;
-export const flashcardSideHtmlSchema = z.string().trim().min(1).max(8_000);
-const flashcardIdSchema = z.uuid();
+const flashcardIdSchema = workspaceEntryIdSchema;
 
 export interface Flashcard {
 	id: string;
@@ -32,27 +31,12 @@ interface FlashcardHtmlCard {
 	back: string;
 }
 
-const allowedNodeTypes = new Set([
-	"doc",
-	"paragraph",
-	"text",
-	"bulletList",
-	"orderedList",
-	"listItem",
-	"codeBlock",
-	"hardBreak",
-	"inlineMath",
-	"blockMath",
-]);
-
-const allowedMarkTypes = new Set(["bold", "italic", "strike", "code", "link", "underline"]);
-
 export function createFlashcardSetFromHtml(cards: Array<{ front: string; back: string }>) {
 	if (cards.length === 0) throw new Error("A flashcard set needs at least one card.");
 	return {
 		version: FLASHCARD_SET_VERSION,
 		cards: cards.map((card) => ({
-			id: crypto.randomUUID(),
+			id: createWorkspaceEntryId("c"),
 			front: parseFlashcardSideHtml(card.front),
 			back: parseFlashcardSideHtml(card.back),
 		})),
@@ -60,9 +44,7 @@ export function createFlashcardSetFromHtml(cards: Array<{ front: string; back: s
 }
 
 export function parseFlashcardSideHtml(html: string) {
-	const document = parseDocumentAiHtml(html);
-	assertFlashcardRichText(document);
-	return document;
+	return parseEntryRichTextHtml(html, "Flashcard");
 }
 
 export function parseFlashcardSetContent(content: string | null): FlashcardSetContent {
@@ -92,67 +74,29 @@ export function parseFlashcardSetContent(content: string | null): FlashcardSetCo
 		}
 		seenIds.add(cardId.data);
 
-		const front = parseStoredFlashcardSide(card.front);
-		const back = parseStoredFlashcardSide(card.back);
-		assertFlashcardRichText(front);
-		assertFlashcardRichText(back);
+		const front = parseStoredEntryRichText(card.front, "Flashcard");
+		const back = parseStoredEntryRichText(card.back, "Flashcard");
 		return { id: cardId.data, front, back };
 	});
 
 	return { version: FLASHCARD_SET_VERSION, cards };
 }
 
-function parseStoredFlashcardSide(value: unknown) {
-	const projection = coerceTiptapDocumentProjection(value);
-	if (projection.warnings.length > 0) {
-		throw new Error("Flashcard content contains invalid rich text.");
-	}
-	return projection.document;
-}
-
 export function stringifyFlashcardSetContent(content: FlashcardSetContent) {
 	return `${JSON.stringify(content)}\n`;
 }
 
-export function serializeFlashcardSideToHtml(side: TiptapDocumentJson) {
-	return serializeTiptapDocumentToHtml(side);
-}
-
 export async function createFlashcardRevision(card: Flashcard) {
 	return (await sha256Base64UrlText(JSON.stringify({ front: card.front, back: card.back }))).slice(
 		0,
-		10,
+		6,
 	);
 }
 
 export function serializeFlashcardSetToHtml(content: FlashcardSetContent): FlashcardHtmlCard[] {
 	return content.cards.map((card) => ({
 		id: card.id,
-		front: serializeFlashcardSideToHtml(card.front),
-		back: serializeFlashcardSideToHtml(card.back),
+		front: serializeTiptapDocumentToHtml(card.front),
+		back: serializeTiptapDocumentToHtml(card.back),
 	}));
 }
-
-function assertFlashcardRichText(value: unknown) {
-	visitRichTextValue(value);
-}
-
-function visitRichTextValue(value: unknown) {
-	if (Array.isArray(value)) {
-		for (const entry of value) visitRichTextValue(entry);
-		return;
-	}
-	if (!isRecord(value)) return;
-
-	if (typeof value.type === "string" && !allowedNodeTypes.has(value.type)) {
-		throw new Error(`Flashcards do not support ${value.type} content yet.`);
-	}
-	if (Array.isArray(value.marks)) {
-		for (const mark of value.marks) {
-			if (!isRecord(mark) || typeof mark.type !== "string" || !allowedMarkTypes.has(mark.type)) {
-				throw new Error("Flashcard content contains an unsupported text mark.");
-			}
-		}
-	}
-	if ("content" in value) visitRichTextValue(value.content);
-}
diff --git a/src/features/workspaces/flashcards/flashcard-edits.test.ts b/src/features/workspaces/flashcards/flashcard-edits.test.ts
index f113523ea..9cc52a0b3 100644
--- a/src/features/workspaces/flashcards/flashcard-edits.test.ts
+++ b/src/features/workspaces/flashcards/flashcard-edits.test.ts
@@ -92,7 +92,7 @@ describe("applyFlashcardEdits", () => {
 		expect(result.failed).toMatchObject([
 			{ code: "no_change", index: 0 },
 			{ code: "no_change", index: 1 },
-			{ code: "cannot_delete_last_card", index: 2 },
+			{ code: "cannot_delete_last_entry", index: 2 },
 		]);
 		expect(result.content.cards).toEqual(set.cards);
 	});
@@ -162,7 +162,7 @@ async function createTargets(...cards: Flashcard[]) {
 				async (card, index) =>
 					[
 						refs[index]!,
-						{ cardId: card.id, revision: await createFlashcardRevision(card) },
+						{ entryId: card.id, revision: await createFlashcardRevision(card) },
 					] as const,
 			),
 		),
diff --git a/src/features/workspaces/flashcards/flashcard-edits.ts b/src/features/workspaces/flashcards/flashcard-edits.ts
index 72f6a4aad..ba7be66ee 100644
--- a/src/features/workspaces/flashcards/flashcard-edits.ts
+++ b/src/features/workspaces/flashcards/flashcard-edits.ts
@@ -1,46 +1,52 @@
 import { z } from "zod";
 
 import {
-	replaceUniqueText,
-	type ReplaceUniqueTextFailureCode,
-} from "#/features/workspaces/content/replace-unique-text";
+	applyOrderedEntryEdits,
+	OrderedEntryEditError,
+	type OrderedEntryEditTarget,
+} from "#/features/workspaces/content/ordered-entry-edits";
+import { replaceUniqueText } from "#/features/workspaces/content/replace-unique-text";
 import {
 	createFlashcardRevision,
-	flashcardSideHtmlSchema,
 	parseFlashcardSideHtml,
-	serializeFlashcardSideToHtml,
+	type Flashcard,
 	type FlashcardSetContent,
 } from "#/features/workspaces/flashcards/flashcard-content";
-import { workspaceReferenceInputSchema } from "#/features/workspaces/locations/workspace-location";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
+import {
+	createWorkspaceEntryId,
+	workspaceUnitRefInputSchema,
+} from "#/features/workspaces/locations/workspace-location";
 
 const editTextSchema = z.string().max(8_000);
 
 export const flashcardEditSchema = z.union([
 	z.strictObject({
 		op: z.enum(["insert_before", "insert_after"]),
-		ref: workspaceReferenceInputSchema,
-		front: flashcardSideHtmlSchema,
-		back: flashcardSideHtmlSchema,
+		ref: workspaceUnitRefInputSchema,
+		front: entryRichTextHtmlSchema,
+		back: entryRichTextHtmlSchema,
 	}),
 	z
 		.strictObject({
 			op: z.literal("update"),
-			ref: workspaceReferenceInputSchema,
-			front: flashcardSideHtmlSchema.optional(),
-			back: flashcardSideHtmlSchema.optional(),
+			ref: workspaceUnitRefInputSchema,
+			front: entryRichTextHtmlSchema.optional(),
+			back: entryRichTextHtmlSchema.optional(),
 		})
 		.refine((value) => value.front !== undefined || value.back !== undefined, {
 			message: "Provide a new front or back.",
 		}),
 	z.strictObject({
 		op: z.literal("replace"),
-		ref: workspaceReferenceInputSchema,
-		front: flashcardSideHtmlSchema,
-		back: flashcardSideHtmlSchema,
+		ref: workspaceUnitRefInputSchema,
+		front: entryRichTextHtmlSchema,
+		back: entryRichTextHtmlSchema,
 	}),
 	z.strictObject({
 		op: z.literal("replace_text"),
-		ref: workspaceReferenceInputSchema,
+		ref: workspaceUnitRefInputSchema,
 		side: z.enum(["front", "back"]),
 		find: editTextSchema
 			.min(1)
@@ -50,137 +56,82 @@ export const flashcardEditSchema = z.union([
 	z
 		.strictObject({
 			op: z.literal("move"),
-			ref: workspaceReferenceInputSchema,
-			beforeRef: workspaceReferenceInputSchema.optional(),
-			afterRef: workspaceReferenceInputSchema.optional(),
+			ref: workspaceUnitRefInputSchema,
+			beforeRef: workspaceUnitRefInputSchema.optional(),
+			afterRef: workspaceUnitRefInputSchema.optional(),
 		})
 		.refine((edit) => Boolean(edit.beforeRef) !== Boolean(edit.afterRef), {
 			message: "Provide exactly one of beforeRef or afterRef.",
 		}),
 	z.strictObject({
 		op: z.literal("delete"),
-		ref: workspaceReferenceInputSchema,
+		ref: workspaceUnitRefInputSchema,
 	}),
 ]);
 
 export type FlashcardEdit = z.output<typeof flashcardEditSchema>;
-export type FlashcardEditTarget = { cardId: string; revision: string };
-export type FlashcardEditFailureCode =
-	| "cannot_delete_last_card"
-	| "ref_not_found"
-	| "ref_stale"
-	| "invalid_card_content"
-	| "no_change"
-	| ReplaceUniqueTextFailureCode;
 
 export async function applyFlashcardEdits(
 	content: FlashcardSetContent,
 	edits: FlashcardEdit[],
-	targets: ReadonlyMap<string, FlashcardEditTarget>,
+	targets: ReadonlyMap<string, OrderedEntryEditTarget>,
 ) {
-	const cards = [...content.cards];
-	const initialRevisions = new Map(
-		await Promise.all(
-			cards.map(async (card) => [card.id, await createFlashcardRevision(card)] as const),
-		),
-	);
-	const failed: Array<{ code: FlashcardEditFailureCode; detail?: string; index: number }> = [];
-	let applied = 0;
-
-	for (const [index, edit] of edits.entries()) {
-		try {
-			const before = JSON.stringify(cards);
-			const cardIndex = findCardIndex(cards, edit.ref, targets, initialRevisions);
-			if (edit.op === "insert_before" || edit.op === "insert_after") {
-				const insertionIndex = edit.op === "insert_before" ? cardIndex : cardIndex + 1;
-				cards.splice(insertionIndex, 0, {
-					id: crypto.randomUUID(),
-					front: parseFlashcardSideHtml(edit.front),
-					back: parseFlashcardSideHtml(edit.back),
-				});
-			} else if (edit.op === "update") {
-				const card = cards[cardIndex]!;
-				cards[cardIndex] = {
-					...card,
-					...(edit.front === undefined ? {} : { front: parseFlashcardSideHtml(edit.front) }),
-					...(edit.back === undefined ? {} : { back: parseFlashcardSideHtml(edit.back) }),
-				};
-			} else if (edit.op === "replace") {
-				cards[cardIndex] = {
-					id: cards[cardIndex]!.id,
-					front: parseFlashcardSideHtml(edit.front),
-					back: parseFlashcardSideHtml(edit.back),
-				};
-			} else if (edit.op === "replace_text") {
-				const card = cards[cardIndex]!;
-				const replaced = replaceUniqueText(
-					serializeFlashcardSideToHtml(card[edit.side]),
-					edit.find,
-					edit.replace,
-				);
-				if (!replaced.ok) {
-					throw new FlashcardEditError(replaced.code, replaced.detail);
-				}
-				cards[cardIndex] = {
-					...card,
-					[edit.side]: parseFlashcardSideHtml(replaced.text),
-				};
-			} else if (edit.op === "delete") {
-				if (cards.length === 1) {
-					throw new FlashcardEditError(
-						"cannot_delete_last_card",
-						"A flashcard set needs at least one card.",
-					);
-				}
-				cards.splice(cardIndex, 1);
-			} else if (edit.op === "move") {
-				const destinationRef = edit.beforeRef ?? edit.afterRef;
-				if (!destinationRef || destinationRef === edit.ref) {
-					throw new FlashcardEditError("no_change");
-				}
-				findCardIndex(cards, destinationRef, targets, initialRevisions);
-				const [card] = cards.splice(cardIndex, 1);
-				const destinationIndex = findCardIndex(cards, destinationRef, targets, initialRevisions);
-				if (!card) throw new FlashcardEditError("ref_not_found");
-				cards.splice(edit.beforeRef ? destinationIndex : destinationIndex + 1, 0, card);
-			} else {
-				throw new Error("Unsupported flashcard edit.");
-			}
-			if (JSON.stringify(cards) === before) throw new FlashcardEditError("no_change");
-			applied += 1;
-		} catch (error) {
-			failed.push({
-				code: error instanceof FlashcardEditError ? error.code : "invalid_card_content",
-				...(error instanceof Error && error.message ? { detail: error.message } : {}),
-				index,
-			});
-		}
-	}
+	const result = await applyOrderedEntryEdits({
+		entries: content.cards,
+		edits,
+		targets,
+		computeRevision: createFlashcardRevision,
+		createEntry: createCardFromEdit,
+		reviseEntry: reviseCard,
+		lastEntryDetail: "A flashcard set needs at least one card.",
+	});
 
-	return { applied, failed, content: { ...content, cards } };
+	return {
+		applied: result.applied,
+		failed: result.failed,
+		content: { ...content, cards: result.entries },
+	};
 }
 
-function findCardIndex(
-	cards: FlashcardSetContent["cards"],
-	ref: string,
-	targets: ReadonlyMap<string, FlashcardEditTarget>,
-	initialRevisions: ReadonlyMap<string, string>,
-) {
-	const target = targets.get(ref);
-	if (!target) throw new FlashcardEditError("ref_not_found");
-	const index = cards.findIndex((card) => card.id === target.cardId);
-	if (index < 0) throw new FlashcardEditError("ref_not_found");
-	if (initialRevisions.get(target.cardId) !== target.revision) {
-		throw new FlashcardEditError("ref_stale");
+function createCardFromEdit(edit: FlashcardEdit): Flashcard {
+	if (edit.op !== "insert_before" && edit.op !== "insert_after") {
+		throw new Error("Unsupported flashcard edit.");
 	}
-	return index;
+	return {
+		id: createWorkspaceEntryId("c"),
+		front: parseFlashcardSideHtml(edit.front),
+		back: parseFlashcardSideHtml(edit.back),
+	};
 }
 
-class FlashcardEditError extends Error {
-	constructor(
-		readonly code: Exclude<FlashcardEditFailureCode, "invalid_card_content">,
-		message?: string,
-	) {
-		super(message);
+function reviseCard(card: Flashcard, edit: FlashcardEdit): Flashcard {
+	if (edit.op === "update") {
+		return {
+			...card,
+			...(edit.front === undefined ? {} : { front: parseFlashcardSideHtml(edit.front) }),
+			...(edit.back === undefined ? {} : { back: parseFlashcardSideHtml(edit.back) }),
+		};
+	}
+	if (edit.op === "replace") {
+		return {
+			id: card.id,
+			front: parseFlashcardSideHtml(edit.front),
+			back: parseFlashcardSideHtml(edit.back),
+		};
+	}
+	if (edit.op === "replace_text") {
+		const replaced = replaceUniqueText(
+			serializeTiptapDocumentToHtml(card[edit.side]),
+			edit.find,
+			edit.replace,
+		);
+		if (!replaced.ok) {
+			throw new OrderedEntryEditError(replaced.code, replaced.detail);
+		}
+		return {
+			...card,
+			[edit.side]: parseFlashcardSideHtml(replaced.text),
+		};
 	}
+	throw new Error("Unsupported flashcard edit.");
 }
diff --git a/src/features/workspaces/flashcards/flashcard-functions.ts b/src/features/workspaces/flashcards/flashcard-functions.ts
index 14983bcba..e3f4c9d52 100644
--- a/src/features/workspaces/flashcards/flashcard-functions.ts
+++ b/src/features/workspaces/flashcards/flashcard-functions.ts
@@ -1,6 +1,8 @@
 import { createServerFn } from "@tanstack/react-start";
 import { z } from "zod";
 
+import { workspaceEntryIdSchema } from "#/features/workspaces/locations/workspace-location";
+
 import {
 	readFlashcardViewer,
 	recordFlashcardStudyRating,
@@ -23,7 +25,7 @@ export const getFlashcardViewerFn = createServerFn({ method: "GET" })
 export const recordFlashcardStudyRatingFn = createServerFn({ method: "POST" })
 	.validator(
 		flashcardItemInputSchema.extend({
-			cardId: z.uuid(),
+			cardId: workspaceEntryIdSchema,
 			rating: flashcardStudyRatingSchema,
 		}),
 	)
diff --git a/src/features/workspaces/flashcards/flashcard-persistence.ts b/src/features/workspaces/flashcards/flashcard-persistence.ts
index ceb80dd5d..0c17c9d39 100644
--- a/src/features/workspaces/flashcards/flashcard-persistence.ts
+++ b/src/features/workspaces/flashcards/flashcard-persistence.ts
@@ -14,17 +14,9 @@ import {
 	withWorkspaceTransaction,
 } from "#/features/workspaces/persistence/workspace-postgres-support";
 import { notifyWorkspaceRoom } from "#/features/workspaces/realtime/workspace-room-notifier";
-import { assertCanReadWorkspace } from "#/features/workspaces/server/permissions";
 
-export async function readFlashcardSet(input: {
-	itemId: string;
-	workspaceId: string;
-	userId?: string;
-}) {
+export async function readFlashcardSet(input: { itemId: string; workspaceId: string }) {
 	return await withDb(async (db) => {
-		if (input.userId) {
-			await assertCanReadWorkspace(db, { workspaceId: input.workspaceId, userId: input.userId });
-		}
 		const [row] = await db
 			.select({ content: workspaceItemContents.content })
 			.from(workspaceItems)
diff --git a/src/features/workspaces/flashcards/flashcard-study-session.ts b/src/features/workspaces/flashcards/flashcard-study-session.ts
index a64791473..3917da0d3 100644
--- a/src/features/workspaces/flashcards/flashcard-study-session.ts
+++ b/src/features/workspaces/flashcards/flashcard-study-session.ts
@@ -4,6 +4,7 @@ import type {
 	FlashcardStudyRating,
 	FlashcardStudyState,
 } from "#/features/workspaces/flashcards/flashcard-study-state";
+import { shuffleInPlace } from "#/lib/shuffle";
 
 export type FlashcardStudyMode = "all" | "missed";
 
@@ -46,11 +47,5 @@ export function createFlashcardStudyQueue(
 		}
 	}
 
-	if (!input.shuffled) return cardIds;
-
-	for (let index = cardIds.length - 1; index > 0; index -= 1) {
-		const swapIndex = Math.floor(random() * (index + 1));
-		[cardIds[index], cardIds[swapIndex]] = [cardIds[swapIndex]!, cardIds[index]!];
-	}
-	return cardIds;
+	return input.shuffled ? shuffleInPlace(cardIds, random) : cardIds;
 }
diff --git a/src/features/workspaces/flashcards/flashcard-study-state.ts b/src/features/workspaces/flashcards/flashcard-study-state.ts
index 951dd25d0..cf54ab09c 100644
--- a/src/features/workspaces/flashcards/flashcard-study-state.ts
+++ b/src/features/workspaces/flashcards/flashcard-study-state.ts
@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { workspaceEntryIdSchema } from "#/features/workspaces/locations/workspace-location";
+
 export const flashcardStudyRatingSchema = z.enum(["again", "hard", "good", "easy"]);
 export type FlashcardStudyRating = z.output<typeof flashcardStudyRatingSchema>;
 
@@ -11,7 +13,7 @@ export const flashcardReviewSchema = z.object({
 
 export const flashcardStudyStateSchema = z.object({
 	kind: z.literal("flashcard"),
-	cards: z.record(z.uuid(), flashcardReviewSchema),
+	cards: z.record(workspaceEntryIdSchema, flashcardReviewSchema),
 });
 
 export type FlashcardStudyState = z.output<typeof flashcardStudyStateSchema>;
diff --git a/src/features/workspaces/locations/workspace-location-context.test.tsx b/src/features/workspaces/locations/workspace-location-context.test.tsx
index f8dad6774..6c80feebc 100644
--- a/src/features/workspaces/locations/workspace-location-context.test.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.test.tsx
@@ -30,6 +30,7 @@ describe("WorkspaceLocationProvider", () => {
 			type: "file",
 			name: "Book.pdf",
 			color: null,
+			refKey: "ref-file-1",
 			metadataJson: {},
 			sortOrder: 1,
 			createdAt: "2026-08-13T00:00:00.000Z",
diff --git a/src/features/workspaces/locations/workspace-location-context.tsx b/src/features/workspaces/locations/workspace-location-context.tsx
index fceaae93f..c59ea90f7 100644
--- a/src/features/workspaces/locations/workspace-location-context.tsx
+++ b/src/features/workspaces/locations/workspace-location-context.tsx
@@ -2,7 +2,11 @@ import { FileQuestion, type LucideIcon } from "lucide-react";
 import { createContext, type ReactNode, use, useCallback, useState } from "react";
 import { toast } from "sonner";
 
-import type { WorkspaceLocation } from "#/features/workspaces/locations/workspace-location";
+import {
+	parseWorkspaceAddress,
+	resolveWorkspaceAddressLocation,
+	type WorkspaceLocation,
+} from "#/features/workspaces/locations/workspace-location";
 import { getWorkspaceItemDisplay } from "#/features/workspaces/model/item-display";
 import type { WorkspaceItem } from "#/features/workspaces/contracts";
 
@@ -24,6 +28,8 @@ type WorkspaceLocationContextValue = {
 	completeRevealRequest: (request: WorkspaceLocationRevealRequest, revealed: boolean) => void;
 	getItem: (itemId: string) => WorkspaceItem | undefined;
 	getPresentation: (location: WorkspaceLocation) => WorkspaceLocationPresentation;
+	/** Resolves a self-describing address like `Xk7p2Qa9/p5` against the live workspace. */
+	resolveAddress: (ref: unknown) => WorkspaceLocation | undefined;
 	reveal: (location: WorkspaceLocation) => boolean;
 	revealRequest: WorkspaceLocationRevealRequest | null;
 };
@@ -56,6 +62,16 @@ export function WorkspaceLocationProvider({
 		getItem(itemId) {
 			return itemsById.get(itemId);
 		},
+		resolveAddress(ref) {
+			const address = typeof ref === "string" ? parseWorkspaceAddress(ref) : undefined;
+			if (!address) return undefined;
+			for (const item of itemsById.values()) {
+				if (item.refKey === address.refKey) {
+					return resolveWorkspaceAddressLocation(item, address);
+				}
+			}
+			return undefined;
+		},
 		getPresentation(location) {
 			const item = itemsById.get(location.itemId);
 			const itemName = item?.name ?? "Source unavailable";
@@ -95,6 +111,9 @@ function getWorkspaceLocatorLabel(location: WorkspaceLocation) {
 			return `p. ${location.pageNumber}`;
 		case "document-block":
 		case "flashcard":
+		case "quiz-question":
+			// Content-positional labels ("Card 3", "Question 3") need the item's
+			// current content, so the citation component supplies them.
 			return undefined;
 	}
 }
diff --git a/src/features/workspaces/locations/workspace-location.test.ts b/src/features/workspaces/locations/workspace-location.test.ts
index 8ae8010d1..85325813f 100644
--- a/src/features/workspaces/locations/workspace-location.test.ts
+++ b/src/features/workspaces/locations/workspace-location.test.ts
@@ -1,108 +1,95 @@
 import { describe, expect, it } from "vitest";
 
 import {
-	createWorkspaceReferenceRecords,
-	getWorkspaceLocationKey,
-	indexWorkspaceReferenceRecords,
-	parseWorkspaceReference,
+	parseWorkspaceAddress,
+	parseWorkspaceUnitRef,
+	resolveWorkspaceAddressLocation,
 	workspaceLocationSchema,
 } from "#/features/workspaces/locations/workspace-location";
 
-describe("workspace location", () => {
-	it.each([
-		[{ itemId: "item-1", kind: "item", version: 1 }, "1:item:item-1"],
-		[{ itemId: "item-1", kind: "pdf-page", pageNumber: 12, version: 1 }, "1:pdf-page:item-1:12"],
-		[
-			{
-				itemId: "item-1",
-				kind: "flashcard",
-				cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
-				version: 1,
-			},
-			"1:flashcard:item-1:f67080f9-0158-4565-86a9-4c90ed6809d2",
-		],
-		[
-			{ blockId: "b_abcdefghijkl", itemId: "item-1", kind: "document-block", version: 1 },
-			"1:document-block:item-1:b_abcdefghijkl",
-		],
-	])("parses and keys %o", (input, expectedKey) => {
-		const result = workspaceLocationSchema.safeParse(input);
-
-		expect(result.success).toBe(true);
-		if (result.success) {
-			expect(getWorkspaceLocationKey(result.data)).toBe(expectedKey);
-		}
-	});
-
-	it.each([
-		{ itemId: "", kind: "item", version: 1 },
-		{ itemId: "item-1", kind: "pdf-page", pageNumber: 0, version: 1 },
-		{ cardId: "not-a-uuid", itemId: "item-1", kind: "flashcard", version: 1 },
-		{ blockId: "block-1", itemId: "item-1", kind: "document-block", version: 1 },
-		{ itemId: "item-1", kind: "item", version: 2 },
-		{ extra: true, itemId: "item-1", kind: "item", version: 1 },
-	])("rejects invalid location %o", (input) => {
-		expect(workspaceLocationSchema.safeParse(input).success).toBe(false);
-	});
-});
-
-describe("workspace reference", () => {
-	it("creates an 11-character opaque reference", () => {
-		const location = { itemId: "item-1", kind: "item", version: 1 } as const;
-		const [{ ref }] = createWorkspaceReferenceRecords([location]);
-
-		expect(ref).toMatch(/^wr_[0-9A-Za-z]{8}$/);
-		expect(ref).toHaveLength(11);
-		expect(parseWorkspaceReference(ref)).toBe(ref);
-	});
-
-	it("reuses one ref for the same durable location", () => {
-		const location = { itemId: "item-1", kind: "pdf-page", pageNumber: 7, version: 1 } as const;
-		const records = createWorkspaceReferenceRecords([location, { ...location }], {
-			createCandidate: () => "wr_AAAAAAAA",
+describe("workspace addresses", () => {
+	it("parses item, unit, and revisioned forms", () => {
+		expect(parseWorkspaceAddress("Xk7p2Qa9")).toEqual({ refKey: "Xk7p2Qa9" });
+		expect(parseWorkspaceAddress("Xk7p2Qa9/p12")).toEqual({ refKey: "Xk7p2Qa9", unit: "p12" });
+		expect(parseWorkspaceAddress("Xk7p2Qa9/b_x7Kp2Qa9x8Lm.r_4f2a1b")).toEqual({
+			refKey: "Xk7p2Qa9",
+			unit: "b_x7Kp2Qa9x8Lm",
+			revision: "4f2a1b",
 		});
-
-		expect(records).toEqual([{ location, ref: "wr_AAAAAAAA" }]);
-	});
-
-	it("retries a colliding candidate", () => {
-		const candidates = ["wr_AAAAAAAA", "wr_AAAAAAAA", "wr_BBBBBBBB"];
-		const records = createWorkspaceReferenceRecords(
-			[
-				{ itemId: "item-1", kind: "item", version: 1 },
-				{ itemId: "item-2", kind: "item", version: 1 },
-			],
-			{
-				createCandidate: () => candidates.shift() ?? "wr_CCCCCCCC",
-			},
-		);
-
-		expect(records.map(({ ref }) => ref)).toEqual(["wr_AAAAAAAA", "wr_BBBBBBBB"]);
+		expect(parseWorkspaceAddress("not an address")).toBeUndefined();
+		expect(parseWorkspaceAddress("wr_7Kp2Qa9x")).toBeUndefined();
 	});
 
-	it("retains editable revisions and makes conflicting transcript refs unusable", () => {
-		const location = {
-			blockId: "b_abcdefghijkl",
+	it("interprets units against the item's type", () => {
+		const address = parseWorkspaceAddress("Xk7p2Qa9/p12")!;
+		expect(resolveWorkspaceAddressLocation({ id: "item-1", type: "file" }, address)).toEqual({
 			itemId: "item-1",
-			kind: "document-block",
+			kind: "pdf-page",
+			pageNumber: 12,
 			version: 1,
-		} as const;
-		const [record] = createWorkspaceReferenceRecords([{ location, revision: "0123456789" }], {
-			createCandidate: () => "wr_AAAAAAAA",
 		});
+		// The same unit means nothing on a document.
+		expect(
+			resolveWorkspaceAddressLocation({ id: "item-1", type: "document" }, address),
+		).toBeUndefined();
 
-		expect(record).toEqual({ location, ref: "wr_AAAAAAAA", revision: "0123456789" });
 		expect(
-			indexWorkspaceReferenceRecords([record!, { ...record!, revision: "9876543210" }]).get(
-				record!.ref,
+			resolveWorkspaceAddressLocation(
+				{ id: "item-1", type: "flashcard" },
+				parseWorkspaceAddress("Xk7p2Qa9/c_9xKp2Qab")!,
+			),
+		).toEqual({ cardId: "c_9xKp2Qab", itemId: "item-1", kind: "flashcard", version: 1 });
+		expect(
+			resolveWorkspaceAddressLocation(
+				{ id: "item-1", type: "quiz" },
+				parseWorkspaceAddress("Xk7p2Qa9/f67080f9-0158-4565-86a9-4c90ed6809d2")!,
+			),
+		).toEqual({
+			itemId: "item-1",
+			kind: "quiz-question",
+			questionId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
+			version: 1,
+		});
+		expect(
+			resolveWorkspaceAddressLocation(
+				{ id: "item-1", type: "document" },
+				parseWorkspaceAddress("Xk7p2Qa9")!,
 			),
-		).toBeNull();
+		).toEqual({ itemId: "item-1", kind: "item", version: 1 });
 	});
 
-	it.each(["", "wr_short", "xx_AAAAAAAA", "wr_!!!!!!!!", "wr_AAAAAAAAA"])(
-		"rejects malformed ref %s",
-		(input) => {
-			expect(parseWorkspaceReference(input)).toBeUndefined();
-		},
-	);
+	it("parses edit unit refs with their revision", () => {
+		expect(parseWorkspaceUnitRef("b_x7Kp2Qa9x8Lm.r_4f2a1b")).toEqual({
+			unit: "b_x7Kp2Qa9x8Lm",
+			revision: "4f2a1b",
+		});
+		expect(parseWorkspaceUnitRef("b_x7Kp2Qa9x8Lm")).toBeUndefined();
+	});
+
+	it("keeps persisted locations validating legacy and short entry ids", () => {
+		expect(
+			workspaceLocationSchema.safeParse({
+				cardId: "f67080f9-0158-4565-86a9-4c90ed6809d2",
+				itemId: "item-1",
+				kind: "flashcard",
+				version: 1,
+			}).success,
+		).toBe(true);
+		expect(
+			workspaceLocationSchema.safeParse({
+				cardId: "c_9xKp2Qab",
+				itemId: "item-1",
+				kind: "flashcard",
+				version: 1,
+			}).success,
+		).toBe(true);
+		expect(
+			workspaceLocationSchema.safeParse({
+				cardId: "not-an-id",
+				itemId: "item-1",
+				kind: "flashcard",
+				version: 1,
+			}).success,
+		).toBe(false);
+	});
 });
diff --git a/src/features/workspaces/locations/workspace-location.ts b/src/features/workspaces/locations/workspace-location.ts
index 67f9dc81d..89f94fdc0 100644
--- a/src/features/workspaces/locations/workspace-location.ts
+++ b/src/features/workspaces/locations/workspace-location.ts
@@ -3,19 +3,30 @@ import { z } from "zod";
 
 const WORKSPACE_REFERENCE_ALPHABET =
 	"0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz";
-const WORKSPACE_REFERENCE_RANDOM_LENGTH = 8;
-const WORKSPACE_REFERENCE_COLLISION_ATTEMPTS = 32;
-const createRandomWorkspaceReferenceSuffix = customAlphabet(
-	WORKSPACE_REFERENCE_ALPHABET,
-	WORKSPACE_REFERENCE_RANDOM_LENGTH,
-);
+/** Mints the short, durable, model-facing handle a workspace item keeps for life. */
+export const createWorkspaceItemRefKey = customAlphabet(WORKSPACE_REFERENCE_ALPHABET, 8);
 const workspaceLocationItemIdSchema = z.string().trim().min(1);
 
+const createWorkspaceEntryIdSuffix = customAlphabet(WORKSPACE_REFERENCE_ALPHABET, 8);
+
+/** Mints the id of one card or question, e.g. `c_9xKp2Qab`. */
+export function createWorkspaceEntryId(prefix: "c" | "q") {
+	return `${prefix}_${createWorkspaceEntryIdSuffix()}`;
+}
+
 /**
- * Durable, versioned pointer to content inside a workspace.
- *
- * Short AI-facing references are aliases for this value and must never replace
- * it in persisted application state.
+ * One flashcard or quiz-question id. Early content minted UUIDs; everything
+ * since mints the short prefixed form, and both stay valid ids forever.
+ */
+export const workspaceEntryIdSchema = z.union([
+	z.string().regex(/^[cq]_[0-9A-Za-z]{8}$/),
+	z.uuid(),
+]);
+
+/**
+ * Durable, versioned pointer to content inside a workspace, as persisted by
+ * document and chat citations. Model-facing addresses parse into this against
+ * the item they name.
  */
 export const workspaceLocationSchema = z.discriminatedUnion("kind", [
 	z.strictObject({
@@ -38,7 +49,13 @@ export const workspaceLocationSchema = z.discriminatedUnion("kind", [
 	z.strictObject({
 		itemId: workspaceLocationItemIdSchema,
 		kind: z.literal("flashcard"),
-		cardId: z.uuid(),
+		cardId: workspaceEntryIdSchema,
+		version: z.literal(1),
+	}),
+	z.strictObject({
+		itemId: workspaceLocationItemIdSchema,
+		kind: z.literal("quiz-question"),
+		questionId: workspaceEntryIdSchema,
 		version: z.literal(1),
 	}),
 ]);
@@ -46,127 +63,89 @@ export const workspaceLocationSchema = z.discriminatedUnion("kind", [
 /** A parsed durable workspace location. */
 export type WorkspaceLocation = Readonly<z.output<typeof workspaceLocationSchema>>;
 
-/** Schema for the exact short reference the model is allowed to copy. */
-export const workspaceReferenceInputSchema = z.string().regex(/^wr_[0-9A-Za-z]{8}$/);
-export const workspaceReferenceSchema = workspaceReferenceInputSchema.brand<"WorkspaceReference">();
-
-/** Short model-facing alias for a durable workspace location. */
-export type WorkspaceReference = z.output<typeof workspaceReferenceSchema>;
-
-/** Schema for a durable location retained behind a short reference. */
-export const workspaceReferenceRecordSchema = z.strictObject({
-	location: workspaceLocationSchema,
-	ref: workspaceReferenceSchema,
-	revision: z
-		.string()
-		.regex(/^[A-Za-z0-9_-]{10}$/)
-		.optional(),
-});
-
-/** Durable record retained behind a short workspace reference. */
-export type WorkspaceReferenceRecord = Readonly<z.output<typeof workspaceReferenceRecordSchema>>;
-
 /**
- * Produces the canonical in-memory key for a workspace location.
+ * The model-facing address grammar: `refKey[/unit][.r_revision]`.
  *
- * @param location - Parsed workspace location.
- * @returns A collision-free key within location schema version 1.
+ * `refKey` is the item's durable 8-character handle. `unit` names one piece of
+ * it — `p5` a physical page, `b_…` a document block, a card or question id for
+ * study items — and is interpreted against the item's type, so the token never
+ * has to encode what kind of thing it names. `.r_…` carries the 6-character
+ * content revision an edit must present. The whole string is self-describing:
+ * nothing has to be minted, stored, or kept alive server-side for it to
+ * resolve, so an address from any point in a conversation keeps working.
  */
-export function getWorkspaceLocationKey(location: WorkspaceLocation) {
-	switch (location.kind) {
-		case "item":
-			return `1:item:${location.itemId}`;
-		case "pdf-page":
-			return `1:pdf-page:${location.itemId}:${location.pageNumber}`;
-		case "document-block":
-			return `1:document-block:${location.itemId}:${location.blockId}`;
-		case "flashcard":
-			return `1:flashcard:${location.itemId}:${location.cardId}`;
-	}
-}
+const workspaceAddressPattern =
+	/^([0-9A-Za-z]{8})(?:\/([A-Za-z0-9_-]{1,40}?))?(?:\.r_([A-Za-z0-9_-]{6}))?$/;
 
-/**
- * Parses an untrusted short workspace reference.
- *
- * @param input - Untrusted model or persisted value.
- * @returns A branded reference when valid.
- */
-export function parseWorkspaceReference(input: unknown) {
-	const parsed = workspaceReferenceSchema.safeParse(input);
+export const workspaceAddressInputSchema = z.string().regex(workspaceAddressPattern);
 
-	return parsed.success ? parsed.data : undefined;
+export interface WorkspaceAddress {
+	refKey: string;
+	unit?: string;
+	revision?: string;
 }
 
-/** Index app-issued refs while making collisions unusable. */
-export function indexWorkspaceReferenceRecords(
-	records: readonly WorkspaceReferenceRecord[],
-): ReadonlyMap<WorkspaceReference, WorkspaceReferenceRecord | null> {
-	const index = new Map<WorkspaceReference, WorkspaceReferenceRecord | null>();
-	for (const record of records) {
-		const existing = index.get(record.ref);
-		if (existing === undefined) {
-			index.set(record.ref, record);
-		} else if (
-			existing &&
-			(getWorkspaceLocationKey(existing.location) !== getWorkspaceLocationKey(record.location) ||
-				existing.revision !== record.revision)
-		) {
-			index.set(record.ref, null);
-		}
-	}
-	return index;
+export function parseWorkspaceAddress(input: unknown): WorkspaceAddress | undefined {
+	if (typeof input !== "string") return undefined;
+	const match = workspaceAddressPattern.exec(input.trim());
+	if (!match) return undefined;
+	return {
+		refKey: match[1]!,
+		...(match[2] ? { unit: match[2] } : {}),
+		...(match[3] ? { revision: match[3] } : {}),
+	};
 }
 
 /**
- * Creates deduplicated, collision-checked refs for durable locations.
- *
- * The optional candidate source is an internal test seam. Production callers
- * should use the default cryptographically strong Nano ID source.
+ * Interprets an address's unit against the item it names.
  *
- * @param locations - Durable locations in desired record order.
- * @param options - Optional candidate source for deterministic verification.
- * @returns One reference record per distinct location.
+ * @returns The durable location, or undefined when the unit cannot belong to
+ * an item of this type.
  */
-export function createWorkspaceReferenceRecords(
-	targets: readonly (WorkspaceLocation | { location: WorkspaceLocation; revision: string })[],
-	options: { readonly createCandidate?: () => string } = {},
-): WorkspaceReferenceRecord[] {
-	const createCandidate =
-		options.createCandidate ?? (() => `wr_${createRandomWorkspaceReferenceSuffix()}`);
-	const locationKeys = new Set<string>();
-	const refs = new Set<WorkspaceReference>();
-	const records: WorkspaceReferenceRecord[] = [];
-
-	for (const target of targets) {
-		const { location, revision } =
-			"location" in target ? target : { location: target, revision: undefined };
-		const locationKey = getWorkspaceLocationKey(location);
-		if (locationKeys.has(locationKey)) {
-			continue;
-		}
-
-		let allocatedRef: WorkspaceReference | undefined;
-		for (let attempt = 0; attempt < WORKSPACE_REFERENCE_COLLISION_ATTEMPTS; attempt += 1) {
-			const ref = parseWorkspaceReference(createCandidate());
-			if (!ref) {
-				throw new Error("Workspace reference candidate source returned an invalid value.");
-			}
-			if (refs.has(ref)) {
-				continue;
-			}
-
-			allocatedRef = ref;
-			break;
-		}
+export function resolveWorkspaceAddressLocation(
+	item: { id: string; type: "document" | "file" | "flashcard" | "folder" | "quiz" },
+	address: WorkspaceAddress,
+): WorkspaceLocation | undefined {
+	if (address.unit === undefined) {
+		return { itemId: item.id, kind: "item", version: 1 };
+	}
+	if (item.type === "file") {
+		const page = /^p([1-9]\d{0,5})$/.exec(address.unit);
+		return page
+			? { itemId: item.id, kind: "pdf-page", pageNumber: Number(page[1]), version: 1 }
+			: undefined;
+	}
+	if (item.type === "document") {
+		return /^b_[A-Za-z0-9_-]{12}$/.test(address.unit)
+			? { blockId: address.unit, itemId: item.id, kind: "document-block", version: 1 }
+			: undefined;
+	}
+	if (item.type === "flashcard") {
+		const cardId = workspaceEntryIdSchema.safeParse(address.unit);
+		return cardId.success
+			? { cardId: cardId.data, itemId: item.id, kind: "flashcard", version: 1 }
+			: undefined;
+	}
+	if (item.type === "quiz") {
+		const questionId = workspaceEntryIdSchema.safeParse(address.unit);
+		return questionId.success
+			? { itemId: item.id, kind: "quiz-question", questionId: questionId.data, version: 1 }
+			: undefined;
+	}
+	return undefined;
+}
 
-		if (!allocatedRef) {
-			throw new Error("Unable to allocate a collision-free workspace reference.");
-		}
+/**
+ * A unit ref as copied from a read into an edit: `unit.r_revision`. The item
+ * is already named by the edit call's path, so the ref stays item-relative.
+ */
+const workspaceUnitRefPattern = /^([A-Za-z0-9_-]{1,40}?)\.r_([A-Za-z0-9_-]{6})$/;
 
-		locationKeys.add(locationKey);
-		refs.add(allocatedRef);
-		records.push({ location, ref: allocatedRef, ...(revision ? { revision } : {}) });
-	}
+export const workspaceUnitRefInputSchema = z.string().regex(workspaceUnitRefPattern);
 
-	return records;
+export function parseWorkspaceUnitRef(
+	input: string,
+): { unit: string; revision: string } | undefined {
+	const match = workspaceUnitRefPattern.exec(input);
+	return match ? { unit: match[1]!, revision: match[2]! } : undefined;
 }
diff --git a/src/features/workspaces/model/item-display.ts b/src/features/workspaces/model/item-display.ts
index ad04ff237..b6ebf680a 100644
--- a/src/features/workspaces/model/item-display.ts
+++ b/src/features/workspaces/model/item-display.ts
@@ -1,4 +1,4 @@
-import { FilePen, Folder, Layers3, Paperclip, Upload } from "lucide-react";
+import { FilePen, Folder, Layers3, ListChecks, Paperclip, Upload } from "lucide-react";
 
 import {
 	type WorkspaceItem,
@@ -15,6 +15,7 @@ const workspaceItemIcons = {
 	file: Paperclip,
 	flashcard: Layers3,
 	folder: Folder,
+	quiz: ListChecks,
 } satisfies Record<WorkspaceItemType, typeof FilePen>;
 
 /**
@@ -47,7 +48,7 @@ export function getWorkspaceItemDisplay(item: WorkspaceItem) {
 	};
 }
 
-function createWorkspaceItemAction(type: "document" | "flashcard" | "folder") {
+function createWorkspaceItemAction(type: "document" | "flashcard" | "folder" | "quiz") {
 	const display = getWorkspaceItemTypeDisplay(type);
 	return {
 		kind: "item" as const,
@@ -77,6 +78,6 @@ export const workspaceCreateMenuActionGroups = [
 	},
 	{
 		id: "study",
-		actions: [createWorkspaceItemAction("flashcard")],
+		actions: [createWorkspaceItemAction("flashcard"), createWorkspaceItemAction("quiz")],
 	},
 ] as const;
diff --git a/src/features/workspaces/model/workspace-ai-context-snapshot.test.ts b/src/features/workspaces/model/workspace-ai-context-snapshot.test.ts
index adec38ee5..919893218 100644
--- a/src/features/workspaces/model/workspace-ai-context-snapshot.test.ts
+++ b/src/features/workspaces/model/workspace-ai-context-snapshot.test.ts
@@ -5,6 +5,7 @@ import { buildWorkspaceAiContextSnapshot } from "#/features/workspaces/model/wor
 
 const item: WorkspaceItem = {
 	color: null,
+	refKey: "ref-cards-1",
 	createdAt: "2026-08-13T00:00:00.000Z",
 	id: "cards-1",
 	metadataJson: {},
diff --git a/src/features/workspaces/model/workspace-page.test.ts b/src/features/workspaces/model/workspace-page.test.ts
index 4e14033d0..f14e9ba51 100644
--- a/src/features/workspaces/model/workspace-page.test.ts
+++ b/src/features/workspaces/model/workspace-page.test.ts
@@ -27,6 +27,7 @@ function createItem(input: Pick<WorkspaceItem, "id"> & Partial<WorkspaceItem>):
 		color: null,
 		createdAt: "2026-01-01T00:00:00.000Z",
 		id: input.id,
+		refKey: input.refKey ?? input.id,
 		metadataJson: {},
 		name: input.id,
 		parentId: input.parentId ?? null,
diff --git a/src/features/workspaces/model/workspace-page.ts b/src/features/workspaces/model/workspace-page.ts
index 027d61ce1..0f34110de 100644
--- a/src/features/workspaces/model/workspace-page.ts
+++ b/src/features/workspaces/model/workspace-page.ts
@@ -9,6 +9,7 @@ import {
 	WORKSPACE_ITEM_SORT_STEP,
 } from "#/features/workspaces/defaults";
 import { buildWorkspaceItemCreateBootstrap } from "#/features/workspaces/model/workspace-item-create-bootstrap";
+import { createWorkspaceItemRefKey } from "#/features/workspaces/locations/workspace-location";
 import {
 	getWorkspaceRootItems,
 	getWorkspaceSubtreeItemIds,
@@ -32,12 +33,14 @@ export function createWorkspaceItemInPage(
 		initialContent: input.initialContent,
 	});
 
+	// Placeholder until the realtime upsert delivers the server-minted key.
 	return upsertWorkspaceItemInPage(page, {
 		id: input.id,
 		workspaceId: input.workspaceId,
 		parentId,
 		type: input.type,
 		name,
+		refKey: createWorkspaceItemRefKey(),
 		color: input.color ?? null,
 		metadataJson,
 		sortOrder: getNextWorkspaceItemSortOrder(page.items, parentId),
diff --git a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
index 4e23555b6..5ccf3499f 100644
--- a/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
+++ b/src/features/workspaces/operations/__snapshots__/workspace-tool-surface.test.ts.snap
@@ -45,7 +45,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
   "additionalProperties": false,
   "properties": {
     "items": {
-      "description": "One or more folders, documents, or flashcard sets to create in order, at most 20. Parent folders must already exist or be created earlier in the same request.",
+      "description": "One or more workspace items to create in order, at most 20. Parent folders must already exist or be created earlier in the same request.",
       "items": {
         "oneOf": [
           {
@@ -72,7 +72,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
             "description": "Document to create.",
             "properties": {
               "initialContent": {
-                "description": "Optional initial HTML content. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as <div data-type="widget" title="Short title">…HTML-escaped fragment…</div>.",
+                "description": "Optional initial HTML content. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure> — draw a diagram or describe the visual in words instead. Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="Xk7p2Qa9/b_x7Kp2Qa9x8Lm"></citation> placed after the claim it supports — the address is the item's ref, or ref/unit for a page, block, card, or question, with any .r_ suffix dropped. A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as <div data-type="widget" title="Short title">…HTML-escaped fragment…</div>.",
                 "maxLength": 512000,
                 "type": "string",
               },
@@ -97,7 +97,7 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
             "description": "Flashcard set to create.",
             "properties": {
               "cards": {
-                "description": "Ordered cards. Flashcard fronts and backs are HTML. Keep each side concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. Do not use headings, tables, images, widgets, task lists, or citations inside a card.",
+                "description": "Ordered cards. Flashcard fronts and backs are HTML. Keep each side concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. Do not use headings, tables, images, widgets, task lists, or citations inside a card. Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram.",
                 "items": {
                   "additionalProperties": false,
                   "properties": {
@@ -141,6 +141,74 @@ exports[`workspace tool surface > workspace_create_items input schema is stable
             ],
             "type": "object",
           },
+          {
+            "additionalProperties": false,
+            "description": "Quiz to create.",
+            "properties": {
+              "path": {
+                "description": "Final absolute path for the quiz.",
+                "minLength": 1,
+                "type": "string",
+              },
+              "questions": {
+                "description": "Ordered multiple-choice questions. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
+                "items": {
+                  "additionalProperties": false,
+                  "properties": {
+                    "correctAnswer": {
+                      "description": "HTML for the single correct option. Never mark it in the stem; its final position is shuffled server-side.",
+                      "maxLength": 8000,
+                      "minLength": 1,
+                      "type": "string",
+                    },
+                    "distractors": {
+                      "description": "HTML for each incorrect option: strictly wrong, plausible, and grounded in a specific misconception. Use 3 for a standard question, 1 for true/false.",
+                      "items": {
+                        "maxLength": 8000,
+                        "minLength": 1,
+                        "type": "string",
+                      },
+                      "maxItems": 4,
+                      "minItems": 1,
+                      "type": "array",
+                    },
+                    "explanation": {
+                      "description": "Short HTML explanation of why the correct answer is right, touching on why the others are not.",
+                      "maxLength": 8000,
+                      "minLength": 1,
+                      "type": "string",
+                    },
+                    "question": {
+                      "description": "HTML question stem.",
+                      "maxLength": 8000,
+                      "minLength": 1,
+                      "type": "string",
+                    },
+                  },
+                  "required": [
+                    "question",
+                    "correctAnswer",
+                    "distractors",
+                    "explanation",
+                  ],
+                  "type": "object",
+                },
+                "maxItems": 100,
+                "minItems": 1,
+                "type": "array",
+              },
+              "type": {
+                "const": "quiz",
+                "type": "string",
+              },
+            },
+            "required": [
+              "type",
+              "path",
+              "questions",
+            ],
+            "type": "object",
+          },
         ],
       },
       "maxItems": 20,
@@ -187,7 +255,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
       "description": "Document edits.",
       "properties": {
         "edits": {
-          "description": "Ordered document edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. update accepts exactly one top-level block; replace may replace one block with several. move requires exactly one of beforeRef or afterRef. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as <div data-type="widget" title="Short title">…HTML-escaped fragment…</div>.",
+          "description": "Ordered document edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. update accepts exactly one top-level block; replace may replace one block with several. move requires exactly one of beforeRef or afterRef. Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure> — draw a diagram or describe the visual in words instead. Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="Xk7p2Qa9/b_x7Kp2Qa9x8Lm"></citation> placed after the claim it supports — the address is the item's ref, or ref/unit for a page, block, card, or question, with any .r_ suffix dropped. A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as <div data-type="widget" title="Short title">…HTML-escaped fragment…</div>.",
           "items": {
             "anyOf": [
               {
@@ -209,7 +277,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                   },
                   "ref": {
                     "description": "Exact ref from a recent document or block read.",
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -229,7 +297,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                   },
                   "ref": {
                     "description": "Exact ref from a recent document or block read.",
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -254,7 +322,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                   },
                   "ref": {
                     "description": "Exact ref from a recent document or block read.",
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                   "replace": {
@@ -276,12 +344,12 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                 "properties": {
                   "afterRef": {
                     "description": "Exact ref from a recent document or block read.",
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                   "beforeRef": {
                     "description": "Exact ref from a recent document or block read.",
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                   "op": {
@@ -290,7 +358,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                   },
                   "ref": {
                     "description": "Exact ref from a recent document or block read.",
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -328,7 +396,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
       "description": "Flashcard edits.",
       "properties": {
         "edits": {
-          "description": "Ordered flashcard edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. replace changes both sides; replace_text requires front or back as side; move requires exactly one of beforeRef or afterRef. Flashcard fronts and backs are HTML. Keep each side concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. Do not use headings, tables, images, widgets, task lists, or citations inside a card.",
+          "description": "Ordered flashcard edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. replace changes both sides; replace_text requires front or back as side; move requires exactly one of beforeRef or afterRef. Flashcard fronts and backs are HTML. Keep each side concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. Do not use headings, tables, images, widgets, task lists, or citations inside a card. Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram.",
           "items": {
             "anyOf": [
               {
@@ -352,7 +420,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                     "type": "string",
                   },
                   "ref": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -382,7 +450,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                     "type": "string",
                   },
                   "ref": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -410,7 +478,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                     "type": "string",
                   },
                   "ref": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -436,7 +504,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                     "type": "string",
                   },
                   "ref": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                   "replace": {
@@ -465,11 +533,11 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                 "additionalProperties": false,
                 "properties": {
                   "afterRef": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                   "beforeRef": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                   "op": {
@@ -477,7 +545,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                     "type": "string",
                   },
                   "ref": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -495,7 +563,7 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
                     "type": "string",
                   },
                   "ref": {
-                    "pattern": "^wr_[0-9A-Za-z]{8}$",
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
                     "type": "string",
                   },
                 },
@@ -528,6 +596,257 @@ exports[`workspace tool surface > workspace_edit_item input schema is stable 1`]
       ],
       "type": "object",
     },
+    {
+      "additionalProperties": false,
+      "description": "Quiz edits.",
+      "properties": {
+        "edits": {
+          "description": "Ordered quiz edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. insert and replace take a full authored question and reshuffle its options; update changes only the stem or explanation in place; replace_text requires question, options, or explanation as field and never reshuffles; move requires exactly one of beforeRef or afterRef. Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML. A code block carries its language as a class on the inner <code>: <pre><code class="language-python">…</code></pre>. Without that class the block renders unhighlighted and unlabelled. Do not use headings, tables, images, widgets, task lists, or citations inside a question. Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram's alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram. A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.",
+          "items": {
+            "anyOf": [
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "correctAnswer": {
+                    "description": "HTML for the single correct option. Never mark it in the stem; its final position is shuffled server-side.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "distractors": {
+                    "description": "HTML for each incorrect option: strictly wrong, plausible, and grounded in a specific misconception. Use 3 for a standard question, 1 for true/false.",
+                    "items": {
+                      "maxLength": 8000,
+                      "minLength": 1,
+                      "type": "string",
+                    },
+                    "maxItems": 4,
+                    "minItems": 1,
+                    "type": "array",
+                  },
+                  "explanation": {
+                    "description": "Short HTML explanation of why the correct answer is right, touching on why the others are not.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "op": {
+                    "enum": [
+                      "insert_before",
+                      "insert_after",
+                    ],
+                    "type": "string",
+                  },
+                  "question": {
+                    "description": "HTML question stem.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "ref": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                },
+                "required": [
+                  "op",
+                  "ref",
+                  "question",
+                  "correctAnswer",
+                  "distractors",
+                  "explanation",
+                ],
+                "type": "object",
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "explanation": {
+                    "description": "New HTML explanation.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "op": {
+                    "const": "update",
+                    "type": "string",
+                  },
+                  "question": {
+                    "description": "New HTML question stem.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "ref": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                },
+                "required": [
+                  "op",
+                  "ref",
+                ],
+                "type": "object",
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "correctAnswer": {
+                    "description": "HTML for the single correct option. Never mark it in the stem; its final position is shuffled server-side.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "distractors": {
+                    "description": "HTML for each incorrect option: strictly wrong, plausible, and grounded in a specific misconception. Use 3 for a standard question, 1 for true/false.",
+                    "items": {
+                      "maxLength": 8000,
+                      "minLength": 1,
+                      "type": "string",
+                    },
+                    "maxItems": 4,
+                    "minItems": 1,
+                    "type": "array",
+                  },
+                  "explanation": {
+                    "description": "Short HTML explanation of why the correct answer is right, touching on why the others are not.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "op": {
+                    "const": "replace",
+                    "type": "string",
+                  },
+                  "question": {
+                    "description": "HTML question stem.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "ref": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                },
+                "required": [
+                  "op",
+                  "ref",
+                  "question",
+                  "correctAnswer",
+                  "distractors",
+                  "explanation",
+                ],
+                "type": "object",
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "field": {
+                    "description": "Where to look: the stem, all options together, or the explanation.",
+                    "enum": [
+                      "question",
+                      "options",
+                      "explanation",
+                    ],
+                    "type": "string",
+                  },
+                  "find": {
+                    "description": "Exact HTML text from the selected field. It must appear exactly once.",
+                    "maxLength": 8000,
+                    "minLength": 1,
+                    "type": "string",
+                  },
+                  "op": {
+                    "const": "replace_text",
+                    "type": "string",
+                  },
+                  "ref": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                  "replace": {
+                    "description": "Replacement text. May be empty.",
+                    "maxLength": 8000,
+                    "type": "string",
+                  },
+                },
+                "required": [
+                  "op",
+                  "ref",
+                  "field",
+                  "find",
+                  "replace",
+                ],
+                "type": "object",
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "afterRef": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                  "beforeRef": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                  "op": {
+                    "const": "move",
+                    "type": "string",
+                  },
+                  "ref": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                },
+                "required": [
+                  "op",
+                  "ref",
+                ],
+                "type": "object",
+              },
+              {
+                "additionalProperties": false,
+                "properties": {
+                  "op": {
+                    "const": "delete",
+                    "type": "string",
+                  },
+                  "ref": {
+                    "pattern": "^([A-Za-z0-9_-]{1,40}?)\\.r_([A-Za-z0-9_-]{6})$",
+                    "type": "string",
+                  },
+                },
+                "required": [
+                  "op",
+                  "ref",
+                ],
+                "type": "object",
+              },
+            ],
+          },
+          "maxItems": 100,
+          "minItems": 1,
+          "type": "array",
+        },
+        "path": {
+          "description": "Absolute path of one actual ThinkEx quiz to edit.",
+          "minLength": 1,
+          "type": "string",
+        },
+        "type": {
+          "const": "quiz",
+          "type": "string",
+        },
+      },
+      "required": [
+        "type",
+        "path",
+        "edits",
+      ],
+      "type": "object",
+    },
   ],
 }
 `;
@@ -695,7 +1014,7 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
                 "type": "string",
               },
               "range": {
-                "description": "Up to 20 physical pages from an extracted file, like 1, 3, 5-7, or 1,4-6. Defaults to page 1.",
+                "description": "Up to 20 physical pages from an extracted file, like 1, 3, 5-7, or 1,4-6.",
                 "minLength": 1,
                 "pattern": "^\\d+(?:\\s*-\\s*\\d+)?(?:\\s*,\\s*\\d+(?:\\s*-\\s*\\d+)?)*$",
                 "type": "string",
@@ -712,7 +1031,7 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
             "additionalProperties": false,
             "properties": {
               "mode": {
-                "const": "cards",
+                "const": "entries",
                 "type": "string",
               },
               "path": {
@@ -721,7 +1040,7 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
                 "type": "string",
               },
               "range": {
-                "description": "Up to 20 card numbers from a flashcard set, like 1, 3, 5-7, or 1,4-6.",
+                "description": "Up to 20 entry numbers. Flashcards and quiz questions take lists like 1, 3, 5-7; document blocks take one contiguous range like 5-12.",
                 "minLength": 1,
                 "pattern": "^\\d+(?:\\s*-\\s*\\d+)?(?:\\s*,\\s*\\d+(?:\\s*-\\s*\\d+)?)*$",
                 "type": "string",
@@ -734,32 +1053,6 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
             ],
             "type": "object",
           },
-          {
-            "additionalProperties": false,
-            "properties": {
-              "cursor": {
-                "description": "Opaque cursor returned by a previous read.",
-                "maxLength": 4096,
-                "minLength": 1,
-                "type": "string",
-              },
-              "mode": {
-                "const": "continue",
-                "type": "string",
-              },
-              "path": {
-                "description": "Absolute path of the workspace item to read.",
-                "minLength": 1,
-                "type": "string",
-              },
-            },
-            "required": [
-              "path",
-              "cursor",
-              "mode",
-            ],
-            "type": "object",
-          },
           {
             "additionalProperties": false,
             "properties": {
@@ -767,21 +1060,15 @@ exports[`workspace tool surface > workspace_read_items input schema is stable 1`
                 "const": "ref",
                 "type": "string",
               },
-              "path": {
-                "description": "Absolute path of the workspace item to read.",
-                "minLength": 1,
-                "type": "string",
-              },
               "ref": {
-                "description": "Ref from an earlier read. Returns the exact content it identifies with a current ref.",
-                "pattern": "^wr_[0-9A-Za-z]{8}$",
+                "description": "Address from an earlier read or citation, like itemRef or itemRef/unit.",
+                "pattern": "^([0-9A-Za-z]{8})(?:\\/([A-Za-z0-9_-]{1,40}?))?(?:\\.r_([A-Za-z0-9_-]{6}))?$",
                 "type": "string",
               },
             },
             "required": [
-              "path",
-              "ref",
               "mode",
+              "ref",
             ],
             "type": "object",
           },
diff --git a/src/features/workspaces/operations/create-items.ts b/src/features/workspaces/operations/create-items.ts
index b1b9eec0d..726ba599a 100644
--- a/src/features/workspaces/operations/create-items.ts
+++ b/src/features/workspaces/operations/create-items.ts
@@ -18,9 +18,10 @@ import {
 	stringifyFlashcardSetContent,
 } from "#/features/workspaces/flashcards/flashcard-content";
 import {
-	createWorkspaceReferenceRecords,
-	type WorkspaceReferenceRecord,
-} from "#/features/workspaces/locations/workspace-location";
+	createQuizSetFromInputs,
+	stringifyQuizSetContent,
+	type QuizQuestionInput,
+} from "#/features/workspaces/quizzes/quiz-content";
 import {
 	getParentWorkspacePath,
 	getWorkspacePathName,
@@ -40,6 +41,11 @@ export type CreateWorkspaceItemOperationInput =
 			type: "flashcard";
 			path: string;
 			cards: Array<{ front: string; back: string }>;
+	  }
+	| {
+			type: "quiz";
+			path: string;
+			questions: QuizQuestionInput[];
 	  };
 
 export interface CreateWorkspaceItemsOperationInput {
@@ -58,13 +64,14 @@ export interface CreateWorkspaceItemsFailure {
 export interface CreatedWorkspaceItem {
 	itemId: string;
 	path: string;
-	type: "document" | "flashcard" | "folder";
+	/** The item's durable address, for citations and later reads. */
+	ref: string;
+	type: "document" | "flashcard" | "folder" | "quiz";
 }
 
 export interface CreateWorkspaceItemsOperationResult {
 	items: CreatedWorkspaceItem[];
 	failed: CreateWorkspaceItemsFailure[];
-	references: WorkspaceReferenceRecord[];
 }
 
 type CreateWorkspaceItemPathResolution =
@@ -177,17 +184,12 @@ export async function createWorkspaceItemsOperation(
 		items.push({
 			itemId: id,
 			path: createdPath,
+			ref: command.result.refKey,
 			type: itemInput.type,
 		});
 	}
 
-	return {
-		items,
-		failed,
-		references: createWorkspaceReferenceRecords(
-			items.map((item) => ({ itemId: item.itemId, kind: "item", version: 1 })),
-		),
-	};
+	return { items, failed };
 }
 
 function resolveCreateWorkspaceItemParent(resolution: WorkspacePathResolution):
@@ -278,10 +280,13 @@ function getCreateWorkspaceItemInitialContent(input: CreateWorkspaceItemOperatio
 			detail?: string;
 			status: "failed";
 	  } {
-	if (input.type === "flashcard") {
+	if (input.type === "flashcard" || input.type === "quiz") {
 		try {
 			return {
-				content: stringifyFlashcardSetContent(createFlashcardSetFromHtml(input.cards)),
+				content:
+					input.type === "flashcard"
+						? stringifyFlashcardSetContent(createFlashcardSetFromHtml(input.cards))
+						: stringifyQuizSetContent(createQuizSetFromInputs(input.questions)),
 				status: "ready",
 			};
 		} catch (error) {
diff --git a/src/features/workspaces/operations/document-citations.ts b/src/features/workspaces/operations/document-citations.ts
index 209a96869..a97f547a8 100644
--- a/src/features/workspaces/operations/document-citations.ts
+++ b/src/features/workspaces/operations/document-citations.ts
@@ -2,16 +2,21 @@ import {
 	applyDocumentCitationLocations,
 	readDocumentCitationRefs,
 } from "#/features/workspaces/documents/document-ai-html";
-import { indexWorkspaceReferenceRecords } from "#/features/workspaces/locations/workspace-location";
+import {
+	parseWorkspaceAddress,
+	resolveWorkspaceAddressLocation,
+	type WorkspaceLocation,
+} from "#/features/workspaces/locations/workspace-location";
+import { getWorkspaceItemRefKeyIndex } from "#/features/workspaces/persistence/workspace-items";
 import type { WorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
 
 /**
- * Turn the refs an assistant cited into the locations a document can keep.
+ * Turn the addresses an assistant cited into the locations a document keeps.
  *
- * The assistant cites `wr_` refs, the same way it cites in a chat reply, but a
- * ref only means something inside the turn that produced it. Resolving here
- * lets the document store the item and page it points at; what that source is
- * called is read from the workspace when the citation is drawn.
+ * The assistant cites the same `refKey/unit` addresses it reads with. They
+ * resolve statelessly — refKey to item, unit against the item's type — so the
+ * document stores the durable location, and what that source is called is
+ * read from the workspace when the citation is drawn.
  */
 export async function resolveDocumentCitations(input: {
 	context: WorkspaceAccessContext;
@@ -19,16 +24,21 @@ export async function resolveDocumentCitations(input: {
 }): Promise<string> {
 	const refs = readDocumentCitationRefs(input.html);
 
-	if (refs.length === 0 || !input.context.resolveWorkspaceReferences) {
+	if (refs.length === 0) {
 		return input.html;
 	}
 
-	const records = await input.context.resolveWorkspaceReferences(refs);
-	const locations = new Map(
-		[...indexWorkspaceReferenceRecords(records)].flatMap(([ref, record]) =>
-			record ? [[ref, record.location] as const] : [],
-		),
-	);
+	const refKeyIndex = await getWorkspaceItemRefKeyIndex({
+		workspaceId: input.context.workspaceId,
+	});
+	const locations = new Map<string, WorkspaceLocation>();
+	for (const ref of new Set(refs)) {
+		const address = parseWorkspaceAddress(ref);
+		if (!address) continue;
+		const resolved = refKeyIndex.get(address.refKey);
+		const location = resolved ? resolveWorkspaceAddressLocation(resolved.item, address) : undefined;
+		if (location) locations.set(ref, location);
+	}
 
 	return applyDocumentCitationLocations(input.html, locations);
 }
diff --git a/src/features/workspaces/operations/edit-item.ts b/src/features/workspaces/operations/edit-item.ts
index 30cde0279..d9e65039a 100644
--- a/src/features/workspaces/operations/edit-item.ts
+++ b/src/features/workspaces/operations/edit-item.ts
@@ -12,20 +12,22 @@ import { resolveDocumentCitations } from "#/features/workspaces/operations/docum
 import {
 	applyFlashcardEdits,
 	type FlashcardEdit,
-	type FlashcardEditTarget,
 } from "#/features/workspaces/flashcards/flashcard-edits";
 import { updateFlashcardSet } from "#/features/workspaces/flashcards/flashcard-persistence";
+import { applyQuizEdits, type QuizEdit } from "#/features/workspaces/quizzes/quiz-edits";
+import { updateQuizSet } from "#/features/workspaces/quizzes/quiz-persistence";
+import type { OrderedEntryEditTarget } from "#/features/workspaces/content/ordered-entry-edits";
 import {
-	indexWorkspaceReferenceRecords,
-	parseWorkspaceReference,
-	type WorkspaceReferenceRecord,
+	parseWorkspaceUnitRef,
+	workspaceEntryIdSchema,
 } from "#/features/workspaces/locations/workspace-location";
 
 type EditWorkspaceItemFailureCode = (typeof editWorkspaceItemFailureCodes)[number];
 
 export type EditWorkspaceItemOperationInput =
 	| { edits: DocumentAiEdit[]; path: string; type: "document" }
-	| { edits: FlashcardEdit[]; path: string; type: "flashcard" };
+	| { edits: FlashcardEdit[]; path: string; type: "flashcard" }
+	| { edits: QuizEdit[]; path: string; type: "quiz" };
 
 interface EditWorkspaceItemFailure {
 	code: EditWorkspaceItemFailureCode;
@@ -37,7 +39,7 @@ export interface EditWorkspaceItemOperationResult {
 	applied: number;
 	failed: EditWorkspaceItemFailure[];
 	itemId?: string;
-	itemType?: "document" | "flashcard";
+	itemType?: "document" | "flashcard" | "quiz";
 	lineChanges?: DocumentEditLineChanges;
 	path: string;
 }
@@ -77,66 +79,51 @@ export async function editWorkspaceItemOperation(
 		};
 	}
 
-	if (input.type === "flashcard") {
-		const targets = await resolveEditTargets<FlashcardEdit, FlashcardEditTarget>(
-			accessContext,
-			input.edits,
-			(record) =>
-				record.location.kind === "flashcard" &&
-				record.location.itemId === resolution.item.id &&
-				record.revision
-					? { cardId: record.location.cardId, revision: record.revision }
-					: undefined,
-		);
+	if (input.type === "flashcard" || input.type === "quiz") {
+		const itemId = resolution.item.id;
+		const targets = collectEntryEditTargets(input.edits);
 		const { env } = await import("cloudflare:workers");
-		const result = await updateFlashcardSet(
-			env,
-			{
-				actorUserId: accessContext.actor.userId,
-				itemId: resolution.item.id,
-				workspaceId: accessContext.workspaceId,
-			},
-			async (content) => {
-				const applied = await applyFlashcardEdits(content, input.edits, targets);
-				return { changed: applied.applied > 0, content: applied.content, result: applied };
-			},
-		);
+		const persistenceInput = {
+			actorUserId: accessContext.actor.userId,
+			itemId,
+			workspaceId: accessContext.workspaceId,
+		};
+		const result =
+			input.type === "flashcard"
+				? await updateFlashcardSet(env, persistenceInput, async (content) => {
+						const applied = await applyFlashcardEdits(content, input.edits, targets);
+						return { changed: applied.applied > 0, content: applied.content, result: applied };
+					})
+				: await updateQuizSet(env, persistenceInput, async (content) => {
+						const applied = await applyQuizEdits(content, input.edits, targets);
+						return { changed: applied.applied > 0, content: applied.content, result: applied };
+					});
 		return {
 			applied: result.applied,
 			failed: result.failed,
-			itemId: resolution.item.id,
-			itemType: "flashcard",
+			itemId,
+			itemType: input.type,
 			path: resolution.path,
 		};
 	}
-	const [targets, documentSession] = await Promise.all([
-		resolveEditTargets(accessContext, input.edits, (record) =>
-			record.location.kind === "document-block" &&
-			record.location.itemId === resolution.item.id &&
-			record.revision
-				? `${record.location.blockId}.r_${record.revision}`
-				: undefined,
-		),
-		getDocumentSession({
-			itemId: resolution.item.id,
-			workspaceId: accessContext.workspaceId,
-		}),
-	]);
+	const documentSession = await getDocumentSession({
+		itemId: resolution.item.id,
+		workspaceId: accessContext.workspaceId,
+	});
 
 	const result = await documentSession.applyEdits({
 		edits: await Promise.all(
-			input.edits.map(async (edit) => {
-				const contentEdit = replacePublicRefs(edit, targets);
-				return "html" in contentEdit
+			input.edits.map(async (edit) =>
+				"html" in edit
 					? {
-							...contentEdit,
+							...edit,
 							html: await resolveDocumentCitations({
 								context: accessContext,
-								html: contentEdit.html,
+								html: edit.html,
 							}),
 						}
-					: contentEdit;
-			}),
+					: edit,
+			),
 		),
 		operationId: accessContext.operationId,
 	});
@@ -151,52 +138,27 @@ export async function editWorkspaceItemOperation(
 	};
 }
 
-async function resolveEditTargets<
-	TEdit extends { ref: string; afterRef?: string; beforeRef?: string },
-	TTarget,
->(
-	context: WorkspaceAccessContext,
-	edits: readonly TEdit[],
-	toTarget: (record: WorkspaceReferenceRecord) => TTarget | undefined,
+/**
+ * Parses every entry ref an edit batch mentions. A unit ref is self-contained
+ * — entry id plus content revision — so targeting needs no lookup; a ref whose
+ * unit is not an entry id simply resolves to nothing and the edit engine
+ * reports `ref_not_found` at the right index.
+ */
+function collectEntryEditTargets(
+	edits: readonly { ref: string; afterRef?: string; beforeRef?: string }[],
 ) {
-	const refs = [...new Set(edits.flatMap(getReferencedRefs))];
-	const records =
-		refs.length > 0 && context.resolveWorkspaceReferences
-			? await context.resolveWorkspaceReferences(refs)
-			: [];
-	const recordsByRef = indexWorkspaceReferenceRecords(records);
-	const targets = new Map<string, TTarget>();
-	for (const ref of refs) {
-		const parsedRef = parseWorkspaceReference(ref);
-		const record = parsedRef ? recordsByRef.get(parsedRef) : undefined;
-		const target = record ? toTarget(record) : undefined;
-		if (target) targets.set(ref, target);
+	const targets = new Map<string, OrderedEntryEditTarget>();
+	for (const edit of edits) {
+		for (const ref of [edit.ref, edit.beforeRef, edit.afterRef]) {
+			if (!ref || targets.has(ref)) continue;
+			const parsed = parseWorkspaceUnitRef(ref);
+			if (!parsed || !workspaceEntryIdSchema.safeParse(parsed.unit).success) continue;
+			targets.set(ref, { entryId: parsed.unit, revision: parsed.revision });
+		}
 	}
-
 	return targets;
 }
 
-function replacePublicRefs<TEdit extends { ref: string; afterRef?: string; beforeRef?: string }>(
-	edit: TEdit,
-	targets: ReadonlyMap<string, string>,
-): TEdit {
-	// Unresolved refs stay invalid so the document engine reports them at their original edit index.
-	return {
-		...edit,
-		ref: targets.get(edit.ref) ?? edit.ref,
-		...(edit.beforeRef ? { beforeRef: targets.get(edit.beforeRef) ?? edit.beforeRef } : {}),
-		...(edit.afterRef ? { afterRef: targets.get(edit.afterRef) ?? edit.afterRef } : {}),
-	};
-}
-
-function getReferencedRefs(edit: { ref: string; afterRef?: string; beforeRef?: string }) {
-	return [
-		edit.ref,
-		...(edit.beforeRef ? [edit.beforeRef] : []),
-		...(edit.afterRef ? [edit.afterRef] : []),
-	];
-}
-
 async function getDocumentSession(input: { itemId: string; workspaceId: string }) {
 	const { env } = await import("cloudflare:workers");
 
diff --git a/src/features/workspaces/operations/link-items.test.ts b/src/features/workspaces/operations/link-items.test.ts
index f59e25410..9fb64e912 100644
--- a/src/features/workspaces/operations/link-items.test.ts
+++ b/src/features/workspaces/operations/link-items.test.ts
@@ -61,6 +61,7 @@ const documentItem: WorkspaceItem = {
 	parentId: null,
 	type: "document",
 	name: "Cell Notes",
+	refKey: "Xk7p2Qa9",
 	color: null,
 	metadataJson: {},
 	sortOrder: 1,
diff --git a/src/features/workspaces/operations/read-items.ts b/src/features/workspaces/operations/read-items.ts
index fafde0683..9e1a9214a 100644
--- a/src/features/workspaces/operations/read-items.ts
+++ b/src/features/workspaces/operations/read-items.ts
@@ -6,13 +6,10 @@ import {
 } from "#/features/workspaces/content/workspace-content-contract";
 import { readWorkspaceContent } from "#/features/workspaces/content/workspace-content-reader";
 import { recordWorkspaceFileReadOutcomes } from "#/features/workspaces/content/workspace-read-observability";
-import { createWorkspaceReadReferences } from "#/features/workspaces/content/workspace-read-references";
 import { getDocumentSessionFromEnv } from "#/features/workspaces/document-session-access";
 import { readFlashcardViewer } from "#/features/workspaces/flashcards/flashcard-study-persistence";
-import {
-	indexWorkspaceReferenceRecords,
-	parseWorkspaceReference,
-} from "#/features/workspaces/locations/workspace-location";
+import { readQuizViewer } from "#/features/workspaces/quizzes/quiz-study-persistence";
+import { getWorkspaceItemRefKeyIndex } from "#/features/workspaces/persistence/workspace-items";
 import type { WorkspaceAccessContext } from "#/features/workspaces/operations/workspace-access-context";
 import { authorizeWorkspaceOperation } from "#/features/workspaces/operations/workspace-operation-context";
 
@@ -28,14 +25,8 @@ export async function readWorkspaceItemsOperation(
 		access: "read",
 		context: accessContext,
 	});
-	const requestedRefs = input.requests.flatMap((request) =>
-		request.mode === "ref" ? [request.ref] : [],
-	);
-	const referenceTargets = indexWorkspaceReferenceRecords(
-		requestedRefs.length > 0 && accessContext.resolveWorkspaceReferences
-			? await accessContext.resolveWorkspaceReferences(requestedRefs)
-			: [],
-	);
+	// Lazy so path-only batches skip it; shared so N ref requests cost one page read.
+	let refKeyIndex: ReturnType<typeof getWorkspaceItemRefKeyIndex> | undefined;
 	const results = await readWorkspaceContent({
 		bucket: env.WORKSPACE_FILES,
 		getDocumentSession: (itemId) =>
@@ -49,10 +40,15 @@ export async function readWorkspaceItemsOperation(
 				userId: accessContext.actor.userId,
 				workspaceId: accessContext.workspaceId,
 			}),
-		resolveReference: (itemId, ref) => {
-			const parsedRef = parseWorkspaceReference(ref);
-			const record = parsedRef ? referenceTargets.get(parsedRef) : undefined;
-			return record?.location.itemId === itemId ? record.location : undefined;
+		readQuizItem: (itemId) =>
+			readQuizViewer({
+				itemId,
+				userId: accessContext.actor.userId,
+				workspaceId: accessContext.workspaceId,
+			}),
+		resolveRefKey: async (refKey) => {
+			refKeyIndex ??= getWorkspaceItemRefKeyIndex({ workspaceId: accessContext.workspaceId });
+			return (await refKeyIndex).get(refKey);
 		},
 		requests: input.requests,
 		workspaceId: accessContext.workspaceId,
@@ -65,8 +61,5 @@ export async function readWorkspaceItemsOperation(
 		workspaceId: accessContext.workspaceId,
 	});
 
-	return {
-		references: createWorkspaceReadReferences(results),
-		results,
-	};
+	return { results };
 }
diff --git a/src/features/workspaces/operations/workspace-access-context.ts b/src/features/workspaces/operations/workspace-access-context.ts
index 0078c27a4..ad3970f36 100644
--- a/src/features/workspaces/operations/workspace-access-context.ts
+++ b/src/features/workspaces/operations/workspace-access-context.ts
@@ -1,4 +1,3 @@
-import type { WorkspaceReferenceRecord } from "#/features/workspaces/locations/workspace-location";
 import {
 	assertAccessScope,
 	createAccessActor,
@@ -11,27 +10,18 @@ export type WorkspaceAccessScope = (typeof workspaceAccessScopes)[number];
 
 export interface WorkspaceAccessContext extends ScopedAccessContext<WorkspaceAccessScope> {
 	operationId: string;
-	/**
-	 * Resolves short refs retained in the chat transcript for reads, edits,
-	 * citations, and navigation. Absent outside a chat turn.
-	 */
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 	workspaceId: string;
 }
 
 export function createWorkspaceAccessContext(input: {
 	scopes: readonly WorkspaceAccessScope[];
 	operationId: string;
-	resolveWorkspaceReferences?: (refs: readonly string[]) => Promise<WorkspaceReferenceRecord[]>;
 	userId: string;
 	workspaceId: string;
 }): WorkspaceAccessContext {
 	return {
 		actor: createAccessActor(input),
 		operationId: input.operationId,
-		...(input.resolveWorkspaceReferences
-			? { resolveWorkspaceReferences: input.resolveWorkspaceReferences }
-			: {}),
 		workspaceId: input.workspaceId,
 	};
 }
diff --git a/src/features/workspaces/operations/workspace-operation-failure-codes.ts b/src/features/workspaces/operations/workspace-operation-failure-codes.ts
index e999e6adf..8930ec66d 100644
--- a/src/features/workspaces/operations/workspace-operation-failure-codes.ts
+++ b/src/features/workspaces/operations/workspace-operation-failure-codes.ts
@@ -27,8 +27,8 @@ export const editWorkspaceItemFailureCodes = [
 	"path_not_absolute",
 	"path_not_found",
 	"unsupported_item_type",
-	"cannot_delete_last_card",
-	"invalid_card_content",
+	"cannot_delete_last_entry",
+	"invalid_entry_content",
 	...documentAiEditFailureCodes,
 	"content_changed",
 	"operation_id_conflict",
diff --git a/src/features/workspaces/operations/workspace-tool-definitions.ts b/src/features/workspaces/operations/workspace-tool-definitions.ts
index ff5c43d10..81c0169ef 100644
--- a/src/features/workspaces/operations/workspace-tool-definitions.ts
+++ b/src/features/workspaces/operations/workspace-tool-definitions.ts
@@ -144,7 +144,7 @@ export const workspaceToolDefinitions = [
 		name: "workspace_read_items",
 		access: "read",
 		description:
-			"Read ThinkEx documents, flashcard sets, and extracted files by absolute path. Document chunks and flashcards include short, freshness-checked refs. Flashcard reads also return HTML fronts and backs plus the current user's study progress; again means missed, while hard, good, and easy mean got it. Use mode cards with a card-number range for targeted flashcard reads. Continue long documents, flashcard sets, or files with nextCursor. Use mode ref to read the exact content identified by an earlier ref; this returns elided widget source in full before editing. Files also support physical-page selections.",
+			"Read ThinkEx documents, flashcard sets, quizzes, and extracted files. Every item is an ordered list of units — document blocks, cards, questions, or physical pages — and every result names the numbered units it covered plus the total, so continue by requesting the next range: mode entries for blocks, cards, or questions; mode pages for file pages. mode start returns the first chunk. Each result carries the item's durable ref, and blocks, cards, and questions carry unit refs with a current .r_ revision — copy them exactly into edits, and cite as ref or ref/unit. Use mode ref with an address to read one unit in full; that is how elided widget source is fetched before editing. Flashcard reads include the current user's study progress (again means missed; hard, good, and easy mean got it). Quiz reads return options in user-visible order with the correct one marked, plus the user's answers and score.",
 		inputSchema: workspaceReadItemsInputSchema,
 		inputExamples: workspaceReadItemsInputExamples,
 		outputSchema: workspaceReadItemsOutputSchema,
@@ -192,7 +192,7 @@ export const workspaceToolDefinitions = [
 		name: "workspace_create_items",
 		access: "write",
 		description:
-			"Create folders, documents, or flashcard sets at exact absolute paths. A slash separates folders, so use another character inside an item name. Set type and provide that branch's fields. If a path already exists, creation fails instead of renaming. After creating items from sources, record those sources with workspace_link_items.",
+			"Create folders, documents, flashcard sets, or quizzes at exact absolute paths. A slash separates folders, so use another character inside an item name. Set type and provide that branch's fields. If a path already exists, creation fails instead of renaming. After creating items from sources, record those sources with workspace_link_items.",
 		inputSchema: workspaceCreateItemsInputSchema,
 		inputExamples: workspaceCreateItemsInputExamples,
 		outputSchema: workspaceCreateItemsOutputSchema,
@@ -223,7 +223,7 @@ export const workspaceToolDefinitions = [
 		name: "workspace_edit_item",
 		access: "write",
 		description:
-			"Edit one document or flashcard set by absolute path. Read it first, then copy the exact refs it returned. The same refs also work for citations and navigation. Flashcard edits apply immediately; document edits retain their review flow. Use workspace_link_items for item-level relationships.",
+			"Edit one document, flashcard set, or quiz by absolute path. Read it first, then copy each target's exact unit ref (like b_x7Kp2Qa9x8Lm.r_4f2a1b) from that read; the .r_ revision is how a stale edit fails loudly instead of hitting the wrong content. Flashcard and quiz edits apply immediately; document edits retain their review flow. Use workspace_link_items for item-level relationships.",
 		inputSchema: workspaceEditItemInputSchema,
 		inputExamples: workspaceEditItemInputExamples,
 		outputSchema: workspaceEditItemOutputSchema,
diff --git a/src/features/workspaces/operations/workspace-tool-schemas.ts b/src/features/workspaces/operations/workspace-tool-schemas.ts
index 4b576c2c1..547395826 100644
--- a/src/features/workspaces/operations/workspace-tool-schemas.ts
+++ b/src/features/workspaces/operations/workspace-tool-schemas.ts
@@ -17,14 +17,14 @@ import {
 	workspaceItemTypeSchema,
 	workspaceRelationKindSchema,
 } from "#/features/workspaces/contracts";
-import { workspaceReferenceRecordSchema } from "#/features/workspaces/locations/workspace-location";
 import {
 	documentAiEditSchema,
 	documentAiHtmlSchema,
 } from "#/features/workspaces/documents/document-ai-edits";
 import { workspaceFileAssetKindSchema } from "#/features/workspaces/model/workspace-file";
 import { flashcardEditSchema } from "#/features/workspaces/flashcards/flashcard-edits";
-import { flashcardSideHtmlSchema } from "#/features/workspaces/flashcards/flashcard-content";
+import { quizEditSchema, quizQuestionInputSchema } from "#/features/workspaces/quizzes/quiz-edits";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
 
 export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
 
@@ -36,6 +36,14 @@ export { workspaceReadItemsInputSchema, workspaceReadItemsOutputSchema };
 const workspaceHtmlMathInstruction =
 	'This is HTML, so math is markup rather than delimiters: use <span data-type="inline-math" data-latex="..."></span> or <div data-type="block-math" data-latex="..."></div>, and keep dollar signs out of the data-latex value. Put every subscript and superscript (exponents like 10^8, indices like x_1) inside math rather than <sub>/<sup> tags. Chemistry renders with \\ce{...} (e.g. \\ce{CH4 + 2 O2 -> CO2 + 2 H2O}) and quantities with units render with \\pu{...} (e.g. \\pu{9.81 m/s^2}), both inside data-latex. Write literal money as plain text ($30, never \\$30) — a backslash before a dollar sign shows on screen in HTML.';
 
+/**
+ * The one diagram route every HTML surface shares. A mermaid block is an
+ * ordinary code block, so cards and questions get diagrams without opening
+ * their allowlist to widgets — which stay documents-only.
+ */
+const workspaceHtmlDiagramInstruction =
+	'Draw a diagram as a mermaid code block: <pre><code class="language-mermaid">flowchart TD; A[Start] --> B[End]</code></pre>. It renders as a diagram wherever the item is read or studied, and is left out of a PDF export entirely, so never let a diagram carry a point the surrounding text does not also make. Keep it to about ten nodes with short labels, and include concise accTitle and accDescr lines — they become the diagram\'s alt text. No frontmatter, init directives, custom styles, HTML, links, or images inside the diagram.';
+
 /**
  * The one code-block detail HTML does not make obvious. Every reader
  * normalizes aliases and casing, so the class prefix is the whole contract.
@@ -49,9 +57,11 @@ const workspaceHtmlCodeInstruction =
  */
 const workspaceWidgetHtmlInstruction = `A widget is one interactive block inside a document. Use one when the user explicitly asks for a widget, asks for interaction or live computation, or wants a document visual that ordinary blocks cannot express. Keep ordinary content in ordinary blocks. Before authoring or editing widget source, activate the "widget-authoring" skill and follow its HTML, sandbox, layout, and editing contract. Serialize the result as <div data-type="widget" title="Short title">…HTML-escaped fragment…</div>.`;
 
-export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} ${workspaceHtmlCodeInstruction} For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure>, and describe the visual in words instead. Cite workspace sources in documents exactly as in a chat reply, with <citation ref="wr_7Kp2Qa9x"></citation> placed after the claim it supports. ${workspaceWidgetHtmlInstruction}`;
+export const workspaceDocumentHtmlInstruction = `Use semantic HTML with paragraphs, h1-h4, blockquotes, lists, code blocks, horizontal rules, tables, links, and standard text marks. ${workspaceHtmlMathInstruction} ${workspaceHtmlCodeInstruction} For checkboxes, use <ul data-type="taskList"><li data-type="taskItem" data-checked="false"><label><input type="checkbox"><span></span></label><div><p>Item</p></div></li></ul>. Documents cannot hold images: never use <img> or <figure> — draw a diagram or describe the visual in words instead. ${workspaceHtmlDiagramInstruction} Cite workspace sources in documents exactly as in a chat reply, with <citation ref="Xk7p2Qa9/b_x7Kp2Qa9x8Lm"></citation> placed after the claim it supports — the address is the item's ref, or ref/unit for a page, block, card, or question, with any .r_ suffix dropped. ${workspaceWidgetHtmlInstruction}`;
+
+export const workspaceFlashcardHtmlInstruction = `Flashcard fronts and backs are HTML. Keep each side concise. Use paragraphs, lists, links, code blocks, and standard text marks only. ${workspaceHtmlMathInstruction} ${workspaceHtmlCodeInstruction} Do not use headings, tables, images, widgets, task lists, or citations inside a card. ${workspaceHtmlDiagramInstruction}`;
 
-export const workspaceFlashcardHtmlInstruction = `Flashcard fronts and backs are HTML. Keep each side concise. Use paragraphs, lists, links, code blocks, and standard text marks only. ${workspaceHtmlMathInstruction} ${workspaceHtmlCodeInstruction} Do not use headings, tables, images, widgets, task lists, or citations inside a card.`;
+export const workspaceQuizHtmlInstruction = `Question stems, options, and explanations are HTML. Keep them concise. Use paragraphs, lists, links, code blocks, and standard text marks only. ${workspaceHtmlMathInstruction} ${workspaceHtmlCodeInstruction} Do not use headings, tables, images, widgets, task lists, or citations inside a question. ${workspaceHtmlDiagramInstruction} A diagram usually belongs in the stem or the explanation; if one option needs it, give them all one, since an option taller than the rest hints at the answer. Write correctAnswer as its own field and never hint at it in the stem or option order: the server shuffles the options and records which one is correct. Every distractor must be strictly wrong yet plausible, reflect a specific misconception, and match the correct answer's length and tone. Prefer 3 distractors; use 1 for true/false. Questions should test understanding from the source material, not trivia recall.`;
 
 const workspacePathSchema = z.string().min(1);
 const workspaceIndexSchema = z.number().int().nonnegative();
@@ -161,6 +171,19 @@ export const workspaceEditItemInputSchema = z.discriminatedUnion("type", [
 				),
 		})
 		.describe("Flashcard edits."),
+	z
+		.object({
+			type: z.literal("quiz"),
+			path: z.string().min(1).describe("Absolute path of one actual ThinkEx quiz to edit."),
+			edits: z
+				.array(quizEditSchema)
+				.min(1)
+				.max(100)
+				.describe(
+					`Ordered quiz edits using exact refs from a read. Available operations: insert_before, insert_after, update, replace, replace_text, move, and delete. insert and replace take a full authored question and reshuffle its options; update changes only the stem or explanation in place; replace_text requires question, options, or explanation as field and never reshuffles; move requires exactly one of beforeRef or afterRef. ${workspaceQuizHtmlInstruction}`,
+				),
+		})
+		.describe("Quiz edits."),
 ]);
 
 export const workspaceLinkItemsInputSchema = z.object({
@@ -228,8 +251,8 @@ export const workspaceCreateItemsInputSchema = z.object({
 						cards: z
 							.array(
 								z.object({
-									front: flashcardSideHtmlSchema.describe("HTML shown before the card flips."),
-									back: flashcardSideHtmlSchema.describe("HTML shown after the card flips."),
+									front: entryRichTextHtmlSchema.describe("HTML shown before the card flips."),
+									back: entryRichTextHtmlSchema.describe("HTML shown after the card flips."),
 								}),
 							)
 							.min(1)
@@ -237,12 +260,23 @@ export const workspaceCreateItemsInputSchema = z.object({
 							.describe(`Ordered cards. ${workspaceFlashcardHtmlInstruction}`),
 					})
 					.describe("Flashcard set to create."),
+				z
+					.object({
+						type: z.literal("quiz"),
+						path: z.string().min(1).describe("Final absolute path for the quiz."),
+						questions: z
+							.array(quizQuestionInputSchema)
+							.min(1)
+							.max(100)
+							.describe(`Ordered multiple-choice questions. ${workspaceQuizHtmlInstruction}`),
+					})
+					.describe("Quiz to create."),
 			]),
 		)
 		.min(1)
 		.max(20)
 		.describe(
-			"One or more folders, documents, or flashcard sets to create in order, at most 20. Parent folders must already exist or be created earlier in the same request.",
+			"One or more workspace items to create in order, at most 20. Parent folders must already exist or be created earlier in the same request.",
 		),
 });
 
@@ -273,7 +307,10 @@ export const workspaceReadItemsInputExamples = createInputExamples<
 		requests: [{ mode: "start", path: "/Demo Folder/Demo Flashcards" }],
 	},
 	{
-		requests: [{ mode: "cards", path: "/Demo Folder/Demo Flashcards", range: "1-3" }],
+		requests: [{ mode: "entries", path: "/Demo Folder/Demo Flashcards", range: "1-3" }],
+	},
+	{
+		requests: [{ mode: "start", path: "/Demo Folder/Demo Quiz" }],
 	},
 	{
 		requests: [
@@ -287,9 +324,8 @@ export const workspaceReadItemsInputExamples = createInputExamples<
 	{
 		requests: [
 			{
-				ref: "wr_7Kp2Qa9x",
+				ref: "Xk7p2Qa9/b_x7Kp2Qa9x8Lm",
 				mode: "ref",
-				path: "/Demo Folder/Demo Document",
 			},
 		],
 	},
@@ -328,6 +364,23 @@ export const workspaceCreateItemsInputExamples = createInputExamples<
 			path: "/Demo Folder/Demo Flashcards",
 			cards: [{ front: "<p>What is ATP?</p>", back: "<p>The cell's main energy carrier.</p>" }],
 		},
+		{
+			type: "quiz",
+			path: "/Demo Folder/Demo Quiz",
+			questions: [
+				{
+					question: "<p>What does ATP primarily provide to a cell?</p>",
+					correctAnswer: "<p>Readily usable chemical energy</p>",
+					distractors: [
+						"<p>Long-term energy storage</p>",
+						"<p>Structural support for the membrane</p>",
+						"<p>Genetic information for protein synthesis</p>",
+					],
+					explanation:
+						"<p>ATP transfers readily usable energy; fats store energy long-term, membranes get structure from lipids and proteins, and genetic information lives in DNA.</p>",
+				},
+			],
+		},
 	],
 });
 
@@ -345,7 +398,7 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		path: "/Demo Folder/Demo Document",
 		edits: [
 			{
-				ref: "wr_7Kp2Qa9x",
+				ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
 				op: "replace",
 				html: "<p>Updated paragraph.</p>",
 			},
@@ -356,8 +409,8 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		path: "/Demo Folder/Demo Document",
 		edits: [
 			{
-				ref: "wr_7Kp2Qa9x",
-				afterRef: "wr_8Lq3Rb0y",
+				ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
+				afterRef: "b_y8Lq3Rb0y9Mn.r_9c3d2e",
 				op: "move",
 			},
 		],
@@ -367,7 +420,7 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		path: "/Demo Folder/Demo Document",
 		edits: [
 			{
-				ref: "wr_7Kp2Qa9x",
+				ref: "b_x7Kp2Qa9x8Lm.r_4f2a1b",
 				op: "replace_text",
 				find: "gravity = 9.8",
 				replace: "gravity = 3.7",
@@ -380,11 +433,24 @@ export const workspaceEditItemInputExamples = createInputExamples<
 		edits: [
 			{
 				op: "update",
-				ref: "wr_7Kp2Qa9x",
+				ref: "c_9xKp2Qab.r_4f2a1b",
 				back: "<p>The cell's main energy carrier.</p>",
 			},
 		],
 	},
+	{
+		type: "quiz",
+		path: "/Demo Folder/Demo Quiz",
+		edits: [
+			{
+				op: "replace_text",
+				ref: "q_8Lq3Rb0y.r_9c3d2e",
+				field: "options",
+				find: "Long-term energy storage",
+				replace: "Long-term energy reserves",
+			},
+		],
+	},
 );
 
 export const workspaceLinkItemsInputExamples = createInputExamples<
@@ -428,13 +494,12 @@ export const workspaceListItemsOutputSchema = z.object({
 export const workspaceCreateItemsOutputSchema = createWorkspaceItemsResultSchema({
 	itemSchema: workspacePathItemSchema.extend({
 		itemId: z.string().min(1),
-		type: z.enum(["document", "flashcard", "folder"]),
+		ref: z.string().min(1).describe("The item's durable address for citations and reads."),
+		type: z.enum(["document", "flashcard", "folder", "quiz"]),
 	}),
 	failureSchema: createFailureSchema(createWorkspaceItemsFailureCodes).extend({
 		detail: z.string().optional().describe("Why this item was refused, when the reason is known."),
 	}),
-}).extend({
-	references: z.array(workspaceReferenceRecordSchema),
 });
 
 export const workspaceDeleteItemsOutputSchema = createWorkspaceItemsResultSchema({
@@ -460,7 +525,7 @@ export const workspaceEditItemOutputSchema = z.object({
 	path: workspacePathSchema,
 	applied: z.number().int().min(0),
 	itemId: z.string().optional(),
-	itemType: z.enum(["document", "flashcard"]).optional(),
+	itemType: z.enum(["document", "flashcard", "quiz"]).optional(),
 	lineChanges: z
 		.object({ added: z.number().int().min(0), removed: z.number().int().min(0) })
 		.optional(),
diff --git a/src/features/workspaces/operations/workspace-tool-surface.test.ts b/src/features/workspaces/operations/workspace-tool-surface.test.ts
index 7ad877ab3..e9bae42ad 100644
--- a/src/features/workspaces/operations/workspace-tool-surface.test.ts
+++ b/src/features/workspaces/operations/workspace-tool-surface.test.ts
@@ -45,10 +45,10 @@ describe("workspace tool surface", () => {
 	}
 
 	it("gives documents and flashcards the same edit verbs and ref protocol", () => {
-		const documentRef = "wr_AAAAAAAA";
-		const otherDocumentRef = "wr_BBBBBBBB";
-		const flashcardRef = "wr_CCCCCCCC";
-		const otherFlashcardRef = "wr_DDDDDDDD";
+		const documentRef = "b_x7Kp2Qa9x8Lm.r_4f2a1b";
+		const otherDocumentRef = "b_y8Lq3Rb0y9Mn.r_9c3d2e";
+		const flashcardRef = "c_9xKp2Qab.r_4f2a1b";
+		const otherFlashcardRef = "c_8Lq3Rb0y.r_9c3d2e";
 		const sharedVerbs = [
 			"insert_before",
 			"insert_after",
diff --git a/src/features/workspaces/persistence/workspace-files.ts b/src/features/workspaces/persistence/workspace-files.ts
index 7c5db3799..16550a5a6 100644
--- a/src/features/workspaces/persistence/workspace-files.ts
+++ b/src/features/workspaces/persistence/workspace-files.ts
@@ -1,5 +1,7 @@
 import { and, asc, eq, inArray } from "drizzle-orm";
 
+import { createWorkspaceItemRefKey } from "#/features/workspaces/locations/workspace-location";
+
 import {
 	workspaceFileAssets,
 	workspaceItemPages,
@@ -102,6 +104,7 @@ export async function createWorkspaceFileFromUpload(
 			type: "file",
 			name: nameResolution.name,
 			nameKey: getWorkspaceItemNameKey(nameResolution.name),
+			refKey: createWorkspaceItemRefKey(),
 			color: null,
 			metadata,
 			sortOrder: await getNextWorkspaceSortOrder(transaction, input.workspaceId, parentId),
diff --git a/src/features/workspaces/persistence/workspace-items.ts b/src/features/workspaces/persistence/workspace-items.ts
index 17e21ca34..bedeb5d63 100644
--- a/src/features/workspaces/persistence/workspace-items.ts
+++ b/src/features/workspaces/persistence/workspace-items.ts
@@ -2,6 +2,7 @@ import { and, asc, desc, eq, inArray, or } from "drizzle-orm";
 
 import { workspaceItemContents, workspaceItemRelations, workspaceItems } from "#/db/schema";
 import { withDb } from "#/db/server";
+import { createWorkspaceItemRefKey } from "#/features/workspaces/locations/workspace-location";
 import {
 	type WorkspaceItem,
 	getWorkspaceItemContentKind,
@@ -123,6 +124,22 @@ export async function getWorkspaceItemPaths(input: WorkspaceScoped<GetWorkspaceI
 	});
 }
 
+/**
+ * Resolves item address refKeys to live items and their paths. Costs one
+ * workspace page read however many refKeys the caller then looks up, so
+ * callers with several refs to resolve share a single index.
+ */
+export async function getWorkspaceItemRefKeyIndex(input: WorkspaceScoped<object>) {
+	const { items } = await readWorkspacePage({ workspaceId: input.workspaceId });
+	const paths = buildWorkspaceItemPathIndex(items);
+	return new Map(
+		items.flatMap((item) => {
+			const path = paths.get(item.id);
+			return path ? [[item.refKey, { item, path }] as const] : [];
+		}),
+	);
+}
+
 export async function listWorkspaceItemRelations(
 	input: WorkspaceScoped<ListWorkspaceItemRelationsArgs>,
 ) {
@@ -221,6 +238,7 @@ export async function createWorkspaceItem(
 			type,
 			name: nameResolution.name,
 			nameKey: getWorkspaceItemNameKey(nameResolution.name),
+			refKey: createWorkspaceItemRefKey(),
 			color,
 			metadata: bootstrap.metadataJson,
 			sortOrder: await getNextWorkspaceSortOrder(transaction, input.workspaceId, parentId),
diff --git a/src/features/workspaces/persistence/workspace-postgres-support.ts b/src/features/workspaces/persistence/workspace-postgres-support.ts
index 9dbf12d2c..9063a0b2f 100644
--- a/src/features/workspaces/persistence/workspace-postgres-support.ts
+++ b/src/features/workspaces/persistence/workspace-postgres-support.ts
@@ -242,6 +242,7 @@ export function mapWorkspaceItem(row: ItemRow): WorkspaceItem {
 		parentId: row.parentId,
 		type,
 		name: row.name,
+		refKey: row.refKey,
 		color: row.color,
 		metadataJson: toWorkspaceMetadata(row.metadata),
 		sortOrder: row.sortOrder,
diff --git a/src/features/workspaces/quizzes/quiz-content.test.ts b/src/features/workspaces/quizzes/quiz-content.test.ts
new file mode 100644
index 000000000..2c8fe8a04
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-content.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	createQuizSetFromInputs,
+	materializeQuizQuestion,
+	parseQuizSetContent,
+	serializeQuizSetToHtml,
+	stringifyQuizSetContent,
+} from "#/features/workspaces/quizzes/quiz-content";
+
+const atpQuestion = {
+	question: "<p>What does ATP provide?</p>",
+	correctAnswer: "<p>Usable energy</p>",
+	distractors: ["<p>Genetic information</p>", "<p>Structural support</p>", "<p>Oxygen storage</p>"],
+	explanation: "<p>ATP transfers readily usable energy.</p>",
+};
+
+describe("materializeQuizQuestion", () => {
+	it("shuffles the correct answer in and records which option it became", () => {
+		const question = materializeQuizQuestion(atpQuestion);
+
+		expect(question.kind).toBe("multiple_choice");
+		expect(question.options).toHaveLength(4);
+		const serialized = serializeQuizSetToHtml({ version: 1, questions: [question] })[0]!;
+		const correct = serialized.options.filter((option) => option.correct);
+		expect(correct).toHaveLength(1);
+		expect(correct[0]!.text).toBe("<p>Usable energy</p>");
+	});
+
+	it("does not always place the correct answer first", () => {
+		const positions = new Set(
+			Array.from({ length: 40 }, () => {
+				const question = materializeQuizQuestion(atpQuestion);
+				return question.options.findIndex((option) => option.id === question.correctOptionId);
+			}),
+		);
+		expect(positions.size).toBeGreaterThan(1);
+	});
+
+	it("rejects duplicate options and bad distractor counts", () => {
+		expect(() =>
+			materializeQuizQuestion({ ...atpQuestion, distractors: ["<p>Usable energy</p>"] }),
+		).toThrow("distinct");
+		expect(() => materializeQuizQuestion({ ...atpQuestion, distractors: [] })).toThrow(
+			"1 to 4 distractors",
+		);
+	});
+
+	it("rejects content outside the entry rich-text dialect", () => {
+		expect(() =>
+			materializeQuizQuestion({ ...atpQuestion, question: "<h1>Heading stem</h1>" }),
+		).toThrow("Quiz content cannot contain heading nodes.");
+	});
+});
+
+describe("parseQuizSetContent", () => {
+	it("round-trips a stored quiz", () => {
+		const set = createQuizSetFromInputs([atpQuestion]);
+		const parsed = parseQuizSetContent(stringifyQuizSetContent(set));
+		expect(parsed).toEqual(set);
+	});
+
+	it("rejects empty, malformed, and tampered content", () => {
+		expect(() => parseQuizSetContent(null)).toThrow("Quiz content is missing.");
+		expect(() => parseQuizSetContent('{"version":1,"questions":[]}')).toThrow(
+			"at least one question",
+		);
+		const set = createQuizSetFromInputs([atpQuestion]);
+		const tampered = {
+			...set,
+			questions: [{ ...set.questions[0]!, correctOptionId: crypto.randomUUID() }],
+		};
+		expect(() => parseQuizSetContent(JSON.stringify(tampered))).toThrow("without a correct option");
+	});
+});
diff --git a/src/features/workspaces/quizzes/quiz-content.ts b/src/features/workspaces/quizzes/quiz-content.ts
new file mode 100644
index 000000000..f9428168d
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-content.ts
@@ -0,0 +1,221 @@
+import {
+	parseEntryRichTextHtml,
+	parseStoredEntryRichText,
+} from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
+import type { TiptapDocumentJson } from "#/features/workspaces/documents/tiptap-document";
+import {
+	createWorkspaceEntryId,
+	workspaceEntryIdSchema,
+} from "#/features/workspaces/locations/workspace-location";
+import { sha256Base64UrlText } from "#/lib/binary";
+import { isRecord } from "#/lib/record";
+import { shuffleInPlace } from "#/lib/shuffle";
+
+export const QUIZ_SET_VERSION = 1;
+const quizIdSchema = workspaceEntryIdSchema;
+
+export const QUIZ_QUESTION_MIN_DISTRACTORS = 1;
+export const QUIZ_QUESTION_MAX_DISTRACTORS = 4;
+
+/**
+ * One quiz question as stored. Options hold their display order: the server
+ * shuffled the correct answer in at creation, because models place unshuffled
+ * correct answers at predictable positions. `kind` leaves room for
+ * free-response siblings in a later content version.
+ */
+export interface QuizQuestion {
+	id: string;
+	kind: "multiple_choice";
+	question: TiptapDocumentJson;
+	options: QuizOption[];
+	correctOptionId: string;
+	explanation: TiptapDocumentJson;
+}
+
+export interface QuizOption {
+	id: string;
+	text: TiptapDocumentJson;
+}
+
+export interface QuizSetContent {
+	version: typeof QUIZ_SET_VERSION;
+	questions: QuizQuestion[];
+}
+
+/**
+ * What the model authors: the correct answer stays a separate field and never
+ * carries a position, and the explanation is written in the same pass as the
+ * question so an incoherent one surfaces a bad question before it is stored.
+ */
+export interface QuizQuestionInput {
+	question: string;
+	correctAnswer: string;
+	distractors: string[];
+	explanation: string;
+}
+
+export function parseQuizRichTextHtml(html: string) {
+	return parseEntryRichTextHtml(html, "Quiz");
+}
+
+export function createQuizSetFromInputs(questions: QuizQuestionInput[]) {
+	if (questions.length === 0) throw new Error("A quiz needs at least one question.");
+	return {
+		version: QUIZ_SET_VERSION,
+		questions: questions.map((question) => materializeQuizQuestion(question)),
+	} satisfies QuizSetContent;
+}
+
+/**
+ * Parses one authored question and shuffles the correct answer in among the
+ * distractors. Storing the shuffled order keeps every reader — users, edits,
+ * and citations — on one stable arrangement.
+ */
+export function materializeQuizQuestion(input: QuizQuestionInput): QuizQuestion {
+	if (
+		input.distractors.length < QUIZ_QUESTION_MIN_DISTRACTORS ||
+		input.distractors.length > QUIZ_QUESTION_MAX_DISTRACTORS
+	) {
+		throw new Error(
+			`A question needs ${QUIZ_QUESTION_MIN_DISTRACTORS} to ${QUIZ_QUESTION_MAX_DISTRACTORS} distractors.`,
+		);
+	}
+
+	const correct = {
+		id: crypto.randomUUID(),
+		text: parseEntryRichTextHtml(input.correctAnswer, "Quiz"),
+	};
+	const options = [
+		correct,
+		...input.distractors.map((distractor) => ({
+			id: crypto.randomUUID(),
+			text: parseEntryRichTextHtml(distractor, "Quiz"),
+		})),
+	];
+	assertDistinctOptions(options);
+	shuffleInPlace(options);
+
+	return {
+		id: createWorkspaceEntryId("q"),
+		kind: "multiple_choice",
+		question: parseEntryRichTextHtml(input.question, "Quiz"),
+		options,
+		correctOptionId: correct.id,
+		explanation: parseEntryRichTextHtml(input.explanation, "Quiz"),
+	};
+}
+
+export function parseQuizSetContent(content: string | null): QuizSetContent {
+	if (!content?.trim()) {
+		throw new Error("Quiz content is missing.");
+	}
+
+	const value: unknown = JSON.parse(content);
+	if (!isRecord(value) || value.version !== QUIZ_SET_VERSION || !Array.isArray(value.questions)) {
+		throw new Error("Quiz content has an unsupported format.");
+	}
+	if (value.questions.length === 0) {
+		throw new Error("A quiz needs at least one question.");
+	}
+
+	const seenIds = new Set<string>();
+	const questions = value.questions.map((question) => {
+		if (!isRecord(question) || question.kind !== "multiple_choice") {
+			throw new Error("Quiz content contains an unsupported question kind.");
+		}
+		const questionId = quizIdSchema.safeParse(question.id);
+		if (!questionId.success) {
+			throw new Error("Quiz content contains an invalid question ID.");
+		}
+		if (seenIds.has(questionId.data)) {
+			throw new Error("Quiz content contains a duplicate question ID.");
+		}
+		seenIds.add(questionId.data);
+
+		if (
+			!Array.isArray(question.options) ||
+			question.options.length < QUIZ_QUESTION_MIN_DISTRACTORS + 1 ||
+			question.options.length > QUIZ_QUESTION_MAX_DISTRACTORS + 1
+		) {
+			throw new Error("Quiz content contains a question with an invalid option count.");
+		}
+		const seenOptionIds = new Set<string>();
+		const options = question.options.map((option) => {
+			if (!isRecord(option)) {
+				throw new Error("Quiz content contains an invalid option.");
+			}
+			const optionId = quizIdSchema.safeParse(option.id);
+			if (!optionId.success || seenOptionIds.has(optionId.data)) {
+				throw new Error("Quiz content contains an invalid option ID.");
+			}
+			seenOptionIds.add(optionId.data);
+			return { id: optionId.data, text: parseStoredEntryRichText(option.text, "Quiz") };
+		});
+		if (
+			typeof question.correctOptionId !== "string" ||
+			!seenOptionIds.has(question.correctOptionId)
+		) {
+			throw new Error("Quiz content contains a question without a correct option.");
+		}
+
+		return {
+			id: questionId.data,
+			kind: "multiple_choice" as const,
+			question: parseStoredEntryRichText(question.question, "Quiz"),
+			options,
+			correctOptionId: question.correctOptionId,
+			explanation: parseStoredEntryRichText(question.explanation, "Quiz"),
+		};
+	});
+
+	return { version: QUIZ_SET_VERSION, questions };
+}
+
+export function stringifyQuizSetContent(content: QuizSetContent) {
+	return `${JSON.stringify(content)}\n`;
+}
+
+export async function createQuizQuestionRevision(question: QuizQuestion) {
+	return (
+		await sha256Base64UrlText(
+			JSON.stringify({
+				correctOptionId: question.correctOptionId,
+				explanation: question.explanation,
+				options: question.options,
+				question: question.question,
+			}),
+		)
+	).slice(0, 6);
+}
+
+export interface QuizHtmlQuestion {
+	id: string;
+	question: string;
+	options: Array<{ id: string; text: string; correct: boolean }>;
+	explanation: string;
+}
+
+export function serializeQuizSetToHtml(content: QuizSetContent): QuizHtmlQuestion[] {
+	return content.questions.map((question) => ({
+		id: question.id,
+		question: serializeTiptapDocumentToHtml(question.question),
+		options: question.options.map((option) => ({
+			id: option.id,
+			text: serializeTiptapDocumentToHtml(option.text),
+			correct: option.id === question.correctOptionId,
+		})),
+		explanation: serializeTiptapDocumentToHtml(question.explanation),
+	}));
+}
+
+function assertDistinctOptions(options: QuizOption[]) {
+	const seen = new Set<string>();
+	for (const option of options) {
+		const key = serializeTiptapDocumentToHtml(option.text);
+		if (seen.has(key)) {
+			throw new Error("Every option in a question must be distinct.");
+		}
+		seen.add(key);
+	}
+}
diff --git a/src/features/workspaces/quizzes/quiz-edits.test.ts b/src/features/workspaces/quizzes/quiz-edits.test.ts
new file mode 100644
index 000000000..5b4f4593d
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-edits.test.ts
@@ -0,0 +1,159 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	createQuizQuestionRevision,
+	createQuizSetFromInputs,
+	type QuizQuestion,
+} from "#/features/workspaces/quizzes/quiz-content";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
+import { applyQuizEdits, quizEditSchema } from "#/features/workspaces/quizzes/quiz-edits";
+
+const firstQuestion = {
+	question: "<p>What does ATP provide?</p>",
+	correctAnswer: "<p>Usable energy</p>",
+	distractors: ["<p>Genetic information</p>"],
+	explanation: "<p>ATP transfers energy.</p>",
+};
+const secondQuestion = {
+	question: "<p>Where does glycolysis happen?</p>",
+	correctAnswer: "<p>The cytoplasm</p>",
+	distractors: ["<p>The nucleus</p>"],
+	explanation: "<p>Glycolysis happens in the cytoplasm.</p>",
+};
+
+describe("applyQuizEdits", () => {
+	it("supports the shared edit verbs while preserving question identity", async () => {
+		const set = createQuizSetFromInputs([firstQuestion, secondQuestion]);
+		const [first, second] = set.questions;
+		const { refs, targets } = await createTargets(first!, second!);
+		const [firstRef, secondRef] = refs;
+
+		const result = await applyQuizEdits(
+			set,
+			[
+				{ op: "insert_before", ref: secondRef!, ...firstQuestion, question: "<p>Extra?</p>" },
+				{ op: "update", ref: secondRef!, explanation: "<p>Updated explanation.</p>" },
+				{
+					op: "replace_text",
+					ref: secondRef!,
+					field: "options",
+					find: "The nucleus",
+					replace: "The mitochondria",
+				},
+				{ op: "move", ref: firstRef!, afterRef: secondRef! },
+				{ op: "replace", ref: firstRef!, ...firstQuestion, question: "<p>Rewritten?</p>" },
+			],
+			targets,
+		);
+
+		expect(result.failed).toEqual([]);
+		expect(result.applied).toBe(5);
+		expect(result.content.questions).toHaveLength(3);
+		const revisedSecond = result.content.questions.find((entry) => entry.id === second!.id)!;
+		expect(serializeTiptapDocumentToHtml(revisedSecond.explanation)).toBe(
+			"<p>Updated explanation.</p>",
+		);
+		expect(
+			revisedSecond.options.map((option) => serializeTiptapDocumentToHtml(option.text)),
+		).toContain("<p>The mitochondria</p>");
+		// replace keeps the id so citations to the question survive re-authoring.
+		expect(result.content.questions.some((entry) => entry.id === first!.id)).toBe(true);
+	});
+
+	it("keeps the correct option correct after an in-place option fix", async () => {
+		const set = createQuizSetFromInputs([firstQuestion]);
+		const question = set.questions[0]!;
+		const { refs, targets } = await createTargets(question);
+
+		const result = await applyQuizEdits(
+			set,
+			[
+				{
+					op: "replace_text",
+					ref: refs[0]!,
+					field: "options",
+					find: "Usable energy",
+					replace: "Readily usable energy",
+				},
+			],
+			targets,
+		);
+
+		expect(result.failed).toEqual([]);
+		const revised = result.content.questions[0]!;
+		const correct = revised.options.find((option) => option.id === revised.correctOptionId)!;
+		expect(serializeTiptapDocumentToHtml(correct.text)).toBe("<p>Readily usable energy</p>");
+	});
+
+	it("rejects option fixes that match more than one option", async () => {
+		const set = createQuizSetFromInputs([
+			{ ...firstQuestion, distractors: ["<p>Usable heat</p>"] },
+		]);
+		const { refs, targets } = await createTargets(set.questions[0]!);
+
+		const result = await applyQuizEdits(
+			set,
+			[{ op: "replace_text", ref: refs[0]!, field: "options", find: "Usable", replace: "Free" }],
+			targets,
+		);
+
+		expect(result.applied).toBe(0);
+		expect(result.failed).toMatchObject([{ code: "edit_not_unique", index: 0 }]);
+	});
+
+	it("reports stale refs, missing refs, and last-question deletes", async () => {
+		const set = createQuizSetFromInputs([firstQuestion]);
+		const { refs, targets } = await createTargets(set.questions[0]!);
+		const changed = createQuizSetFromInputs([secondQuestion]);
+		changed.questions[0]!.id = set.questions[0]!.id;
+
+		const stale = await applyQuizEdits(
+			changed,
+			[{ op: "update", ref: refs[0]!, question: "<p>New?</p>" }],
+			targets,
+		);
+		expect(stale.failed).toMatchObject([{ code: "ref_stale", index: 0 }]);
+
+		const result = await applyQuizEdits(
+			set,
+			[
+				{ op: "delete", ref: "wr_ZZZZZZZZ" },
+				{ op: "delete", ref: refs[0]! },
+			],
+			targets,
+		);
+		expect(result.failed).toMatchObject([
+			{ code: "ref_not_found", index: 0 },
+			{ code: "cannot_delete_last_entry", index: 1 },
+		]);
+	});
+
+	it("requires an explicit destination for moves", () => {
+		const ref = "wr_AAAAAAAA";
+		expect(quizEditSchema.safeParse({ op: "move", ref }).success).toBe(false);
+		expect(
+			quizEditSchema.safeParse({
+				op: "move",
+				ref,
+				beforeRef: "wr_BBBBBBBB",
+				afterRef: "wr_CCCCCCCC",
+			}).success,
+		).toBe(false);
+	});
+});
+
+async function createTargets(...questions: QuizQuestion[]) {
+	const refs = questions.map((_, index) => `wr_${String(index).padStart(8, "A")}`);
+	const targets = new Map(
+		await Promise.all(
+			questions.map(
+				async (question, index) =>
+					[
+						refs[index]!,
+						{ entryId: question.id, revision: await createQuizQuestionRevision(question) },
+					] as const,
+			),
+		),
+	);
+	return { refs, targets };
+}
diff --git a/src/features/workspaces/quizzes/quiz-edits.ts b/src/features/workspaces/quizzes/quiz-edits.ts
new file mode 100644
index 000000000..d111162e5
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-edits.ts
@@ -0,0 +1,191 @@
+import { z } from "zod";
+
+import {
+	applyOrderedEntryEdits,
+	OrderedEntryEditError,
+	type OrderedEntryEditTarget,
+} from "#/features/workspaces/content/ordered-entry-edits";
+import { replaceUniqueText } from "#/features/workspaces/content/replace-unique-text";
+import {
+	createQuizQuestionRevision,
+	materializeQuizQuestion,
+	parseQuizRichTextHtml,
+	QUIZ_QUESTION_MAX_DISTRACTORS,
+	QUIZ_QUESTION_MIN_DISTRACTORS,
+	type QuizQuestion,
+	type QuizSetContent,
+} from "#/features/workspaces/quizzes/quiz-content";
+import { entryRichTextHtmlSchema } from "#/features/workspaces/content/entry-rich-text";
+import { serializeTiptapDocumentToHtml } from "#/features/workspaces/documents/document-ai-html";
+import { workspaceUnitRefInputSchema } from "#/features/workspaces/locations/workspace-location";
+
+const editTextSchema = z.string().max(8_000);
+
+const authoredQuestionFields = {
+	question: entryRichTextHtmlSchema.describe("HTML question stem."),
+	correctAnswer: entryRichTextHtmlSchema.describe(
+		"HTML for the single correct option. Never mark it in the stem; its final position is shuffled server-side.",
+	),
+	distractors: z
+		.array(entryRichTextHtmlSchema)
+		.min(QUIZ_QUESTION_MIN_DISTRACTORS)
+		.max(QUIZ_QUESTION_MAX_DISTRACTORS)
+		.describe(
+			"HTML for each incorrect option: strictly wrong, plausible, and grounded in a specific misconception. Use 3 for a standard question, 1 for true/false.",
+		),
+	explanation: entryRichTextHtmlSchema.describe(
+		"Short HTML explanation of why the correct answer is right, touching on why the others are not.",
+	),
+};
+
+/** One authored question, as the create tool accepts it. */
+export const quizQuestionInputSchema = z.object(authoredQuestionFields);
+
+export const quizEditSchema = z.union([
+	z.strictObject({
+		op: z.enum(["insert_before", "insert_after"]),
+		ref: workspaceUnitRefInputSchema,
+		...authoredQuestionFields,
+	}),
+	z
+		.strictObject({
+			op: z.literal("update"),
+			ref: workspaceUnitRefInputSchema,
+			question: entryRichTextHtmlSchema.optional().describe("New HTML question stem."),
+			explanation: entryRichTextHtmlSchema.optional().describe("New HTML explanation."),
+		})
+		.refine((value) => value.question !== undefined || value.explanation !== undefined, {
+			message: "Provide a new question or explanation.",
+		}),
+	z.strictObject({
+		op: z.literal("replace"),
+		ref: workspaceUnitRefInputSchema,
+		...authoredQuestionFields,
+	}),
+	z.strictObject({
+		op: z.literal("replace_text"),
+		ref: workspaceUnitRefInputSchema,
+		field: z
+			.enum(["question", "options", "explanation"])
+			.describe("Where to look: the stem, all options together, or the explanation."),
+		find: editTextSchema
+			.min(1)
+			.describe("Exact HTML text from the selected field. It must appear exactly once."),
+		replace: editTextSchema.describe("Replacement text. May be empty."),
+	}),
+	z
+		.strictObject({
+			op: z.literal("move"),
+			ref: workspaceUnitRefInputSchema,
+			beforeRef: workspaceUnitRefInputSchema.optional(),
+			afterRef: workspaceUnitRefInputSchema.optional(),
+		})
+		.refine((edit) => Boolean(edit.beforeRef) !== Boolean(edit.afterRef), {
+			message: "Provide exactly one of beforeRef or afterRef.",
+		}),
+	z.strictObject({
+		op: z.literal("delete"),
+		ref: workspaceUnitRefInputSchema,
+	}),
+]);
+
+export type QuizEdit = z.output<typeof quizEditSchema>;
+
+export async function applyQuizEdits(
+	content: QuizSetContent,
+	edits: QuizEdit[],
+	targets: ReadonlyMap<string, OrderedEntryEditTarget>,
+) {
+	const result = await applyOrderedEntryEdits({
+		entries: content.questions,
+		edits,
+		targets,
+		computeRevision: createQuizQuestionRevision,
+		createEntry: createQuestionFromEdit,
+		reviseEntry: reviseQuestion,
+		lastEntryDetail: "A quiz needs at least one question.",
+	});
+
+	return {
+		applied: result.applied,
+		failed: result.failed,
+		content: { ...content, questions: result.entries },
+	};
+}
+
+function createQuestionFromEdit(edit: QuizEdit): QuizQuestion {
+	if (edit.op !== "insert_before" && edit.op !== "insert_after") {
+		throw new Error("Unsupported quiz edit.");
+	}
+	return materializeQuizQuestion(edit);
+}
+
+function reviseQuestion(question: QuizQuestion, edit: QuizEdit): QuizQuestion {
+	if (edit.op === "update") {
+		return {
+			...question,
+			...(edit.question === undefined ? {} : { question: parseQuizRichTextHtml(edit.question) }),
+			...(edit.explanation === undefined
+				? {}
+				: { explanation: parseQuizRichTextHtml(edit.explanation) }),
+		};
+	}
+	if (edit.op === "replace") {
+		// A replace re-authors the whole question, so the options reshuffle.
+		return { ...materializeQuizQuestion(edit), id: question.id };
+	}
+	if (edit.op === "replace_text") {
+		return replaceQuestionText(question, edit);
+	}
+	throw new Error("Unsupported quiz edit.");
+}
+
+function replaceQuestionText(
+	question: QuizQuestion,
+	edit: Extract<QuizEdit, { op: "replace_text" }>,
+): QuizQuestion {
+	if (edit.field === "options") {
+		// The find must be unique across every option so an in-place fix cannot
+		// silently touch the wrong one — and it never reshuffles.
+		const candidates: Array<{ index: number; text: string }> = [];
+		let matchedTwiceInOne = false;
+		for (const [index, option] of question.options.entries()) {
+			const replaced = replaceUniqueText(
+				serializeTiptapDocumentToHtml(option.text),
+				edit.find,
+				edit.replace,
+			);
+			if (replaced.ok) candidates.push({ index, text: replaced.text });
+			else if (replaced.code === "edit_not_unique") matchedTwiceInOne = true;
+		}
+		if (candidates.length === 0 && !matchedTwiceInOne) {
+			throw new OrderedEntryEditError(
+				"edit_not_found",
+				`No option matches: ${edit.find.slice(0, 80)}`,
+			);
+		}
+		if (candidates.length !== 1 || matchedTwiceInOne) {
+			throw new OrderedEntryEditError(
+				"edit_not_unique",
+				"The text matches more than one place; include more surrounding text so it matches once.",
+			);
+		}
+		const candidate = candidates[0]!;
+		const options = [...question.options];
+		options[candidate.index] = {
+			...options[candidate.index]!,
+			text: parseQuizRichTextHtml(candidate.text),
+		};
+		return { ...question, options };
+	}
+
+	const replaced = replaceUniqueText(
+		serializeTiptapDocumentToHtml(question[edit.field]),
+		edit.find,
+		edit.replace,
+	);
+	if (!replaced.ok) {
+		throw new OrderedEntryEditError(replaced.code, replaced.detail);
+	}
+	return { ...question, [edit.field]: parseQuizRichTextHtml(replaced.text) };
+}
diff --git a/src/features/workspaces/quizzes/quiz-functions.ts b/src/features/workspaces/quizzes/quiz-functions.ts
new file mode 100644
index 000000000..82f272b69
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-functions.ts
@@ -0,0 +1,37 @@
+import { createServerFn } from "@tanstack/react-start";
+import { z } from "zod";
+
+import { workspaceEntryIdSchema } from "#/features/workspaces/locations/workspace-location";
+
+import {
+	readQuizViewer,
+	recordQuizAnswer,
+	resetQuizStudyProgress,
+} from "#/features/workspaces/quizzes/quiz-study-persistence";
+import { getCurrentUserId } from "#/features/workspaces/server/permissions";
+
+const quizItemInputSchema = z.object({
+	itemId: z.string().min(1),
+	workspaceId: z.string().min(1),
+});
+
+export const getQuizViewerFn = createServerFn({ method: "GET" })
+	.validator(quizItemInputSchema)
+	.handler(async ({ data }) => {
+		return await readQuizViewer({ ...data, userId: await getCurrentUserId() });
+	});
+
+export const recordQuizAnswerFn = createServerFn({ method: "POST" })
+	.validator(
+		quizItemInputSchema.extend({
+			questionId: workspaceEntryIdSchema,
+			selectedOptionId: z.uuid(),
+		}),
+	)
+	.handler(async ({ data }) => recordQuizAnswer({ ...data, userId: await getCurrentUserId() }));
+
+export const resetQuizStudyProgressFn = createServerFn({ method: "POST" })
+	.validator(quizItemInputSchema)
+	.handler(async ({ data }) =>
+		resetQuizStudyProgress({ ...data, userId: await getCurrentUserId() }),
+	);
diff --git a/src/features/workspaces/quizzes/quiz-persistence.ts b/src/features/workspaces/quizzes/quiz-persistence.ts
new file mode 100644
index 000000000..dd54bb897
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-persistence.ts
@@ -0,0 +1,96 @@
+import { and, eq } from "drizzle-orm";
+
+import { workspaceItemContents, workspaceItems } from "#/db/schema";
+import { withDb } from "#/db/server";
+import {
+	parseQuizSetContent,
+	stringifyQuizSetContent,
+	type QuizSetContent,
+} from "#/features/workspaces/quizzes/quiz-content";
+import {
+	lockWorkspaceForActor,
+	nextWorkspaceRevision,
+	requireActiveWorkspaceItem,
+	withWorkspaceTransaction,
+} from "#/features/workspaces/persistence/workspace-postgres-support";
+import { notifyWorkspaceRoom } from "#/features/workspaces/realtime/workspace-room-notifier";
+
+export async function readQuizSet(input: { itemId: string; workspaceId: string }) {
+	return await withDb(async (db) => {
+		const [row] = await db
+			.select({ content: workspaceItemContents.content })
+			.from(workspaceItems)
+			.innerJoin(workspaceItemContents, eq(workspaceItems.id, workspaceItemContents.itemId))
+			.where(
+				and(
+					eq(workspaceItems.id, input.itemId),
+					eq(workspaceItems.workspaceId, input.workspaceId),
+					eq(workspaceItems.type, "quiz"),
+				),
+			)
+			.limit(1);
+		if (!row) throw new Error("Workspace item is not a quiz.");
+		return parseQuizSetContent(row.content);
+	});
+}
+
+export async function updateQuizSet<T>(
+	env: Cloudflare.Env,
+	input: {
+		actorUserId?: string | null;
+		itemId: string;
+		workspaceId: string;
+	},
+	update: (content: QuizSetContent) =>
+		| {
+				changed: boolean;
+				content: QuizSetContent;
+				result: T;
+		  }
+		| Promise<{ changed: boolean; content: QuizSetContent; result: T }>,
+) {
+	const command = await withWorkspaceTransaction(async (transaction) => {
+		await lockWorkspaceForActor(transaction, input.workspaceId, input.actorUserId);
+		const [row] = await transaction
+			.select({ content: workspaceItemContents.content })
+			.from(workspaceItems)
+			.innerJoin(workspaceItemContents, eq(workspaceItems.id, workspaceItemContents.itemId))
+			.where(
+				and(
+					eq(workspaceItems.id, input.itemId),
+					eq(workspaceItems.workspaceId, input.workspaceId),
+					eq(workspaceItems.type, "quiz"),
+				),
+			)
+			.limit(1);
+		if (!row) throw new Error("Workspace item is not a quiz.");
+		const updated = await update(parseQuizSetContent(row.content));
+		if (!updated.changed) return { item: null, revision: null, result: updated.result };
+		const now = new Date();
+		await transaction
+			.update(workspaceItemContents)
+			.set({ content: stringifyQuizSetContent(updated.content) })
+			.where(eq(workspaceItemContents.itemId, input.itemId));
+		await transaction
+			.update(workspaceItems)
+			.set({ updatedAt: now })
+			.where(
+				and(eq(workspaceItems.workspaceId, input.workspaceId), eq(workspaceItems.id, input.itemId)),
+			);
+		return {
+			item: await requireActiveWorkspaceItem(transaction, input.workspaceId, input.itemId),
+			revision: await nextWorkspaceRevision(transaction, input.workspaceId),
+			result: updated.result,
+		};
+	});
+
+	if (command.item && command.revision !== null) {
+		await notifyWorkspaceRoom(env, {
+			type: "workspace.items.upserted",
+			workspaceId: input.workspaceId,
+			revision: command.revision,
+			items: [command.item],
+		});
+	}
+	return command.result;
+}
diff --git a/src/features/workspaces/quizzes/quiz-queries.ts b/src/features/workspaces/quizzes/quiz-queries.ts
new file mode 100644
index 000000000..95bc14ca1
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-queries.ts
@@ -0,0 +1,110 @@
+import { queryOptions, useMutation, useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+
+import {
+	getQuizViewerFn,
+	recordQuizAnswerFn,
+	resetQuizStudyProgressFn,
+} from "#/features/workspaces/quizzes/quiz-functions";
+import {
+	applyQuizAnswer,
+	createEmptyQuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
+
+type QuizViewerData = Awaited<ReturnType<typeof getQuizViewerFn>>;
+
+export function quizViewerQueryOptions(input: {
+	itemId: string;
+	updatedAt: string;
+	workspaceId: string;
+}) {
+	return queryOptions({
+		queryKey: [...quizViewerItemQueryKey(input), input.updatedAt],
+		queryFn: () =>
+			getQuizViewerFn({
+				data: { itemId: input.itemId, workspaceId: input.workspaceId },
+			}),
+	});
+}
+
+export function useResetQuizStudyProgress(input: {
+	itemId: string;
+	updatedAt: string;
+	workspaceId: string;
+}) {
+	const queryClient = useQueryClient();
+	const viewerQuery = quizViewerQueryOptions(input);
+	const itemQueryKey = quizViewerItemQueryKey(input);
+	return useMutation({
+		scope: { id: `quiz-study:${input.itemId}` },
+		mutationFn: () =>
+			resetQuizStudyProgressFn({
+				data: { itemId: input.itemId, workspaceId: input.workspaceId },
+			}),
+		onMutate: async () => {
+			await queryClient.cancelQueries({ queryKey: itemQueryKey });
+			const previous = queryClient.getQueryData(viewerQuery.queryKey);
+			queryClient.setQueriesData<QuizViewerData>({ queryKey: itemQueryKey }, (current) =>
+				current ? { ...current, studyState: createEmptyQuizStudyState() } : current,
+			);
+			return { previous };
+		},
+		onSuccess: (studyState) => {
+			queryClient.setQueriesData<QuizViewerData>({ queryKey: itemQueryKey }, (current) =>
+				current ? { ...current, studyState } : current,
+			);
+		},
+		onError: (_error, _variables, context) => {
+			queryClient.setQueryData(viewerQuery.queryKey, context?.previous);
+			void queryClient.invalidateQueries({ queryKey: itemQueryKey });
+			toast.error("Your quiz progress could not be reset.");
+		},
+	});
+}
+
+export function useRecordQuizAnswer(input: {
+	itemId: string;
+	updatedAt: string;
+	workspaceId: string;
+}) {
+	const queryClient = useQueryClient();
+	const viewerQuery = quizViewerQueryOptions(input);
+	const itemQueryKey = quizViewerItemQueryKey(input);
+	return useMutation({
+		scope: { id: `quiz-study:${input.itemId}` },
+		mutationFn: (answer: { questionId: string; selectedOptionId: string }) =>
+			recordQuizAnswerFn({
+				data: { itemId: input.itemId, workspaceId: input.workspaceId, ...answer },
+			}),
+		onMutate: async (answer) => {
+			await queryClient.cancelQueries({ queryKey: itemQueryKey });
+			const previous = queryClient.getQueryData(viewerQuery.queryKey);
+			queryClient.setQueriesData<QuizViewerData>({ queryKey: itemQueryKey }, (current) =>
+				current
+					? {
+							...current,
+							studyState: applyQuizAnswer(current.studyState, {
+								...answer,
+								answeredAt: new Date().toISOString(),
+							}),
+						}
+					: current,
+			);
+			return { previous };
+		},
+		onSuccess: (studyState) => {
+			queryClient.setQueriesData<QuizViewerData>({ queryKey: itemQueryKey }, (current) =>
+				current ? { ...current, studyState } : current,
+			);
+		},
+		onError: (_error, _answer, context) => {
+			queryClient.setQueryData(viewerQuery.queryKey, context?.previous);
+			void queryClient.invalidateQueries({ queryKey: itemQueryKey });
+			toast.error("Your answer could not be saved.");
+		},
+	});
+}
+
+function quizViewerItemQueryKey(input: { itemId: string; workspaceId: string }) {
+	return ["workspace-quizzes", input.workspaceId, input.itemId] as const;
+}
diff --git a/src/features/workspaces/quizzes/quiz-study-persistence.ts b/src/features/workspaces/quizzes/quiz-study-persistence.ts
new file mode 100644
index 000000000..6d53f80d2
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-study-persistence.ts
@@ -0,0 +1,163 @@
+import { and, eq } from "drizzle-orm";
+
+import { workspaceItemContents, workspaceItems, workspaceItemUserStates } from "#/db/schema";
+import { withDb } from "#/db/server";
+import { parseQuizSetContent } from "#/features/workspaces/quizzes/quiz-content";
+import {
+	applyQuizAnswer,
+	createEmptyQuizStudyState,
+	getQuizAnswer,
+	parseQuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
+import { assertCanReadWorkspace } from "#/features/workspaces/server/permissions";
+import type { Transaction } from "#/features/workspaces/persistence/workspace-postgres-support";
+
+export async function readQuizViewer(input: {
+	itemId: string;
+	userId: string;
+	workspaceId: string;
+}) {
+	return await withDb(async (db) => {
+		await assertCanReadWorkspace(db, input);
+		const [row] = await db
+			.select({ content: workspaceItemContents.content, state: workspaceItemUserStates.state })
+			.from(workspaceItems)
+			.innerJoin(workspaceItemContents, eq(workspaceItems.id, workspaceItemContents.itemId))
+			.leftJoin(
+				workspaceItemUserStates,
+				and(
+					eq(workspaceItemUserStates.itemId, workspaceItems.id),
+					eq(workspaceItemUserStates.userId, input.userId),
+				),
+			)
+			.where(
+				and(
+					eq(workspaceItems.id, input.itemId),
+					eq(workspaceItems.workspaceId, input.workspaceId),
+					eq(workspaceItems.type, "quiz"),
+				),
+			)
+			.limit(1);
+		if (!row) throw new Error("Quiz not found.");
+		return {
+			questions: parseQuizSetContent(row.content).questions,
+			studyState: parseQuizStudyState(row.state),
+		};
+	});
+}
+
+/**
+ * Locks in one answer. Answers are first-pick-wins — a second submission for
+ * the same question (a stale tab, a double click) leaves the recorded answer
+ * alone, so the graded state a user saw never changes under them.
+ */
+export async function recordQuizAnswer(input: {
+	itemId: string;
+	questionId: string;
+	selectedOptionId: string;
+	userId: string;
+	workspaceId: string;
+}) {
+	return await withDb((db) =>
+		db.transaction(async (transaction) => {
+			const questions = await requireQuizSet(transaction, input);
+			const question = questions.find((entry) => entry.id === input.questionId);
+			if (!question) {
+				throw new Error("Quiz question not found.");
+			}
+			if (!question.options.some((option) => option.id === input.selectedOptionId)) {
+				throw new Error("Quiz option not found.");
+			}
+
+			const state = await lockQuizStudyState(transaction, input);
+			if (getQuizAnswer(question, state)) {
+				return state;
+			}
+			const nextState = applyQuizAnswer(state, {
+				questionId: input.questionId,
+				selectedOptionId: input.selectedOptionId,
+				answeredAt: new Date().toISOString(),
+			});
+
+			await updateQuizStudyState(transaction, input, nextState);
+			return nextState;
+		}),
+	);
+}
+
+export async function resetQuizStudyProgress(input: {
+	itemId: string;
+	userId: string;
+	workspaceId: string;
+}) {
+	return await withDb((db) =>
+		db.transaction(async (transaction) => {
+			await requireQuizSet(transaction, input);
+			await lockQuizStudyState(transaction, input);
+			const state = createEmptyQuizStudyState();
+			await updateQuizStudyState(transaction, input, state);
+			return state;
+		}),
+	);
+}
+
+async function requireQuizSet(
+	transaction: Transaction,
+	input: { itemId: string; userId: string; workspaceId: string },
+) {
+	await assertCanReadWorkspace(transaction, input);
+	const [item] = await transaction
+		.select({ content: workspaceItemContents.content })
+		.from(workspaceItems)
+		.innerJoin(workspaceItemContents, eq(workspaceItems.id, workspaceItemContents.itemId))
+		.where(
+			and(
+				eq(workspaceItems.id, input.itemId),
+				eq(workspaceItems.workspaceId, input.workspaceId),
+				eq(workspaceItems.type, "quiz"),
+			),
+		)
+		.limit(1);
+	if (!item) throw new Error("Quiz not found.");
+	return parseQuizSetContent(item.content).questions;
+}
+
+async function lockQuizStudyState(
+	transaction: Transaction,
+	input: { itemId: string; userId: string },
+) {
+	const emptyState = createEmptyQuizStudyState();
+	await transaction
+		.insert(workspaceItemUserStates)
+		.values({ itemId: input.itemId, userId: input.userId, state: emptyState })
+		.onConflictDoNothing();
+	const [row] = await transaction
+		.select({ state: workspaceItemUserStates.state })
+		.from(workspaceItemUserStates)
+		.where(
+			and(
+				eq(workspaceItemUserStates.userId, input.userId),
+				eq(workspaceItemUserStates.itemId, input.itemId),
+			),
+		)
+		.limit(1)
+		.for("update");
+	if (!row) throw new Error("Quiz study state could not be created.");
+	return parseQuizStudyState(row.state);
+}
+
+async function updateQuizStudyState(
+	transaction: Transaction,
+	input: { itemId: string; userId: string },
+	state: ReturnType<typeof createEmptyQuizStudyState>,
+) {
+	await transaction
+		.update(workspaceItemUserStates)
+		.set({ state, updatedAt: new Date() })
+		.where(
+			and(
+				eq(workspaceItemUserStates.userId, input.userId),
+				eq(workspaceItemUserStates.itemId, input.itemId),
+			),
+		);
+}
diff --git a/src/features/workspaces/quizzes/quiz-study-session.ts b/src/features/workspaces/quizzes/quiz-study-session.ts
new file mode 100644
index 000000000..8cb4c27f0
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-study-session.ts
@@ -0,0 +1,53 @@
+import type { QuizQuestion } from "#/features/workspaces/quizzes/quiz-content";
+import {
+	getQuizAnswer,
+	type QuizStudyProgress,
+	type QuizStudyState,
+} from "#/features/workspaces/quizzes/quiz-study-state";
+import { shuffleInPlace } from "#/lib/shuffle";
+
+export type QuizStudyMode = "all" | "missed";
+
+/** Builds one stable question queue without changing the quiz's stored order. */
+export function createQuizStudyQueue(
+	input: {
+		questions: QuizQuestion[];
+		mode: QuizStudyMode;
+		shuffled: boolean;
+		studyState: QuizStudyState;
+	},
+	random: () => number = Math.random,
+) {
+	const questionIds: string[] = [];
+	for (const question of input.questions) {
+		const answer = getQuizAnswer(question, input.studyState);
+		const missed = answer !== undefined && answer.selectedOptionId !== question.correctOptionId;
+		if (input.mode === "all" || missed) {
+			questionIds.push(question.id);
+		}
+	}
+
+	return input.shuffled ? shuffleInPlace(questionIds, random) : questionIds;
+}
+
+/** What the AI's live view context says about the open quiz. */
+export function getQuizStudyViewState(input: {
+	answered: boolean;
+	correct?: boolean;
+	mode: QuizStudyMode;
+	progress: QuizStudyProgress;
+	sessionPosition: number;
+	sessionTotal: number;
+	shuffled: boolean;
+	sourceQuestionNumber: number;
+}) {
+	const answerState = input.answered
+		? `answered ${input.correct ? "correctly" : "incorrectly"}`
+		: "not answered yet";
+	const order = input.shuffled ? "shuffled" : "original order";
+	const mode = input.mode === "missed" ? "missed questions" : "all questions";
+	return {
+		label: `question ${input.sourceQuestionNumber}`,
+		detail: `question ${input.sourceQuestionNumber} of ${input.progress.totalQuestions}, ${answerState}, quiz progress: ${input.progress.answeredCount} of ${input.progress.totalQuestions} answered (${input.progress.correctCount} correct, ${input.progress.incorrectCount} incorrect), session: ${mode}, position ${input.sessionPosition} of ${input.sessionTotal}, ${order}`,
+	};
+}
diff --git a/src/features/workspaces/quizzes/quiz-study-state.test.ts b/src/features/workspaces/quizzes/quiz-study-state.test.ts
new file mode 100644
index 000000000..b7fc3a25d
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-study-state.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+import { createQuizSetFromInputs } from "#/features/workspaces/quizzes/quiz-content";
+import {
+	applyQuizAnswer,
+	createEmptyQuizStudyState,
+	getQuizAnswer,
+	parseQuizStudyState,
+	summarizeQuizStudyProgress,
+} from "#/features/workspaces/quizzes/quiz-study-state";
+
+const set = createQuizSetFromInputs([
+	{
+		question: "<p>2 + 2?</p>",
+		correctAnswer: "<p>4</p>",
+		distractors: ["<p>5</p>"],
+		explanation: "<p>Basic addition.</p>",
+	},
+	{
+		question: "<p>3 + 3?</p>",
+		correctAnswer: "<p>6</p>",
+		distractors: ["<p>7</p>"],
+		explanation: "<p>Basic addition.</p>",
+	},
+]);
+const [first, second] = set.questions;
+
+describe("quiz study state", () => {
+	it("summarizes correct, incorrect, and unanswered questions", () => {
+		let state = createEmptyQuizStudyState();
+		state = applyQuizAnswer(state, {
+			questionId: first!.id,
+			selectedOptionId: first!.correctOptionId,
+			answeredAt: "2026-08-14T00:00:00.000Z",
+		});
+		const wrongOption = second!.options.find((option) => option.id !== second!.correctOptionId)!;
+		state = applyQuizAnswer(state, {
+			questionId: second!.id,
+			selectedOptionId: wrongOption.id,
+			answeredAt: "2026-08-14T00:00:00.000Z",
+		});
+
+		expect(summarizeQuizStudyProgress(set.questions, state)).toEqual({
+			answeredCount: 2,
+			correctCount: 1,
+			incorrectCount: 1,
+			totalQuestions: 2,
+			unansweredCount: 0,
+		});
+	});
+
+	it("treats an answer to a re-authored question as unanswered", () => {
+		const state = applyQuizAnswer(createEmptyQuizStudyState(), {
+			questionId: first!.id,
+			selectedOptionId: crypto.randomUUID(),
+			answeredAt: "2026-08-14T00:00:00.000Z",
+		});
+
+		expect(getQuizAnswer(first!, state)).toBeUndefined();
+		expect(summarizeQuizStudyProgress(set.questions, state).answeredCount).toBe(0);
+	});
+
+	it("parses stored state and defaults missing state to empty", () => {
+		expect(parseQuizStudyState(null)).toEqual({ kind: "quiz", answers: {} });
+		expect(() => parseQuizStudyState({ kind: "flashcard", cards: {} })).toThrow();
+	});
+});
diff --git a/src/features/workspaces/quizzes/quiz-study-state.ts b/src/features/workspaces/quizzes/quiz-study-state.ts
new file mode 100644
index 000000000..d000fb6dd
--- /dev/null
+++ b/src/features/workspaces/quizzes/quiz-study-state.ts
@@ -0,0 +1,102 @@
+import { z } from "zod";
+
+import { workspaceEntryIdSchema } from "#/features/workspaces/locations/workspace-location";
+
+/**
+ * One user's current run through a quiz. Answers lock on selection — the
+ * viewer grades immediately — and a retake resets the whole record, mirroring
+ * flashcard study state. `kind` keeps the shared user-state rows
+ * self-describing next to their flashcard siblings.
+ */
+export const quizAnswerSchema = z.object({
+	selectedOptionId: z.uuid(),
+	answeredAt: z.string(),
+});
+
+export type QuizAnswer = z.output<typeof quizAnswerSchema>;
+
+export const quizStudyStateSchema = z.object({
+	kind: z.literal("quiz"),
+	answers: z.record(workspaceEntryIdSchema, quizAnswerSchema),
+});
+
+export type QuizStudyState = z.output<typeof quizStudyStateSchema>;
+
+export const quizStudyProgressSchema = z.object({
+	answeredCount: z.number().int().nonnegative(),
+	correctCount: z.number().int().nonnegative(),
+	incorrectCount: z.number().int().nonnegative(),
+	totalQuestions: z.number().int().nonnegative(),
+	unansweredCount: z.number().int().nonnegative(),
+});
+
+export type QuizStudyProgress = z.output<typeof quizStudyProgressSchema>;
+
+export function createEmptyQuizStudyState(): QuizStudyState {
+	return { kind: "quiz", answers: {} };
+}
+
+export function parseQuizStudyState(value: unknown): QuizStudyState {
+	if (value === null || value === undefined) return createEmptyQuizStudyState();
+	return quizStudyStateSchema.parse(value);
+}
+
+export function summarizeQuizStudyProgress(
+	questions: ReadonlyArray<{
+		id: string;
+		correctOptionId: string;
+		options: ReadonlyArray<{ id: string }>;
+	}>,
+	state: QuizStudyState,
+): QuizStudyProgress {
+	let correctCount = 0;
+	let incorrectCount = 0;
+
+	for (const question of questions) {
+		const answer = getQuizAnswer(question, state);
+		if (!answer) continue;
+		if (answer.selectedOptionId === question.correctOptionId) correctCount += 1;
+		else incorrectCount += 1;
+	}
+
+	const answeredCount = correctCount + incorrectCount;
+	return {
+		answeredCount,
+		correctCount,
+		incorrectCount,
+		totalQuestions: questions.length,
+		unansweredCount: questions.length - answeredCount,
+	};
+}
+
+/**
+ * The user's live answer to one question. An answer whose option no longer
+ * exists — the question was re-authored since — reads as unanswered rather
+ * than as a wrong pick the user never made.
+ */
+export function getQuizAnswer(
+	question: { id: string; options: ReadonlyArray<{ id: string }> },
+	state: QuizStudyState,
+): QuizAnswer | undefined {
+	const answer = state.answers[question.id];
+	if (!answer) return undefined;
+	return question.options.some((option) => option.id === answer.selectedOptionId)
+		? answer
+		: undefined;
+}
+
+export function applyQuizAnswer(
+	state: QuizStudyState,
+	input: { questionId: string; selectedOptionId: string; answeredAt: string },
+): QuizStudyState {
+	return {
+		...state,
+		answers: {
+			...state.answers,
+			[input.questionId]: {
+				selectedOptionId: input.selectedOptionId,
+				answeredAt: input.answeredAt,
+			},
+		},
+	};
+}
diff --git a/src/features/workspaces/workspace-item-registry.ts b/src/features/workspaces/workspace-item-registry.ts
index e694f56f7..5a5afe96a 100644
--- a/src/features/workspaces/workspace-item-registry.ts
+++ b/src/features/workspaces/workspace-item-registry.ts
@@ -1,6 +1,6 @@
 import { z } from "zod";
 
-export const WORKSPACE_ITEM_TYPES = ["folder", "document", "flashcard", "file"] as const;
+export const WORKSPACE_ITEM_TYPES = ["folder", "document", "flashcard", "quiz", "file"] as const;
 export const workspaceItemTypeSchema = z.enum(WORKSPACE_ITEM_TYPES);
 export type WorkspaceItemType = z.infer<typeof workspaceItemTypeSchema>;
 
@@ -49,6 +49,14 @@ const workspaceItemRegistry = {
 		label: "Flashcards",
 		menuLabel: "Flashcards",
 	},
+	quiz: {
+		color: "emerald",
+		contentKind: "structured",
+		defaultName: "New quiz",
+		isContainer: false,
+		label: "Quiz",
+		menuLabel: "Quiz",
+	},
 	file: {
 		color: "rose",
 		contentKind: "file",
diff --git a/src/lib/binary.ts b/src/lib/binary.ts
index f04ffe7b9..aab904feb 100644
--- a/src/lib/binary.ts
+++ b/src/lib/binary.ts
@@ -21,10 +21,6 @@ export function decodeBase64Url(value: string) {
 	return Uint8Array.from(atob(padded), (character) => character.charCodeAt(0));
 }
 
-export function encodeBase64UrlText(value: string) {
-	return encodeBase64Url(textEncoder.encode(value));
-}
-
 export function decodeBase64UrlText(value: string) {
 	return textDecoder.decode(decodeBase64Url(value));
 }
diff --git a/src/lib/shuffle.ts b/src/lib/shuffle.ts
new file mode 100644
index 000000000..a94c31cf9
--- /dev/null
+++ b/src/lib/shuffle.ts
@@ -0,0 +1,10 @@
+/** Fisher–Yates, in place. Pass a seeded `random` for deterministic tests. */
+export function shuffleInPlace<T>(values: T[], random: () => number = Math.random) {
+	for (let index = values.length - 1; index > 0; index -= 1) {
+		const swapIndex = Math.floor(random() * (index + 1));
+		const value = values[index]!;
+		values[index] = values[swapIndex]!;
+		values[swapIndex] = value;
+	}
+	return values;
+}
diff --git a/src/styles.css b/src/styles.css
index 96ccc268a..5270eb542 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -514,6 +514,15 @@
 		color: var(--foreground);
 	}
 
+	/*
+	 * Prose inside a surface that already supplies its own measure and padding —
+	 * a quiz question or answer row — where the reading-measure padding above
+	 * would read as a stray indent.
+	 */
+	.workspace-document-prose.is-flush {
+		padding-inline: 0;
+	}
+
 	/*
 	 * Review marks follow word-processor tracked changes rather than a code diff:
 	 * new text is underlined in the app's accent, removed text is struck through
@@ -607,6 +616,15 @@
 		line-height: 1.7;
 	}
 
+	/*
+	 * That min-height is a click target for empty paragraphs while editing. In a
+	 * read-only render it only adds space under the last line, which pushes the
+	 * text off-centre against anything aligned beside it — a quiz option's letter.
+	 */
+	.workspace-document-prose[contenteditable="false"] p {
+		min-height: 0;
+	}
+
 	.workspace-document-prose ul,
 	.workspace-document-prose ol {
 		padding-left: 1.35rem;
@@ -727,6 +745,21 @@
 		display: none;
 	}
 
+	/* A mermaid diagram, drawn from a code block. Nobody edits the syntax by
+	   hand, so the block behaves like an image: click to select, then move or
+	   delete it whole. */
+	.workspace-document-prose .workspace-document-diagram[data-selected="true"] {
+		outline: 2px solid var(--ring);
+		outline-offset: 1px;
+		border-radius: var(--radius);
+	}
+
+	/* The mermaid source, which ProseMirror must render somewhere but the reader
+	   should never see. The drawing is the visible form of this text. */
+	.workspace-document-prose .workspace-document-diagram-source {
+		display: none;
+	}
+
 	/* Collapsible sections. The Details node view renders a toggle button next to
 	   the summary and hides the content div, so it only needs layout here — the
 	   AI writes <details> and there is no toolbar affordance for inserting one. */