drafted 1.18.0 → 1.18.2

package/mcp/active-project-store.mjs

@@ -0,0 +1,81 @@
+/**
+ * Active-project persistence for the stdio MCP.
+ *
+ * The active project lives only in the in-memory sessionStates Map, so a
+ * `system restart mode=mcp` / skill-edit pass that re-spawns the stdio MCP
+ * wipes it — the recurring "active project keeps resetting, re-open it" churn.
+ * Persisting it lets the long-lived stdio process rehydrate transparently after
+ * a restart.
+ *
+ * Keyed by SERVER URL + cwd so two concurrent same-machine agent sessions (each
+ * its own stdio MCP, same launch config) don't clobber each other's active
+ * project. The server is part of the key because project and org ids are only
+ * meaningful within one server's DATABASE: this repo registers both a prod
+ * (`https://drafted.live`) and a local-dev (`http://localhost:3477`) stdio MCP,
+ * and with a cwd-only key the local MCP's project+boundOrgId were rehydrated by
+ * the prod MCP at boot — which pinned the prod session's working org to an org
+ * id that exists only in the local dev DB (`get_org` reported a workingOrg with
+ * name:null that was in no membership, and every project-less call failed with
+ * `not a member of org "<local-uuid>"`). Cross-database state must never share a
+ * key. Only the stdio process persists here; HTTP/remote user sessions are keyed
+ * by a real Drafted session id and never call into this store.
+ *
+ * Side-effect-free on import (no network, no eager writes) so it can be unit
+ * tested against the real code without booting the MCP server.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { homedir } from 'os';
+
+const DEFAULT_FILE = process.env.DRAFTED_MCP_STATE_FILE || join(homedir(), '.drafted', 'mcp-state.json');
+
+function defaultCwd() {
+  try { return process.cwd(); } catch { return '__default__'; }
+}
+
+// serverUrl first: a URL never contains "|", so the composite key is unambiguous.
+function stateKey(cwd, serverUrl) {
+  return serverUrl ? `${serverUrl}|${cwd}` : cwd;
+}
+
+export function loadPersistedProject({ file = DEFAULT_FILE, cwd = defaultCwd(), serverUrl = '' } = {}) {
+  try {
+    const all = JSON.parse(readFileSync(file, 'utf8'));
+    // Pre-composite-key entries (bare cwd) are NOT read back: they carry no record of
+    // which server minted their ids, and adopting one is exactly the cross-DB bleed
+    // above. Worst case the agent re-opens its project once.
+    const e = all && all[stateKey(cwd, serverUrl)];
+    if (e && e.activeProjectId) {
+      return {
+        activeProjectId: e.activeProjectId,
+        activeProjectMeta: e.activeProjectMeta || null,
+        boundOrgId: e.boundOrgId || null,
+      };
+    }
+  } catch { /* no state file yet / unreadable — start fresh */ }
+  return null;
+}
+
+export function savePersistedProject(entry, { file = DEFAULT_FILE, cwd = defaultCwd(), serverUrl = '' } = {}) {
+  try {
+    let all = {};
+    try { all = JSON.parse(readFileSync(file, 'utf8')) || {}; } catch { /* recreate */ }
+    const key = stateKey(cwd, serverUrl);
+    if (key !== cwd) delete all[cwd]; // drop the un-namespaced legacy entry for this cwd
+    if (entry && entry.activeProjectId) {
+      all[key] = {
+        activeProjectId: entry.activeProjectId,
+        activeProjectMeta: entry.activeProjectMeta || null,
+        boundOrgId: entry.boundOrgId || null,
+      };
+    } else {
+      delete all[key];
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(all), { mode: 0o600 });
+    return true;
+  } catch {
+    // Best-effort; persistence is an optimization, never block a tool on it.
+    return false;
+  }
+}

package/mcp/gates.mjs

@@ -0,0 +1,187 @@
+// Pure gate logic for the Drafted compounding harness.
+//
+// These helpers are intentionally side-effect free (no `api()`, no network, no
+// module state) so they can be unit tested in isolation. mcp/server.mjs imports
+// them and wires the decisions into the tool handlers + per-session getState().
+//
+// See docs/plans/compounding-harness.md and the Drafted "gates-checklist" frame.
+
+// One combined per-project budget for the auto-injected priming set:
+// attached-skill bodies + project anchor bodies + the active layer's rules.
+// Single source of truth lives in src/shared so the server-side deposit caps
+// enforce the identical limit. Re-exported here for the MCP gate helpers.
+import { PROJECT_CONTEXT_BUDGET_CHARS, selectWithinBudget } from '../src/shared/gate-budget.mjs';
+export { PROJECT_CONTEXT_BUDGET_CHARS, selectWithinBudget };
+
+// ── Per-session gate flags (reset every MCP session) ──────────────────────────
+
+export function createGateState() {
+  return { wikiSearched: false, skillSearched: false, templateSearched: false };
+}
+
+// kind: 'wiki' | 'skill' | 'template'
+export function markSearched(gateState, kind) {
+  if (kind === 'wiki') gateState.wikiSearched = true;
+  else if (kind === 'skill') gateState.skillSearched = true;
+  else if (kind === 'template') gateState.templateSearched = true;
+  return gateState;
+}
+
+// ── Enforce gates (create chain). Return an error string if blocked, else null ─
+
+export function g1Block(gateState, wikiIndex) {
+  if (gateState.wikiSearched) return null;
+  let msg =
+    'G1: search the org wiki before reading or editing anything. ' +
+    'Call fs(search, path="/wiki", query="<relevant terms>") first, then retry. ' +
+    'More knowledge = less searching — start by drawing on what the org already knows.';
+  if (wikiIndex) msg += `\n\nWiki index (what exists to search):\n${wikiIndex}`;
+  return msg;
+}
+
+export function g2Block(gateState) {
+  if (gateState.skillSearched) return null;
+  return (
+    'G2: search for prior-art skills before creating one. ' +
+    'Call fs(search, path="/skills", query="<topic>") first — if a close match exists, improve it ' +
+    '(/drafted:improve-skill) instead of duplicating — then retry skill(action="add").'
+  );
+}
+
+export function g3Block(gateState) {
+  const missing = [];
+  if (!gateState.wikiSearched) missing.push('fs(search, path="/wiki")');
+  if (!gateState.skillSearched) missing.push('fs(search, path="/skills")');
+  if (!gateState.templateSearched) missing.push('fs(ls, path="/skills")');
+  if (missing.length === 0) return null;
+  return (
+    `G3: search before creating a project. Run ${missing.join(', ')} first ` +
+    '(reuse existing knowledge, skills, and templates), then retry project(action="create").'
+  );
+}
+
+// ── Per-project context budget (auto-inject set) ──────────────────────────────
+
+function itemChars(it) {
+  if (typeof it === 'number') return it;
+  if (typeof it === 'string') return it.length;
+  if (it && typeof it === 'object') {
+    if (typeof it.chars === 'number') return it.chars;
+    if (it.content != null) return String(it.content).length;
+  }
+  return 0;
+}
+
+export function sumChars(items) {
+  if (!Array.isArray(items)) return 0;
+  return items.reduce((total, it) => total + itemChars(it), 0);
+}
+
+export function budgetRemaining(currentTotal, budget = PROJECT_CONTEXT_BUDGET_CHARS) {
+  return Math.max(0, budget - currentTotal);
+}
+
+export function wouldExceedBudget(currentTotal, addChars, budget = PROJECT_CONTEXT_BUDGET_CHARS) {
+  return currentTotal + addChars > budget;
+}
+
+export function budgetError(currentTotal, addChars, label, budget = PROJECT_CONTEXT_BUDGET_CHARS) {
+  const remaining = budgetRemaining(currentTotal, budget);
+  return (
+    `Per-project context budget exceeded: ${label} needs ${addChars} chars but only ${remaining} ` +
+    `of ${budget} remain. Tighten existing attached skills / anchors / layer rules first ` +
+    `(see /drafted:improve-project-harness).`
+  );
+}
+
+// ── G6 layer-rule default detection ───────────────────────────────────────────
+
+// A layer prompt is "default" (skip G6 inject) when it is empty or byte-identical
+// to the template's default prompt for that layer key.
+export function isLayerPromptDefault(layerPrompt, templateDefaultPrompt) {
+  const p = (layerPrompt ?? '').trim();
+  if (p === '') return true;
+  const d = (templateDefaultPrompt ?? '').trim();
+  return d !== '' && p === d;
+}
+
+export function shouldInjectLayerPrompt(layerPrompt, templateDefaultPrompt) {
+  return !isLayerPromptDefault(layerPrompt, templateDefaultPrompt);
+}
+
+// ── Wiki index formatting (bounded map injected with the G1 block) ────────────
+
+export function formatWikiIndex(pages, max = 50) {
+  if (!Array.isArray(pages) || pages.length === 0) return '(wiki is empty — no pages yet)';
+  const lines = pages.slice(0, max).map((p) => {
+    const path = typeof p === 'string' ? p : p.path ?? p.slug ?? '';
+    const title = typeof p === 'object' && p && p.title ? ` — ${p.title}` : '';
+    return `  ${path}${title}`;
+  });
+  const more = pages.length > max ? `\n  …and ${pages.length - max} more` : '';
+  return lines.join('\n') + more;
+}
+
+// ── Project index formatting ──────────────────────────────────────────────────
+// `ls /projects` is an ls, not a stat: one addressable line per project. The
+// previous shape returned the raw /api/projects rows — ~2.4KB each once the
+// per-project `layers` config (912B avg on prod) is pretty-printed — so an org
+// with 180 projects blew the 90KB tool-result cap and came back truncated
+// mid-JSON at 38. Names and paths are what an agent needs to pick one; layers,
+// format, template and share rollups belong on `ls` of the single project.
+
+function relAge(then, now = Date.now()) {
+  const t = then ? new Date(then).getTime() : NaN;
+  if (!Number.isFinite(t)) return '';
+  const d = Math.max(0, Math.floor((now - t) / 86400000));
+  if (d === 0) return 'today';
+  if (d < 7) return `${d}d`;
+  if (d < 60) return `${Math.floor(d / 7)}w`;
+  if (d < 730) return `${Math.floor(d / 30)}mo`;
+  return `${Math.floor(d / 365)}y`;
+}
+
+export function projectPath(p) {
+  const org = p.orgSlug || p.orgId || '';
+  const name = p.slug || p.name || p.id;
+  const folder = p.folder ? `${p.folder}/` : '';
+  return `/o/${org}/projects/${folder}${name}`;
+}
+
+/**
+ * One line per project, most-recently-touched first, with a header naming where
+ * this session is bound. `boundPath` comes from the MCP session's own state —
+ * never the shared active-project row (DRAFT-36: nothing another session can
+ * rewrite may drive what this one reports).
+ */
+export function formatProjectIndex(projects, { max = 50, boundPath = null, now = Date.now() } = {}) {
+  if (!Array.isArray(projects) || projects.length === 0) {
+    return '(no projects — create one with fs(mkdir, path="/o/<org>/projects/<name>"))';
+  }
+  const sorted = [...projects].sort((a, b) => {
+    const at = new Date(a.updatedAt || a.createdAt || 0).getTime();
+    const bt = new Date(b.updatedAt || b.createdAt || 0).getTime();
+    return bt - at;
+  });
+  const shown = sorted.slice(0, max);
+  const paths = shown.map(projectPath);
+  const width = Math.min(60, Math.max(...paths.map((s) => s.length)));
+  const lines = shown.map((p, i) => {
+    const n = Number(p.frameCount);
+    const frames = Number.isFinite(n) && p.frameCount != null ? `${n} frame${n === 1 ? '' : 's'}` : '';
+    const age = relAge(p.updatedAt || p.createdAt, now);
+    const detail = [frames, age].filter(Boolean).join('  ');
+    return `  ${paths[i].padEnd(width)}  ${detail}`.trimEnd();
+  });
+  const orgs = new Set(projects.map((p) => p.orgSlug || p.orgId).filter(Boolean));
+  const header = [
+    `${projects.length} project${projects.length === 1 ? '' : 's'}`,
+    orgs.size > 1 ? `${orgs.size} orgs` : null,
+    boundPath ? `bound: ${boundPath}` : null,
+  ].filter(Boolean).join(' · ');
+  const more = projects.length > max
+    ? `\n  …and ${projects.length - max} more (recency order — narrow with pattern="<glob>" or fs(search, path="/projects", query="<terms>"))`
+    : '';
+  return `${header}\n\n${lines.join('\n')}${more}`;
+}
+

package/mcp/server.mjs

@@ -18,10 +18,10 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import { z } from 'zod';
 import { registerAppResource, RESOURCE_MIME_TYPE } from '@modelcontextprotocol/ext-apps/server';
 import WebSocket from 'ws';
-import { LAYERS } from '../shared/constants.mjs';
+import { LAYERS } from '../src/shared/constants.mjs';
 import { emptyExcalidrawScene, stringifyExcalidrawScene } from '../src/shared/excalidraw.mjs';
 import { formatOkfLogEntry, appendOkfLogEntry } from '../src/shared/okf-log.mjs';
-import { createGateState, markSearched, g1Block, g2Block, g3Block, selectWithinBudget, wouldExceedBudget, budgetError, formatWikiIndex, PROJECT_CONTEXT_BUDGET_CHARS } from './gates.mjs';
+import { createGateState, markSearched, g1Block, g2Block, g3Block, selectWithinBudget, wouldExceedBudget, budgetError, formatWikiIndex, formatProjectIndex, projectPath, PROJECT_CONTEXT_BUDGET_CHARS } from './gates.mjs';
 import { loadPersistedProject, savePersistedProject } from './active-project-store.mjs';
 
 // Frame actions that mutate content — gated by G1 (wiki search before editing).
@@ -350,7 +350,7 @@ const TOOL_ANNOTATIONS = {
   minion:              { title: 'Minions',             readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Manage Minions: checklist-driven intake surfaces that guide a consumer through a checklist (via a shareable /c/<slug> link) and write a producible into the project. Dispatch by `action`: meta, list, get, create, update, enable, disable, delete. QA your own Minions with test_start/test_say/test_resolve — drive the checklist conversation yourself (works even when disabled). Requires the agent allowlist.' },
   trigger:             { title: 'Inbound triggers',    readOnlyHint: false, destructiveHint: true,  openWorldHint: true,  description: 'Manage inbound webhook triggers for the ACTIVE PROJECT: an external system (AppSheet bot, GitHub, form tool) POSTs to the trigger URL and the server runs an agent conversation in the project from the stored prompt template + payload. Dispatch by `action`: create (returns URL + secret token ONCE — relay it to the user immediately, not retrievable later), list, update (enable/disable, edit template, daily limit, executor), rotate (new token), test (fire a synthetic delivery), deliveries (audit log), delete; for executor="queue" triggers, pending/claim/complete let a LOCAL agent poll and work queued deliveries. Requires the agent allowlist.' },
   fs:                  { title: 'Filesystem',           readOnlyHint: false, destructiveHint: true,  openWorldHint: false, description: 'Navigate Drafted like a local filesystem: /wiki/<path> pages, /skills/<slug> procedures, /projects/<folder?>/<project>/<layer>/<lane>/<file> frames. Verbs: ls, read, write, edit, mv, rm, search.' },
-  repo:                { title: 'Git repos',           readOnlyHint: false, destructiveHint: true,  openWorldHint: true,  description: 'Registered git repos — the org index of .agents/ skills + identities. A connected repo is the source of truth for its skills; authoring a Drafted skill whose slug collides with a repo-indexed skill returns 409 repo_owned pointing at the repo. Dispatch by `action`: list (paginated, compact mode), add (link a repo to a folder, --branch optional), rescan (re-fetch the tracked branch), entries (search the index). Content stays in git; Drafted keeps a read-only index.' },
+  repo:                { title: 'Git repos',           readOnlyHint: false, destructiveHint: true,  openWorldHint: true,  description: 'Registered git repos — the org index of .agents/ skills + identities. A connected repo is the source of truth for its skills; EVERY repo connected to ANY folder in the org is searchable and usable org-wide (no org-level repo — the union is the library). Skills from connected repos are readable via fs(read, path="/skills/<slug>") — fetched from git at read time, always fresh. Authoring a Drafted skill whose slug collides with a repo-indexed skill returns 409 repo_owned pointing at the repo. Dispatch by `action`: list (paginated, compact mode), add (link a repo to a folder, --branch optional), rescan (re-fetch the tracked branch), entries (search the index). Content stays in git; Drafted keeps a read-only index.' },
 };
 
 function isMutatingToolCall(name, args = {}) {
@@ -1483,6 +1483,18 @@ function withProjectOverride(meta, fn) {
   );
 }
 
+// Run `fn` with NO project scope, so api() stops auto-appending ?projectId=<bound>.
+// Org-wide questions (searching /projects for a project that exists SOMEWHERE) must
+// not silently inherit whatever project this session happens to be bound to —
+// that scopes the answer to one project and reports "no matches" for the rest.
+function withoutProjectScope(fn) {
+  const base = getState();
+  return requestState.run(
+    { ...base, projectId: null, projectMeta: null, _session: base._session || getSessionState() },
+    fn,
+  );
+}
+
 // Tools that address frames/assets/layout inside ONE project. These accept the
 // per-call `projectId` override; everything else resolves org-side.
 const PROJECT_SCOPED_TOOLS = new Set(['fs']);
@@ -1603,11 +1615,7 @@ async function joinAgentWsRoom(projectId) {
   }
   if (!agentWs) return;
   const msg = JSON.stringify({ type: 'join', projectId, agent: true, agentLabel: getAgentLabel() });
-  if (agentWs.readyState === WebSocket.OPEN) {
-    agentWs.send(msg);
-  } else if (agentWs.readyState === WebSocket.CONNECTING) {
-    agentWs.once('open', () => agentWs.send(msg));
-  }
+  sendAgentWsWhenOpen(msg);
 }
 
 // Tools that are pure introspection/sign-in, not "the agent started working" — excluded from
@@ -1625,11 +1633,26 @@ async function announceSubstantiveWork() {
   }
   if (!agentWs) return;
   const msg = JSON.stringify({ type: 'agent-active', projectId: getState().projectId || null });
-  if (agentWs.readyState === WebSocket.OPEN) {
-    agentWs.send(msg);
-  } else if (agentWs.readyState === WebSocket.CONNECTING) {
-    agentWs.once('open', () => agentWs.send(msg));
-  }
+  sendAgentWsWhenOpen(msg);
+}
+
+// Fire-and-forget send that can NEVER crash the MCP process: captures the socket so a
+// concurrent connectAgentWs() can't swap the global mid-flight (the once('open') closure
+// used to read the global — a reassignment left it sending on a still-CONNECTING socket,
+// the uncaught throw killed the stdio child, and every subsequent MCP call was dead).
+// A dropped ping is harmless (presence/announce only); a dead MCP server is not.
+function sendAgentWsWhenOpen(msg) {
+  const ws = agentWs;
+  if (!ws) return;
+  try {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(msg);
+    } else if (ws.readyState === WebSocket.CONNECTING) {
+      ws.once('open', () => {
+        try { if (ws.readyState === WebSocket.OPEN) ws.send(msg); } catch { /* raced close */ }
+      });
+    }
+  } catch { /* fire-and-forget */ }
 }
 
 // Clone session and connect WebSocket on startup (delayed to let server be ready).
@@ -2927,8 +2950,15 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
       }
       case 'read': {
         if (!slug) return err(new Error('read /skills/<slug>'));
-        const s = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader);
-        return ok(s?.content || '');
+        let s = null;
+        try { s = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader); } catch { /* not in the skills table — fall through to the repo index */ }
+        if (s) return ok(s?.content || '');
+        // Phase 5 resolution: any repo connected to any folder in the org is
+        // readable org-wide. Content is fetched from git at read time (never
+        // stored) — always fresh from the tracked branch.
+        const gitSkill = await api('GET', `/api/repos/skill-content/${encodeURIComponent(slug)}`, undefined, orgHeader).catch(() => null);
+        if (gitSkill?.content != null) return ok(gitSkill.content);
+        return err(new Error(`skill not found: ${slug} — not in the Drafted library and not indexed from any connected repo (repo(action="entries", kind="skill") lists what is indexed)`));
       }
       case 'write': {
         if (!slug) return err(new Error('write /skills/<slug> requires a slug'));
@@ -2983,21 +3013,75 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
     // Resolve the project from the path: <folder?>/<project>/<layer>/<lane>/<file>
     let projectRef = null, layer, lane, filename;
     if (parts.length === 0) {
-      // /projects or /o/<org>/projects — list projects (archived ones live in the
-      // Archive bin and are hidden from the agent's active list — mirroring the web UI).
-      // An org-scoped root lists ONLY that org's projects (Shape A).
-      const projects = await api('GET', '/api/projects');
-      const active = Array.isArray(projects?.projects)
-        ? { ...projects, projects: projects.projects.filter(x => x.folder !== '__archived') }
-        : projects;
-      if (orgFromPath && Array.isArray(active?.projects)) {
+      // /projects or /o/<org>/projects — the root itself. Only ls and search are
+      // meaningful here; everything else needs a project in the path. This used
+      // to return the listing for EVERY action, so fs(search, path="/projects")
+      // silently answered a search with the full project dump.
+      if (action !== 'ls' && action !== 'search') {
+        return err(new Error(`fs ${action} needs a project in the path — /projects is the root (e.g. /o/<org>/projects/<project>/<layer>/<lane>/<file>). Use ls to list or search to find one.`));
+      }
+      // Archived projects live in the Archive bin and are hidden from the agent's
+      // active list — mirroring the web UI. An org-scoped root lists ONLY that
+      // org's projects (Shape A).
+      const listing = await api('GET', '/api/projects');
+      let rows = (Array.isArray(listing?.projects) ? listing.projects : []).filter(x => x.folder !== '__archived');
+      if (orgFromPath) {
         const kept = [];
-        for (const x of active.projects) {
+        for (const x of rows) {
           if (await pathOrgMatches(orgFromPath, x)) kept.push(x);
         }
-        active.projects = kept;
+        rows = kept;
+      }
+      // The bound project is read from THIS session's state, never the shared
+      // active-project row (DRAFT-36 concurrency invariant).
+      const bound = getState().projectMeta;
+      const boundPath = bound?.id ? projectPath(bound) : null;
+
+      if (action === 'ls') {
+        if (pattern) {
+          const rx = new RegExp('^' + String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$', 'i');
+          rows = rows.filter(x => rx.test(x.slug || '') || rx.test(x.name || ''));
+        }
+        return ok(formatProjectIndex(rows, { boundPath }));
       }
-      return ok(active);
+
+      // search: "is there already a project for X?" — match project names first,
+      // then frame labels across the org, so the answer is a handful of
+      // addressable paths instead of the whole inventory.
+      const q = String(query || '').trim();
+      if (!q) return err(new Error('search requires a query — e.g. fs(search, path="/projects", query="<terms>")'));
+      const needle = q.toLowerCase();
+      const hitProjects = rows.filter(x =>
+        [x.name, x.slug, x.description].some(v => String(v || '').toLowerCase().includes(needle))
+      );
+      let frames = [];
+      let frameError = null;
+      try {
+        // Unscoped: this is the org-wide "does anything for X exist?" question.
+        const res = await withoutProjectScope(() => api('GET', `/api/search?q=${encodeURIComponent(q)}`));
+        frames = Array.isArray(res) ? res : (res?.results || []);
+      } catch (e) {
+        // Project matches still answer "does this exist?", so don't fail the whole
+        // call — but say the frame leg broke rather than implying zero hits.
+        frameError = e?.message || String(e);
+      }
+      if (orgFromPath) {
+        const allowed = new Set(rows.map(x => x.id));
+        frames = frames.filter(f => allowed.has(f.projectId));
+      }
+      const out = [];
+      out.push(hitProjects.length
+        ? `Projects matching "${q}":\n${formatProjectIndex(hitProjects, { boundPath })}`
+        : `No project name or description matches "${q}".`);
+      if (frames.length) {
+        const lines = frames.slice(0, 25).map(f =>
+          `  /o/${f.orgSlug || f.orgId}/projects/${f.projectSlug || f.projectId}/${f.layer}/${f.lane || ''}/${f.label}`.replace(/\/\//g, '/')
+        );
+        out.push(`\nFrames matching "${q}" (${frames.length}${frames.length > 25 ? ', first 25' : ''}):\n${lines.join('\n')}`);
+      } else if (frameError) {
+        out.push(`\n(frame search unavailable: ${frameError} — project matches above are complete, frame matches were not checked)`);
+      }
+      return ok(out.join('\n'));
     }
     if (parts.length >= 4) {
       projectRef = parts.length === 4 ? parts[0] : parts[1]; // no-folder vs folder form
@@ -3193,8 +3277,21 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
           return ok(result);
         }
         case 'search': {
-          const result = await api('GET', `/api/fs/search?q=${encodeURIComponent(query || '')}`, undefined, orgHeader);
-          return ok(result);
+          // /api/fs/search has never existed — this 404'd on every call (no fs
+          // route matches a single `/search` segment). /api/search is the real
+          // frame-search route; scope it to the project from the path.
+          const q = String(query || '').trim();
+          if (!q) return err(new Error('search requires a query — e.g. fs(search, path="/projects/<project>", query="<terms>")'));
+          // No explicit &projectId here: run() executes inside withProjectOverride,
+          // so api() already appends the path's project. Adding a second one makes
+          // Express parse projectId as an ARRAY and the scope match nothing.
+          const res = await api('GET', `/api/search?q=${encodeURIComponent(q)}`);
+          const frames = Array.isArray(res) ? res : (res?.results || []);
+          if (!frames.length) return ok(`No frames matching "${q}".`);
+          const lines = frames.slice(0, 50).map(f =>
+            `  /o/${f.orgSlug || f.orgId}/projects/${f.projectSlug || f.projectId}/${f.layer}/${f.lane || ''}/${f.label}`.replace(/\/\//g, '/')
+          );
+          return ok(`${frames.length} frame${frames.length === 1 ? '' : 's'} matching "${q}":\n${lines.join('\n')}`);
         }
         default:
           return err(new Error(`fs ${action} not supported for /projects`));

package/mcp/test-file-path-text.mjs

@@ -0,0 +1,58 @@
+/**
+ * Regression for textFromLocalFile() — the `file_path` text seam used by
+ * fs(write) on /wiki and /skills.
+ *
+ *   node mcp/test-file-path-text.mjs
+ *
+ * Why this exists: /projects uploads bytes (base64 + contentType), /wiki and
+ * /skills take markdown text. Routing a file down the wrong seam stores
+ * mojibake that only surfaces when someone reads the page back, so the binary
+ * guard below is the load-bearing assertion, not a nicety.
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { textFromLocalFile } from './server.mjs';
+
+const dir = mkdtempSync(join(tmpdir(), 'drafted-filepath-'));
+
+// Plain markdown round-trips byte-for-byte.
+const md = join(dir, 'page.md');
+const body = '# Title\n\nBody with a UTF-8 em dash — and an accent é.\n';
+writeFileSync(md, body, 'utf8');
+assert.equal(textFromLocalFile(md), body);
+
+// Multi-byte characters survive — a latin1 read would mangle these.
+assert.ok(textFromLocalFile(md).includes('—'));
+assert.ok(textFromLocalFile(md).includes('é'));
+
+// Empty file returns '' rather than throwing. The caller decides: both write
+// sites treat falsy text as "no content supplied" and error with guidance.
+const empty = join(dir, 'empty.md');
+writeFileSync(empty, '');
+assert.equal(textFromLocalFile(empty), '');
+
+// Binary is refused. A PNG header contains NUL bytes.
+const png = join(dir, 'shot.png');
+writeFileSync(png, Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00]));
+assert.throws(() => textFromLocalFile(png), /looks binary/);
+
+// Directories are refused with a clear message, not an EISDIR stack trace.
+const sub = join(dir, 'nested');
+mkdirSync(sub);
+assert.throws(() => textFromLocalFile(sub), /is a directory/);
+
+// Missing files name the path the caller passed, not the resolved one.
+assert.throws(() => textFromLocalFile(join(dir, 'nope.md')), /file not found/);
+
+// Relative paths resolve against cwd rather than being read blindly.
+assert.throws(() => textFromLocalFile('definitely-not-here-xyz.md'), /file not found/);
+
+console.log('file_path text seam ok — utf8 preserved, binary and dirs refused');
+
+// Importing server.mjs opens the MCP WebSocket at module scope, which pins the
+// event loop open forever. mcp/test-org-guards.mjs only exits because it
+// finishes in ~176ms — before the socket connects — so it passes on a race
+// rather than by design. Exit explicitly instead of inheriting that luck.
+process.exit(0);