ignotum 0.0.6 → 0.0.7

package/dist/cli/bin.mjs

@@ -29650,6 +29650,10 @@ Function$1.dual(2, (value, descriptor) => {
 	});
 	return value;
 });
+const getValueDescriptor = (value) => {
+	if (!Predicate.hasProperty(value, ValueDescriptorTypeId)) return void 0;
+	return Schema.is(ValueDescriptor)(value[ValueDescriptorTypeId]) ? value[ValueDescriptorTypeId] : void 0;
+};
 //#endregion
 //#region ../contracts/dist/deployment.js
 const ArtifactPath = Schema.String.check(Schema.isPattern(/^(?!\/)(?![A-Za-z]:\/)(?!.*(?:^|\/)\.\.(?:\/|$))(?!.*(?:^|\/)\.(?:\/|$))(?!.*\/\/)[^\\\0]+$/)).pipe(Schema.brand("ignotum/deployment/ArtifactPath"));
@@ -29705,12 +29709,17 @@ const SchemaSnapshotField = Schema.Struct({
 	name: Schema.String,
 	value: ValueDescriptor
 });
+const SchemaSnapshotIndex = Schema.Struct({
+	name: Schema.String,
+	fields: Schema.Array(Schema.String)
+});
 const SchemaSnapshotTable = Schema.Struct({
 	name: Schema.String,
-	fields: Schema.Array(SchemaSnapshotField)
+	fields: Schema.Array(SchemaSnapshotField),
+	indexes: Schema.Array(SchemaSnapshotIndex)
 });
 const SchemaSnapshot = Schema.Struct({
-	formatVersion: Schema.Literal(1),
+	formatVersion: Schema.Literal(2),
 	tables: Schema.Array(SchemaSnapshotTable)
 });
 const ServerFunctionArtifact = Schema.Struct({
@@ -29839,7 +29848,7 @@ var IdGenerator = class IdGenerator extends Context.Service()("@ignotum/shared/i
 };
 //#endregion
 //#region package.json
-var version = "0.0.6";
+var version = "0.0.7";
 //#endregion
 //#region src/cli/codegen.ts
 const generatedHeader = "// Generated by `ignotum codegen`. Do not edit.";
@@ -30085,12 +30094,12 @@ const controlClientLayer = Layer.effect(ControlClient, Effect.gen(function* () {
 }));
 //#endregion
 //#region ../contracts/dist/json.js
-const encodeScalar = (value) => Schema.decodeSync(Schema.String)(JSON.stringify(value));
+const encodeScalar$1 = (value) => Schema.decodeSync(Schema.String)(JSON.stringify(value));
 const encodeCanonicalJson = (value) => {
-	if (value === null || Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) return encodeScalar(value);
+	if (value === null || Predicate.isString(value) || Predicate.isNumber(value) || Predicate.isBoolean(value)) return encodeScalar$1(value);
 	if (Predicate.isObject(value)) return `{${Array$1.map(Array$1.sort(String$1.Order)(Object.keys(value)), (key) => {
 		const field = Schema.decodeUnknownSync(Schema.Json)(value[key]);
-		return `${encodeScalar(key)}:${encodeCanonicalJson(field)}`;
+		return `${encodeScalar$1(key)}:${encodeCanonicalJson(field)}`;
 	}).join(",")}}`;
 	return `[${Schema.decodeUnknownSync(Schema.Array(Schema.Json))(value).map(encodeCanonicalJson).join(",")}]`;
 };
@@ -30173,6 +30182,58 @@ const documentNotFound = (table, id) => Brand.nominal()({
 	id
 });
 //#endregion
+//#region ../contracts/dist/runtime/pagination.js
+const PaginationCursor = Schema.String.check(Schema.isBase64Url()).pipe(Schema.brand("ignotum/runtime/PaginationCursor"));
+const PaginationPageSize = Schema.Int.check(Schema.isBetween({
+	minimum: 1,
+	maximum: 1e3
+})).pipe(Schema.brand("ignotum/runtime/PaginationPageSize"));
+Schema.Struct({
+	cursor: Schema.NullOr(PaginationCursor),
+	pageSize: PaginationPageSize
+});
+const TablePosition = Schema.Struct({
+	type: Schema.Literal("Table"),
+	createdAt: Schema.Int,
+	id: Schema.String
+});
+const IndexPosition = Schema.Struct({
+	type: Schema.Literal("Index"),
+	key: Schema.String.check(Schema.isPattern(/^(?:[0-9a-f]{2})*$/)).pipe(Schema.brand("ignotum/runtime/EncodedIndexKey"))
+});
+const PaginationPosition = Schema.Union([TablePosition, IndexPosition]);
+const CursorPayload = Schema.Struct({
+	version: Schema.Literal(1),
+	query: Schema.String,
+	position: PaginationPosition
+});
+const CursorPayloadJson = Schema.fromJsonString(CursorPayload);
+const paginationQueryIdentity = (tableId, index, lower, upper, order) => encodeCanonicalJson([
+	tableId,
+	index,
+	lower ?? null,
+	upper ?? null,
+	order
+]);
+const encodePaginationCursor = (query, position) => PaginationCursor.make(Encoding.encodeBase64Url(Schema.encodeSync(CursorPayloadJson)({
+	version: 1,
+	query,
+	position
+})));
+const decodePaginationCursor = (cursor) => Schema.decodeSync(CursorPayloadJson)(Result.getOrThrow(Encoding.decodeBase64UrlString(cursor)));
+Schema.Union([
+	Schema.String,
+	Schema.Finite,
+	Schema.Boolean
+]);
+const schemaIndexLimits = {
+	fieldsPerIndex: 8,
+	indexesPerSchema: 128,
+	indexesPerTable: 16,
+	keyBytes: 4096,
+	nameBytes: 64
+};
+//#endregion
 //#region ../contracts/dist/runtime/schema.js
 const FunctionSchemaTypeId = Symbol.for("ignotum/runtime/schema/FunctionSchema");
 const getFunctionSchema = (value) => value[FunctionSchemaTypeId];
@@ -30472,19 +30533,36 @@ const readArtifactDirectory = Effect.fn("Deployment.readArtifactDirectory")(func
 const makeSchemaSnapshot = (schema) => {
 	const definition = schema[SchemaDefinitionTypeId];
 	return {
-		formatVersion: 1,
+		formatVersion: 2,
 		tables: Array$1.map(Array$1.sort(String$1.Order)(Object.keys(definition)), (name) => {
 			const table = definition[name];
 			if (table === void 0 || table.descriptor.type !== "object") throw new Error(`The table '${name}' does not have a canonical Ignotum descriptor.`);
+			const indexes = Object.values(table.indexes).map((index) => ({
+				name: index.name,
+				fields: globalThis.Array.from(index.fields)
+			})).sort((left, right) => left.name.localeCompare(right.name));
 			return {
 				name,
-				fields: table.descriptor.fields
+				fields: table.descriptor.fields,
+				indexes
 			};
 		})
 	};
 };
 const encodeSchemaSnapshot = (snapshot) => `${encodeCanonical(SchemaSnapshot, snapshot)}\n`;
-Function$1.dual(2, (previous, next) => previous === void 0 || encodeCanonical(SchemaSnapshot, previous) === encodeCanonical(SchemaSnapshot, next));
+Function$1.dual(2, (previous, next) => previous === void 0 || encodeCanonical(SchemaSnapshot, {
+	...previous,
+	tables: previous.tables.map((table) => ({
+		...table,
+		indexes: []
+	}))
+}) === encodeCanonical(SchemaSnapshot, {
+	...next,
+	tables: next.tables.map((table) => ({
+		...table,
+		indexes: []
+	}))
+}));
 //#endregion
 //#region src/cli/app-configuration.ts
 const AppConfiguration = Schema.Struct({
@@ -31912,6 +31990,113 @@ const sqliteCauseWithErrno = (cause) => {
 	return Object.assign(cause, { errno: errcode });
 };
 //#endregion
+//#region ../contracts/dist/runtime/index.js
+const IndexIdentity = Schema.String.pipe(Schema.brand("ignotum/runtime/IndexIdentity"));
+const EncodedIndexKey = Schema.String.check(Schema.isPattern(/^(?:[0-9a-f]{2})*$/)).pipe(Schema.brand("ignotum/runtime/EncodedIndexKey"));
+const IndexScalarValue = Schema.Union([
+	Schema.Boolean,
+	Schema.Finite,
+	Schema.String
+]);
+const scalarValueKind = (value) => Schema.is(Schema.Boolean)(value) ? "boolean" : Schema.is(Schema.Finite)(value) ? "number" : "string";
+const encodeString = (value) => {
+	const bytes = [];
+	for (let index = 0; index < value.length; index += 1) {
+		const unit = value.charCodeAt(index);
+		bytes.push(1, unit >>> 8, unit & 255);
+	}
+	bytes.push(0);
+	return Array.from(bytes);
+};
+const encodeNumber = (input) => {
+	const value = Object.is(input, -0) ? 0 : input;
+	if (!Number.isFinite(value)) throw new Error("Index numbers must be finite.");
+	const bytes = /* @__PURE__ */ new Uint8Array(8);
+	new DataView(bytes.buffer).setFloat64(0, value, false);
+	if ((bytes[0] ?? 0) >= 128) for (let index = 0; index < bytes.length; index += 1) bytes[index] = 255 - bytes[index];
+	else bytes[0] = (bytes[0] ?? 0) ^ 128;
+	return Array.from(bytes);
+};
+const scalarKind = (descriptor) => {
+	switch (descriptor.type) {
+		case "boolean": return "boolean";
+		case "date":
+		case "integer":
+		case "number": return "number";
+		case "id":
+		case "string": return "string";
+		case "literal": return scalarValueKind(descriptor.value);
+		case "literals": {
+			const first = descriptor.values[0];
+			if (first === void 0) throw new Error("Indexed literal sets cannot be empty.");
+			const kind = scalarValueKind(first);
+			if (descriptor.values.some((value) => scalarValueKind(value) !== kind)) throw new Error("Indexed literal sets cannot mix value types.");
+			return kind;
+		}
+		default: throw new Error(`Values of type '${descriptor.type}' cannot be indexed.`);
+	}
+};
+const encodeScalar = (descriptor, value) => {
+	switch (scalarKind(descriptor)) {
+		case "boolean":
+			if (!Schema.is(Schema.Boolean)(value)) throw new Error("Expected an indexed boolean value.");
+			return [value ? 1 : 0];
+		case "number":
+			if (!Schema.is(Schema.Finite)(value)) throw new Error("Expected an indexed number value.");
+			return encodeNumber(value);
+		case "string":
+			if (!Schema.is(Schema.String)(value)) throw new Error("Expected an indexed string value.");
+			return encodeString(value);
+	}
+};
+const encodeBytes = (bytes) => EncodedIndexKey.make(bytes.map((byte) => byte.toString(16).padStart(2, "0")).join(""));
+const encodeIndexPrefix = (descriptors, values) => {
+	if (descriptors.length !== values.length) throw new Error("Index descriptors and values must have the same length.");
+	const bytes = descriptors.flatMap((descriptor, index) => encodeScalar(descriptor, values[index]));
+	if (bytes.length > schemaIndexLimits.keyBytes) throw new Error(`Index keys cannot exceed ${schemaIndexLimits.keyBytes} bytes.`);
+	return encodeBytes(bytes);
+};
+const encodeIndexKey = (descriptors, values, createdAt, id) => {
+	const bytes = [
+		...descriptors.flatMap((descriptor, index) => encodeScalar(descriptor, values[index])),
+		...encodeNumber(createdAt),
+		...encodeString(id)
+	];
+	if (bytes.length > schemaIndexLimits.keyBytes) throw new Error(`Index keys cannot exceed ${schemaIndexLimits.keyBytes} bytes.`);
+	return encodeBytes(bytes);
+};
+const successorIndexPrefix = (prefix) => {
+	const bytes = Array.from({ length: prefix.length / 2 }, (_, index) => Number.parseInt(prefix.slice(index * 2, index * 2 + 2), 16));
+	for (let index = bytes.length - 1; index >= 0; index -= 1) {
+		const byte = bytes[index];
+		if (byte === void 0 || byte === 255) continue;
+		bytes[index] = byte + 1;
+		return encodeBytes(bytes.slice(0, index + 1));
+	}
+};
+const encodeIndexRange = (descriptors, equal, lower, upper) => {
+	const equalDescriptors = descriptors.slice(0, equal.length);
+	const prefix = encodeIndexPrefix(equalDescriptors, equal);
+	const rangeDescriptor = descriptors[equal.length];
+	if ((lower !== void 0 || upper !== void 0) && rangeDescriptor === void 0) throw new Error("An index range exceeded the index fields.");
+	const encodedLower = lower === void 0 ? prefix.length === 0 ? void 0 : prefix : EncodedIndexKey.make(`${prefix}${encodeIndexPrefix([rangeDescriptor], [lower.value])}`);
+	const encodedUpper = upper === void 0 ? prefix.length === 0 ? void 0 : successorIndexPrefix(prefix) : EncodedIndexKey.make(`${prefix}${encodeIndexPrefix([rangeDescriptor], [upper.value])}`);
+	const finalLower = encodedLower !== void 0 && lower !== void 0 && !lower.inclusive ? successorIndexPrefix(encodedLower) : encodedLower;
+	const finalUpper = encodedUpper !== void 0 && upper !== void 0 && upper.inclusive ? successorIndexPrefix(encodedUpper) : encodedUpper;
+	if (finalLower === void 0 && finalUpper === void 0) return {};
+	if (finalLower === void 0) return { upper: finalUpper };
+	if (finalUpper === void 0) return { lower: finalLower };
+	return {
+		lower: finalLower,
+		upper: finalUpper
+	};
+};
+const indexIdentity = (tableId, name, fields) => IndexIdentity.make(encodeCanonicalJson([
+	tableId,
+	name,
+	fields
+]));
+//#endregion
 //#region ../contracts/dist/runtime/hosted.js
 const QueryKey = Schema.String.pipe(Schema.brand("ignotum/hosted/QueryKey"));
 const TableDependency = Schema.Struct({
@@ -31923,9 +32108,32 @@ const DocumentDependency = Schema.Struct({
 	tableId: TableId,
 	id: GeneratedId
 });
-const DependencyKey = Schema.Union([TableDependency, DocumentDependency]);
-const DependencySet = Schema.Array(DependencyKey);
-const InvalidationSet = Schema.Array(DependencyKey);
+const IndexRangeDependency = Schema.Struct({
+	type: Schema.Literal("IndexRange"),
+	tableId: TableId,
+	index: IndexIdentity,
+	lower: Schema.optional(EncodedIndexKey),
+	upper: Schema.optional(EncodedIndexKey)
+});
+const IndexPointInvalidation = Schema.Struct({
+	type: Schema.Literal("IndexPoint"),
+	tableId: TableId,
+	index: IndexIdentity,
+	key: EncodedIndexKey
+});
+const ReadDependency = Schema.Union([
+	TableDependency,
+	DocumentDependency,
+	IndexRangeDependency
+]);
+const WriteInvalidation = Schema.Union([
+	TableDependency,
+	DocumentDependency,
+	IndexPointInvalidation
+]);
+Schema.Union([ReadDependency, IndexPointInvalidation]);
+const DependencySet = Schema.Array(ReadDependency);
+const InvalidationSet = Schema.Array(WriteInvalidation);
 const RuntimeQueryResult = Schema.Struct({
 	type: Schema.Literal("Query"),
 	result: WireResult,
@@ -31997,10 +32205,19 @@ Schema.Union([
 	RuntimeInvocationRejected,
 	RuntimeInvocationUnavailable
 ]);
-const dependencyKey = (dependency) => dependency.type === "Table" ? encodeCanonicalJson([dependency.type, dependency.tableId]) : encodeCanonicalJson([
+const dependencyKey = (dependency) => dependency.type === "Table" ? encodeCanonicalJson([dependency.type, dependency.tableId]) : dependency.type === "Document" ? encodeCanonicalJson([
 	dependency.type,
 	dependency.tableId,
 	dependency.id
+]) : dependency.type === "IndexPoint" ? encodeCanonicalJson([
+	dependency.type,
+	dependency.index,
+	dependency.key
+]) : encodeCanonicalJson([
+	dependency.type,
+	dependency.index,
+	dependency.lower ?? null,
+	dependency.upper ?? null
 ]);
 const canonicalQueryKey = (deploymentId, functionAddress, args) => QueryKey.make(encodeCanonicalJson([
 	deploymentId,
@@ -32022,6 +32239,19 @@ const documentDependency = (tableId, id) => ({
 	tableId,
 	id
 });
+const indexRangeDependency = (tableId, index, lower, upper) => ({
+	type: "IndexRange",
+	tableId,
+	index,
+	lower,
+	upper
+});
+const indexPointInvalidation = (tableId, index, key) => ({
+	type: "IndexPoint",
+	tableId,
+	index,
+	key
+});
 //#endregion
 //#region ../runtime/dist/functions.js
 var FunctionRuntime = class extends Context.Service()("@ignotum/runtime/functions/FunctionRuntime") {};
@@ -32030,6 +32260,8 @@ var FunctionRuntime = class extends Context.Service()("@ignotum/runtime/function
 const makeDependencyIndex = () => {
 	const dependenciesByQuery = MutableHashMap.empty();
 	const queriesByDependency = MutableHashMap.empty();
+	const rangesByQuery = MutableHashMap.empty();
+	const queriesByIndex = MutableHashMap.empty();
 	const remove = (queryId) => {
 		const dependencies = Option.getOrUndefined(MutableHashMap.get(dependenciesByQuery, queryId));
 		if (dependencies === void 0) return;
@@ -32039,12 +32271,23 @@ const makeDependencyIndex = () => {
 			MutableHashSet.remove(queries, queryId);
 			if (MutableHashSet.size(queries) === 0) MutableHashMap.remove(queriesByDependency, key);
 		}
+		const ranges = Option.getOrElse(MutableHashMap.get(rangesByQuery, queryId), () => []);
+		for (const range of ranges) {
+			const queries = Option.getOrUndefined(MutableHashMap.get(queriesByIndex, range.index));
+			if (queries === void 0) continue;
+			MutableHashSet.remove(queries, queryId);
+			if (MutableHashSet.size(queries) === 0) MutableHashMap.remove(queriesByIndex, range.index);
+		}
+		MutableHashMap.remove(rangesByQuery, queryId);
 		MutableHashMap.remove(dependenciesByQuery, queryId);
 	};
 	const record = (queryId, dependencies) => {
 		remove(queryId);
-		const keys = MutableHashSet.fromIterable(dependencies.map(dependencyKey));
+		const exact = dependencies.filter((dependency) => dependency.type !== "IndexRange");
+		const ranges = dependencies.filter((dependency) => dependency.type === "IndexRange");
+		const keys = MutableHashSet.fromIterable(exact.map(dependencyKey));
 		MutableHashMap.set(dependenciesByQuery, queryId, keys);
+		MutableHashMap.set(rangesByQuery, queryId, ranges);
 		for (const key of keys) {
 			const current = Option.getOrElse(MutableHashMap.get(queriesByDependency, key), () => {
 				const created = MutableHashSet.empty();
@@ -32053,10 +32296,24 @@ const makeDependencyIndex = () => {
 			});
 			MutableHashSet.add(current, queryId);
 		}
+		for (const range of ranges) {
+			const current = Option.getOrElse(MutableHashMap.get(queriesByIndex, range.index), () => {
+				const created = MutableHashSet.empty();
+				MutableHashMap.set(queriesByIndex, range.index, created);
+				return created;
+			});
+			MutableHashSet.add(current, queryId);
+		}
 	};
 	const affected = (invalidations) => {
 		const queries = MutableHashSet.empty();
 		for (const invalidation of invalidations) {
+			if (invalidation.type === "IndexPoint") {
+				const indexed = Option.getOrUndefined(MutableHashMap.get(queriesByIndex, invalidation.index));
+				if (indexed === void 0) continue;
+				for (const queryId of indexed) if (Option.getOrElse(MutableHashMap.get(rangesByQuery, queryId), () => []).some((range) => range.index === invalidation.index && (range.lower === void 0 || invalidation.key >= range.lower) && (range.upper === void 0 || invalidation.key < range.upper))) MutableHashSet.add(queries, queryId);
+				continue;
+			}
 			const current = Option.getOrUndefined(MutableHashMap.get(queriesByDependency, dependencyKey(invalidation)));
 			if (current !== void 0) for (const queryId of current) MutableHashSet.add(queries, queryId);
 		}
@@ -32073,8 +32330,15 @@ var QueryInvalidation = class extends Context.Service()("@ignotum/runtime/sync/Q
 //#region ../contracts/dist/runtime/transport.js
 const runtimeInvocationPath = "/v1/invoke";
 const runtimeRevisionPath = "/v1/revision";
+const runtimeIndexPreparePath = "/v1/indexes/prepare";
+const runtimeIndexCommitPath = "/v1/indexes/commit";
 const appSyncPath = `/_ignotum/v1/sync`;
-const RuntimeRequestPath = Schema.Literals([runtimeInvocationPath, runtimeRevisionPath]);
+const RuntimeRequestPath = Schema.Literals([
+	runtimeInvocationPath,
+	runtimeRevisionPath,
+	runtimeIndexPreparePath,
+	runtimeIndexCommitPath
+]);
 const RuntimeRequestTimestamp = Schema.FiniteFromString.pipe(Schema.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0)), Schema.brand("ignotum/runtime/RequestTimestamp"));
 const RuntimeRequestSignature = Sha256.pipe(Schema.brand("ignotum/runtime/RequestSignature"));
 Schema.Struct({
@@ -32093,6 +32357,11 @@ Schema.Struct({
 	deploymentId: Schema.optional(DeploymentId),
 	bodySha256: Sha256
 });
+Schema.Struct({
+	appId: AppId,
+	deploymentId: DeploymentId
+});
+Schema.Struct({ completed: Schema.Literal(true) });
 const RuntimeErrorCode = Schema.Literals([
 	"InvalidRequest",
 	"InvalidSignature",
@@ -32153,7 +32422,38 @@ const initialDevelopmentSchema = Effect.gen(function* () {
     ) STRICT
   `;
 });
-const developmentMigrationLoader = Migrator.fromRecord({ "0001_initial_development_schema": initialDevelopmentSchema });
+const addDevelopmentIndexes = Effect.gen(function* () {
+	const sql = yield* Client.SqlClient;
+	yield* sql`
+    CREATE TABLE indexes (
+      id INTEGER PRIMARY KEY NOT NULL,
+      tableId TEXT NOT NULL REFERENCES tables(id) ON DELETE CASCADE,
+      identity TEXT NOT NULL UNIQUE,
+      name TEXT NOT NULL,
+      fields TEXT NOT NULL CHECK (json_valid(fields))
+    ) STRICT
+  `;
+	yield* sql`
+    CREATE TABLE indexEntries (
+      indexId INTEGER NOT NULL REFERENCES indexes(id) ON DELETE CASCADE,
+      tableId TEXT NOT NULL,
+      documentId TEXT NOT NULL,
+      key TEXT NOT NULL,
+      PRIMARY KEY (indexId, documentId),
+      FOREIGN KEY (tableId, documentId)
+        REFERENCES documents(tableId, id)
+        ON DELETE CASCADE
+    ) STRICT
+  `;
+	yield* sql`
+    CREATE UNIQUE INDEX index_entries_by_key
+    ON indexEntries (indexId, key)
+  `;
+});
+const developmentMigrationLoader = Migrator.fromRecord({
+	"0001_initial_development_schema": initialDevelopmentSchema,
+	"0002_application_indexes": addDevelopmentIndexes
+});
 var DevelopmentDatabase = class DevelopmentDatabase extends Context.Service()("ignotum/dev-runtime/migrations/DevelopmentDatabase") {
 	static layer = Layer.effect(DevelopmentDatabase, Migrator.make({})({
 		loader: developmentMigrationLoader,
@@ -32168,6 +32468,16 @@ const StoredDocument = Schema.Struct({
 	updatedAt: Schema.Int,
 	fields: Schema.String
 });
+const IndexedStoredDocument = Schema.Struct({
+	...StoredDocument.fields,
+	key: Schema.String
+});
+const StoredIndex = Schema.Struct({
+	id: Schema.Natural,
+	identity: Schema.String,
+	name: Schema.String,
+	fields: Schema.String
+});
 const StoredTable = Schema.Struct({
 	id: TableId,
 	name: Schema.String
@@ -32240,6 +32550,18 @@ const toRuntimeDocument = Effect.fn("LocalDatabase.toRuntimeDocument")(function*
 	};
 });
 const nextUpdatedAt = (now, previous) => Math.max(DateTime.toEpochMillis(now), previous + 1);
+const decodeIndexScalar = Schema.decodeUnknownSync(IndexScalarValue);
+const indexDescriptors = (table, fields) => fields.map((field) => {
+	const schema = table.fields[field];
+	const descriptor = schema === void 0 ? void 0 : getValueDescriptor(schema);
+	if (descriptor === void 0) throw new Error(`Index field '${field}' has no descriptor.`);
+	return descriptor;
+});
+const storedIndexKey = (index, row) => {
+	const fields = Schema.decodeSync(Schema.fromJsonString(Schema.JsonObject))(row.fields);
+	const values = index.definition.fields.map((field) => decodeIndexScalar(fields[field]));
+	return encodeIndexKey(index.descriptors, values, row.createdAt, row.id);
+};
 var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-runtime/database/LocalDatabase") {
 	static layer = Layer.effect(LocalDatabase, Effect.gen(function* () {
 		const ids = yield* IdGenerator;
@@ -32283,6 +32605,31 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
           FROM documents
           WHERE tableId = ${tableId}
           ORDER BY createdAt ASC, id ASC
+        `
+		});
+		const listIndexes = SqlSchema.findAll({
+			Request: TableLookup,
+			Result: StoredIndex,
+			execute: ({ tableId }) => sql`
+          SELECT id, identity, name, fields
+          FROM indexes
+          WHERE tableId = ${tableId}
+          ORDER BY id ASC
+        `
+		});
+		const insertIndex = SqlSchema.findOne({
+			Request: Schema.Struct({
+				tableId: TableId,
+				identity: Schema.String,
+				name: Schema.String,
+				fields: Schema.String
+			}),
+			Result: StoredIndex,
+			execute: ({ tableId, identity, name, fields }) => sql`
+          INSERT INTO indexes (tableId, identity, name, fields)
+          VALUES (${tableId}, ${identity}, ${name}, ${fields})
+          ON CONFLICT (identity) DO UPDATE SET identity = excluded.identity
+          RETURNING id, identity, name, fields
         `
 		});
 		const currentRevision = SqlSchema.findOne({
@@ -32316,6 +32663,64 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
 				definition
 			};
 		});
+		const resolvedIndexes = Effect.fn("LocalDatabase.resolvedIndexes")(function* (table) {
+			const stored = yield* listIndexes({ tableId: table.id });
+			return Object.values(table.definition.indexes).map((definition) => {
+				const identity = indexIdentity(table.id, definition.name, definition.fields);
+				const row = stored.find((candidate) => candidate.identity === identity);
+				if (row === void 0) throw new Error(`Index '${definition.name}' is not prepared.`);
+				return {
+					...row,
+					definition,
+					descriptors: indexDescriptors(table.definition, definition.fields)
+				};
+			});
+		});
+		const prepareIndexes = Effect.fn("LocalDatabase.prepareIndexes")(function* (schema) {
+			for (const [tableName, definition] of Object.entries(schema[SchemaDefinitionTypeId])) {
+				const table = yield* resolveTable(schema, tableName);
+				const stored = yield* listIndexes({ tableId: table.id });
+				const expected = /* @__PURE__ */ new Set();
+				for (const index of Object.values(definition.indexes)) {
+					const identity = indexIdentity(table.id, index.name, index.fields);
+					expected.add(identity);
+					if (stored.some((candidate) => candidate.identity === identity)) continue;
+					const fields = JSON.stringify(index.fields);
+					const resolved = {
+						...yield* insertIndex({
+							tableId: table.id,
+							identity,
+							name: index.name,
+							fields
+						}).pipe(Effect.catchTags({ NoSuchElementError: Effect.die })),
+						definition: index,
+						descriptors: indexDescriptors(definition, index.fields)
+					};
+					const documents = yield* collectStored({ tableId: table.id });
+					yield* Effect.forEach(documents, (document) => sql`
+                INSERT INTO indexEntries (indexId, tableId, documentId, key)
+                VALUES (${resolved.id}, ${table.id}, ${document.id}, ${storedIndexKey(resolved, document)})
+              `);
+				}
+				yield* Effect.forEach(stored.filter((index) => !expected.has(index.identity)), (index) => sql`DELETE FROM indexes WHERE id = ${index.id}`);
+			}
+		});
+		const indexKeys = Effect.fn("LocalDatabase.indexKeys")(function* (table, row) {
+			return (yield* resolvedIndexes(table)).map((index) => ({
+				index,
+				key: storedIndexKey(index, row),
+				identity: indexIdentity(table.id, index.name, index.definition.fields)
+			}));
+		});
+		const writeIndexEntries = Effect.fn("LocalDatabase.writeIndexEntries")(function* (table, row) {
+			const keys = yield* indexKeys(table, row);
+			yield* Effect.forEach(keys, ({ index, key }) => sql`
+            INSERT INTO indexEntries (indexId, tableId, documentId, key)
+            VALUES (${index.id}, ${table.id}, ${row.id}, ${key})
+            ON CONFLICT (indexId, documentId) DO UPDATE SET key = excluded.key
+          `);
+			return keys;
+		});
 		const find = Effect.fn("LocalDatabase.find")(function* (schema, tableName, id, dependencies) {
 			const table = yield* resolveTable(schema, tableName);
 			const documentId = GeneratedId.make(id);
@@ -32327,11 +32732,100 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
 			if (Option.isNone(row)) return void 0;
 			return yield* toRuntimeDocument(table.definition, tableName, row.value, "get");
 		});
-		const collect = Effect.fn("LocalDatabase.collect")(function* (schema, tableName, dependencies) {
+		const queryDocuments = Effect.fn("LocalDatabase.queryDocuments")(function* (schema, tableName, selectedIndex, bounds, order, limit, pagination, dependencies) {
 			const table = yield* resolveTable(schema, tableName);
-			dependencies?.record(tableDependency(table.id));
-			const rows = yield* collectStored({ tableId: table.id });
-			return yield* Effect.forEach(rows, (row) => toRuntimeDocument(table.definition, tableName, row, "collect"));
+			if (selectedIndex === void 0) {
+				dependencies?.record(tableDependency(table.id));
+				const queryIdentity = paginationQueryIdentity(table.id, null, void 0, void 0, order);
+				const decodedCursor = pagination?.cursor === null || pagination === void 0 ? void 0 : decodePaginationCursor(pagination.cursor);
+				if (decodedCursor !== void 0 && decodedCursor.query !== queryIdentity) throw new Error("A pagination cursor belongs to another query.");
+				const cursor = decodedCursor?.position;
+				if (cursor !== void 0 && cursor.type !== "Table") throw new Error("A pagination cursor has the wrong position type.");
+				const clauses = ["tableId = ?"];
+				const parameters = [table.id];
+				if (cursor !== void 0) {
+					const operator = order === "Asc" ? ">" : "<";
+					clauses.push(`(createdAt ${operator} ? OR (createdAt = ? AND id ${operator} ?))`);
+					parameters.push(cursor.createdAt, cursor.createdAt, cursor.id);
+				}
+				const storageLimit = pagination === void 0 ? limit : pagination.pageSize + 1;
+				if (storageLimit !== void 0) parameters.push(storageLimit);
+				const rows = yield* sql.unsafe(`SELECT id, createdAt, updatedAt, fields
+             FROM documents
+             WHERE ${clauses.join(" AND ")}
+             ORDER BY createdAt ${order === "Asc" ? "ASC" : "DESC"}, id ${order === "Asc" ? "ASC" : "DESC"}${storageLimit === void 0 ? "" : " LIMIT ?"}`, parameters);
+				const decoded = yield* Schema.decodeUnknownEffect(Schema.Array(StoredDocument))(rows);
+				const hasMore = pagination !== void 0 && decoded.length > pagination.pageSize;
+				const pageRows = pagination === void 0 ? decoded : decoded.slice(0, pagination.pageSize);
+				const documents = yield* Effect.forEach(pageRows, (row) => toRuntimeDocument(table.definition, tableName, row, "collect"));
+				const last = pageRows.at(-1);
+				return {
+					documents,
+					nextCursor: !hasMore || last === void 0 ? null : encodePaginationCursor(queryIdentity, {
+						type: "Table",
+						createdAt: last.createdAt,
+						id: last.id
+					})
+				};
+			}
+			const index = (yield* resolvedIndexes(table)).find((candidate) => candidate.name === selectedIndex);
+			if (index === void 0) throw new Error(`Unknown index '${selectedIndex}'.`);
+			const identity = indexIdentity(table.id, index.name, index.definition.fields);
+			const queryIdentity = paginationQueryIdentity(table.id, identity, bounds.lower, bounds.upper, order);
+			const decodedCursor = pagination?.cursor === null || pagination === void 0 ? void 0 : decodePaginationCursor(pagination.cursor);
+			if (decodedCursor !== void 0 && decodedCursor.query !== queryIdentity) throw new Error("A pagination cursor belongs to another query.");
+			const cursor = decodedCursor?.position;
+			if (cursor !== void 0 && cursor.type !== "Index") throw new Error("A pagination cursor has the wrong position type.");
+			const cursorLower = cursor !== void 0 && order === "Asc" ? successorIndexPrefix(cursor.key) : void 0;
+			const cursorUpper = cursor !== void 0 && order === "Desc" ? cursor.key : void 0;
+			const effectiveBounds = {
+				lower: bounds.lower === void 0 ? cursorLower : cursorLower === void 0 || bounds.lower > cursorLower ? bounds.lower : cursorLower,
+				upper: bounds.upper === void 0 ? cursorUpper : cursorUpper === void 0 || bounds.upper < cursorUpper ? bounds.upper : cursorUpper
+			};
+			const clauses = ["entries.indexId = ?"];
+			const parameters = [index.id];
+			if (effectiveBounds.lower !== void 0) {
+				clauses.push("entries.key >= ?");
+				parameters.push(effectiveBounds.lower);
+			}
+			if (effectiveBounds.upper !== void 0) {
+				clauses.push("entries.key < ?");
+				parameters.push(effectiveBounds.upper);
+			}
+			const storageLimit = pagination === void 0 ? limit : pagination.pageSize + 1;
+			if (storageLimit !== void 0) parameters.push(storageLimit);
+			const rows = yield* sql.unsafe(`SELECT documents.id, documents.createdAt, documents.updatedAt, documents.fields,
+                  entries.key
+           FROM indexEntries AS entries
+           JOIN documents
+             ON documents.tableId = entries.tableId
+            AND documents.id = entries.documentId
+           WHERE ${clauses.join(" AND ")}
+           ORDER BY entries.key ${order === "Asc" ? "ASC" : "DESC"}${storageLimit === void 0 ? "" : " LIMIT ?"}`, parameters);
+			const decoded = yield* Schema.decodeUnknownEffect(Schema.Array(IndexedStoredDocument))(rows);
+			const hasMore = pagination !== void 0 && decoded.length > pagination.pageSize;
+			const pageRows = pagination === void 0 ? decoded : decoded.slice(0, pagination.pageSize);
+			let dependencyBounds = effectiveBounds;
+			if (pagination === void 0 ? limit !== void 0 && limit > 0 && decoded.length === limit : hasMore) {
+				const last = pageRows.at(-1);
+				if (last !== void 0) dependencyBounds = order === "Asc" ? {
+					...effectiveBounds,
+					upper: successorIndexPrefix(EncodedIndexKey.make(last.key))
+				} : {
+					...effectiveBounds,
+					lower: EncodedIndexKey.make(last.key)
+				};
+			}
+			dependencies?.record(indexRangeDependency(table.id, identity, dependencyBounds.lower, dependencyBounds.upper));
+			const documents = yield* Effect.forEach(pageRows, (row) => toRuntimeDocument(table.definition, tableName, row, "collect"));
+			const last = pageRows.at(-1);
+			return {
+				documents,
+				nextCursor: !hasMore || last === void 0 ? null : encodePaginationCursor(queryIdentity, {
+					type: "Index",
+					key: EncodedIndexKey.make(last.key)
+				})
+			};
 		});
 		const insert = Effect.fn("LocalDatabase.insert")(function* (schema, tableName, value, invalidations) {
 			const table = yield* resolveTable(schema, tableName);
@@ -32342,14 +32836,25 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
           INSERT INTO documents (id, tableId, createdAt, updatedAt, fields)
           VALUES (${id}, ${table.id}, ${now}, ${now}, ${fields})
         `;
-			invalidations.record(tableDependency(table.id), documentDependency(table.id, id));
+			const keys = yield* writeIndexEntries(table, {
+				id,
+				createdAt: now,
+				updatedAt: now,
+				fields
+			});
+			invalidations.record(tableDependency(table.id), documentDependency(table.id, id), ...keys.map(({ identity, key }) => indexPointInvalidation(table.id, identity, key)));
 			return id;
 		});
 		const deleteDocument = Effect.fn("LocalDatabase.delete")(function* (schema, tableName, id, invalidations) {
 			const table = yield* resolveTable(schema, tableName);
 			const documentId = GeneratedId.make(id);
+			const stored = yield* findStored({
+				id,
+				tableId: table.id
+			});
+			const keys = Option.isSome(stored) ? yield* indexKeys(table, stored.value) : [];
 			yield* sql`DELETE FROM documents WHERE id = ${id} AND tableId = ${table.id}`;
-			invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId));
+			invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId), ...keys.map(({ identity, key }) => indexPointInvalidation(table.id, identity, key)));
 		});
 		const patch = Effect.fn("LocalDatabase.patch")(function* (schema, tableName, id, value, invalidations) {
 			const table = yield* resolveTable(schema, tableName);
@@ -32358,6 +32863,8 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
 				id,
 				tableId: table.id
 			});
+			const oldKeys = Option.isSome(stored) ? yield* indexKeys(table, stored.value) : [];
+			let newKeys = oldKeys.slice(0, 0);
 			if (Option.isSome(stored)) {
 				const current = yield* decodeFields(table.definition, tableName, stored.value, "patch");
 				const fields = yield* encodeFields(table.definition, tableName, {
@@ -32370,8 +32877,13 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
             SET fields = ${fields}, updatedAt = ${updatedAt}
             WHERE id = ${id} AND tableId = ${table.id}
           `;
+				newKeys = yield* writeIndexEntries(table, {
+					...stored.value,
+					fields,
+					updatedAt
+				});
 			}
-			invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId));
+			invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId), ...[...oldKeys, ...newKeys].map(({ identity, key }) => indexPointInvalidation(table.id, identity, key)));
 		});
 		const replace = Effect.fn("LocalDatabase.replace")(function* (schema, tableName, id, value, invalidations) {
 			const table = yield* resolveTable(schema, tableName);
@@ -32380,6 +32892,8 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
 				id,
 				tableId: table.id
 			});
+			const oldKeys = Option.isSome(stored) ? yield* indexKeys(table, stored.value) : [];
+			let newKeys = oldKeys.slice(0, 0);
 			if (Option.isSome(stored)) {
 				const fields = yield* encodeFields(table.definition, tableName, value, "replace", id);
 				const updatedAt = nextUpdatedAt(yield* DateTime.now, stored.value.updatedAt);
@@ -32388,14 +32902,121 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
             SET fields = ${fields}, updatedAt = ${updatedAt}
             WHERE id = ${id} AND tableId = ${table.id}
           `;
+				newKeys = yield* writeIndexEntries(table, {
+					...stored.value,
+					fields,
+					updatedAt
+				});
 			}
-			invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId));
-		});
-		const makeReader = (schema, dependencies) => Object.freeze({
-			find: (tableName, id) => resultFromEffect(find(schema, tableName, id, dependencies).pipe(Effect.orDie)),
-			get: (tableName, id) => resultFromEffect(find(schema, tableName, id, dependencies).pipe(Effect.orDie, Effect.flatMap((document) => document === void 0 ? Effect.fail(documentNotFound(tableName, id)) : Effect.succeed(document)))),
-			query: (tableName) => Object.freeze({ collect: () => resultFromEffect(collect(schema, tableName, dependencies).pipe(Effect.orDie)) })
+			invalidations.record(tableDependency(table.id), documentDependency(table.id, documentId), ...[...oldKeys, ...newKeys].map(({ identity, key }) => indexPointInvalidation(table.id, identity, key)));
 		});
+		const makeReader = (schema, dependencies) => {
+			const databaseQuery = (tableName, selectedIndex, selectedBounds = {}, order = "Asc") => {
+				const table = schema[SchemaDefinitionTypeId][tableName];
+				if (table === void 0) throw new Error(`Unknown database table '${tableName}'.`);
+				const run = (limit) => queryDocuments(schema, tableName, selectedIndex, selectedBounds, order, limit, void 0, dependencies).pipe(Effect.map(({ documents }) => documents), Effect.orDie);
+				const runPage = (pagination) => queryDocuments(schema, tableName, selectedIndex, selectedBounds, order, void 0, pagination, dependencies).pipe(Effect.orDie);
+				const validateLimit = (count) => {
+					if (!Number.isInteger(count) || count < 0 || count > 1e3) throw new Error("Query limits must be integers between 0 and 1000.");
+					return count;
+				};
+				return Object.freeze({
+					index: (name, buildRange) => {
+						if (selectedIndex !== void 0) throw new Error("A query can select only one index.");
+						const definition = table.indexes[name];
+						if (definition === void 0) throw new Error(`Unknown index '${name}' on table '${tableName}'.`);
+						if (buildRange === void 0) return databaseQuery(tableName, name, {}, order);
+						const fields = [
+							...definition.fields,
+							"createdAt",
+							"id"
+						];
+						const descriptors = [
+							...indexDescriptors(table, definition.fields),
+							{ type: "date" },
+							{
+								type: "id",
+								table: tableName
+							}
+						];
+						const equal = [];
+						let lower;
+						let upper;
+						let position = 0;
+						const encodeValue = (field, value) => {
+							const codec = field === "createdAt" ? Schema.DateFromMillis : field === "id" ? GeneratedId : table.fields[field];
+							if (codec === void 0) throw new Error(`Unknown index field '${field}'.`);
+							return decodeIndexScalar(Schema.encodeUnknownSync(codec)(value));
+						};
+						const expectField = (field) => {
+							const expected = fields[position];
+							if (field !== expected) throw new Error(`Expected index field '${expected}', received '${field}'.`);
+						};
+						const builder = {
+							eq: (field, value) => {
+								if (lower !== void 0 || upper !== void 0) throw new Error("Equality cannot follow an index bound.");
+								expectField(field);
+								equal.push(encodeValue(field, value));
+								position += 1;
+								return builder;
+							},
+							gt: (field, value) => {
+								expectField(field);
+								if (lower !== void 0) throw new Error("An index range has one lower bound.");
+								lower = {
+									value: encodeValue(field, value),
+									inclusive: false
+								};
+								return builder;
+							},
+							gte: (field, value) => {
+								expectField(field);
+								if (lower !== void 0) throw new Error("An index range has one lower bound.");
+								lower = {
+									value: encodeValue(field, value),
+									inclusive: true
+								};
+								return builder;
+							},
+							lt: (field, value) => {
+								expectField(field);
+								if (upper !== void 0) throw new Error("An index range has one upper bound.");
+								upper = {
+									value: encodeValue(field, value),
+									inclusive: false
+								};
+								return builder;
+							},
+							lte: (field, value) => {
+								expectField(field);
+								if (upper !== void 0) throw new Error("An index range has one upper bound.");
+								upper = {
+									value: encodeValue(field, value),
+									inclusive: true
+								};
+								return builder;
+							}
+						};
+						buildRange(builder);
+						return databaseQuery(tableName, name, encodeIndexRange(descriptors, equal, lower, upper), order);
+					},
+					order: (direction) => databaseQuery(tableName, selectedIndex, selectedBounds, direction === "asc" ? "Asc" : "Desc"),
+					collect: () => resultFromEffect(run()),
+					take: (count) => resultFromEffect(run(validateLimit(count))),
+					first: () => resultFromEffect(run(1).pipe(Effect.map((documents) => documents[0]))),
+					unique: () => resultFromEffect(run(2).pipe(Effect.flatMap((documents) => documents.length > 1 ? Effect.die(/* @__PURE__ */ new Error("A unique query matched more than one document.")) : Effect.succeed(documents[0])))),
+					paginate: (options) => resultFromEffect(runPage(options).pipe(Effect.map(({ documents, nextCursor }) => ({
+						items: documents,
+						nextCursor
+					}))))
+				});
+			};
+			return Object.freeze({
+				find: (tableName, id) => resultFromEffect(find(schema, tableName, id, dependencies).pipe(Effect.orDie)),
+				get: (tableName, id) => resultFromEffect(find(schema, tableName, id, dependencies).pipe(Effect.orDie, Effect.flatMap((document) => document === void 0 ? Effect.fail(documentNotFound(tableName, id)) : Effect.succeed(document)))),
+				query: (tableName) => databaseQuery(tableName)
+			});
+		};
 		const makeWriter = (schema, invalidations) => {
 			const reader = makeReader(schema);
 			return Object.freeze({
@@ -32407,6 +33028,7 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
 			});
 		};
 		const trackedQueryTransaction = (schema, use) => sql.withTransaction(Effect.gen(function* () {
+			yield* prepareIndexes(schema).pipe(Effect.orDie);
 			const dependencies = makeDependencyRecorder();
 			const value = yield* use(Object.freeze({ db: makeReader(schema, dependencies) }));
 			const { revision: observedRevision } = yield* currentRevision(void 0).pipe(Effect.orDie);
@@ -32417,6 +33039,7 @@ var LocalDatabase = class LocalDatabase extends Context.Service()("ignotum/dev-r
 			};
 		}));
 		const trackedMutationTransaction = (schema, use) => sql.withTransaction(Effect.gen(function* () {
+			yield* prepareIndexes(schema).pipe(Effect.orDie);
 			const invalidations = makeDependencyRecorder();
 			const value = yield* use(Object.freeze({ db: makeWriter(schema, invalidations) }));
 			const { revision: committedRevision } = yield* advanceRevision(void 0).pipe(Effect.orDie);
@@ -32997,20 +33620,22 @@ const agentAppFiles = [
 		path: "AGENTS.md"
 	},
 	{
-		content: "---\nname: ignotum\ndescription: Build and modify an Ignotum app. Use when working on its schema, server functions, generated API, client UI, or local development workflow.\n---\n\n# Working on an Ignotum app\n\nAn Ignotum app defines a database schema, server functions, and a JSX client. Ignotum supplies the\ndatabase runtime, generated bindings, realtime query updates, Vite dev server, JSX runtime, and\nTailwind setup.\n\nThe current release supports local development. Do not assume that authentication, files, actions,\nworkflows, scheduled jobs, or production deployment APIs exist.\n\n## Start with the app\n\nInspect `server/schema.ts`, the function modules in `server`, the files in `client`, `package.json`,\nand `tsconfig.json` before changing code.\n\nThe required `client/index.tsx` default-exports `app({ title, component })` from `ignotum/client`.\nKeep the title as a non-empty quoted string. An optional `client/icon.svg` is discovered as the app\nfavicon. Do not add another metadata file or import Ignotum's Tailwind stylesheet.\n\nTreat `_generated` as compiler output. Read it when you need to understand an inferred type, but do\nnot edit it. After code changes, regenerate the bindings and run the typechecker:\n\n```sh\nnpx ignotum codegen\nnpx tsc --noEmit\n```\n\nFor normal Ignotum app work, do not add an HTML file, Vite configuration, Tailwind configuration,\nAPI routes, or direct database setup.\n\n## Read the relevant reference\n\nThe bundled references are the Ignotum user guides. Read only the guides needed for the task:\n\n- For app creation and installation, read [getting started](references/getting-started.md) or\n  [manual setup](references/manual-setup.md).\n- For tables, fields, IDs, and generated document types, read\n  [schema syntax](references/schema.md).\n- For validators and their TypeScript types, read [values](references/values.md).\n- For queries, mutations, database access, Results, and application errors, read\n  [server functions](references/server-functions.md).\n- For hooks, query state, mutations, JSX, and Tailwind, read [client](references/client.md).\n- For development commands, code generation, flags, and local data, read\n  [dev server](references/dev-server.md).\n- For the complete guide list, read the [documentation index](references/index.md).\n\n## Rules that cross guide boundaries\n\n- Define tables in `server/schema.ts`.\n- Put queries and mutations in TypeScript files directly inside `server`.\n- Import server builders from `@/_generated/server.js` and client references from\n  `@/_generated/api.js`. Keep the `.js` suffix.\n- Put code used by both the client and server in `shared` and import it through `@/shared`.\n- Never edit `_generated`.\n- Use JSX and hooks from `ignotum/client`, not React or Preact packages directly.\n- Keep the app inside Ignotum's current model unless the user explicitly asks to move beyond it.\n",
+		content: "---\nname: ignotum\ndescription: Build and modify an Ignotum app. Use when working on its schema, server functions, generated API, client UI, or local development workflow.\n---\n\n# Working on an Ignotum app\n\nAn Ignotum app defines a database schema, server functions, and a JSX client. Ignotum supplies the\ndatabase runtime, generated bindings, realtime query updates, Vite dev server, JSX runtime, and\nTailwind setup.\n\nThe current release supports local development. Do not assume that authentication, files, actions,\nworkflows, scheduled jobs, or production deployment APIs exist.\n\n## Start with the app\n\nInspect `server/schema.ts`, the function modules in `server`, the files in `client`, `package.json`,\nand `tsconfig.json` before changing code.\n\nThe required `client/index.tsx` default-exports `app({ title, component })` from `ignotum/client`.\nKeep the title as a non-empty quoted string. An optional `client/icon.svg` is discovered as the app\nfavicon. Do not add another metadata file or import Ignotum's Tailwind stylesheet.\n\nTreat `_generated` as compiler output. Read it when you need to understand an inferred type, but do\nnot edit it. After code changes, regenerate the bindings and run the typechecker:\n\n```sh\nnpx ignotum codegen\nnpx tsc --noEmit\n```\n\nFor normal Ignotum app work, do not add an HTML file, Vite configuration, Tailwind configuration,\nAPI routes, or direct database setup.\n\n## Read the relevant reference\n\nThe bundled references are the Ignotum user guides. Read only the guides needed for the task:\n\n- For app creation and installation, read [getting started](references/getting-started.md) or\n  [manual setup](references/manual-setup.md).\n- For tables, fields, indexes, IDs, and generated document types, read\n  [schema syntax](references/schema.md).\n- For validators and their TypeScript types, read [values](references/values.md).\n- For queries, mutations, Results, and application errors, read\n  [server functions](references/server-functions.md).\n- For document reads, indexes, ranges, ordering, pagination, and result methods, read\n  [database reads](references/reading-data.md).\n- For inserts, patches, replacements, deletes, and transaction behavior, read\n  [database writes](references/writing-data.md).\n- For hooks, query state, paginated lists, mutations, JSX, and Tailwind, read\n  [client](references/client.md).\n- For development commands, code generation, flags, and local data, read\n  [dev server](references/dev-server.md).\n- For the complete guide list, read the [documentation index](references/index.md).\n\n## Rules that cross guide boundaries\n\n- Define tables in `server/schema.ts`.\n- Put queries and mutations in TypeScript files directly inside `server`.\n- Import server builders from `@/_generated/server.js` and client references from\n  `@/_generated/api.js`. Keep the `.js` suffix.\n- Put code used by both the client and server in `shared` and import it through `@/shared`.\n- Never edit `_generated`.\n- Use JSX and hooks from `ignotum/client`, not React or Preact packages directly.\n- Keep the app inside Ignotum's current model unless the user explicitly asks to move beyond it.\n",
 		path: ".agents/skills/ignotum/SKILL.md"
 	},
 	...[
-		["client.md", "# Client\n\nIgnotum apps use JSX, hooks from `ignotum/client`, and Tailwind CSS. The required\n`client/index.tsx` file defines the browser title and root component:\n\n```tsx\nimport { app, Query, Result, useMutation, useQuery } from \"ignotum/client\";\n\nimport { api } from \"@/_generated/api.js\";\n\nfunction App() {\n  return <main>My App</main>;\n}\n\nexport default app({\n  title: \"My App\",\n  component: App,\n});\n```\n\nThe title must be a non-empty quoted string in the `app(...)` definition so Ignotum can include it\nin the first HTML response.\n\n## Tailwind CSS\n\nIgnotum loads Tailwind CSS automatically. App code does not need to import a framework stylesheet.\n\nStyle JSX with Tailwind utility classes. Use the JSX `class` attribute:\n\n```tsx\nfunction App() {\n  return (\n    <main class=\"mx-auto max-w-xl px-6 py-16\">\n      <h1 class=\"text-2xl font-semibold text-zinc-950\">Todos</h1>\n    </main>\n  );\n}\n```\n\nThe app does not need a Tailwind configuration file. Custom CSS files are ordinary client modules:\ngive them any filename and import them from app code when needed.\n\n## Public files\n\nPut files that need their own URL in a top-level `public` directory next to `client` and `server`.\nThe directory structure becomes the URL structure. For example, `public/documents/manual.pdf` is\navailable at `/documents/manual.pdf` after deployment.\n\nPublic files are limited to AVIF, GIF, ICO, JPEG, PNG, WebP, and PDF. Ignotum checks that a file's\ncontents match its extension and rejects symbolic links, executable or code formats, and paths\nunder the reserved `_ignotum` name. Use `client/icon.svg` for the app favicon; arbitrary SVG files\nare not accepted in `public`. Put the directory at the app root—`client/public` is rejected.\n\n## Run a query\n\n`useQuery` takes a generated query reference. Pass the typed arguments when the query declares\nthem:\n\n```tsx\nconst todos = useQuery(api.todos.list);\nconst todo = useQuery(api.todos.get, { id });\nconst selectedTodo = useQuery(api.todos.get, id === undefined ? Query.skip : { id });\n```\n\n`Query.skip` keeps a query pending without opening a subscription. Use it when the arguments are\nnot available yet.\n\nThe first value is pending. Match every state with `Result.match`:\n\n```tsx\nreturn Result.match(todos, {\n  pending: () => <p class=\"text-zinc-500\">Loading...</p>,\n  value: (items) => (\n    <ul>\n      {items.map((todo) => (\n        <li key={todo.id}>{todo.text}</li>\n      ))}\n    </ul>\n  ),\n});\n```\n\nIgnotum keeps an active query up to date. A successful mutation refreshes affected subscribed\nqueries in every open client. Queries that did not read the changed documents or tables do not run\nagain.\n\n## Run a mutation\n\n`useMutation` takes a generated mutation reference and returns a function:\n\n```tsx\nconst createTodo = useMutation(api.todos.create);\n\nvoid createTodo({ text }).then(\n  Result.match({\n    value: (id) => console.log(id),\n    error: {\n      InvalidTodoText: ({ text }) => console.log(`Invalid text: ${text}`),\n      TodoLimitReached: ({ limit }) => console.log(`The limit is ${limit}`),\n    },\n    internalError: ({ requestId }) => console.log(`Request ${requestId} failed.`),\n  }),\n);\n```\n\nAn argument-free mutation returns a zero-argument function:\n\n```tsx\nconst clearTodos = useMutation(api.todos.clear);\nvoid clearTodos();\n```\n\nThe client `Result` API only inspects completed server responses. Server-only operations such as\n`Result.fail`, `Result.succeed`, `Result.try`, `yield*`, and `.catch()` are not available here.\n\nApplication errors are handled by `error`, either with one function or an exhaustive map keyed by\n`_tag`. An `InternalServerError` contains a request ID and is thrown when `Result.match` has no\n`internalError` handler. During rendering, it reaches the nearest UI error boundary. A mutation can\nhandle it locally with `internalError`, as above. Operation-scoped protocol failures reject mutation\npromises or reach the nearest query UI error boundary. Ignotum retries transient connection failures,\nkeeps the latest query state, and replays pending mutations after the next connection handshake.\n\nHosted apps limit connections, subscriptions, active unique queries, and mutation traffic. See\n[Limits](limits.md) for the current values and retry retention.\n"],
+		["client.md", "# Client\n\nIgnotum apps use JSX, hooks from `ignotum/client`, and Tailwind CSS. The required\n`client/index.tsx` file defines the browser title and root component:\n\n```tsx\nimport { app, Query, Result, useMutation, usePaginatedQuery, useQuery } from \"ignotum/client\";\n\nimport { api } from \"@/_generated/api.js\";\n\nfunction App() {\n  return <main>My App</main>;\n}\n\nexport default app({\n  title: \"My App\",\n  component: App,\n});\n```\n\nThe title must be a non-empty quoted string in the `app(...)` definition so Ignotum can include it\nin the first HTML response.\n\n## Tailwind CSS\n\nIgnotum loads Tailwind CSS automatically. App code does not need to import a framework stylesheet.\n\nStyle JSX with Tailwind utility classes. Use the JSX `class` attribute:\n\n```tsx\nfunction App() {\n  return (\n    <main class=\"mx-auto max-w-xl px-6 py-16\">\n      <h1 class=\"text-2xl font-semibold text-zinc-950\">Todos</h1>\n    </main>\n  );\n}\n```\n\nThe app does not need a Tailwind configuration file. Custom CSS files are ordinary client modules:\ngive them any filename and import them from app code when needed.\n\n## Public files\n\nPut files that need their own URL in a top-level `public` directory next to `client` and `server`.\nThe directory structure becomes the URL structure. For example, `public/documents/manual.pdf` is\navailable at `/documents/manual.pdf` after deployment.\n\nPublic files are limited to AVIF, GIF, ICO, JPEG, PNG, WebP, and PDF. Ignotum checks that a file's\ncontents match its extension and rejects symbolic links, executable or code formats, and paths\nunder the reserved `_ignotum` name. Use `client/icon.svg` for the app favicon; arbitrary SVG files\nare not accepted in `public`. Put the directory at the app root—`client/public` is rejected.\n\n## Run a query\n\n`useQuery` takes a generated query reference. Pass the typed arguments when the query declares\nthem:\n\n```tsx\nconst todos = useQuery(api.todos.list);\nconst todo = useQuery(api.todos.get, { id });\nconst selectedTodo = useQuery(api.todos.get, id === undefined ? Query.skip : { id });\n```\n\n`Query.skip` keeps a query pending without opening a subscription. Use it when the arguments are\nnot available yet.\n\nThe first value is pending. Match every state with `Result.match`:\n\n```tsx\nreturn Result.match(todos, {\n  pending: () => <p class=\"text-zinc-500\">Loading...</p>,\n  value: (items) => (\n    <ul>\n      {items.map((todo) => (\n        <li key={todo.id}>{todo.text}</li>\n      ))}\n    </ul>\n  ),\n});\n```\n\nIgnotum keeps an active query up to date. A successful mutation refreshes affected subscribed\nqueries in every open client. Queries that did not read the changed documents or tables do not run\nagain.\n\n## Load a paginated query\n\n`usePaginatedQuery` calls a query with a `pagination: values.pagination()` argument and a\n`values.page(...)` return value. Pass only the query's other arguments. The hook supplies the\ncursor and uses 20 items per page by default:\n\n```tsx\nconst events = usePaginatedQuery(api.events.list, {\n  project: \"api\",\n  level: \"error\",\n});\n\nreturn Result.match(events, {\n  pending: () => <p>Loading...</p>,\n  value: ({ items, loadMore, status }) => (\n    <>\n      {items.map((event) => (\n        <p key={event.id}>{event.message}</p>\n      ))}\n      {status !== \"Exhausted\" && (\n        <button disabled={status === \"LoadingMore\"} onClick={loadMore}>\n          {status === \"LoadingMore\" ? \"Loading...\" : \"Load more\"}\n        </button>\n      )}\n    </>\n  ),\n});\n```\n\nPass `{ pageSize: number }` as the third argument to choose another size. The hook keeps earlier\nitems visible while it loads the next page. Changing the query arguments starts again from the\nfirst page. `Result.match` does not need another matcher because `LoadingMore` still has usable\nitems.\n\n## Run a mutation\n\n`useMutation` takes a generated mutation reference and returns a function:\n\n```tsx\nconst createTodo = useMutation(api.todos.create);\n\nvoid createTodo({ text }).then(\n  Result.match({\n    value: (id) => console.log(id),\n    error: {\n      InvalidTodoText: ({ text }) => console.log(`Invalid text: ${text}`),\n      TodoLimitReached: ({ limit }) => console.log(`The limit is ${limit}`),\n    },\n    internalError: ({ requestId }) => console.log(`Request ${requestId} failed.`),\n  }),\n);\n```\n\nAn argument-free mutation returns a zero-argument function:\n\n```tsx\nconst clearTodos = useMutation(api.todos.clear);\nvoid clearTodos();\n```\n\nThe client `Result` API only inspects completed server responses. Server-only operations such as\n`Result.fail`, `Result.succeed`, `Result.try`, `yield*`, and `.catch()` are not available here.\n\nApplication errors are handled by `error`, either with one function or an exhaustive map keyed by\n`_tag`. An `InternalServerError` contains a request ID and is thrown when `Result.match` has no\n`internalError` handler. During rendering, it reaches the nearest UI error boundary. A mutation can\nhandle it locally with `internalError`, as above. Operation-scoped protocol failures reject mutation\npromises or reach the nearest query UI error boundary. Ignotum retries transient connection failures,\nkeeps the latest query state, and replays pending mutations after the next connection handshake.\n\nHosted apps limit connections, subscriptions, active unique queries, and mutation traffic. See\n[Limits](limits.md) for the current values and retry retention.\n"],
 		["deploy.md", "# Deploy\n\nSet your API token in your shell:\n\n```sh\nexport IGNOTUM_API_TOKEN=your-token\n```\n\nDo not put the token in the app directory or commit it to source control.\n\nOn the first deploy, pass the app slug:\n\n```sh\nnpx ignotum deploy --app my-app\n```\n\nIf the slug belongs to one of your apps, Ignotum links it. Otherwise, Ignotum creates the app.\nWithout `--app`, the first deploy asks for the slug interactively.\n\nIgnotum stores the app ID, slug, and API URL in `.ignotum/app.json`. It never stores the access\ntoken there. Later deploys reuse the saved app, so the command has no app flag:\n\n```sh\nnpx ignotum deploy\n```\n\nThere is no separate build command. `deploy` generates the current bindings and builds both parts\nof the application, uploads the artifact, and makes the new deployment active.\n\nThe client output contains the SPA shell, generated assets, and validated files from the top-level\n`public` directory. The server output contains one bundle for every exported query or mutation.\nIgnotum writes both under `.ignotum/build` only after the complete build succeeds. If a rebuild\nfails, the previous successful output stays in place.\n\nUploads stream from disk. If an upload is interrupted after it begins, Ignotum leaves the active\ndeployment unchanged and prints the incomplete deployment ID. A rejected upload reports the\nAPI's reason. A successful deploy prints the app URL and deployment ID.\n\nThe CLI uses `https://api.ignotum.cloud` by default. Set `IGNOTUM_API_URL` only when targeting a\ndifferent Ignotum API, such as a local or development deployment.\n\nIgnotum rejects deployments that exceed the hosted file or artifact size limits. It also removes\nunfinished uploads and older inactive deployments after their retention periods. See\n[Limits](limits.md) for the current values.\n"],
 		["dev-server.md", "# Dev server\n\nRun the dev server from the app root:\n\n```sh\nnpx ignotum dev\n```\n\nIt expects these files:\n\n```text\nclient/index.tsx\nserver/schema.ts\n```\n\nThe dev server generates the client and server bindings, reads the `app(...)` definition from\n`client/index.tsx`, loads Tailwind automatically, and serves the app at\n<http://127.0.0.1:3210>. It reloads client and server changes and updates active queries after\nserver changes and successful mutations.\n\nYou do not need an HTML file, Vite configuration, Tailwind configuration, or framework stylesheet.\nAdd an optional `client/icon.svg` and Ignotum uses it as the favicon automatically. With no icon\nfile, the HTML contains no favicon link.\n\n## Flags\n\nUse flags to change the address or open the browser:\n\n```sh\nnpx ignotum dev --host 0.0.0.0 --port 3000 --open\n```\n\nThe defaults are host `127.0.0.1`, port `3210`, and no automatic browser opening.\n\n## Code generation\n\nThe dev server runs code generation when it starts. It updates generated files when you add or\nremove a server function file.\n\nRun code generation before typechecking without the dev server:\n\n```sh\nnpx ignotum codegen\nnpx tsc --noEmit\n```\n\nIgnotum creates:\n\n- `_generated/server.ts` with schema-bound `query`, `mutation`, and `values` exports;\n- `_generated/api.ts` with client references such as `api.todos.list`;\n- `_generated/types.ts` with `DataModel`, `Doc`, and `Id`.\n\nDo not edit generated files.\n\n## Local data\n\nData persists between dev-server restarts. Stop the server and reset that data with:\n\n```sh\nnpx ignotum dev db reset\n```\n"],
-		["getting-started.md", "# Getting started\n\nIgnotum requires Node.js 22.18 or newer.\n\nCreate an app:\n\n```sh\nnpx ignotum new my-app\ncd my-app\nnpx ignotum dev\n```\n\nOpen <http://127.0.0.1:3210>. The generated app is a small counter with a schema, a query, a\nmutation, and a JSX client.\n\n`ignotum new` installs dependencies with pnpm when it is available. It falls back to npm only when\npnpm is not installed. It generates `_generated`, initializes a Git repository, and creates an\n`Init` commit containing the generated files after the rest of the setup finishes.\n\nPass `.` to create the app in the current directory. The directory must be empty:\n\n```sh\nnpx ignotum new .\n```\n\nUse `--no-git` to skip Git or `--no-install` to skip dependency installation. You can install the\ndependencies later with the same pnpm and npm fallback behavior:\n\n```sh\nnpx ignotum install\n```\n\nRead [schema syntax](schema.md), [server functions](server-functions.md), and the\n[client guide](client.md) to build the app. The [manual setup](manual-setup.md) recreates the counter\napp without `ignotum new`. When it is ready, follow the [deploy guide](deploy.md) to create or link\nthe hosted app and publish it.\n"],
-		["index.md", "# Ignotum\n\nAn Ignotum app has a schema, server functions, and a client. Ignotum is opinionated about the\nclient tooling. Every app uses JSX, hooks from `ignotum/client`, and Tailwind CSS.\n\nThe current release supports local development and hosted deployment.\n\n- [Getting started](getting-started.md) creates and runs a counter app with `ignotum new`.\n- [Manual setup](manual-setup.md) recreates the generated counter app by hand.\n- [Schema syntax](schema.md) covers tables, fields, IDs, and generated document types.\n- [Values](values.md) lists every value validator and its TypeScript type.\n- [Server functions](server-functions.md) covers queries, mutations, database access, and errors.\n- [Client](client.md) covers queries, mutations, results, and Tailwind styling.\n- [Dev server](dev-server.md) covers local development, code generation, flags, and data reset.\n- [Deploy](deploy.md) creates or links an app, then uploads and activates a deployment.\n- [Limits](limits.md) lists hosted limits for functions, data, realtime updates, and deployments.\n"],
-		["limits.md", "# Limits\n\nThese limits apply to hosted Ignotum apps. The local dev server does not reproduce every hosted\nlimit, so an operation that works locally can still be rejected after deployment.\n\nIgnotum reports connection, traffic, time, result, and storage-quota failures as\n`ResourceLimitExceeded`. A database read or write that crosses a document or collection limit can\nappear as a temporary function failure. A deployment that exceeds a limit fails before activation,\nso the current deployment stays active.\n\n## Server functions\n\n| Limit                                   |      Value |\n| --------------------------------------- | ---------: |\n| Function arguments                      |     16 KiB |\n| Function result                         |      1 MiB |\n| Execution time                          | 10 seconds |\n| Memory                                  |     32 MiB |\n| Stack                                   |    512 KiB |\n| Ignotum operations during one execution |      1,000 |\n\nArgument and result sizes use their JSON representation. The result limit applies to successful\nresults and application errors.\n\nAn Ignotum operation is a call through the function context, such as a database read or write. A\nfunction stops when it reaches the execution time or operation limit.\n\nIgnotum retries one query execution when app data changes while it runs. That execution makes at\nmost four attempts and stops after 15 seconds. The query fails temporarily if it cannot read a\nconsistent result in that time.\n\n## App data\n\n| Limit                                   |          Value |\n| --------------------------------------- | -------------: |\n| Stored fields in one document           |        256 KiB |\n| Documents returned by `collect()`       |          1,000 |\n| Document fields returned by `collect()` |          1 MiB |\n| Stored app data                         | 64 MiB per app |\n\nThe 1 MiB function-result limit still applies to `collect()`. Document IDs and timestamps take some\nspace in that result, so a collection can reach the result limit before its fields reach 1 MiB.\n\nIf a mutation would take the app over its storage limit, Ignotum rolls back the whole mutation.\nThe quota covers stored documents and the records Ignotum keeps to process mutations safely.\nDeployment files do not count as stored app data.\n\n## Realtime connections and calls\n\n| Limit                     |                        Value |\n| ------------------------- | ---------------------------: |\n| Live connections          |                  256 per app |\n| Incoming realtime message |                       64 KiB |\n| Subscriptions             |           128 per connection |\n| Active unique queries     |                   64 per app |\n| Realtime query refresh    | 4 attempts within 15 seconds |\n| Concurrent operations     |                   32 per app |\n| Mutation execution        |          1 at a time per app |\n| Unresolved mutations      |                   32 per app |\n| Mutation calls            |        60 per minute per app |\n\nA unique query is one function and argument combination. Several components or browser tabs can\nsubscribe to the same unique query without using another unique-query slot.\n\nA realtime refresh can repeat a query execution when app data changes again during the refresh.\n\nThe unresolved-mutation limit protects calls whose outcome is not known yet, such as a call waiting\nfor a retry after a connection failure. Once Ignotum receives a final result, that call no longer\ncounts toward the limit.\n\nIgnotum runs mutations for the same app one at a time. Queries and other live calls can still use\nthe remaining concurrent-operation slots.\n\n## Mutation retries\n\nThe client keeps the ID of a pending mutation and reuses it after a reconnect. Ignotum remembers up\nto 10,000 mutation results per app for seven days. During that period, a retry returns the recorded\nresult instead of running the mutation again.\n\nDo not treat this as permanent duplicate protection. A mutation may run again after its record has\nexpired or fallen outside the 10,000 most recent results.\n\n## Deployments\n\n| Limit                          |   Value |\n| ------------------------------ | ------: |\n| Files listed in one deployment |     512 |\n| One listed file                |  16 MiB |\n| Deployment inventory           |   1 MiB |\n| Server files combined          |  64 MiB |\n| Listed files combined          | 128 MiB |\n\nIgnotum never deletes the active deployment. It also protects the three newest deployments that\ncompleted successfully. An older inactive deployment becomes eligible for deletion after seven\ndays. An unfinished upload becomes eligible after 24 hours.\n"],
-		["manual-setup.md", "# Manual setup\n\nIgnotum requires Node.js 22.18 or newer. This guide recreates the counter app from `ignotum new`\nwithout running the app generator. It uses pnpm to install dependencies.\n\nCreate the app directory:\n\n```sh\nmkdir my-ignotum-app\ncd my-ignotum-app\n```\n\nCreate this structure:\n\n```text\nmy-ignotum-app/\n  client/\n    index.tsx\n    icon.svg\n  public/\n    manual.pdf\n  server/\n    counter.ts\n    schema.ts\n  shared/\n    utils.ts\n  package.json\n  tsconfig.json\n```\n\n## Configure the package\n\nAdd `package.json`:\n\n```json\n{\n  \"name\": \"my-ignotum-app\",\n  \"private\": true,\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"typecheck\": \"ignotum codegen && tsc --noEmit\"\n  },\n  \"dependencies\": {\n    \"ignotum\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"typescript\": \"^7.0.2\"\n  },\n  \"engines\": {\n    \"node\": \">=22.18.0\"\n  }\n}\n```\n\nInstall the dependencies:\n\n```sh\npnpm install\n```\n\n## Configure TypeScript\n\nAdd `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2023\",\n    \"lib\": [\"ES2023\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"jsx\": \"react-jsx\",\n    \"jsxImportSource\": \"ignotum/client\",\n    \"strict\": true,\n    \"noEmit\": true,\n    \"skipLibCheck\": true,\n    \"paths\": {\n      \"@/*\": [\"./*\"]\n    }\n  },\n  \"include\": [\"_generated\", \"client\", \"server\", \"shared\"]\n}\n```\n\n## Add shared code\n\nAdd `shared/utils.ts`:\n\n```ts\nexport const counterIncrement = 1;\n```\n\nBoth the client and server can import files in `shared` through `@/shared`.\n\n## Define the schema\n\nAdd `server/schema.ts`:\n\n```ts\nimport { defineSchema } from \"ignotum/server\";\n\nexport default defineSchema(({ table, values }) => ({\n  counters: table({\n    value: values.number(),\n  }),\n}));\n```\n\n## Add the server functions\n\nAdd `server/counter.ts`:\n\n```ts\nimport { mutation, query, values } from \"@/_generated/server.js\";\nimport { counterIncrement } from \"@/shared/utils.js\";\n\nexport const get = query({\n  returns: values.number(),\n\n  handler: function* (ctx) {\n    const counters = yield* ctx.db.query(\"counters\").collect();\n    return counters[0]?.value ?? 0;\n  },\n});\n\nexport const increment = mutation({\n  returns: values.number(),\n\n  handler: function* (ctx) {\n    const counters = yield* ctx.db.query(\"counters\").collect();\n    const counter = counters[0];\n    const value = (counter?.value ?? 0) + counterIncrement;\n\n    if (counter === undefined) {\n      yield* ctx.db.insert(\"counters\", { value });\n    } else {\n      yield* ctx.db.patch(\"counters\", counter.id, { value });\n    }\n\n    return value;\n  },\n});\n```\n\nKeep the `.js` suffix on imports from `@/_generated`, even though the generated files use\nTypeScript.\n\n## Add the client\n\nAdd `client/index.tsx`:\n\n```tsx\nimport { app, Result, useMutation, useQuery } from \"ignotum/client\";\n\nimport { api } from \"@/_generated/api.js\";\nimport { counterIncrement } from \"@/shared/utils.js\";\n\nfunction App() {\n  const count = useQuery(api.counter.get);\n  const increment = useMutation(api.counter.increment);\n\n  return (\n    <main class=\"mx-auto max-w-sm px-6 py-20 text-center\">\n      <h1 class=\"text-2xl font-semibold\">Counter</h1>\n      {Result.match(count, {\n        pending: () => <p class=\"mt-6\">Loading...</p>,\n        value: (value) => (\n          <>\n            <p class=\"my-6 text-5xl tabular-nums\">{value}</p>\n            <button\n              class=\"rounded bg-zinc-900 px-4 py-2 text-white\"\n              type=\"button\"\n              onClick={() => void increment()}\n            >\n              Increment by {counterIncrement}\n            </button>\n          </>\n        ),\n      })}\n    </main>\n  );\n}\n\nexport default app({\n  title: \"Counter\",\n  component: App,\n});\n```\n\nIgnotum loads Tailwind automatically. You do not need an HTML file, Vite configuration, Tailwind\nconfiguration, or framework stylesheet. Custom CSS files are ordinary client modules and can use\nany filename when imported from app code.\n\nThe `client/icon.svg` file is optional. When present, Ignotum discovers it automatically and uses it\nas the favicon. When absent, the app has no favicon link.\n\nThe top-level `public` directory is optional. Its AVIF, GIF, ICO, JPEG, PNG, WebP, and PDF files keep\ntheir relative paths as public URLs. Do not put this directory inside `client`.\n\n## Run the app\n\nStart the dev server:\n\n```sh\nnpx ignotum dev\n```\n\nOpen <http://127.0.0.1:3210>. Ignotum creates `_generated` before starting the app.\n\nRead [schema syntax](schema.md), [server functions](server-functions.md), and the\n[client guide](client.md) to continue building the app.\n"],
-		["schema.md", "# Schema syntax\n\nDefine the data model in `server/schema.ts`. The keys returned from `defineSchema` are table\nnames, and each `table` call defines that table's fields:\n\n```ts\nimport { defineSchema } from \"ignotum/server\";\n\nexport default defineSchema(({ table, values }) => ({\n  users: table({\n    name: values.string(),\n  }),\n  todos: table({\n    text: values.string(),\n    completed: values.boolean(),\n    ownerId: values.optional(values.id(\"users\")),\n  }),\n}));\n```\n\n## Field values\n\nRead [values](values.md) for the complete validator list and the TypeScript type produced by each\none. `values.id` only accepts a table declared in the same schema. Arrays and objects can be nested,\nand their contents can use any value validator.\n\n## System fields\n\nIgnotum adds three fields to every stored document:\n\n| Field       | Type                      |\n| ----------- | ------------------------- |\n| `id`        | The ID type for its table |\n| `createdAt` | `Date`                    |\n| `updatedAt` | `Date`                    |\n\nDo not declare these fields in a table. Do not pass them to `insert`, `patch`, or `replace`.\n\n## Generated types\n\n`_generated/types.ts` exports the data model, document, and ID types:\n\n```ts\nimport type { DataModel, Doc, Id } from \"@/_generated/types.js\";\n\ntype Todo = Doc<\"todos\">;\ntype TodoId = Id<\"todos\">;\n```\n\n`Doc<\"todos\">` includes the fields from the `todos` table and its three system fields. An\n`Id<\"todos\">` cannot be passed where an `Id<\"users\">` is required.\n"],
-		["server-functions.md", "# Server functions\n\nPut queries and mutations in `.ts` files directly inside `server`. The file name becomes the API\nmodule, and each exported function keeps its export name:\n\n```text\nserver/todos.ts -> api.todos.list\nserver/users.ts -> api.users.get\n```\n\nIgnotum ignores `schema.ts`, `index.ts`, test files, and names beginning with `_`.\n\nImport schema-bound builders from the generated server file. Import `Result` only when the module\nintroduces or catches typed errors:\n\n```ts\nimport { Result } from \"ignotum/server\";\n\nimport { mutation, query, values } from \"@/_generated/server.js\";\n```\n\nKeep the `.js` suffix on generated imports.\n\n## Define a function\n\nA function has optional argument, return, and public error schemas, plus a generator handler:\n\n```ts\nexport const getTitle = query({\n  args: {\n    id: values.id(\"todos\"),\n  },\n  returns: values.string(),\n\n  handler: function* (ctx, args) {\n    const todo = yield* ctx.db.get(\"todos\", args.id);\n    return todo.text;\n  },\n});\n```\n\nOmit `args` when the function takes no arguments. Omit `returns` when it returns nothing. An\nomitted `returns` only permits a `void` handler; Ignotum never infers an unchecked return schema.\n`yield*` waits for an Ignotum operation and propagates its typed application errors. Return\nsuccessful values with ordinary `return`.\n\nIgnotum validates arguments before running the handler. It also validates returned values and\npublic application errors before sending them to a client.\n\nAn argument-free query and a mutation with no return value can stay small:\n\n```ts\nconst Todo = values.doc(\"todos\");\n\nexport const list = query({\n  returns: values.array(Todo),\n\n  handler: function* (ctx) {\n    return yield* ctx.db.query(\"todos\").collect();\n  },\n});\n\nexport const remove = mutation({\n  args: { id: values.id(\"todos\") },\n\n  handler: function* (ctx, args) {\n    yield* ctx.db.delete(\"todos\", args.id);\n  },\n});\n```\n\nCall an argument-free query as `useQuery(api.todos.list)`. An argument-free mutation returns a\nzero-argument function:\n\n```ts\nconst clear = useMutation(api.todos.clear);\nvoid clear();\n```\n\n## Database reads\n\nUse `find` when a missing document is a normal result:\n\n```ts\nconst todo = yield * ctx.db.find(\"todos\", args.id);\n// Todo | undefined\n```\n\nUse `get` when the document should exist:\n\n```ts\nconst todo = yield * ctx.db.get(\"todos\", args.id);\n// Todo\n```\n\nA missing `get` fails with a typed `DocumentNotFound` value containing `table` and `id`. Collect a\nwhole table through a query:\n\n```ts\nconst todos = yield * ctx.db.query(\"todos\").collect();\n```\n\nQuery handlers only receive read methods.\n\nHosted apps limit document size, collection reads, function runtime, and stored app data. See\n[Limits](limits.md) for the current values.\n\n## Database writes\n\nMutation handlers receive the read methods and these writes:\n\n```ts\nconst id =\n  yield *\n  ctx.db.insert(\"todos\", {\n    text: \"Learn Ignotum\",\n    completed: false,\n  });\n\nyield * ctx.db.patch(\"todos\", id, { completed: true });\n\nyield *\n  ctx.db.replace(\"todos\", id, {\n    text: \"Build an app\",\n    completed: false,\n  });\n\nyield * ctx.db.delete(\"todos\", id);\n```\n\n`patch` changes only supplied fields. `replace` requires every non-optional table field. Ignotum\nrolls back a mutation when its handler fails with a typed application error or encounters an\ninternal failure.\n\n## Application errors\n\nDefine an application error with `values.error`. Its name becomes `_tag`:\n\n```ts\nconst TodoNotFound = values.error(\"TodoNotFound\", {\n  id: values.id(\"todos\"),\n});\n```\n\n`Result.fail` deliberately stops the operation with a typed error:\n\n```ts\nyield * Result.fail(TodoNotFound({ id: args.id }));\n```\n\nThe `errors` field is optional. If omitted, Ignotum infers the handler's remaining application\nerrors. If supplied, it is the public contract and the handler must conform to it:\n\n```ts\nexport const toggle = mutation({\n  args: {\n    id: values.id(\"todos\"),\n  },\n  returns: values.boolean(),\n  errors: TodoNotFound,\n\n  handler: function* (ctx, args) {\n    const todo = yield* ctx.db.get(\"todos\", args.id).catch({\n      DocumentNotFound: (error) => Result.fail(TodoNotFound({ id: error.id })),\n    });\n\n    const completed = !todo.completed;\n    yield* ctx.db.patch(\"todos\", args.id, { completed });\n    return completed;\n  },\n});\n```\n\nCombine public errors with `values.union`:\n\n```ts\nerrors: values.union(InvalidTodoText, TodoLimitReached),\n```\n\n## Catch and recover\n\nEvery Result operation has a partial, tag-based `catch`. Handlers receive the narrowed error type.\nUnmatched errors continue through the channel:\n\n```ts\nconst settings =\n  yield *\n  loadSettings().catch({\n    SettingsNotFound: () => defaultSettings,\n  });\n```\n\nReturn a plain value to recover. Return `Result.fail(...)` to map one error to another. Unknown tag\nnames fail the TypeScript check.\n\nUse `Result.try` for one catch boundary around several operations:\n\n```ts\nconst author =\n  yield *\n  Result.try(function* () {\n    const membership = yield* ctx.db.get(\"memberships\", topic.membershipId);\n    return yield* ctx.db.get(\"users\", membership.userId);\n  }).catch({\n    DocumentNotFound: () => Result.fail(InvalidAuthor({ topicId: topic.id })),\n  });\n```\n\nThere is no async variant. Ignotum operations always use `yield*` in server code.\n\n## Standalone results\n\n`Result.succeed` remains useful for helpers that return a Result:\n\n```ts\nfunction validateName(name: string) {\n  if (name.length === 0) {\n    return Result.fail(InvalidName({}));\n  }\n\n  return Result.succeed(name.trim());\n}\n```\n\nA handler can use the helper with `const name = yield* validateName(args.name)`. Normal handlers do\nnot wrap successful returns in `Result.succeed`.\n\n## Internal failures and defects\n\nDatabase outages, internal runtime failures, and thrown JavaScript exceptions are not application\nerrors. Ignotum logs their full cause and sends only:\n\n```ts\n{\n  _tag: \"InternalServerError\",\n  requestId: \"...\",\n}\n```\n\nEvery generated client function includes `InternalServerError` in its Result error union. The\nrequest ID links the client-visible failure to server logs without exposing private details.\n`InternalServerError` is reserved by Ignotum: never define it with `values.error` or include it in a\nfunction's `errors` schema.\n"],
-		["values.md", "# Values\n\nUse `values` validators to describe table fields, function arguments, return values, and application\nerrors. Each validator checks values at runtime and supplies the matching TypeScript type.\n\n| Validator                                 | TypeScript type                       | Notes                                                                                                |\n| ----------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `values.string()`                         | `string`                              |                                                                                                      |\n| `values.number()`                         | `number`                              | Accepts finite JavaScript numbers, including integers.                                               |\n| `values.integer()`                        | `number`                              | Accepts safe integers.                                                                               |\n| `values.boolean()`                        | `boolean`                             |                                                                                                      |\n| `values.date()`                           | `Date`                                | Accepts valid JavaScript dates.                                                                      |\n| `values.null()`                           | `null`                                | Accepts only `null`.                                                                                 |\n| `values.literal(value)`                   | The exact type of `value`             | Accepts one string, finite number, or boolean value.                                                 |\n| `values.literals(first, second, ...rest)` | A union of the supplied literal types | Requires at least two string, finite number, or boolean values.                                      |\n| `values.id(\"todos\")`                      | `Id<\"todos\">`                         | Accepts an ID for a table declared in the same schema. IDs for different tables are different types. |\n| `values.doc(\"todos\")`                     | `Doc<\"todos\">`                        | Accepts a complete document, including its `id`, `createdAt`, and `updatedAt` system fields.         |\n| `values.optional(value)`                  | `T \\| undefined`                      | Makes an object or table field optional. The field may be omitted.                                   |\n| `values.nullable(value)`                  | `T \\| null`                           | The value remains required unless it is also wrapped with `optional`.                                |\n| `values.array(value)`                     | `ReadonlyArray<T>`                    | Every item must match `value`.                                                                       |\n| `values.object(fields)`                   | An object matching `fields`           | Defines an object with known field names.                                                            |\n| `values.record(value)`                    | `Readonly<Record<string, T>>`         | Defines an object with dynamic string keys whose values all match `value`.                           |\n| `values.union(...values)`                 | A union of the supplied types         | Accepts a value matching any supplied validator.                                                     |\n| `values.never()`                          | `never`                               | No value can pass this validator.                                                                    |\n| `values.error(\"Name\", fields)`            | A tagged error object                 | Defines an application error whose `_tag` is the supplied name.                                      |\n\n`T` means the TypeScript type produced by the wrapped validator.\n\n`values.doc` is available on the schema-bound `values` exported by `_generated/server.ts`. It is\nnot available while defining `server/schema.ts`, because the table definitions are still being\ncreated there.\n\n## Object transforms\n\nValidators created by `values.object(fields)` and `values.doc(\"table\")` support these chainable\nmethods:\n\n| Method              | Result                                                               |\n| ------------------- | -------------------------------------------------------------------- |\n| `.pick(...keys)`    | Keeps the listed fields. Every key must exist.                       |\n| `.omit(...keys)`    | Removes the listed fields. Every key must exist.                     |\n| `.extend(fields)`   | Adds fields. It rejects names that already exist.                    |\n| `.override(fields)` | Replaces validators for existing fields. It rejects new field names. |\n| `.partial()`        | Makes every current field optional.                                  |\n\nEach method works from the result of the previous method. Added fields can be picked, omitted, or\noverridden immediately. An omitted name can be added again with a different validator.\n\n```ts\nconst TodoInput = values.doc(\"todos\").omit(\"id\", \"createdAt\", \"updatedAt\").partial().extend({\n  requestId: values.string(),\n});\n```\n\nUse `override` when changing an existing field. This makes replacements visible in the definition\nand prevents `extend` from silently weakening fields such as `id`:\n\n```ts\nconst EditableTodo = values.doc(\"todos\").override({\n  title: values.optional(values.string()),\n});\n```\n\nThese methods are only available on fixed object validators. Arrays, records, unions, errors, and\nprimitive validators do not expose them. After transforming a document validator, its inferred type\nmatches the current fields in the chain rather than the complete document type.\n\n### Reuse embedded objects in the schema\n\nCreate a fixed object validator inside the `defineSchema` callback when several stored fields share\nan object shape. A transform can derive a stored variant without repeating its fields:\n\n```ts\ndefineSchema(({ table, values }) => {\n  const Contact = values.object({\n    email: values.string(),\n    phone: values.string(),\n  });\n\n  return {\n    users: table({\n      contact: Contact,\n    }),\n    publicProfiles: table({\n      contact: Contact.omit(\"phone\"),\n    }),\n  };\n});\n```\n\nThis pattern suits embedded objects stored by more than one table, including full and reduced\nversions of the same object. The base validator stays inside `defineSchema`, where `values.id` can\ncheck its table references against the completed schema.\n\n### Derive server function validators from documents\n\nUse the schema-bound `values` from `_generated/server.ts` when a function input or output follows a\nstored document. These validators know every table name and the complete document fields, including\n`id`, `createdAt`, and `updatedAt`.\n\nReusable server validators can live in an ignored server module such as `server/_validators.ts`:\n\n```ts\nimport { values } from \"@/_generated/server.js\";\n\nexport const TodoInput = values.doc(\"todos\").omit(\"id\", \"createdAt\", \"updatedAt\").partial();\n\nexport const PublicTodo = values.doc(\"todos\").omit(\"updatedAt\");\n```\n\nImport these validators into queries and mutations that need the same contract. This works well for\npatch inputs and document projections. Do not import generated validators into `server/schema.ts`.\nDocument validators depend on the schema, so importing them while defining that schema would create\na cycle.\n\n## Examples\n\n```ts\nconst TodoStatus = values.literals(\"pending\", \"completed\");\n\nconst Todo = values.doc(\"todos\");\n\nexport const list = query({\n  returns: values.array(Todo),\n  handler: function* (ctx) {\n    return yield* ctx.db.query(\"todos\").collect();\n  },\n});\n```\n\nUse the other validators to define reusable values that do not represent a stored document:\n\n```ts\nconst TodoInput = values.object({\n  status: TodoStatus,\n  scheduledAt: values.nullable(values.date()),\n  scores: values.record(values.integer()),\n  title: values.string(),\n});\n```\n\nUse `optional` when a field may be absent. Use `nullable` when a present field may contain `null`:\n\n```ts\nvalues.object({\n  nickname: values.optional(values.string()),\n  deletedAt: values.nullable(values.date()),\n});\n```\n"]
+		["getting-started.md", "# Getting started\n\nIgnotum requires Node.js 22.18 or newer.\n\nCreate an app:\n\n```sh\nnpx ignotum new my-app\ncd my-app\nnpx ignotum dev\n```\n\nOpen <http://127.0.0.1:3210>. The generated app is a small counter with a schema, a query, a\nmutation, and a JSX client.\n\n`ignotum new` installs dependencies with pnpm when it is available. It falls back to npm only when\npnpm is not installed. It generates `_generated`, initializes a Git repository, and creates an\n`Init` commit containing the generated files after the rest of the setup finishes.\n\nPass `.` to create the app in the current directory. The directory must be empty:\n\n```sh\nnpx ignotum new .\n```\n\nUse `--no-git` to skip Git or `--no-install` to skip dependency installation. You can install the\ndependencies later with the same pnpm and npm fallback behavior:\n\n```sh\nnpx ignotum install\n```\n\nRead [schema syntax](schema.md), [server functions](server-functions.md),\n[database reads](reading-data.md), [database writes](writing-data.md), and the\n[client guide](client.md) to build the app. The [manual setup](manual-setup.md) recreates the counter\napp without `ignotum new`. When it is ready, follow the [deploy guide](deploy.md) to create or link\nthe hosted app and publish it.\n"],
+		["index.md", "# Ignotum\n\nAn Ignotum app has a schema, server functions, and a client. Ignotum is opinionated about the\nclient tooling. Every app uses JSX, hooks from `ignotum/client`, and Tailwind CSS.\n\nThe current release supports local development and hosted deployment.\n\n- [Getting started](getting-started.md) creates and runs a counter app with `ignotum new`.\n- [Manual setup](manual-setup.md) recreates the generated counter app by hand.\n- [Schema syntax](schema.md) covers tables, fields, IDs, and generated document types.\n- [Values](values.md) lists every value validator and its TypeScript type.\n- [Server functions](server-functions.md) covers queries, mutations, and application errors.\n- [Read from the database](reading-data.md) covers documents, indexes, ranges, ordering, and result methods.\n- [Write to the database](writing-data.md) covers inserts, patches, replacements, deletes, and mutation behavior.\n- [Client](client.md) covers queries, mutations, results, and Tailwind styling.\n- [Dev server](dev-server.md) covers local development, code generation, flags, and data reset.\n- [Deploy](deploy.md) creates or links an app, then uploads and activates a deployment.\n- [Limits](limits.md) lists hosted limits for functions, data, realtime updates, and deployments.\n"],
+		["limits.md", "# Limits\n\nThese limits apply to hosted Ignotum apps. The local dev server does not reproduce every hosted\nlimit, so an operation that works locally can still be rejected after deployment.\n\nIgnotum reports connection, traffic, time, result, and storage-quota failures as\n`ResourceLimitExceeded`. A database read or write that crosses a document or collection limit can\nappear as a temporary function failure. A deployment that exceeds a limit fails before activation,\nso the current deployment stays active.\n\n## Server functions\n\n| Limit                                   |      Value |\n| --------------------------------------- | ---------: |\n| Function arguments                      |     16 KiB |\n| Function result                         |      1 MiB |\n| Execution time                          | 10 seconds |\n| Memory                                  |     32 MiB |\n| Stack                                   |    512 KiB |\n| Ignotum operations during one execution |      1,000 |\n\nArgument and result sizes use their JSON representation. The result limit applies to successful\nresults and application errors.\n\nAn Ignotum operation is a call through the function context, such as a database read or write. A\nfunction stops when it reaches the execution time or operation limit.\n\nIgnotum retries one query execution when app data changes while it runs. That execution makes at\nmost four attempts and stops after 15 seconds. The query fails temporarily if it cannot read a\nconsistent result in that time.\n\n## App data\n\n| Limit                                   |          Value |\n| --------------------------------------- | -------------: |\n| Stored fields in one document           |        256 KiB |\n| Documents returned by `collect()`       |          1,000 |\n| Documents returned by `take()`          |          1,000 |\n| Documents returned by one page          |          1,000 |\n| Document fields returned by `collect()` |          1 MiB |\n| Stored app data                         | 64 MiB per app |\n\nThe 1 MiB function-result limit still applies to `collect()`. Document IDs and timestamps take some\nspace in that result, so a collection can reach the result limit before its fields reach 1 MiB.\n\nIf a mutation would take the app over its storage limit, Ignotum rolls back the whole mutation.\nThe quota covers stored documents, application indexes, and the records Ignotum keeps to process\nmutations safely. Deployment files do not count as stored app data.\n\n## Schema indexes\n\n| Limit                        |          Value |\n| ---------------------------- | -------------: |\n| Indexes on one table         |             16 |\n| Indexes in one schema        |            128 |\n| Declared fields in one index |              8 |\n| Index name                   | 64 UTF-8 bytes |\n| One encoded index key        |          4 KiB |\n\nEvery index also includes `createdAt` and `id` after its declared fields. The key limit applies to\nthe combined encoded field values and those final ordering values. A document must fit every index\ndeclared for its table.\n\n## Realtime connections and calls\n\n| Limit                     |                        Value |\n| ------------------------- | ---------------------------: |\n| Live connections          |                  256 per app |\n| Incoming realtime message |                       64 KiB |\n| Subscriptions             |           128 per connection |\n| Active unique queries     |                   64 per app |\n| Realtime query refresh    | 4 attempts within 15 seconds |\n| Concurrent operations     |                   32 per app |\n| Mutation execution        |          1 at a time per app |\n| Unresolved mutations      |                   32 per app |\n| Mutation calls            |        60 per minute per app |\n\nA unique query is one function and argument combination. Several components or browser tabs can\nsubscribe to the same unique query without using another unique-query slot.\n\nA realtime refresh can repeat a query execution when app data changes again during the refresh.\n\nThe unresolved-mutation limit protects calls whose outcome is not known yet, such as a call waiting\nfor a retry after a connection failure. Once Ignotum receives a final result, that call no longer\ncounts toward the limit.\n\nIgnotum runs mutations for the same app one at a time. Queries and other live calls can still use\nthe remaining concurrent-operation slots.\n\n## Mutation retries\n\nThe client keeps the ID of a pending mutation and reuses it after a reconnect. Ignotum remembers up\nto 10,000 mutation results per app for seven days. During that period, a retry returns the recorded\nresult instead of running the mutation again.\n\nDo not treat this as permanent duplicate protection. A mutation may run again after its record has\nexpired or fallen outside the 10,000 most recent results.\n\n## Deployments\n\n| Limit                          |   Value |\n| ------------------------------ | ------: |\n| Files listed in one deployment |     512 |\n| One listed file                |  16 MiB |\n| Deployment inventory           |   1 MiB |\n| Server files combined          |  64 MiB |\n| Listed files combined          | 128 MiB |\n\nIgnotum never deletes the active deployment. It also protects the three newest deployments that\ncompleted successfully. An older inactive deployment becomes eligible for deletion after seven\ndays. An unfinished upload becomes eligible after 24 hours.\n"],
+		["manual-setup.md", "# Manual setup\n\nIgnotum requires Node.js 22.18 or newer. This guide recreates the counter app from `ignotum new`\nwithout running the app generator. It uses pnpm to install dependencies.\n\nCreate the app directory:\n\n```sh\nmkdir my-ignotum-app\ncd my-ignotum-app\n```\n\nCreate this structure:\n\n```text\nmy-ignotum-app/\n  client/\n    index.tsx\n    icon.svg\n  public/\n    manual.pdf\n  server/\n    counter.ts\n    schema.ts\n  shared/\n    utils.ts\n  package.json\n  tsconfig.json\n```\n\n## Configure the package\n\nAdd `package.json`:\n\n```json\n{\n  \"name\": \"my-ignotum-app\",\n  \"private\": true,\n  \"version\": \"1.0.0\",\n  \"type\": \"module\",\n  \"scripts\": {\n    \"typecheck\": \"ignotum codegen && tsc --noEmit\"\n  },\n  \"dependencies\": {\n    \"ignotum\": \"latest\"\n  },\n  \"devDependencies\": {\n    \"typescript\": \"^7.0.2\"\n  },\n  \"engines\": {\n    \"node\": \">=22.18.0\"\n  }\n}\n```\n\nInstall the dependencies:\n\n```sh\npnpm install\n```\n\n## Configure TypeScript\n\nAdd `tsconfig.json`:\n\n```json\n{\n  \"compilerOptions\": {\n    \"target\": \"ES2023\",\n    \"lib\": [\"ES2023\", \"DOM\", \"DOM.Iterable\"],\n    \"module\": \"NodeNext\",\n    \"moduleResolution\": \"NodeNext\",\n    \"jsx\": \"react-jsx\",\n    \"jsxImportSource\": \"ignotum/client\",\n    \"strict\": true,\n    \"noEmit\": true,\n    \"skipLibCheck\": true,\n    \"paths\": {\n      \"@/*\": [\"./*\"]\n    }\n  },\n  \"include\": [\"_generated\", \"client\", \"server\", \"shared\"]\n}\n```\n\n## Add shared code\n\nAdd `shared/utils.ts`:\n\n```ts\nexport const counterIncrement = 1;\n```\n\nBoth the client and server can import files in `shared` through `@/shared`.\n\n## Define the schema\n\nAdd `server/schema.ts`:\n\n```ts\nimport { defineSchema } from \"ignotum/server\";\n\nexport default defineSchema(({ table, values }) => ({\n  counters: table({\n    value: values.number(),\n  }),\n}));\n```\n\n## Add the server functions\n\nAdd `server/counter.ts`:\n\n```ts\nimport { mutation, query, values } from \"@/_generated/server.js\";\nimport { counterIncrement } from \"@/shared/utils.js\";\n\nexport const get = query({\n  returns: values.number(),\n\n  handler: function* (ctx) {\n    const counters = yield* ctx.db.query(\"counters\").collect();\n    return counters[0]?.value ?? 0;\n  },\n});\n\nexport const increment = mutation({\n  returns: values.number(),\n\n  handler: function* (ctx) {\n    const counters = yield* ctx.db.query(\"counters\").collect();\n    const counter = counters[0];\n    const value = (counter?.value ?? 0) + counterIncrement;\n\n    if (counter === undefined) {\n      yield* ctx.db.insert(\"counters\", { value });\n    } else {\n      yield* ctx.db.patch(\"counters\", counter.id, { value });\n    }\n\n    return value;\n  },\n});\n```\n\nKeep the `.js` suffix on imports from `@/_generated`, even though the generated files use\nTypeScript.\n\n## Add the client\n\nAdd `client/index.tsx`:\n\n```tsx\nimport { app, Result, useMutation, useQuery } from \"ignotum/client\";\n\nimport { api } from \"@/_generated/api.js\";\nimport { counterIncrement } from \"@/shared/utils.js\";\n\nfunction App() {\n  const count = useQuery(api.counter.get);\n  const increment = useMutation(api.counter.increment);\n\n  return (\n    <main class=\"mx-auto max-w-sm px-6 py-20 text-center\">\n      <h1 class=\"text-2xl font-semibold\">Counter</h1>\n      {Result.match(count, {\n        pending: () => <p class=\"mt-6\">Loading...</p>,\n        value: (value) => (\n          <>\n            <p class=\"my-6 text-5xl tabular-nums\">{value}</p>\n            <button\n              class=\"rounded bg-zinc-900 px-4 py-2 text-white\"\n              type=\"button\"\n              onClick={() => void increment()}\n            >\n              Increment by {counterIncrement}\n            </button>\n          </>\n        ),\n      })}\n    </main>\n  );\n}\n\nexport default app({\n  title: \"Counter\",\n  component: App,\n});\n```\n\nIgnotum loads Tailwind automatically. You do not need an HTML file, Vite configuration, Tailwind\nconfiguration, or framework stylesheet. Custom CSS files are ordinary client modules and can use\nany filename when imported from app code.\n\nThe `client/icon.svg` file is optional. When present, Ignotum discovers it automatically and uses it\nas the favicon. When absent, the app has no favicon link.\n\nThe top-level `public` directory is optional. Its AVIF, GIF, ICO, JPEG, PNG, WebP, and PDF files keep\ntheir relative paths as public URLs. Do not put this directory inside `client`.\n\n## Run the app\n\nStart the dev server:\n\n```sh\nnpx ignotum dev\n```\n\nOpen <http://127.0.0.1:3210>. Ignotum creates `_generated` before starting the app.\n\nRead [schema syntax](schema.md), [server functions](server-functions.md),\n[database reads](reading-data.md), [database writes](writing-data.md), and the\n[client guide](client.md) to continue building the app.\n"],
+		["reading-data.md", "# Read from the database\n\nQuery and mutation handlers can read documents through `ctx.db`. Every read is explicit: a table\nquery reads that table, while an indexed query follows an index declared in the schema. Ignotum\ndoes not silently load a table and filter it to make an unindexed operation look efficient.\n\n## Read one document\n\nUse `find` when a missing document is an ordinary result:\n\n```ts\nconst todo = yield * ctx.db.find(\"todos\", args.id);\n// Todo | undefined\n```\n\nUse `get` when the document should exist:\n\n```ts\nconst todo = yield * ctx.db.get(\"todos\", args.id);\n// Todo\n```\n\nA missing `get` fails with `DocumentNotFound`, which contains the table and ID. You can expose it,\ncatch it, or map it to one of your own application errors.\n\n## Read a table\n\n`collect` returns every document in the query:\n\n```ts\nconst todos = yield * ctx.db.query(\"todos\").collect();\n```\n\nThis is the right API when the table is intentionally small or the function genuinely needs every\ndocument. It is a full table read, not an indexed lookup. Hosted collection limits still apply.\n\nQueries use ascending `createdAt` order by default, with `id` breaking ties. Reverse the order with\n`order(\"desc\")`:\n\n```ts\nconst newestFirst = yield * ctx.db.query(\"todos\").order(\"desc\").take(20);\n```\n\n## Read through an index\n\nDeclare indexes in the schema, then select one by name:\n\n```ts\n// server/schema.ts\ntodos: table({\n  channel: values.string(),\n  priority: values.integer(),\n  text: values.string(),\n}).index(\"by_channel_priority\", [\"channel\", \"priority\"]);\n```\n\n```ts\nconst todos =\n  yield *\n  ctx.db\n    .query(\"todos\")\n    .index(\"by_channel_priority\", (range) =>\n      range.eq(\"channel\", args.channel).gte(\"priority\", args.minimumPriority),\n    )\n    .collect();\n```\n\nRange fields must follow the index order. Use equality on any leading fields, then optionally add a\nlower bound, an upper bound, or both on the next field:\n\n| Method              | Matches                          |\n| ------------------- | -------------------------------- |\n| `eq(field, value)`  | Equal to `value`                 |\n| `gt(field, value)`  | Greater than `value`             |\n| `gte(field, value)` | Greater than or equal to `value` |\n| `lt(field, value)`  | Less than `value`                |\n| `lte(field, value)` | Less than or equal to `value`    |\n\nFor a two-sided range, chain the bounds on the same field:\n\n```ts\nconst thisWeek =\n  yield *\n  ctx.db\n    .query(\"events\")\n    .index(\"by_workspace_start\", (range) =>\n      range\n        .eq(\"workspaceId\", args.workspaceId)\n        .gte(\"start\", args.weekStart)\n        .lt(\"start\", args.nextWeek),\n    )\n    .collect();\n```\n\nCalling `index` without a range scans that index in its declared order:\n\n```ts\nconst byPriority = yield * ctx.db.query(\"todos\").index(\"by_priority\").collect();\n```\n\nEvery index orders by its declared fields, then `createdAt`, then `id`. The two system fields are\navailable as range fields after all declared fields have been matched with `eq`.\n\n## Choose how many documents to return\n\nAll table and index queries support these terminal methods:\n\n| Method              | Result                                                                 |\n| ------------------- | ---------------------------------------------------------------------- |\n| `collect()`         | Every matching document                                                |\n| `take(number)`      | At most `number` matching documents                                    |\n| `first()`           | The first matching document, or `undefined`                            |\n| `unique()`          | The only matching document, `undefined`, or a failure if several match |\n| `paginate(options)` | One page and a cursor for the next page                                |\n\n`unique()` checks a query result; it does not add a uniqueness constraint to the index. Use\n`first()` when several matches are valid and only the first one matters.\n\nUse `take` or `first` whenever the function only needs a bounded result. Use `collect` when reading\nthe complete matching set is intentional.\n\n## Read pages\n\nAdd a `pagination` argument and return a page validator when a client should load a long ordered\nlist in parts:\n\n```ts\nconst Todo = values.doc(\"todos\");\n\nexport const list = query({\n  args: {\n    completed: values.boolean(),\n    pagination: values.pagination(),\n  },\n  returns: values.page(Todo),\n\n  handler: function* (ctx, { completed, pagination }) {\n    return yield* ctx.db\n      .query(\"todos\")\n      .index(\"by_completed\", (range) => range.eq(\"completed\", completed))\n      .order(\"desc\")\n      .paginate(pagination);\n  },\n});\n```\n\nA page contains `items` and `nextCursor`. A `null` cursor means there are no more matching\ndocuments. Pass a non-null cursor back through `pagination` to continue the same table, index,\nrange, and order. Cursors are opaque and must not be parsed or changed.\n\nPage sizes are integers from 1 through 1,000. Prefer an index for paginated filters so the database\ncan read the requested range directly.\n\n## Reads in mutations\n\nMutation handlers receive the same read API and observe their earlier writes in that mutation.\nThis makes read-modify-write logic straightforward:\n\n```ts\nconst todo = yield * ctx.db.get(\"todos\", args.id);\nyield * ctx.db.patch(\"todos\", todo.id, { completed: !todo.completed });\n```\n\nSee [Write to the database](writing-data.md) for the write methods and transaction behavior.\n"],
+		["schema.md", "# Schema syntax\n\nDefine the data model in `server/schema.ts`. The keys returned from `defineSchema` are table\nnames, and each `table` call defines that table's fields:\n\n```ts\nimport { defineSchema } from \"ignotum/server\";\n\nexport default defineSchema(({ table, values }) => ({\n  users: table({\n    name: values.string(),\n  }),\n  todos: table({\n    text: values.string(),\n    completed: values.boolean(),\n    ownerId: values.optional(values.id(\"users\")),\n  }).index(\"by_completed\", [\"completed\"]),\n}));\n```\n\n## Field values\n\nRead [values](values.md) for the complete validator list and the TypeScript type produced by each\none. `values.id` only accepts a table declared in the same schema. Arrays and objects can be nested,\nand their contents can use any value validator.\n\n## System fields\n\nIgnotum adds three fields to every stored document:\n\n| Field       | Type                      |\n| ----------- | ------------------------- |\n| `id`        | The ID type for its table |\n| `createdAt` | `Date`                    |\n| `updatedAt` | `Date`                    |\n\nDo not declare these fields in a table. Do not pass them to `insert`, `patch`, or `replace`.\n\n## Indexes\n\nChain `index` after a table to declare an ordered index. The first argument is its name; the second\nis the field order:\n\n```ts\nmessages: table({\n  channel: values.string(),\n  authorId: values.id(\"users\"),\n  text: values.string(),\n})\n  .index(\"by_channel\", [\"channel\"])\n  .index(\"by_channel_author\", [\"channel\", \"authorId\"]);\n```\n\nIndex fields must be required booleans, dates, IDs, integers, numbers, strings, or literals. Field\norder matters: `by_channel_author` can efficiently select one channel, or one channel and author,\nbut it is not an author-only index.\n\nEvery index uses `createdAt` and `id` as its final ordering fields. Read\n[Read from the database](reading-data.md) for selecting indexes, building ranges, ordering results,\nand choosing a result method.\n\n## Generated types\n\n`_generated/types.ts` exports the data model, document, and ID types:\n\n```ts\nimport type { DataModel, Doc, Id } from \"@/_generated/types.js\";\n\ntype Todo = Doc<\"todos\">;\ntype TodoId = Id<\"todos\">;\n```\n\n`Doc<\"todos\">` includes the fields from the `todos` table and its three system fields. An\n`Id<\"todos\">` cannot be passed where an `Id<\"users\">` is required.\n"],
+		["server-functions.md", "# Server functions\n\nPut queries and mutations in `.ts` files directly inside `server`. The file name becomes the API\nmodule, and each exported function keeps its export name:\n\n```text\nserver/todos.ts -> api.todos.list\nserver/users.ts -> api.users.get\n```\n\nIgnotum ignores `schema.ts`, `index.ts`, test files, and names beginning with `_`.\n\nImport schema-bound builders from the generated server file. Import `Result` only when the module\nintroduces or catches typed errors:\n\n```ts\nimport { Result } from \"ignotum/server\";\n\nimport { mutation, query, values } from \"@/_generated/server.js\";\n```\n\nKeep the `.js` suffix on generated imports.\n\n## Define a function\n\nA function has optional argument, return, and public error schemas, plus a generator handler:\n\n```ts\nexport const getTitle = query({\n  args: {\n    id: values.id(\"todos\"),\n  },\n  returns: values.string(),\n\n  handler: function* (ctx, args) {\n    const todo = yield* ctx.db.get(\"todos\", args.id);\n    return todo.text;\n  },\n});\n```\n\nOmit `args` when the function takes no arguments. Omit `returns` when it returns nothing. An\nomitted `returns` only permits a `void` handler; Ignotum never infers an unchecked return schema.\n`yield*` waits for an Ignotum operation and propagates its typed application errors. Return\nsuccessful values with ordinary `return`.\n\nIgnotum validates arguments before running the handler. It also validates returned values and\npublic application errors before sending them to a client.\n\nAn argument-free query and a mutation with no return value can stay small:\n\n```ts\nconst Todo = values.doc(\"todos\");\n\nexport const list = query({\n  returns: values.array(Todo),\n\n  handler: function* (ctx) {\n    return yield* ctx.db.query(\"todos\").collect();\n  },\n});\n\nexport const remove = mutation({\n  args: { id: values.id(\"todos\") },\n\n  handler: function* (ctx, args) {\n    yield* ctx.db.delete(\"todos\", args.id);\n  },\n});\n```\n\nCall an argument-free query as `useQuery(api.todos.list)`. An argument-free mutation returns a\nzero-argument function:\n\n```ts\nconst clear = useMutation(api.todos.clear);\nvoid clear();\n```\n\n## Database access\n\nQuery handlers receive the read API. Mutation handlers receive the same reads plus writes, and all\nof a mutation's writes commit together.\n\n- [Read from the database](reading-data.md) covers `find`, `get`, table and index queries, ranges,\n  ordering, `collect`, `take`, `first`, and `unique`.\n- [Write to the database](writing-data.md) covers `insert`, `patch`, `replace`, `delete`, and\n  mutation behavior.\n\nHosted apps limit document size, collection reads, function runtime, and stored app data. See\n[Limits](limits.md) for the current values.\n\n## Application errors\n\nDefine an application error with `values.error`. Its name becomes `_tag`:\n\n```ts\nconst TodoNotFound = values.error(\"TodoNotFound\", {\n  id: values.id(\"todos\"),\n});\n```\n\n`Result.fail` deliberately stops the operation with a typed error:\n\n```ts\nyield * Result.fail(TodoNotFound({ id: args.id }));\n```\n\nThe `errors` field is optional. If omitted, Ignotum infers the handler's remaining application\nerrors. If supplied, it is the public contract and the handler must conform to it:\n\n```ts\nexport const toggle = mutation({\n  args: {\n    id: values.id(\"todos\"),\n  },\n  returns: values.boolean(),\n  errors: TodoNotFound,\n\n  handler: function* (ctx, args) {\n    const todo = yield* ctx.db.get(\"todos\", args.id).catch({\n      DocumentNotFound: (error) => Result.fail(TodoNotFound({ id: error.id })),\n    });\n\n    const completed = !todo.completed;\n    yield* ctx.db.patch(\"todos\", args.id, { completed });\n    return completed;\n  },\n});\n```\n\nCombine public errors with `values.union`:\n\n```ts\nerrors: values.union(InvalidTodoText, TodoLimitReached),\n```\n\n## Catch and recover\n\nEvery Result operation has a partial, tag-based `catch`. Handlers receive the narrowed error type.\nUnmatched errors continue through the channel:\n\n```ts\nconst settings =\n  yield *\n  loadSettings().catch({\n    SettingsNotFound: () => defaultSettings,\n  });\n```\n\nReturn a plain value to recover. Return `Result.fail(...)` to map one error to another. Unknown tag\nnames fail the TypeScript check.\n\nUse `Result.try` for one catch boundary around several operations:\n\n```ts\nconst author =\n  yield *\n  Result.try(function* () {\n    const membership = yield* ctx.db.get(\"memberships\", topic.membershipId);\n    return yield* ctx.db.get(\"users\", membership.userId);\n  }).catch({\n    DocumentNotFound: () => Result.fail(InvalidAuthor({ topicId: topic.id })),\n  });\n```\n\nThere is no async variant. Ignotum operations always use `yield*` in server code.\n\n## Standalone results\n\n`Result.succeed` remains useful for helpers that return a Result:\n\n```ts\nfunction validateName(name: string) {\n  if (name.length === 0) {\n    return Result.fail(InvalidName({}));\n  }\n\n  return Result.succeed(name.trim());\n}\n```\n\nA handler can use the helper with `const name = yield* validateName(args.name)`. Normal handlers do\nnot wrap successful returns in `Result.succeed`.\n\n## Internal failures and defects\n\nDatabase outages, internal runtime failures, and thrown JavaScript exceptions are not application\nerrors. Ignotum logs their full cause and sends only:\n\n```ts\n{\n  _tag: \"InternalServerError\",\n  requestId: \"...\",\n}\n```\n\nEvery generated client function includes `InternalServerError` in its Result error union. The\nrequest ID links the client-visible failure to server logs without exposing private details.\n`InternalServerError` is reserved by Ignotum: never define it with `values.error` or include it in a\nfunction's `errors` schema.\n"],
+		["values.md", "# Values\n\nUse `values` validators to describe table fields, function arguments, return values, and application\nerrors. Each validator checks values at runtime and supplies the matching TypeScript type.\n\n| Validator                                 | TypeScript type                       | Notes                                                                                                |\n| ----------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------- |\n| `values.string()`                         | `string`                              |                                                                                                      |\n| `values.number()`                         | `number`                              | Accepts finite JavaScript numbers, including integers.                                               |\n| `values.integer()`                        | `number`                              | Accepts safe integers.                                                                               |\n| `values.boolean()`                        | `boolean`                             |                                                                                                      |\n| `values.date()`                           | `Date`                                | Accepts valid JavaScript dates.                                                                      |\n| `values.null()`                           | `null`                                | Accepts only `null`.                                                                                 |\n| `values.literal(value)`                   | The exact type of `value`             | Accepts one string, finite number, or boolean value.                                                 |\n| `values.literals(first, second, ...rest)` | A union of the supplied literal types | Requires at least two string, finite number, or boolean values.                                      |\n| `values.id(\"todos\")`                      | `Id<\"todos\">`                         | Accepts an ID for a table declared in the same schema. IDs for different tables are different types. |\n| `values.doc(\"todos\")`                     | `Doc<\"todos\">`                        | Accepts a complete document, including its `id`, `createdAt`, and `updatedAt` system fields.         |\n| `values.pagination()`                     | Pagination options                    | Defines the `pagination` argument used by `.paginate(...)`.                                          |\n| `values.page(value)`                      | A page of `T`                         | Defines the return value of a paginated query.                                                       |\n| `values.optional(value)`                  | `T \\| undefined`                      | Makes an object or table field optional. The field may be omitted.                                   |\n| `values.nullable(value)`                  | `T \\| null`                           | The value remains required unless it is also wrapped with `optional`.                                |\n| `values.array(value)`                     | `ReadonlyArray<T>`                    | Every item must match `value`.                                                                       |\n| `values.object(fields)`                   | An object matching `fields`           | Defines an object with known field names.                                                            |\n| `values.record(value)`                    | `Readonly<Record<string, T>>`         | Defines an object with dynamic string keys whose values all match `value`.                           |\n| `values.union(...values)`                 | A union of the supplied types         | Accepts a value matching any supplied validator.                                                     |\n| `values.never()`                          | `never`                               | No value can pass this validator.                                                                    |\n| `values.error(\"Name\", fields)`            | A tagged error object                 | Defines an application error whose `_tag` is the supplied name.                                      |\n\n`T` means the TypeScript type produced by the wrapped validator.\n\n`values.doc`, `values.pagination`, and `values.page` are available on the schema-bound `values`\nexported by `_generated/server.ts`. They are not available while defining `server/schema.ts`.\n\n## Object transforms\n\nValidators created by `values.object(fields)` and `values.doc(\"table\")` support these chainable\nmethods:\n\n| Method              | Result                                                               |\n| ------------------- | -------------------------------------------------------------------- |\n| `.pick(...keys)`    | Keeps the listed fields. Every key must exist.                       |\n| `.omit(...keys)`    | Removes the listed fields. Every key must exist.                     |\n| `.extend(fields)`   | Adds fields. It rejects names that already exist.                    |\n| `.override(fields)` | Replaces validators for existing fields. It rejects new field names. |\n| `.partial()`        | Makes every current field optional.                                  |\n\nEach method works from the result of the previous method. Added fields can be picked, omitted, or\noverridden immediately. An omitted name can be added again with a different validator.\n\n```ts\nconst TodoInput = values.doc(\"todos\").omit(\"id\", \"createdAt\", \"updatedAt\").partial().extend({\n  requestId: values.string(),\n});\n```\n\nUse `override` when changing an existing field. This makes replacements visible in the definition\nand prevents `extend` from silently weakening fields such as `id`:\n\n```ts\nconst EditableTodo = values.doc(\"todos\").override({\n  title: values.optional(values.string()),\n});\n```\n\nThese methods are only available on fixed object validators. Arrays, records, unions, errors, and\nprimitive validators do not expose them. After transforming a document validator, its inferred type\nmatches the current fields in the chain rather than the complete document type.\n\n### Reuse embedded objects in the schema\n\nCreate a fixed object validator inside the `defineSchema` callback when several stored fields share\nan object shape. A transform can derive a stored variant without repeating its fields:\n\n```ts\ndefineSchema(({ table, values }) => {\n  const Contact = values.object({\n    email: values.string(),\n    phone: values.string(),\n  });\n\n  return {\n    users: table({\n      contact: Contact,\n    }),\n    publicProfiles: table({\n      contact: Contact.omit(\"phone\"),\n    }),\n  };\n});\n```\n\nThis pattern suits embedded objects stored by more than one table, including full and reduced\nversions of the same object. The base validator stays inside `defineSchema`, where `values.id` can\ncheck its table references against the completed schema.\n\n### Derive server function validators from documents\n\nUse the schema-bound `values` from `_generated/server.ts` when a function input or output follows a\nstored document. These validators know every table name and the complete document fields, including\n`id`, `createdAt`, and `updatedAt`.\n\nReusable server validators can live in an ignored server module such as `server/_validators.ts`:\n\n```ts\nimport { values } from \"@/_generated/server.js\";\n\nexport const TodoInput = values.doc(\"todos\").omit(\"id\", \"createdAt\", \"updatedAt\").partial();\n\nexport const PublicTodo = values.doc(\"todos\").omit(\"updatedAt\");\n```\n\nImport these validators into queries and mutations that need the same contract. This works well for\npatch inputs and document projections. Do not import generated validators into `server/schema.ts`.\nDocument validators depend on the schema, so importing them while defining that schema would create\na cycle.\n\n## Examples\n\n```ts\nconst TodoStatus = values.literals(\"pending\", \"completed\");\n\nconst Todo = values.doc(\"todos\");\n\nexport const list = query({\n  returns: values.array(Todo),\n  handler: function* (ctx) {\n    return yield* ctx.db.query(\"todos\").collect();\n  },\n});\n```\n\nUse the other validators to define reusable values that do not represent a stored document:\n\n```ts\nconst TodoInput = values.object({\n  status: TodoStatus,\n  scheduledAt: values.nullable(values.date()),\n  scores: values.record(values.integer()),\n  title: values.string(),\n});\n```\n\nUse `optional` when a field may be absent. Use `nullable` when a present field may contain `null`:\n\n```ts\nvalues.object({\n  nickname: values.optional(values.string()),\n  deletedAt: values.nullable(values.date()),\n});\n```\n"],
+		["writing-data.md", "# Write to the database\n\nMutation handlers can insert, patch, replace, and delete documents through `ctx.db`. Query handlers\nonly receive the read API.\n\n## Insert\n\n`insert` creates a document and returns its table-specific ID:\n\n```ts\nconst id =\n  yield *\n  ctx.db.insert(\"todos\", {\n    text: \"Learn Ignotum\",\n    completed: false,\n  });\n```\n\nSupply every required table field. Omit optional fields when they have no value. Ignotum supplies\n`id`, `createdAt`, and `updatedAt`; never pass those system fields yourself.\n\n## Patch\n\n`patch` changes only the supplied fields:\n\n```ts\nyield * ctx.db.patch(\"todos\", args.id, { completed: true });\n```\n\nAll other fields keep their current values. Patching a missing document has no effect.\n\n## Replace\n\n`replace` supplies a new complete set of application fields:\n\n```ts\nyield *\n  ctx.db.replace(\"todos\", args.id, {\n    text: \"Build an app\",\n    completed: false,\n  });\n```\n\nEvery required field must be present. The document keeps its `id` and `createdAt`, while\n`updatedAt` advances. Replacing a missing document has no effect.\n\n## Delete\n\n`delete` removes a document by ID:\n\n```ts\nyield * ctx.db.delete(\"todos\", args.id);\n```\n\nDeleting a missing document has no effect.\n\n## Mutation behavior\n\nA mutation sees its earlier writes, including through indexed reads. Ignotum commits all of the\nmutation's writes together after the handler succeeds. If the handler fails with an application\nerror or encounters an internal failure, none of its writes are committed.\n\n```ts\nexport const completeOldest = mutation({\n  handler: function* (ctx) {\n    const todo = yield* ctx.db\n      .query(\"todos\")\n      .index(\"by_completed\", (range) => range.eq(\"completed\", false))\n      .first();\n\n    if (todo !== undefined) {\n      yield* ctx.db.patch(\"todos\", todo.id, { completed: true });\n    }\n  },\n});\n```\n\nRead [Read from the database](reading-data.md) for `find`, `get`, table queries, indexed ranges,\nordering, and result methods.\n"]
 	].map(([name, content]) => ({
 		content,
 		path: `.agents/skills/ignotum/references/${name}`