agentbox-app 0.1.6

package/mcp/core/documents.mjs

@@ -0,0 +1,238 @@
+// Documents: everything the store holds that is not code.
+//
+// Three functions cover the ICP, personas, transcripts, findings, reports,
+// notes, and designs, because on disk all of them already ARE the same thing: a
+// file at a path with an envelope in index.json. A read_persona / read_report /
+// read_transcript surface would be three more things to maintain that a path
+// already distinguishes, and it would need a fourth the first time the founder
+// invents a kind of document nobody anticipated.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { readIndex, readCreationContent, saveCreation, setCreationStatus, CREATION_STATUSES } from '../../main/store/project.mjs';
+import { runForProject } from '../../main/store/queues.mjs';
+import { assertInside, deniesGitOrEnvPath } from '../../main/store/paths.mjs';
+import { AGENT_CREATION_KINDS, SCHEMA_VERSION } from '../../shared/contracts.mjs';
+import { libraryFolderOf } from '../../shared/library-folder.mjs';
+import { resolveProduct } from './account.mjs';
+
+const MAX_CONTENT_BYTES = 2 * 1024 * 1024;
+
+// NOT EVERY DOCUMENT IS IN THE CATALOG, and pretending otherwise is the fastest
+// way to make this server lie. The `onboard` product on disk right now has eight
+// persona files and exactly one catalog entry: skills write files directly, sync
+// brings files in, and the founder edits by hand. A reader that consulted only
+// index.json would report that seven of her personas do not exist, which is
+// worse than useless, because it reads as an authoritative answer.
+//
+// So the catalog is treated as what it is, an INDEX OVER the files rather than
+// the set of them, and the disk is walked alongside it. The walk is narrow on
+// purpose: prose only, and never into the directories that hold code, run
+// artifacts, or the store's own bookkeeping, which are large, uninteresting to a
+// reader, and served by better tools elsewhere.
+const READABLE_EXT = new Set(['.md', '.html', '.txt', '.csv']);
+const SKIP_DIRS = new Set([
+  'creations', 'runs', 'workspace', 'records', 'chats', 'databases', 'deployments',
+  'node_modules', '.git', 'dist', 'build', '.next',
+]);
+const MAX_WALK_ENTRIES = 2000;
+
+function walkFiles(root) {
+  const out = [];
+  const stack = [''];
+  while (stack.length && out.length < MAX_WALK_ENTRIES) {
+    const rel = stack.pop();
+    let entries = [];
+    try { entries = fs.readdirSync(path.join(root, rel), { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.name.startsWith('.')) continue;
+      const childRel = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        if (!SKIP_DIRS.has(e.name)) stack.push(childRel);
+        continue;
+      }
+      if (!e.isFile() || !READABLE_EXT.has(path.extname(e.name).toLowerCase())) continue;
+      out.push(childRel);
+    }
+  }
+  return out;
+}
+
+// What a path implies about how it should be read. One rule, used both for
+// files found on disk and for documents written through this server, so the two
+// can never disagree about the same filename.
+function kindForPath(rel) {
+  return /\.html?$/i.test(rel || '') ? 'design' : 'markdown';
+}
+
+function fileView(root, rel) {
+  let updatedAt = null;
+  try { updatedAt = new Date(fs.statSync(path.join(root, rel)).mtimeMs).toISOString(); } catch { /* raced a delete */ }
+  return {
+    id: null,
+    title: path.basename(rel, path.extname(rel)),
+    kind: kindForPath(rel),
+    path: rel,
+    dir: null,
+    folder: rel.includes('/') ? rel.split('/')[0] : null,
+    status: 'current',
+    replacedBy: null,
+    updatedAt,
+    cataloged: false,
+  };
+}
+
+function envelopeView(c) {
+  return {
+    id: c.id,
+    title: c.title,
+    kind: c.kind,
+    path: c.path ?? null,
+    dir: c.dir ?? null,
+    folder: libraryFolderOf(c) || null,
+    status: c.status ?? 'current',
+    replacedBy: c.replacedBy ?? null,
+    updatedAt: c.updatedAt ?? (c.ts ? new Date(c.ts).toISOString() : null),
+    cataloged: true,
+  };
+}
+
+/**
+ * Everything readable in a product: catalog entries, plus prose files on disk
+ * that no catalog entry points at. Never opens a document.
+ *
+ * A catalog entry always wins over the bare file it describes, since it carries
+ * the title and status a person chose.
+ */
+export function listDocuments(ref, { folder = null, kind = null, status = null, pathPrefix = null, query = null, catalogedOnly = false } = {}) {
+  const project = resolveProduct(ref);
+  const idx = readIndex(project.dir);
+  const wanted = query ? String(query).toLowerCase() : null;
+
+  const cataloged = (idx.creations ?? []).filter((c) => !c.deleted).map(envelopeView);
+  const seen = new Set(cataloged.map((c) => c.path).filter(Boolean));
+
+  const loose = catalogedOnly ? [] : walkFiles(project.dir)
+    .filter((rel) => !seen.has(rel))
+    .map((rel) => fileView(project.dir, rel));
+
+  return [...cataloged, ...loose]
+    .filter((c) => (!folder || c.folder === folder)
+      && (!kind || c.kind === kind)
+      && (!status || c.status === status)
+      && (!pathPrefix || (c.path ?? '').startsWith(pathPrefix))
+      && (!wanted || c.title.toLowerCase().includes(wanted) || (c.path ?? '').toLowerCase().includes(wanted)))
+    .sort((a, b) => String(b.updatedAt ?? '').localeCompare(String(a.updatedAt ?? '')));
+}
+
+/** One document, by id or by path. */
+export function readDocument(ref, { id = null, path: relPath = null } = {}) {
+  const project = resolveProduct(ref);
+  if (!id && !relPath) throw new Error('read_document needs either an id or a path');
+  const idx = readIndex(project.dir);
+
+  const envelope = (idx.creations ?? []).find((c) => !c.deleted && (id ? c.id === id : c.path === relPath));
+  if (!envelope) {
+    // An id is a catalog concept, so a miss there is genuinely a miss. A PATH is
+    // not: the file may be sitting right there uncataloged (see the note above
+    // walkFiles), and refusing to read a file that exists because an index does
+    // not mention it would be an obviously wrong answer to an obviously fair
+    // question. Containment and the .git/.env deny-list still apply, since they
+    // are what make an agent-supplied path safe to open at all.
+    if (id) throw new Error(`no document with id ${id} in ${project.name}`);
+    if (deniesGitOrEnvPath(relPath)) throw new Error(`refusing to read a .git/.env path: ${relPath}`);
+    let content;
+    try {
+      content = fs.readFileSync(assertInside(project.dir, relPath), 'utf8');
+    } catch {
+      throw new Error(`no document at path ${relPath} in ${project.name} (list_documents shows what exists)`);
+    }
+    return { ...fileView(project.dir, relPath), content };
+  }
+  if (envelope.dir) {
+    throw new Error(`"${envelope.title}" is folder-backed, which this server does not serve; its files live at ${path.join(project.dir, envelope.dir)}`);
+  }
+
+  return { ...envelopeView(envelope), content: readCreationContent(project.dir, envelope) };
+}
+
+/**
+ * Create, update, retitle, move, or restatus a document.
+ *
+ * One function rather than five, and content is OPTIONAL: omitting it means a
+ * metadata-only change, which is how a rename or a status change happens without
+ * having to read a document back and write it out unchanged (the version of that
+ * which loses a document to a race is exactly the thing this whole design is
+ * trying to stop happening).
+ */
+export async function writeDocument(ref, { id = null, path: relPath = null, title = null, kind = null, content = null, status = null } = {}) {
+  const project = resolveProduct(ref);
+
+  return runForProject(project.id, async () => {
+    const idx = readIndex(project.dir);
+    const existing = id
+      ? (idx.creations ?? []).find((c) => !c.deleted && c.id === id)
+      : (idx.creations ?? []).find((c) => !c.deleted && c.path === relPath);
+
+    if (id && !existing) throw new Error(`no document with id ${id} in ${project.name}`);
+    if (existing?.dir) throw new Error(`"${existing.title}" is folder-backed; this server does not write into folder-backed artifacts`);
+
+    const nextPath = relPath ?? existing?.path;
+    if (!nextPath) throw new Error('a new document needs a path, e.g. "reports/first-run.md" or "personas/marcus.md"');
+    if (deniesGitOrEnvPath(nextPath)) throw new Error(`refusing to write a .git/.env path: ${nextPath}`);
+
+    // THE PATH ALREADY SAYS WHAT THIS IS, so a caller that did not name a kind
+    // gets the one its extension implies rather than a blanket 'markdown'. Two
+    // real failures made this worth deriving:
+    //
+    // A document written to a .html path and catalogued as markdown renders as
+    // escaped source, because the app decides by kind (`kind === 'design' ||
+    // kind === 'canvas'`), so the founder who asked for html got a page of
+    // literal tags. That punished obeying her, which is the worst kind of trap:
+    // the rule looks followed and the result is worse than ignoring it.
+    //
+    // And the old signature default meant kind was NEVER absent, so the
+    // `existing?.kind` fallback below could not fire: renaming a persona or a
+    // transcript silently demoted it to markdown.
+    //
+    // Uncataloged files on disk are already read this way (fileView above), so
+    // this makes a written document and a found one agree.
+    const nextKind = kind ?? existing?.kind ?? kindForPath(nextPath);
+    if (!AGENT_CREATION_KINDS.includes(nextKind)) {
+      throw new Error(`kind must be one of ${AGENT_CREATION_KINDS.join(', ')} (got "${nextKind}")`);
+    }
+    const nextTitle = title ?? existing?.title;
+    if (!nextTitle) throw new Error('a new document needs a title');
+
+    if (content != null) {
+      if (typeof content !== 'string') throw new Error('content must be a string');
+      const bytes = Buffer.byteLength(content, 'utf8');
+      if (bytes > MAX_CONTENT_BYTES) throw new Error(`document is ${bytes} bytes (max ${MAX_CONTENT_BYTES})`);
+    }
+    // A metadata-only write on a document that does not exist yet would create a
+    // catalog entry pointing at nothing, which reads as a document until someone
+    // opens it. Refuse instead.
+    if (content == null && !existing) throw new Error('a new document needs content');
+
+    const envelope = {
+      ...(existing ?? {}),
+      id: existing?.id ?? `a-${crypto.randomBytes(4).toString('hex')}`,
+      kind: nextKind,
+      title: nextTitle,
+      path: nextPath,
+      ts: existing?.ts ?? Date.now(),
+      updatedAt: new Date().toISOString(),
+      schemaVersion: SCHEMA_VERSION,
+    };
+    // A move is a path change; the old file is deliberately left where it is
+    // rather than deleted, because losing a document to a typo'd move is a worse
+    // outcome than an orphan file the founder can see and remove.
+    const moved = existing && existing.path !== nextPath;
+
+    saveCreation(project.dir, envelope, content);
+    if (status && CREATION_STATUSES.includes(status)) setCreationStatus(project.dir, envelope.id, { status });
+
+    return { ...envelopeView(readIndex(project.dir).creations.find((c) => c.id === envelope.id)), created: !existing, moved: moved ? existing.path : null };
+  });
+}

package/mcp/core/page.mjs

@@ -0,0 +1,152 @@
+// LOOKING AT A PAGE A WORKER JUST BUILT, AND ONLY AT A LOCAL ONE.
+//
+// Where this comes from (w-5ebf7bf7bb, MP-09). The terminal clients this app is
+// keeping parity with mostly ship a browser now. Hers, 2026-09-23: a worker
+// driving a browser of OURS is good and should happen; a worker driving the
+// browser she is signed into is not, and she never wants that ability to exist,
+// because that browser holds her logins, her cookies and everything else. That
+// half is a rule in CLAUDE.md with a test behind it.
+//
+// The browser she meant is gone. She had the whole rest screen and the browser
+// inside the app deleted the day before (w-030026f226, for the open source cut),
+// so there is no pane left to drive. This is the smallest honest thing that
+// still delivers what a worker actually needs: start your app, look at it, show
+// her the picture. No window, no logins, nothing of hers.
+//
+// LOCAL ONLY, AND THE RULE IS THE POINT RATHER THAN A SETTING. A worker that can
+// fetch any address is a worker that can post anything it has read to any
+// address. Loopback cannot leave the machine, so the capability is bounded by
+// what it can reach rather than by whoever remembers to review a prompt. If
+// this is ever widened it is a permission design and hers to approve, which is
+// what she said in the same breath as approving the rest of it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { resolveAccount, resolveProduct } from './account.mjs';
+
+/** Where a captured picture lands, beside everything else she is shown. */
+const SHOTS = 'attachments';
+
+/** Only loopback. Anything else is refused with the reason. */
+export function localTarget(url) {
+  let parsed;
+  try { parsed = new URL(String(url ?? '')); } catch { throw Error(`Not a URL: ${url}`); }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw Error(`Only http and https can be opened, not ${parsed.protocol.replace(':', '')}.`);
+  }
+  const host = parsed.hostname.replace(/^\[|\]$/g, '');
+  const local = host === 'localhost' || host === '127.0.0.1' || host === '::1' || host === '0.0.0.0';
+  if (!local) {
+    throw Error(`Only a local address can be opened, and ${parsed.hostname} is not one. This exists so a worker can look at the app it just started; anything wider is a permission decision and not this tool's to make.`);
+  }
+  return parsed.href;
+}
+
+/** Chrome, wherever this Mac keeps it, or null when it has none. */
+export function findChrome(candidates = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+]) {
+  for (const bin of candidates) { try { if (fs.statSync(bin).isFile()) return bin; } catch { /* next */ } }
+  return null;
+}
+
+/**
+ * Open the page headlessly, photograph it, and read its words back.
+ *
+ * `capture` is injected so this is testable without a browser on the machine:
+ * the real one below drives Chrome over the devtools protocol, which is the
+ * same mechanism the design rounds in this repo already use.
+ */
+export async function lookAtPage({ product, url, width = 1280, height = 900, capture = captureWithChrome, now = Date.now } = {}) {
+  const target = localTarget(url);
+  // The account scope has to be set before a product can be found, and this
+  // module is reachable without going through the tool surface that does it.
+  resolveAccount();
+  const found = resolveProduct(product);
+  const dir = found.dir;
+  const slug = found.id ?? path.basename(found.dir);
+  const shot = await capture({ url: target, width, height });
+  if (!shot?.png) throw Error(shot?.error ?? 'The page could not be opened.');
+
+  const name = `page-${new Date(now()).toISOString().replace(/[:.]/g, '-')}.png`;
+  const rel = path.join(SHOTS, name);
+  fs.mkdirSync(path.join(dir, SHOTS), { recursive: true });
+  fs.writeFileSync(path.join(dir, rel), shot.png);
+  return {
+    product: slug,
+    url: target,
+    picture: rel,
+    title: shot.title ?? '',
+    text: (shot.text ?? '').slice(0, 20_000),
+  };
+}
+
+/**
+ * The real capture. Headless Chrome over the devtools protocol: navigate, wait
+ * for the load event, read the rendered text, take the picture. Nothing is
+ * stored in the browser, and it is thrown away with the profile directory.
+ */
+export async function captureWithChrome({ url, width, height, chrome = findChrome(), timeoutMs = 20_000 }) {
+  if (!chrome) return { error: 'No Chrome, Chromium or Edge on this Mac, so there is nothing to open the page with.' };
+  const profile = fs.mkdtempSync(path.join(process.env.TMPDIR ?? '/tmp', 'look-at-page-'));
+  const child = spawn(chrome, [
+    '--headless=new', '--remote-debugging-port=0', `--user-data-dir=${profile}`,
+    '--no-first-run', '--no-default-browser-check', '--hide-scrollbars',
+    `--window-size=${width},${height}`, 'about:blank',
+  ], { stdio: ['ignore', 'ignore', 'pipe'] });
+  const done = () => { try { child.kill('SIGKILL'); } catch { /* already gone */ } try { fs.rmSync(profile, { recursive: true, force: true }); } catch { /* best effort */ } };
+
+  try {
+    const wsUrl = await new Promise((resolve, reject) => {
+      let buf = '';
+      const timer = setTimeout(() => reject(Error('the browser never started')), timeoutMs);
+      child.stderr.on('data', (d) => {
+        buf += d.toString();
+        const m = buf.match(/ws:\/\/[^\s]+/);
+        if (m) { clearTimeout(timer); resolve(m[0]); }
+      });
+      child.once('exit', () => { clearTimeout(timer); reject(Error('the browser exited before it was ready')); });
+    });
+    const ws = new WebSocket(wsUrl);
+    await new Promise((r, j) => { ws.onopen = r; ws.onerror = () => j(Error('could not talk to the browser')); });
+    let id = 1;
+    const waiting = new Map();
+    ws.onmessage = (e) => { const m = JSON.parse(e.data); if (m.id && waiting.has(m.id)) { waiting.get(m.id)(m); waiting.delete(m.id); } };
+    const send = (method, params = {}, sessionId) => new Promise((resolve, reject) => {
+      const mine = id++;
+      waiting.set(mine, (m) => (m.error ? reject(Error(`${method}: ${m.error.message}`)) : resolve(m.result)));
+      ws.send(JSON.stringify({ id: mine, method, params, sessionId }));
+    });
+    const { targetId } = await send('Target.createTarget', { url: 'about:blank' });
+    const { sessionId } = await send('Target.attachToTarget', { targetId, flatten: true });
+    const call = (m, p) => send(m, p, sessionId);
+    await call('Page.enable');
+    await call('Runtime.enable');
+    await call('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 2, mobile: false });
+    await call('Page.navigate', { url });
+    // The load event, or the timeout, whichever comes first: a page that never
+    // finishes loading is still worth photographing.
+    await new Promise((resolve) => {
+      const stop = setTimeout(resolve, Math.min(timeoutMs, 10_000));
+      const onMsg = (e) => {
+        const m = JSON.parse(e.data);
+        if (m.method === 'Page.loadEventFired' && m.sessionId === sessionId) { clearTimeout(stop); ws.removeEventListener('message', onMsg); resolve(); }
+      };
+      ws.addEventListener('message', onMsg);
+    });
+    await new Promise((r) => setTimeout(r, 400));
+    const read = await call('Runtime.evaluate', {
+      expression: '({ title: document.title, text: document.body ? document.body.innerText : "" })',
+      returnByValue: true,
+    });
+    const { data } = await call('Page.captureScreenshot', { format: 'png' });
+    ws.close();
+    return { png: Buffer.from(data, 'base64'), ...(read?.result?.value ?? {}) };
+  } catch (error) {
+    return { error: `The page could not be opened: ${error.message}` };
+  } finally {
+    done();
+  }
+}

package/mcp/core/products.mjs

@@ -0,0 +1,110 @@
+// Products: one per idea the founder is raising. A product is a project
+// directory in the store, which is what the app has always called it.
+//
+// The one genuinely new field here is repoPath. Product CODE lives in an
+// ordinary git checkout outside the store, written by the calling agent with
+// its own editing tools, so a product record needs to say where. The store
+// holds the thinking; the repo holds the software.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { listProjects, createProject, loadProjectAt, patchProjectAt, readIndex, readJson, starterNotesDoc, saveCreation } from '../../main/store/project.mjs';
+import { readWorkItems } from '../../main/store/work-items.mjs';
+import { resolveProduct } from './account.mjs';
+import { SCHEMA_VERSION } from '../../shared/contracts.mjs';
+
+// Fields the MCP may set on project.json beyond what the app already writes.
+const PRODUCT_FIELDS = ['name', 'oneLiner', 'repoPath', 'archived'];
+
+function describe(project, { now = Date.now() } = {}) {
+  const idx = readIndex(project.dir);
+  const meta = readJson(path.join(project.dir, 'project.json'), {}) ?? {};
+  let work = [];
+  try { work = readWorkItems(project.dir, now); } catch { /* a product with no ledger yet */ }
+
+  const live = work.filter((w) => w.status !== 'done');
+  return {
+    id: project.id,
+    name: project.name,
+    dir: project.dir,
+    oneLiner: meta.oneLiner ?? null,
+    repoPath: meta.repoPath ?? null,
+    archived: meta.archived === true,
+    documents: (idx.creations ?? []).filter((c) => !c.deleted).length,
+    workItems: { open: live.filter((w) => w.status === 'open').length, claimed: live.filter((w) => w.status === 'claimed').length, blocked: live.filter((w) => w.status === 'blocked').length },
+    createdAt: project.createdAt ?? null,
+    updatedAt: project.updatedAt ?? null,
+  };
+}
+
+/** Every product in one call: the cross-product view. */
+export function listProducts({ includeArchived = false, now = Date.now() } = {}) {
+  return listProjects()
+    .map((p) => describe(p, { now }))
+    .filter((p) => includeArchived || !p.archived);
+}
+
+export function getProduct(ref, { now = Date.now() } = {}) {
+  return describe(resolveProduct(ref), { now });
+}
+
+/**
+ * Start a new product. Creates the project directory the app already
+ * understands, plus the starter notes doc, so a product made from Claude Code is
+ * indistinguishable from one made in the app.
+ */
+export function createProduct(name, { oneLiner = null, repoPath = null } = {}) {
+  if (!name || !String(name).trim()) throw new Error('a product needs a name');
+  const project = createProject(String(name).trim());
+
+  if (oneLiner || repoPath) patchProjectAt(project.dir, cleanPatch({ oneLiner, repoPath }));
+
+  // The notes doc is the founder's living map, and the app expects one. Written
+  // through saveCreation so it lands in the catalog rather than sitting on disk
+  // as a file nothing knows about.
+  saveCreation(
+    project.dir,
+    { id: 'a-notes', kind: 'markdown', title: `${project.name} notes`, path: 'notes.md', ts: Date.now(), schemaVersion: SCHEMA_VERSION },
+    starterNotesDoc(project.name),
+  );
+
+  return describe({ ...project, dir: project.dir });
+}
+
+// A write goes to the product the read found. resolveProduct answers by looking
+// through the records; deriving the folder again from the resolved id asks a
+// DIFFERENT question, and the two answers only agree while every product's id
+// matches its own folder name. That invariant is false in the real store: one
+// product sits in a folder carrying a DIFFERENT product's id, beside the
+// product whose folder really has that id, so every update aimed at the first
+// silently edited the second and reported the second's record back as if it
+// were the one just changed. Nothing errored. Keeping the resolved directory is
+// what makes the read and the write name the same product, and it is the only
+// lookup that still works when two products share an id.
+export function updateProduct(ref, patch = {}) {
+  const project = resolveProduct(ref);
+  const clean = cleanPatch(patch);
+  if (!Object.keys(clean).length) throw new Error(`nothing to update (recognized fields: ${PRODUCT_FIELDS.join(', ')})`);
+  patchProjectAt(project.dir, clean);
+  return describe({ ...project, ...loadProjectAt(project.dir) });
+}
+
+function cleanPatch(patch) {
+  const out = {};
+  for (const [k, v] of Object.entries(patch ?? {})) {
+    if (!PRODUCT_FIELDS.includes(k) || v == null) continue;
+    if (k === 'archived') { out.archived = v === true; continue; }
+    if (k === 'repoPath') {
+      // Stored as given, but checked: a repo path that does not exist is almost
+      // always a typo, and finding out later means an agent looking for code in
+      // a directory that was never there.
+      const p = path.resolve(String(v).replace(/^~/, process.env.HOME ?? '~'));
+      if (!fs.existsSync(p)) throw new Error(`no such directory: ${p} (repoPath should point at the product's git checkout)`);
+      out.repoPath = p;
+      continue;
+    }
+    const s = String(v).trim();
+    if (s) out[k] = s;
+  }
+  return out;
+}

package/mcp/core/skills.mjs

@@ -0,0 +1,126 @@
+// Skills: the house method, served to whoever is doing the thinking.
+//
+// These are the SAME files the in-app agent runs on (skills/<name>/SKILL.md),
+// served verbatim. Not a fork, deliberately. A second set written for an external
+// brain would read a little better and then drift, and skill drift has already
+// cost this project real work; one source that improves for both surfaces beats
+// two that agree only on the day they were written.
+//
+// What the calling agent needs on top is not a rewrite, it is one paragraph of
+// orientation: these instructions were written for an agent with tools this
+// server does not have. That paragraph is GENERATED from the live tool list
+// below, so it cannot claim a capability that was removed or miss one that was
+// added.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const SKILLS_DIR = path.resolve(HERE, '../../skills');
+
+const NAME_RE = /^[a-z0-9][a-z0-9-]{0,60}$/;
+
+// Front matter is `---\nname: x\ndescription: y\n---`. Parsed loosely on
+// purpose: a skill with a malformed header should still be readable, because
+// the prose is the part that matters.
+function frontMatter(text) {
+  const match = /^---\n([\s\S]*?)\n---/.exec(text);
+  if (!match) return {};
+  const out = {};
+  for (const line of match[1].split('\n')) {
+    const kv = /^([a-zA-Z-]+):\s*(.*)$/.exec(line.trim());
+    if (kv) out[kv[1]] = kv[2].trim();
+  }
+  return out;
+}
+
+export function listSkills() {
+  let entries = [];
+  try {
+    entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true }).filter((e) => e.isDirectory());
+  } catch {
+    return [];
+  }
+  return entries.map((e) => {
+    const file = path.join(SKILLS_DIR, e.name, 'SKILL.md');
+    let text = '';
+    try { text = fs.readFileSync(file, 'utf8'); } catch { return null; }
+    const fm = frontMatter(text);
+    return {
+      name: e.name,
+      description: fm.description ?? firstLine(text),
+      // Enough for an agent to judge whether it wants the whole thing before
+      // spending the tokens on it.
+      bytes: Buffer.byteLength(text, 'utf8'),
+    };
+  }).filter(Boolean).sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function firstLine(text) {
+  const line = text.split('\n').find((l) => l.trim() && !l.startsWith('---') && !l.startsWith('#'));
+  return (line ?? '').trim().slice(0, 200);
+}
+
+/**
+ * One skill, verbatim, with a generated header.
+ *
+ * `capabilities` is the live list of what this server actually exposes, passed
+ * in by the tool layer rather than hard-coded here, so the header and the tool
+ * list are the same fact stated once.
+ */
+export function fetchSkill(name, { capabilities = [], missing = [] } = {}) {
+  if (!NAME_RE.test(String(name ?? ''))) throw new Error(`invalid skill name: ${name}`);
+  const file = path.join(SKILLS_DIR, name, 'SKILL.md');
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch {
+    const names = listSkills().map((s) => s.name).join(', ');
+    throw new Error(`no skill called "${name}". Available: ${names}`);
+  }
+
+  const refs = listReferences(name);
+  return { name, header: header({ capabilities, missing, references: refs }), content: text, references: refs };
+}
+
+// Some skills carry reference files beside SKILL.md (the design skill does).
+// Listed rather than inlined: they are large, and the agent should choose.
+function listReferences(name) {
+  const dir = path.join(SKILLS_DIR, name, 'references');
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => `${name}/references/${f}`);
+  } catch {
+    return [];
+  }
+}
+
+export function fetchReference(rel) {
+  const parts = String(rel ?? '').split('/');
+  if (parts.length !== 3 || parts[1] !== 'references' || !NAME_RE.test(parts[0]) || !/^[a-zA-Z0-9._-]+\.md$/.test(parts[2])) {
+    throw new Error(`invalid reference path: ${rel} (expected "<skill>/references/<file>.md")`);
+  }
+  const file = path.join(SKILLS_DIR, parts[0], 'references', parts[2]);
+  try { return fs.readFileSync(file, 'utf8'); } catch { throw new Error(`no such reference: ${rel}`); }
+}
+
+function header({ capabilities, missing, references }) {
+  const lines = [
+    'This skill was written for the agent inside the app, which has a larger tool set than this server exposes. The method is what matters and it still applies; the tool names sometimes do not.',
+    '',
+    `Through this server you have: ${capabilities.join(', ')}.`,
+  ];
+  if (missing.length) {
+    lines.push(
+      '',
+      `The skill may tell you to use ${missing.join(', ')}. Those are not here. Where it says to provision a database, deploy, push to GitHub, set up analytics, or drive a browser, do it yourself with your own tools and your own accounts, then record what you did as a document.`,
+      'Where it says open_creation, use write_document. Where it says read_creation, use read_document.',
+    );
+  }
+  lines.push(
+    '',
+    'The founder is reachable through whatever interface you are running in, not through this server; there is no ask_user here.',
+  );
+  if (references.length) lines.push('', `Reference files available via fetch_reference: ${references.join(', ')}.`);
+  return lines.join('\n');
+}