@coffer-org/server 1.14.0 → 2.1.0

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { createWriteStream, existsSync } from 'node:fs';
+import { createWriteStream, existsSync, statSync } from 'node:fs';
 import { realpath } from 'node:fs/promises';
 import { pipeline } from 'node:stream/promises';
 import { extname, join, sep } from 'node:path';
@@ -8,17 +8,15 @@ import Fastify from 'fastify';
 import cors from '@fastify/cors';
 import multipart from '@fastify/multipart';
 import fastifyStatic from '@fastify/static';
-import { serialize } from '@mikro-orm/core';
-import { textSearchKeys, recordTitle, titleKey, storageColumnsFor } from '@coffer-org/sdk/shelf';
-import { tokenize } from '@coffer-org/core/search';
 import { shelfTableName } from "./entity-schema.js";
 import { getEm, closeDb } from "./db.js";
+import { recordCounts } from "./counts.js";
 import { ValidationError, NotFoundError } from "./mutate.js";
 import { resolveEmbed } from "./embed.js";
 import { resolveWithinHome, filterSort, listDir } from "./fs-list.js";
 import { initPlugins, teardownPlugins, readDisabled, purgePluginData, getPluginSettings, getPlugins, } from "./plugin-runtime.js";
 import { registerPluginsApi } from "./plugins-api.js";
-import { pluginHooks, HttpError } from "./plugin-hooks.js";
+import { registerPluginUserApi, registerPluginAdminApi } from "./plugin-user-api.js";
 import { registerAuthApi, resolveRequestUser, requireAdmin, PUBLIC_API_PATHS } from "./auth-api.js";
 import { registerMcpHttp } from "./mcp-http.js";
 import { registerOAuthApi } from "./oauth-api.js";
@@ -26,12 +24,16 @@ import { baseUrl } from "./public-url.js";
 import { discoverPluginAssets, discoverRuntime } from "./plugin-discovery.js";
 import { checkLatestVersion, resolveUpdateTarget, resolveAllUpdateTargets, resolveBaseTargets, resolveRuntimeTarget, runNpmInstall, } from "./plugin-updates.js";
 import { buildClientSchema } from "./schema-api.js";
-import { recordList, recordGet, recordCreate, recordUpdate, recordDelete, rowMatch, UnknownTypeError } from "./records-api.js";
+import { recordList, recordListPage, isPagedRequest, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, } from "./records-api.js";
 import { maskTree, preserveTree } from "./field-masking.js";
 import { writePluginSettings } from "./settings-write.js";
 import { rootLogger, getLogger } from "./log.js";
 import { uploadsDir } from "./uploads.js";
+import { mimeForName } from "./file-fields.js";
 import { verifyUploadTicket } from "./upload-ticket.js";
+import { setPluginState } from "./plugin-state.js";
+import { SEARCH_STATE_PLUGIN, SEARCH_CURSOR_KEY } from "./search-indexer.js";
+import { globalSearch } from "./global-search.js";
 const ENV_FILE = join(process.cwd(), '.env');
 if (existsSync(ENV_FILE))
     process.loadEnvFile(ENV_FILE);
@@ -96,8 +98,11 @@ app.post('/api/upload', async (req, reply) => {
         return reply.code(400).send({ error: 'no_file' });
     const ext = extname(data.filename).toLowerCase();
     const name = `${randomUUID()}${ext}`;
-    await pipeline(data.file, createWriteStream(join(UPLOADS, name)));
-    return reply.send({ filename: name });
+    const dest = join(UPLOADS, name);
+    await pipeline(data.file, createWriteStream(dest));
+    const size = statSync(dest).size;
+    const mime = mimeForName(name) ?? (data.mimetype || undefined);
+    return reply.send({ filename: name, name, ...(mime ? { mime } : {}), size });
 });
 app.post('/api/embed', async (req, reply) => {
     const url = req.body?.url;
@@ -108,8 +113,8 @@ app.post('/api/embed', async (req, reply) => {
         return reply.code(422).send({ error: 'unresolved' });
     return reply.send(rec);
 });
-function key(library, type) {
-    return `${library}/${type}`;
+function key(library, shelf) {
+    return `${library}/${shelf}`;
 }
 async function guard(reply, fn) {
     try {
@@ -146,55 +151,30 @@ app.get('/api/libraries', async (req, reply) => {
     return reply.type('application/json').send(librariesPayload.body);
 });
 app.get('/api/counts', async () => {
-    const fork = getEm().fork();
-    const out = {};
+    const targets = [];
     for (const [k, mdef] of shelfDefs) {
         if (mdef.standalone === false)
             continue;
         const ename = entityNames.get(k);
         if (!ename)
             continue;
-        out[k] = await fork.count(ename);
+        targets.push({ key: k, table: ename });
     }
-    return out;
+    return recordCounts(targets);
 });
-const SEARCH_SCAN_LIMIT = 1000;
-const searchLog = getLogger('search');
 app.get('/api/search', async (req) => {
     const { q = '', limit = '20' } = req.query;
-    const tokens = tokenize(q);
-    if (tokens.length === 0 || q.trim().length < 2)
+    if (q.trim().length < 2)
         return [];
     const lim = Math.min(Number(limit) || 20, 100);
-    const fork = getEm().fork();
-    const scored = [];
+    const shelves = [];
     for (const [k, mdef] of shelfDefs) {
-        if (mdef.standalone === false)
-            continue;
-        const ename = entityNames.get(k);
-        if (!ename)
-            continue;
-        if (!textSearchKeys(mdef).length)
+        const table = entityNames.get(k);
+        if (!table)
             continue;
-        const [library, type] = k.split('/');
-        const cols = storageColumnsFor(mdef, [...textSearchKeys(mdef), titleKey(mdef)]);
-        const rows = (await fork.find(ename, {}, { limit: SEARCH_SCAN_LIMIT, fields: cols })).map((r) => serialize(r));
-        if (rows.length === SEARCH_SCAN_LIMIT) {
-            searchLog.warn('scan cap reached', { shelf: k, limit: SEARCH_SCAN_LIMIT });
-        }
-        for (const row of rows) {
-            const m = rowMatch(mdef, row, tokens);
-            if (!m)
-                continue;
-            const label = recordTitle(mdef, row);
-            scored.push({
-                score: m.score,
-                result: { library, type, id: String(row.id), label, snippet: m.snippet },
-            });
-        }
+        shelves.push({ key: k, table, def: mdef });
     }
-    scored.sort((a, b) => b.score - a.score);
-    return scored.slice(0, lim).map((s) => s.result);
+    return globalSearch(shelves, q, lim);
 });
 app.patch('/api/plugins/:id', async (req, reply) => {
     if (!requireAdmin(req, reply))
@@ -228,6 +208,9 @@ app.patch('/api/plugins/:id', async (req, reply) => {
         fork.create('_Plugin', { id, enabled: enabled ? 1 : 0, updated_at: new Date().toISOString() });
     }
     await fork.flush();
+    if (enabled) {
+        await setPluginState(SEARCH_STATE_PLUGIN, SEARCH_CURSOR_KEY, '0');
+    }
     return { ok: true, restartRequired: true };
 });
 app.delete('/api/plugins/:id/data', async (req, reply) => {
@@ -340,26 +323,8 @@ app.put('/api/plugins/:id/settings', (req, reply) => {
         return { ok: true, row };
     });
 });
-app.post('/api/plugins/:id/:action', async (req, reply) => {
-    if (!requireAdmin(req, reply))
-        return;
-    const { id, action } = req.params;
-    const fn = pluginHooks[id]?.actions?.[action];
-    if (!fn)
-        return reply.code(404).send({ error: `unknown action ${id}/${action}` });
-    try {
-        return await fn((req.body ?? {}));
-    }
-    catch (e) {
-        if (e instanceof ValidationError) {
-            const detail = e.issues.map((i) => `${i.path.join('.') || i.field}: ${i.code}`).join('; ');
-            return reply.code(422).send({ error: `Validation error — ${detail}`, issues: e.issues });
-        }
-        if (e instanceof HttpError)
-            return reply.code(e.status).send({ error: e.message });
-        return reply.code(400).send({ error: e.message });
-    }
-});
+registerPluginAdminApi(app, requireAdmin);
+registerPluginUserApi(app);
 app.get('/api/fs/list', async (req, reply) => {
     const home = homedir();
     const q = req.query;
@@ -383,12 +348,12 @@ app.get('/api/fs/list', async (req, reply) => {
         return { dir: abs, entries: [] };
     }
 });
-function maskRecordRow(library, type, row) {
-    const m = getShelf(library, type);
+function maskRecordRow(library, shelf, row) {
+    const m = getShelf(library, shelf);
     let out = m ? maskTree(m.fields, row) : row;
     const ext = out._extends;
     if (ext) {
-        const defs = getExtendsFor(library, type);
+        const defs = getExtendsFor(library, shelf);
         const maskedExt = {};
         for (const [id, sub] of Object.entries(ext)) {
             const def = defs.find((e) => e.id === id);
@@ -398,67 +363,77 @@ function maskRecordRow(library, type, row) {
     }
     return out;
 }
-app.get('/api/:library/:type', async (req, reply) => {
-    const { library, type } = req.params;
-    const { _fields, _extends, ...query } = req.query;
+app.get('/api/:library/:shelf', async (req, reply) => {
+    const { library, shelf } = req.params;
+    const { _fields, _extends, limit, offset, ...query } = req.query;
+    const paged = isPagedRequest(limit, offset);
+    const opts = {
+        view: _fields === 'full' ? 'full' : 'list',
+        extends: _extends === '1',
+    };
     try {
-        const rows = await recordList(library, type, query, {
-            view: _fields === 'full' ? 'full' : 'list',
-            extends: _extends === '1',
+        if (!paged) {
+            const rows = await recordList(library, shelf, query, opts);
+            return rows.map((r) => maskRecordRow(library, shelf, r));
+        }
+        const page = await recordListPage(library, shelf, query, {
+            ...opts,
+            limit: limit === undefined ? undefined : Number(limit),
+            offset: offset === undefined ? undefined : Number(offset),
         });
-        return rows.map((r) => maskRecordRow(library, type, r));
+        return { rows: page.rows.map((r) => maskRecordRow(library, shelf, r)), total: page.total };
     }
     catch (e) {
-        if (e instanceof UnknownTypeError)
-            return reply.code(404).send({ error: 'unknown_type' });
+        if (e instanceof UnknownShelfError)
+            return reply.code(404).send({ error: 'unknown_shelf' });
         throw e;
     }
 });
-app.get('/api/:library/:type/:id', async (req, reply) => {
-    const { library, type, id } = req.params;
+app.get('/api/:library/:shelf/:id', async (req, reply) => {
+    const { library, shelf, id } = req.params;
     const rid = Number(id);
     if (isNaN(rid))
         return reply.code(400).send({ error: 'invalid_id' });
     try {
-        const row = await recordGet(library, type, rid);
+        const row = await recordGet(library, shelf, rid);
         if (!row)
             return reply.code(404).send({ error: 'not_found' });
-        return maskRecordRow(library, type, row);
+        return maskRecordRow(library, shelf, row);
     }
     catch (e) {
-        if (e instanceof UnknownTypeError)
-            return reply.code(404).send({ error: 'unknown_type' });
+        if (e instanceof UnknownShelfError)
+            return reply.code(404).send({ error: 'unknown_shelf' });
         throw e;
     }
 });
-app.post('/api/:library/:type', (req, reply) => guard(reply, async () => {
-    const { library, type } = req.params;
+app.post('/api/:library/:shelf', (req, reply) => guard(reply, async () => {
+    const { library, shelf } = req.params;
     try {
-        const m = getShelf(library, type);
+        const m = getShelf(library, shelf);
         let body = (req.body ?? {});
         if (m)
             body = preserveTree(m.fields, body, {});
-        const row = await recordCreate(library, type, body);
-        return reply.code(201).send(maskRecordRow(library, type, row));
+        const row = await recordCreate(library, shelf, body);
+        return reply.code(201).send(maskRecordRow(library, shelf, row));
     }
     catch (e) {
-        if (e instanceof UnknownTypeError)
-            return reply.code(404).send({ error: 'unknown_type' });
+        if (e instanceof UnknownShelfError)
+            return reply.code(404).send({ error: 'unknown_shelf' });
         throw e;
     }
 }));
-app.patch('/api/:library/:type/:id', (req, reply) => guard(reply, async () => {
-    const { library, type, id } = req.params;
+app.patch('/api/:library/:shelf/:id', (req, reply) => guard(reply, async () => {
+    const { library, shelf, id } = req.params;
     const rid = Number(id);
     if (isNaN(rid))
         return reply.code(400).send({ error: 'invalid_id' });
     try {
-        const m = getShelf(library, type);
+        const m = getShelf(library, shelf);
         let body = (req.body ?? {});
         if (m) {
-            const existing = (await recordGet(library, type, rid)) ?? {};
+            const existing = (await recordGet(library, shelf, rid)) ?? {};
             body = preserveTree(m.fields, body, existing);
-            const exDefs = getExtendsFor(library, type);
+            const exDefs = getExtendsFor(library, shelf);
             const exRecs = (existing._extends ?? {});
             for (const def of exDefs) {
                 const bk = `_extend_${def.id}`;
@@ -468,27 +443,27 @@ app.patch('/api/:library/:type/:id', (req, reply) => guard(reply, async () => {
                 }
             }
         }
-        const row = await recordUpdate(library, type, rid, body);
-        return maskRecordRow(library, type, row);
+        const row = await recordUpdate(library, shelf, rid, body);
+        return maskRecordRow(library, shelf, row);
     }
     catch (e) {
-        if (e instanceof UnknownTypeError)
-            return reply.code(404).send({ error: 'unknown_type' });
+        if (e instanceof UnknownShelfError)
+            return reply.code(404).send({ error: 'unknown_shelf' });
         throw e;
     }
 }));
-app.delete('/api/:library/:type/:id', (req, reply) => guard(reply, async () => {
-    const { library, type, id } = req.params;
+app.delete('/api/:library/:shelf/:id', (req, reply) => guard(reply, async () => {
+    const { library, shelf, id } = req.params;
     const rid = Number(id);
     if (isNaN(rid))
         return reply.code(400).send({ error: 'invalid_id' });
     try {
-        await recordDelete(library, type, rid);
+        await recordDelete(library, shelf, rid);
         return reply.code(204).send();
     }
     catch (e) {
-        if (e instanceof UnknownTypeError)
-            return reply.code(404).send({ error: 'unknown_type' });
+        if (e instanceof UnknownShelfError)
+            return reply.code(404).send({ error: 'unknown_shelf' });
         throw e;
     }
 }));

package/dist/local-api.d.ts

@@ -1,5 +1,5 @@
-import { UnknownTypeError } from './records-api.ts';
-export { UnknownTypeError };
-export declare function localExists(library: string, type: string, id: number): Promise<boolean>;
-export declare function localPost(library: string, type: string, body: unknown): Promise<Record<string, unknown>>;
-export declare function localPatch(library: string, type: string, id: number, body: unknown): Promise<Record<string, unknown>>;
+import { UnknownShelfError } from './records-api.ts';
+export { UnknownShelfError };
+export declare function localExists(library: string, shelf: string, id: number): Promise<boolean>;
+export declare function localPost(library: string, shelf: string, body: unknown): Promise<Record<string, unknown>>;
+export declare function localPatch(library: string, shelf: string, id: number, body: unknown): Promise<Record<string, unknown>>;

package/dist/local-api.js

@@ -1,18 +1,18 @@
-import { recordCreate, recordUpdate, recordGet, UnknownTypeError } from "./records-api.js";
-export { UnknownTypeError };
-export async function localExists(library, type, id) {
+import { recordCreate, recordUpdate, recordGet, UnknownShelfError } from "./records-api.js";
+export { UnknownShelfError };
+export async function localExists(library, shelf, id) {
     try {
-        return Boolean(await recordGet(library, type, id));
+        return Boolean(await recordGet(library, shelf, id));
     }
     catch (e) {
-        if (e instanceof UnknownTypeError)
+        if (e instanceof UnknownShelfError)
             return false;
         throw e;
     }
 }
-export function localPost(library, type, body) {
-    return recordCreate(library, type, body, 'import');
+export function localPost(library, shelf, body) {
+    return recordCreate(library, shelf, body, 'import');
 }
-export function localPatch(library, type, id, body) {
-    return recordUpdate(library, type, id, body, 'import');
+export function localPatch(library, shelf, id, body) {
+    return recordUpdate(library, shelf, id, body, 'import');
 }

package/dist/mcp-http.js

@@ -20,7 +20,19 @@ export async function registerMcpHttp(app) {
         const actor = req.user.login;
         const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         reply.hijack();
-        reply.raw.on('close', () => void transport.close());
+        let closed = false;
+        const closeTransport = async () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                await transport.close();
+            }
+            catch (e) {
+                log.debug(`/mcp transport close: ${e.message}`);
+            }
+        };
+        reply.raw.on('close', () => void closeTransport());
         try {
             const server = await buildMcpServer(role, actor);
             await server.connect(transport);
@@ -33,5 +45,8 @@ export async function registerMcpHttp(app) {
                 reply.raw.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32603, message: 'internal' }, id: null }));
             }
         }
+        finally {
+            await closeTransport();
+        }
     });
 }

package/dist/mcp-local.d.ts

@@ -1,10 +1,17 @@
 import type { CofferClientApi } from '@coffer-org/mcp/client';
 export declare function mapError(e: unknown): never;
+export declare function splitListQuery(raw: Record<string, unknown>): {
+    query: Record<string, unknown>;
+    opts: {
+        limit?: number;
+        offset?: number;
+    };
+};
 export declare class LocalClient implements CofferClientApi {
     getSchema(): Promise<unknown>;
-    listRecords(library: string, type: string, query?: Record<string, unknown>): Promise<unknown>;
-    getRecord(library: string, type: string, id: number): Promise<unknown>;
-    createRecord(library: string, type: string, fields: Record<string, unknown>): Promise<unknown>;
-    updateRecord(library: string, type: string, id: number, fields: Record<string, unknown>): Promise<unknown>;
-    deleteRecord(library: string, type: string, id: number): Promise<unknown>;
+    listRecords(library: string, shelf: string, raw?: Record<string, unknown>): Promise<unknown>;
+    getRecord(library: string, shelf: string, id: number): Promise<unknown>;
+    createRecord(library: string, shelf: string, fields: Record<string, unknown>): Promise<unknown>;
+    updateRecord(library: string, shelf: string, id: number, fields: Record<string, unknown>): Promise<unknown>;
+    deleteRecord(library: string, shelf: string, id: number): Promise<unknown>;
 }

package/dist/mcp-local.js

@@ -1,53 +1,62 @@
 import { ValidationError, NotFoundError } from '@coffer-org/mcp/client';
-import { recordList, recordGet, recordCreate, recordUpdate, recordDelete, UnknownTypeError, } from "./records-api.js";
+import { recordList, recordListPage, recordGet, recordCreate, recordUpdate, recordDelete, UnknownShelfError, } from "./records-api.js";
 import { ValidationError as ServerValidationError } from "./mutate.js";
 import { buildClientSchema } from "./schema-api.js";
 export function mapError(e) {
     if (e instanceof ServerValidationError)
         throw new ValidationError(e.issues ?? []);
-    if (e instanceof UnknownTypeError)
+    if (e instanceof UnknownShelfError)
         throw new NotFoundError('not_found');
     throw e;
 }
+export function splitListQuery(raw) {
+    const { limit, offset, ...query } = raw;
+    if (typeof limit !== 'number')
+        return { query, opts: {} };
+    return { query, opts: { limit, ...(typeof offset === 'number' ? { offset } : {}) } };
+}
 export class LocalClient {
     async getSchema() {
         return buildClientSchema();
     }
-    async listRecords(library, type, query = {}) {
+    async listRecords(library, shelf, raw = {}) {
+        const { query, opts } = splitListQuery(raw);
         try {
-            return await recordList(library, type, query);
+            if (opts.limit === undefined)
+                return await recordList(library, shelf, query);
+            return await recordListPage(library, shelf, query, opts);
         }
         catch (e) {
             mapError(e);
         }
     }
-    async getRecord(library, type, id) {
+    async getRecord(library, shelf, id) {
         try {
-            return await recordGet(library, type, id);
+            return await recordGet(library, shelf, id);
         }
         catch (e) {
             mapError(e);
         }
     }
-    async createRecord(library, type, fields) {
+    async createRecord(library, shelf, fields) {
         try {
-            return await recordCreate(library, type, fields);
+            return await recordCreate(library, shelf, fields);
         }
         catch (e) {
             mapError(e);
         }
     }
-    async updateRecord(library, type, id, fields) {
+    async updateRecord(library, shelf, id, fields) {
         try {
-            return await recordUpdate(library, type, id, fields);
+            return await recordUpdate(library, shelf, id, fields);
         }
         catch (e) {
             mapError(e);
         }
     }
-    async deleteRecord(library, type, id) {
+    async deleteRecord(library, shelf, id) {
         try {
-            await recordDelete(library, type, id);
+            await recordDelete(library, shelf, id);
             return null;
         }
         catch (e) {

package/dist/mcp-tools.js

@@ -2,9 +2,11 @@ import { z } from 'zod';
 import { buildTools } from '@coffer-org/mcp';
 import { SchemaCache } from '@coffer-org/mcp/schema';
 import { LocalClient } from "./mcp-local.js";
+import { frontendInstructions } from "./frontend-agent.js";
 import { mintUploadTicket } from "./upload-ticket.js";
 import { pluginHooks, pluginCtx } from "./plugin-hooks.js";
 import { getActiveRegistry } from "./registry-context.js";
+import { countTargetsFor, recordCounts } from "./counts.js";
 import { describeCondition } from '@coffer-org/sdk/condition';
 import { getEm } from "./db.js";
 import { getPluginSettings } from "./plugin-runtime.js";
@@ -18,7 +20,7 @@ export function formatHits(hits) {
     if (hits.length === 0)
         return 'No matching records.';
     return hits
-        .map((h) => `[${h.type}/${h.recordId}] (dist ${h.distance.toFixed(3)})\n${h.snippet}`)
+        .map((h) => `[${h.shelfKey}/${h.recordId}] (dist ${h.distance.toFixed(3)})\n${h.snippet}`)
         .join('\n\n');
 }
 const ok = (data) => ({
@@ -56,7 +58,7 @@ export async function collectMcpTools(opts = {}) {
             server: 'coffer',
             bareName: 'create_upload_ticket',
             httpName: 'create_upload_ticket',
-            description: 'Mint a short-lived (60 min) upload-only token for POST /api/upload. Use it as a Bearer header to stream local files to the server without sending their bytes through this conversation. The token cannot read or modify records. Response of each upload is {"filename":"<name>"} — store it in a file/image field as {"name":"<name>"}.',
+            description: 'Mint a short-lived (60 min) upload-only token for POST /api/upload. Use it as a Bearer header to stream local files to the server without sending their bytes through this conversation. The token cannot read or modify records. Each upload responds {"name":"<name>","mime":...,"size":...} — store it in a file/image/media field as {"name":"<name>"}. This is the ONLY way to fill such a field: a remote URL written straight into the field is rejected, so download the file locally first and upload that.',
             inputSchema: {},
             scope: 'upload',
             role: 'member',
@@ -66,11 +68,42 @@ export async function collectMcpTools(opts = {}) {
                     token,
                     upload_url: '/api/upload',
                     expires_in: expiresInSec,
-                    how_to: 'curl -H "Authorization: Bearer <token>" -F "file=@<path>" <base-url>/api/upload  →  {"filename":"<name>"}. Then set a file field to {"name":"<name>"}.',
+                    how_to: 'curl -H "Authorization: Bearer <token>" -F "file=@<path>" <base-url>/api/upload  →  {"name":"<name>"}. Then set a file field to {"name":"<name>"}. mime/size are filled in by the server — do not send your own.',
                 });
             },
         });
     }
+    out.push({
+        server: 'coffer',
+        bareName: 'count_records',
+        httpName: 'count_records',
+        description: 'How many records each shelf holds — counted in the database, no rows returned. ' +
+            'Without arguments: every shelf of every library. library — narrow to one library; shelf — to one shelf ' +
+            '(needs library). Use this for "how many …" and for a size overview; never list records just to count them.',
+        inputSchema: { library: z.string().optional(), shelf: z.string().optional() },
+        scope: 'crud',
+        role: 'member',
+        handler: async (args) => {
+            try {
+                const registry = getActiveRegistry();
+                const targets = countTargetsFor(registry.shelves, {
+                    ...(typeof args.library === 'string' ? { library: args.library } : {}),
+                    ...(typeof args.shelf === 'string' ? { shelf: args.shelf } : {}),
+                });
+                const counts = await recordCounts(targets);
+                const shelves = Object.entries(counts)
+                    .map(([key, count]) => {
+                    const [library = '', shelf = ''] = key.split('/');
+                    return { library, shelf, count };
+                })
+                    .sort((a, b) => b.count - a.count);
+                return ok({ shelves, total: shelves.reduce((n, s) => n + s.count, 0) });
+            }
+            catch (e) {
+                return fail(`Error: ${e.message}`);
+            }
+        },
+    });
     for (const [id, h] of Object.entries(pluginHooks)) {
         for (const t of h.agent?.tools ?? []) {
             out.push({
@@ -99,7 +132,7 @@ export async function collectMcpTools(opts = {}) {
             server: 'rag',
             bareName: 'search_records',
             httpName: 'search_records',
-            description: "Semantic search over the user's coffer records. Returns the most relevant records as type/id refs with a text snippet.",
+            description: "Semantic search over the user's coffer records. Returns the most relevant records as library/shelf/id refs with a text snippet.",
             inputSchema: { query: z.string(), k: z.number().int().positive().optional() },
             scope: 'rag',
             role: 'member',
@@ -227,21 +260,31 @@ export async function buildDomainSections() {
             '## Libraries (what each holds / when to use it — pick the right one before searching)\n\n' + blocks.join('\n\n');
     }
     const dataModel = '## Data model\n' +
-        'Library (top-level area) → type/shelf (a kind of record, e.g. things/item) → record (addressed library/type/id) → fields. ' +
+        'Library (top-level area) → shelf (a kind of record, e.g. things/item) → record (addressed library/shelf/id) → fields. ' +
         'Some field values are JSON (e.g. quantity {"value":2000,"unit":"ml"}); some are relations (hold another record\'s id); ' +
-        'some are collections (nested rows — an array). Extends add extra field-sets to a type\'s records, shown only when a ' +
+        "some are collections (nested rows — an array). Extends add extra field-sets to a shelf's records, shown only when a " +
         'condition holds (the "when …" notes below); in a fetched record they sit under `_extends`. ' +
-        'Read: list_libraries → describe_type → list_records/get_record. Write: create_record/update_record (call describe_type first); ' +
+        'Read: list_libraries → describe_shelf → list_records/get_record. Write: create_record/update_record (call describe_shelf first); ' +
         'to remove a record use delete_record — do not blank its fields.';
     const rules = (await collectPluginInstructions()).map(({ id, instructions }) => `## ${id}\n${instructions}`);
-    return overview ? [dataModel, overview, ...rules] : [dataModel, ...rules];
+    const site = await frontendInstructions();
+    return [
+        dataModel,
+        ...(overview ? [overview] : []),
+        ...(site ? [`## web\n${site}`] : []),
+        ...rules,
+    ];
 }
 export function buildMcpInstructions(sections) {
     const base = [
         "Coffer is the user's personal database, organized into libraries (kitchen, people, finance, health, devices, home, garden, documents, travel, and more), each holding typed records.",
-        'Use the tools to read and write this data: call list_libraries to see what exists, describe_type before create_record/update_record, then list_records / get_record to read. When a search_records tool is available, use it for semantic lookup.',
-        'The per-library notes below name the shelves and the rules — not every field. For exact field names, types, and which are required, call describe_type(library, type) rather than guessing from the notes.',
+        'Use the tools to read and write this data: call list_libraries to see what exists, describe_shelf before create_record/update_record, then list_records / get_record to read. When a search_records tool is available, use it for semantic lookup.',
+        'The per-library notes below name the shelves and the rules — not every field. For exact field names, types, and which are required, call describe_shelf(library, shelf) rather than guessing from the notes.',
         'Record field values may be JSON-encoded (e.g. quantity {"value":2000,"unit":"ml"}) — parse them.',
+        'File fields (file/document/audio/video/image/media/avatar/cover/poster) hold a file uploaded to this server, ' +
+            'never a remote URL: {"name":"<filename from POST /api/upload>"}. Writing a URL is rejected. ' +
+            'To store a picture found on the web, download it locally first, then create_upload_ticket → POST /api/upload → write the returned name. ' +
+            'See the field\'s "write" note in describe_shelf.',
     ].join('\n');
     return sections.length ? `${base}\n\n${sections.join('\n\n')}` : base;
 }

package/dist/migrations.d.ts

@@ -10,6 +10,7 @@ export declare function introspectTable(em: EntityManager, table: string): Promi
     }[];
 }>;
 export declare function makeTable(em: EntityManager, table: string): TableOps;
+export declare function renameSystemShelfKey(em: EntityManager): Promise<void>;
 export declare function validateMigrations(pluginId: string, list: Migration[]): void;
 interface RunArgs {
     em: EntityManager;