wizards 0.2.17 → 0.2.19

package/apps/runtime/dist/services/space-origin.js

@@ -0,0 +1,164 @@
+import { and, eq } from "drizzle-orm";
+import { db, schema } from "../db/client.js";
+import { UnreadableDocument } from "../documents/parse.js";
+import { ServiceError } from "./errors.js";
+import { filePaths, pageTree, tablePaths } from "./knowledge.js";
+import { convertDocument, fillCategories, summarizeValues } from "./knowledge-model.js";
+import { putOriginFile } from "./project-files.js";
+import { queueIndex } from "./project-index.js";
+import { putCategory, setItemCategories } from "./space-categories.js";
+import { listOrigin, putOriginPage, putOriginTable, removeOrigin } from "./space-data.js";
+/**
+ * `server.spaceData` of a plugin: Wissen it writes under keys of its own, with Kategorien. The
+ * plugin's id is the origin of everything it writes; a person who changes an item keeps it.
+ */
+export function originData(origin) {
+    return {
+        async putCategories({ space, categories, proposed }) {
+            for (const c of categories) {
+                let tableId = null;
+                if (c.column) {
+                    const table = await db.query.spaceTable.findFirst({
+                        where: and(eq(schema.spaceTable.projectId, space), eq(schema.spaceTable.origin, origin), eq(schema.spaceTable.originKey, c.column.table)),
+                        columns: { id: true },
+                    });
+                    if (!table) {
+                        throw new ServiceError("invalid", `There is no table with the key "${c.column.table}".`);
+                    }
+                    tableId = table.id;
+                }
+                await putCategory(space, {
+                    name: c.name,
+                    type: c.type,
+                    unit: c.unit,
+                    multiple: c.multiple,
+                    ordered: c.ordered,
+                    hint: c.hint,
+                    values: c.values,
+                    tableId,
+                    columnId: c.column?.column ?? null,
+                }, { origin, proposed });
+            }
+        },
+        async putPage(input) {
+            const written = await putOriginPage(origin, {
+                ...input,
+                categories: input.categories,
+            });
+            if (input.fill && written.state === "written") {
+                const changed = await fillCategories(input.space, { pageId: written.id }, input.markdown, input.title).catch((err) => {
+                    console.error(`[plugin ${origin}] Kategorien`, err);
+                    return false;
+                });
+                if (changed) {
+                    queueIndex(`P:${written.id}`);
+                }
+            }
+            return { ...written, path: (await pageTree(input.space)).get(written.id)?.path ?? "" };
+        },
+        async putTable(input) {
+            const written = await putOriginTable(origin, {
+                ...input,
+                categories: input.categories,
+            });
+            return { ...written, path: (await tablePaths(input.space)).get(written.id) ?? "" };
+        },
+        async putFile(input) {
+            const id = await putOriginFile(origin, {
+                ...input,
+                categories: input.categories,
+            });
+            return { id, path: (await filePaths(input.space)).get(id) ?? "" };
+        },
+        async putDocument(input) {
+            const id = await putOriginFile(origin, { ...input, categories: undefined });
+            const file = await db.query.projectFile.findFirst({ where: eq(schema.projectFile.id, id) });
+            if (!file) {
+                throw new ServiceError("not_found", "The document went while it was read.");
+            }
+            const path = (await filePaths(input.space)).get(id) ?? "";
+            const kept = (await db.query.spacePage.findFirst({
+                where: and(eq(schema.spacePage.fileId, id), eq(schema.spacePage.kept, true)),
+                columns: { id: true },
+            })) ??
+                (await db.query.spaceTable.findFirst({
+                    where: and(eq(schema.spaceTable.fileId, id), eq(schema.spaceTable.kept, true)),
+                    columns: { id: true },
+                }));
+            if (kept) {
+                return { id, path, state: "kept", items: [], review: null };
+            }
+            let converted;
+            try {
+                converted = await convertDocument(file, input.data);
+            }
+            catch (err) {
+                if (err instanceof UnreadableDocument) {
+                    queueIndex(`f:${id}`);
+                    return { id, path, state: "written", items: [], review: err.message };
+                }
+                throw err;
+            }
+            await db
+                .update(schema.projectFile)
+                .set({
+                textHash: converted.textHash,
+                pages: converted.pages,
+                chars: converted.chars,
+                updatedAt: new Date(),
+            })
+                .where(eq(schema.projectFile.id, id));
+            const [tree, tables] = await Promise.all([pageTree(input.space), tablePaths(input.space)]);
+            const items = await Promise.all(converted.items.map(async (key) => {
+                const itemId = key.slice(2);
+                if (key[0] === "p") {
+                    const node = tree.get(itemId);
+                    return {
+                        kind: "page",
+                        id: itemId,
+                        path: node?.path ?? "",
+                        title: node?.title ?? "",
+                    };
+                }
+                const table = await db.query.spaceTable.findFirst({
+                    where: eq(schema.spaceTable.id, itemId),
+                    columns: { title: true },
+                });
+                return {
+                    kind: "table",
+                    id: itemId,
+                    path: tables.get(itemId) ?? "",
+                    title: table?.title ?? "",
+                };
+            }));
+            const first = items[0];
+            const ref = first
+                ? first.kind === "page"
+                    ? { pageId: first.id }
+                    : { tableId: first.id }
+                : { fileId: id };
+            if (input.categories) {
+                await setItemCategories(input.space, ref, input.categories, "origin");
+            }
+            if (input.fill) {
+                await fillCategories(input.space, ref, converted.text, input.name).catch((err) => {
+                    console.error(`[plugin ${origin}] Kategorien`, err);
+                    return false;
+                });
+            }
+            if (input.categories || input.fill) {
+                queueIndex(first ? `${first.kind === "page" ? "P" : "t"}:${first.id}` : `f:${id}`);
+            }
+            const review = first?.kind === "page"
+                ? ((await db.query.spacePage.findFirst({
+                    where: eq(schema.spacePage.id, first.id),
+                    columns: { review: true },
+                }))?.review ?? null)
+                : null;
+            return { id, path, state: "written", items, review };
+        },
+        list: (space) => listOrigin(origin, space),
+        remove: (space, key) => removeOrigin(origin, space, key),
+        summarize: (space, category, value) => summarizeValues(space, category, value),
+    };
+}

package/apps/runtime/dist/services/spaces.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { tableColumnsSchema } from "@engenty-wizards/shared/engenty/data-tables";
+import { CATEGORY_TYPES } from "@engenty-wizards/shared/knowledge";
 import { PROJECT_LIMITS } from "@engenty-wizards/shared/projects";
 import { SPACE_DATA_LIMITS } from "@engenty-wizards/shared/space-data";
 import { WORKSPACE_LIMITS } from "@engenty-wizards/shared/workspace";
@@ -17,6 +18,7 @@ import { emitDraftChanged } from "./draft-events.js";
 import { notFound, ServiceError } from "./errors.js";
 import { keepFiles, replaceFiles } from "./files.js";
 import { addProjectFile, projectFiles, removeProjectFile } from "./project-files.js";
+import { reindexSpace } from "./project-index.js";
 import { brandColorSchema, projectFactSchema, projectLimit, removeProject, } from "./projects.js";
 import { deleteWizard, draftIssues, parseDraft, rotateShareLink, shareUrl } from "./wizards.js";
 /**
@@ -411,11 +413,15 @@ export async function removeSyncedSpace(rawSpaceId) {
 // --- the space's own tables and pages --------------------------------------------
 // What the admin made under Space → Daten on the install, not what a wizard keeps: those stay
 // where their runs write them. Sent as a whole, it replaces what came before.
+// Since Wissen: sub-pages, where an item came from, Kategorien and what has them. An install of
+// before sends none of it.
 export const syncDataSchema = z.object({
     tables: z
         .array(z.object({
         id: syncedId,
         title: z.string().min(1).max(120),
+        format: z.enum(["faq"]).nullish(),
+        originLabel: z.string().max(120).nullish(),
         columns: tableColumnsSchema,
         rows: z
             .array(z.object({ id: syncedId, cells: z.record(z.string(), z.unknown()) }))
@@ -427,8 +433,48 @@ export const syncDataSchema = z.object({
         id: syncedId,
         title: z.string().min(1).max(200),
         markdown: z.string().max(SPACE_DATA_LIMITS.pageChars),
+        parentId: syncedId.nullish(),
+        position: z.number().int().min(0).optional(),
+        originLabel: z.string().max(120).nullish(),
     }))
         .max(SPACE_DATA_LIMITS.pages),
+    categories: z
+        .array(z.object({
+        id: syncedId,
+        name: z.string().min(1).max(80),
+        type: z.enum(CATEGORY_TYPES),
+        unit: z.string().max(20).nullish(),
+        multiple: z.boolean(),
+        ordered: z.boolean(),
+        hint: z.string().max(120).nullish(),
+        tableId: syncedId.nullish(),
+        columnId: z.string().max(64).nullish(),
+        position: z.number().int().min(0),
+        values: z
+            .array(z.object({
+            id: syncedId,
+            value: z.string().min(1).max(200),
+            position: z.number().int().min(0),
+            summary: z.string().max(20_000).nullish(),
+        }))
+            .max(2000),
+    }))
+        .max(60)
+        .optional(),
+    /** `p:<page>`, `t:<table>`, `r:<row>`: files stay with the install. */
+    assignments: z
+        .array(z.object({
+        categoryId: syncedId,
+        item: z.string().regex(/^[ptr]:[A-Za-z0-9_-]{8,40}$/),
+        valueId: syncedId.nullish(),
+        text: z.string().max(300).nullish(),
+        num: z.number().nullish(),
+        at: z.number().int().nullish(),
+        bool: z.boolean().nullish(),
+        by: z.enum(["person", "origin", "model"]),
+    }))
+        .max(200_000)
+        .optional(),
 });
 /**
  * Takes the space's own tables and pages a local install sent: those it no longer has go, the
@@ -491,12 +537,120 @@ export async function syncSpaceData(rawSpaceId, input) {
             }
         }
         for (const page of input.pages) {
-            const values = { title: page.title, markdown: page.markdown, updatedAt: now };
+            const values = {
+                title: page.title,
+                markdown: page.markdown,
+                position: page.position ?? 0,
+                originLabel: page.originLabel ?? null,
+                // Its place comes after every page is there.
+                parentId: null,
+                slug: null,
+                updatedAt: now,
+            };
             await db
                 .insert(schema.spacePage)
                 .values({ id: page.id, tenantId: currentTenant(), projectId: spaceId, ...values })
                 .onConflictDoUpdate({ target: schema.spacePage.id, set: values });
         }
+        const pagesThere = new Set(pageIds);
+        for (const page of input.pages) {
+            if (page.parentId && pagesThere.has(page.parentId) && page.parentId !== page.id) {
+                await db
+                    .update(schema.spacePage)
+                    .set({ parentId: page.parentId })
+                    .where(eq(schema.spacePage.id, page.id));
+            }
+        }
+        for (const table of input.tables) {
+            await db
+                .update(schema.spaceTable)
+                .set({ format: table.format ?? null, originLabel: table.originLabel ?? null, slug: null })
+                .where(eq(schema.spaceTable.id, table.id));
+        }
+        if (input.categories) {
+            await syncCategories(spaceId, input.categories, input.assignments ?? []);
+        }
     });
+    await reindexSpace(spaceId);
     return { tables: input.tables.length, pages: input.pages.length };
 }
+/** The Kategorien a local install sent, their values, and what has them: they replace these here. */
+async function syncCategories(spaceId, categories, assignments) {
+    const ids = categories.map((c) => c.id);
+    const taken = ids.length
+        ? await db.query.spaceCategory.findMany({
+            where: inArray(schema.spaceCategory.id, ids),
+            columns: { id: true, projectId: true },
+        })
+        : [];
+    if (taken.some((c) => c.projectId !== spaceId)) {
+        throw new ServiceError("refused", "Eine Kennung ist hier schon vergeben.", {
+            reason: "id_taken",
+        });
+    }
+    await db
+        .delete(schema.spaceCategory)
+        .where(and(eq(schema.spaceCategory.projectId, spaceId), ids.length ? notInArray(schema.spaceCategory.id, ids) : undefined));
+    await db.delete(schema.spaceItemCategory).where(eq(schema.spaceItemCategory.projectId, spaceId));
+    const tables = new Set((await db.query.spaceTable.findMany({
+        where: eq(schema.spaceTable.projectId, spaceId),
+        columns: { id: true },
+    })).map((t) => t.id));
+    const values = new Set();
+    for (const c of categories) {
+        const row = {
+            name: c.name,
+            type: c.type,
+            unit: c.unit ?? null,
+            multiple: c.multiple,
+            ordered: c.ordered,
+            hint: c.hint ?? null,
+            proposed: false,
+            tableId: c.tableId && tables.has(c.tableId) ? c.tableId : null,
+            columnId: c.tableId && tables.has(c.tableId) ? (c.columnId ?? null) : null,
+            position: c.position,
+            updatedAt: new Date(),
+        };
+        await db
+            .insert(schema.spaceCategory)
+            .values({ id: c.id, tenantId: currentTenant(), projectId: spaceId, ...row })
+            .onConflictDoUpdate({ target: schema.spaceCategory.id, set: row });
+        const valueIds = c.values.map((v) => v.id);
+        await db
+            .delete(schema.spaceCategoryValue)
+            .where(and(eq(schema.spaceCategoryValue.categoryId, c.id), valueIds.length ? notInArray(schema.spaceCategoryValue.id, valueIds) : undefined));
+        for (const v of c.values) {
+            const set = {
+                value: v.value,
+                position: v.position,
+                summary: v.summary ?? null,
+                summaryAt: v.summary ? new Date() : null,
+            };
+            await db
+                .insert(schema.spaceCategoryValue)
+                .values({ id: v.id, categoryId: c.id, ...set })
+                .onConflictDoUpdate({ target: schema.spaceCategoryValue.id, set });
+            values.add(v.id);
+        }
+    }
+    const known = new Set(ids);
+    const rows = assignments.filter((a) => known.has(a.categoryId) && (!a.valueId || values.has(a.valueId)));
+    for (let i = 0; i < rows.length; i += 200) {
+        await db.insert(schema.spaceItemCategory).values(rows.slice(i, i + 200).map((a) => {
+            const id = a.item.slice(2);
+            return {
+                projectId: spaceId,
+                categoryId: a.categoryId,
+                pageId: a.item[0] === "p" ? id : null,
+                tableId: a.item[0] === "t" ? id : null,
+                rowId: a.item[0] === "r" ? id : null,
+                valueId: a.valueId ?? null,
+                text: a.text ?? null,
+                num: a.num ?? null,
+                at: a.at ?? null,
+                bool: a.bool ?? null,
+                by: a.by,
+            };
+        }));
+    }
+}

package/apps/runtime/dist/tools/pages.js

@@ -1,11 +1,12 @@
 import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 import { runPages, writeRunPage } from "../services/space-data.js";
+import { pageReadInput, readKnowledgePage } from "./project.js";
 import { attempt, clip } from "./shared.js";
 /**
- * Pages of the space for a step that lists "pages": Markdown its wizard keeps for every run —
- * notes, a log, a summary that grows — and the space's own pages to read. They stand in the
- * studio under Space → Daten.
+ * Pages for a step that lists "pages": Markdown its wizard keeps for every run — notes, a log, a
+ * summary that grows — shown in the studio under Space → Daten. Its page_read also reads the
+ * pages of Wissen, by path.
  */
 export function pageTools(ctx) {
     const projectId = ctx.project.id;
@@ -13,29 +14,33 @@ export function pageTools(ctx) {
     return {
         page_read: createTool({
             id: "page_read",
-            description: "Read a page of the space: one this wizard wrote, or one of the space's own. Without a title it lists the pages there are.",
-            inputSchema: z.object({ title: z.string().optional() }),
-            execute: ({ title }) => attempt(async () => {
-                const pages = await runPages(projectId, wizardId);
-                const of = (p) => (p.wizardId ? "wizard" : "space");
-                if (!title?.trim()) {
-                    return {
-                        pages: pages.map((p) => ({ title: p.title, of: of(p), chars: p.markdown.length })),
-                    };
-                }
-                const page = pages.find((p) => p.title.toLowerCase() === title.trim().toLowerCase());
-                if (!page) {
-                    return {
-                        error: `No page "${title}".`,
-                        pages: pages.map((p) => p.title),
-                    };
-                }
-                return { title: page.title, of: of(page), markdown: clip(page.markdown, 40_000) };
+            description: "Read a page: one this wizard wrote, by its title, or a page of Wissen, by its path (pages/…). Without either it lists the wizard's pages.",
+            inputSchema: z.object({
+                title: z.string().optional().describe("A page this wizard wrote"),
+                path: pageReadInput.path.optional(),
+                section: pageReadInput.section,
+                from: pageReadInput.from,
             }),
+            execute: ({ title, path, section, from }) => {
+                if (path?.trim()) {
+                    return readKnowledgePage(ctx, { path, section, from });
+                }
+                return attempt(async () => {
+                    const pages = await runPages(projectId, wizardId);
+                    if (!title?.trim()) {
+                        return { pages: pages.map((p) => ({ title: p.title, chars: p.markdown.length })) };
+                    }
+                    const page = pages.find((p) => p.title.toLowerCase() === title.trim().toLowerCase());
+                    if (!page) {
+                        return { error: `No page "${title}".`, pages: pages.map((p) => p.title) };
+                    }
+                    return { title: page.title, markdown: clip(page.markdown, 40_000) };
+                });
+            },
         }),
         page_write: createTool({
             id: "page_write",
-            description: "Write a page of this wizard in Markdown, kept for every later run and shown to the admin in the studio. A page with the same title is replaced — or added to with append: true (a log, a list that grows). The space's own pages are read-only.",
+            description: "Write a page of this wizard in Markdown, kept for every later run and shown to the admin in the studio. A page with the same title is replaced — or added to with append: true (a log, a list that grows). Pages of Wissen are read-only.",
             inputSchema: z.object({
                 title: z.string().min(1).max(200),
                 markdown: z.string().max(200_000),

package/apps/runtime/dist/tools/project.js

@@ -1,64 +1,154 @@
+import { whereSchema } from "@engenty-wizards/shared/knowledge";
 import { createTool } from "@mastra/core/tools";
+import { and, eq } from "drizzle-orm";
 import { z } from "zod";
-import { documentText, hasIndexEntries, searchProject } from "../services/project-index.js";
+import { db, schema } from "../db/client.js";
+import { filePaths, knowledgeCounts, listForStep, readPage, readTable, resolvePath, } from "../services/knowledge.js";
+import { documentText, hasIndexEntries, searchKnowledge } from "../services/project-index.js";
 import { attempt, clip } from "./shared.js";
 /**
- * The project's documents, for every agent step of its wizards: search the index, read one
- * whole. The search also finds what the space's plugins put into the index.
+ * Wissen, for every agent step of the space's wizards: search it (a question, filtered by
+ * Kategorien first, checked by a classifier after), list it by Kategorien, read a page, a table
+ * or a file whole by its path. Hits and reads look like files — a path, front matter, Markdown or
+ * CSV — so a model reads them as it reads files. The search also finds what the space's plugins
+ * put into the index.
  */
+const where = whereSchema
+    .optional()
+    .describe('Filter by Kategorien before searching, by their names: a value ("Baustelle": "Graz Süd"), a list of values, a range of numbers ({ "gte": 20000 }) or of days ({ "after": "2026-03-01", "before": "2026-03-31" }), { "contains": "…" } for a text, true/false. project_list without arguments names the Kategorien and their values.');
+export const pageReadInput = {
+    path: z.string().describe("The page's path, as project_search or project_list give it: pages/…"),
+    section: z
+        .string()
+        .optional()
+        .describe("Only this section: a heading of the page, or the start of one"),
+    from: z.number().int().min(0).optional().describe("Character to continue a long page at"),
+};
+/** A page of Wissen by its path, for a step: its front matter and Markdown, in parts. */
+export function readKnowledgePage(ctx, input) {
+    return attempt(async () => {
+        const read = await readPage(ctx.project.id, input.path, input);
+        await ctx.emit("tool", { code: "reads", params: { name: read.path } });
+        return read;
+    });
+}
 export async function projectTools(ctx) {
-    const docs = ctx.projectFiles.filter((f) => f.kind === "document");
-    const entries = await hasIndexEntries(ctx.project.id);
-    if (!(docs.length || entries)) {
+    const projectId = ctx.project.id;
+    const counts = await knowledgeCounts(projectId);
+    const entries = await hasIndexEntries(projectId);
+    if (!(counts.pages || counts.tables || counts.files || entries)) {
         return {};
     }
     const tools = {
         project_search: createTool({
             id: "project_search",
-            description: "Search the project's documents and what its plugins keep for all wizards (wiki pages, questions and answers), and get the passages that fit best. Ask in their language, with the words they would use.",
+            description: "Search Wissen, the space's knowledge: its pages, tables and files, and what its plugins keep (wiki pages, questions and answers). Gives items with their path, Kategorien and best section, each checked for relevance. Ask in their language, with the words they would use; filter with `where` when the task names a Kategorie's value. Then read the items you need whole with page_read or table_read.",
             inputSchema: z.object({
                 query: z.string().describe("What to look for: a question or keywords"),
-                limit: z.number().int().min(1).max(12).optional(),
+                where,
+                limit: z.number().int().min(1).max(12).optional().describe("Items to get, 6 by default"),
             }),
-            execute: ({ query, limit }) => attempt(async () => {
+            execute: (input) => attempt(async () => {
+                const found = await searchKnowledge(projectId, input.query, {
+                    where: input.where,
+                    limit: input.limit,
+                    signal: ctx.signal,
+                });
                 await ctx.emit("tool", {
-                    code: "searchesDocuments",
-                    params: { query: query.slice(0, 60) },
+                    code: "searchesKnowledge",
+                    params: {
+                        query: input.query.slice(0, 60),
+                        relevant: found.hits.length,
+                        candidates: found.candidates,
+                    },
                 });
-                const hits = await searchProject(ctx.project.id, query, limit ?? 6);
                 return {
-                    passages: hits.map((h) => ({ document: h.name, part: h.index, text: h.text })),
+                    hits: found.hits.map((h) => ({
+                        ...(h.path ? { path: h.path } : {}),
+                        title: h.title,
+                        ...(h.categories.length ? { kategorien: h.categories } : {}),
+                        ...(h.heading ? { section: h.heading } : {}),
+                        ...(h.sheet ? { page: h.sheet } : {}),
+                        ...(h.relevance !== null ? { relevance: h.relevance } : {}),
+                        text: clip(h.text, 1500),
+                    })),
+                    checked: found.checked,
+                    candidates: found.candidates,
+                    ...(found.filtered !== null ? { filtered: found.filtered } : {}),
                 };
             }),
         }),
+        project_list: createTool({
+            id: "project_list",
+            description: "List Wissen by its Kategorien. Without `where`: the Kategorien with their values and how many items each has. With `where`: the items it leaves, with their paths — all of them, where project_search gives the best few.",
+            inputSchema: z.object({ where }),
+            execute: (input) => attempt(async () => {
+                const listed = await listForStep(projectId, input.where);
+                await ctx.emit("tool", { code: "listsKnowledge" });
+                return listed;
+            }),
+        }),
     };
-    if (!docs.length) {
-        return tools;
+    if (counts.pages) {
+        tools.page_read = createTool({
+            id: "page_read",
+            description: "Read a page of Wissen whole by its path: front matter (title, Kategorien, its source and original, its parent and sub-pages) and its Markdown. Long pages come in parts: pass `from` to continue. `section` reads one section.",
+            inputSchema: z.object(pageReadInput),
+            execute: (input) => readKnowledgePage(ctx, input),
+        });
+    }
+    if (counts.tables) {
+        tools.table_read = createTool({
+            id: "table_read",
+            description: "Read a table of Wissen by its path: its rows as CSV, filtered by its columns (by their names, like `where` of project_search). A few hundred rows at a time: pass `offset` to continue.",
+            inputSchema: z.object({
+                path: z.string().describe("The table's path: tables/…"),
+                where: whereSchema.optional().describe("Filter by columns, by their names"),
+                columns: z.array(z.string()).max(40).optional().describe("Only these columns"),
+                limit: z.number().int().min(1).max(1000).optional(),
+                offset: z.number().int().min(0).optional(),
+            }),
+            execute: (input) => attempt(async () => {
+                const read = await readTable(projectId, input.path, input);
+                await ctx.emit("tool", { code: "reads", params: { name: read.path } });
+                return read;
+            }),
+        });
+    }
+    if (counts.files) {
+        tools.project_document = createTool({
+            id: "project_document",
+            description: "Read a file of Wissen as text by its path (files/…): a file that is not a page, or the original a page was read from. Long files come in parts: pass `from` to continue.",
+            inputSchema: z.object({
+                path: z
+                    .string()
+                    .describe("The file's path: files/…, as the page's front matter or a hit names it"),
+                from: z.number().int().min(0).optional().describe("Character to start at"),
+            }),
+            execute: ({ path, from }) => attempt(async () => {
+                const found = await resolvePath(projectId, path.startsWith("files/") ? path : `files/${path}`);
+                if (found?.kind !== "file") {
+                    const there = [...(await filePaths(projectId)).values()].slice(0, 40);
+                    throw new Error(`No file "${path}". There are: ${there.join(", ")}`);
+                }
+                const file = await db.query.projectFile.findFirst({
+                    where: and(eq(schema.projectFile.id, found.id), eq(schema.projectFile.projectId, projectId)),
+                });
+                if (!file) {
+                    throw new Error(`No file "${path}".`);
+                }
+                await ctx.emit("tool", { code: "reads", params: { name: file.name } });
+                const text = (await documentText(file)) || file.description;
+                const start = Math.min(from ?? 0, text.length);
+                const part = text.slice(start, start + 12_000);
+                return {
+                    path: found.path,
+                    text: clip(part, 12_000),
+                    next: start + part.length < text.length ? start + part.length : null,
+                    length: text.length,
+                };
+            }),
+        });
     }
-    tools.project_document = createTool({
-        id: "project_document",
-        description: "Read one of the project's documents as text. Long documents come in parts: pass `from` to continue.",
-        inputSchema: z.object({
-            name: z.string().describe("The document's name, as listed"),
-            from: z.number().int().min(0).optional().describe("Character to start at"),
-        }),
-        execute: ({ name, from }) => attempt(async () => {
-            const doc = docs.find((d) => d.name === name) ??
-                docs.find((d) => d.name.toLowerCase().includes(name.toLowerCase()));
-            if (!doc) {
-                throw new Error(`No document "${name}". There are: ${docs.map((d) => d.name).join(", ")}`);
-            }
-            await ctx.emit("tool", { code: "reads", params: { name: doc.name } });
-            const text = await documentText(doc);
-            const start = Math.min(from ?? 0, text.length);
-            const part = text.slice(start, start + 12_000);
-            return {
-                document: doc.name,
-                text: clip(part, 12_000),
-                next: start + part.length < text.length ? start + part.length : null,
-                length: text.length,
-            };
-        }),
-    });
     return tools;
 }