drafted 1.18.1 → 1.18.3

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).
@@ -273,6 +273,19 @@ export function stripUrlOrigin(p) {
   try { return new URL(s).pathname; } catch { return s; }
 }
 
+// A skill is a DIRECTORY: /skills/<slug>/<file>. SKILL.md is the skill's content
+// (the skills table row); every other path is a supporting file (README.md,
+// references/, scripts/) living in skill_files. The handler used to keep only
+// segment 0, so `write /skills/<slug>/README.md` silently rewrote SKILL.md — and
+// the create-time README gate then looked unsatisfiable from this tool.
+// Pure + exported (asserted in mcp/test-skill-paths.mjs).
+export function splitSkillPath(p) {
+  const rest = /^\/skills\/?$/.test(p || '') ? '' : String(p || '').replace(/^\/skills\/?/, '');
+  const segs = rest.split('/').filter(Boolean);
+  const filePath = segs.slice(1).join('/');
+  return { slug: segs[0] || '', filePath, isSkillMd: !filePath || filePath === 'SKILL.md' };
+}
+
 
 export function createMcpServer(transport) {
 // Remote transports (hosted HTTP MCP for claude.ai / ChatGPT) run on the
@@ -1483,6 +1496,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']);
@@ -1531,8 +1556,11 @@ async function connectAgentWs() {
     // suggestedName (basename of the working directory) lets the server offer it in the
     // name-before-work gate message and as the tab placeholder.
     try { agentWs.send(JSON.stringify({ type: 'agent-hello', agentLabel: getAgentLabel(), suggestedName: getSuggestedSessionName() })); } catch {}
+    // Same open-race guard as the hello above: the socket can leave 'open' before
+    // this second send lands, and an unguarded throw here kills the stdio child
+    // (taking the agent's whole MCP connection with it) for a presence message.
     if (getState().projectId) {
-      agentWs.send(JSON.stringify({ type: 'join', projectId: getState().projectId, agent: true, agentLabel: getAgentLabel() }));
+      try { agentWs.send(JSON.stringify({ type: 'join', projectId: getState().projectId, agent: true, agentLabel: getAgentLabel() })); } catch {}
     }
   });
 
@@ -1603,11 +1631,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 +1649,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).
@@ -2736,7 +2775,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
   ops: z.array(z.any()).optional().describe('[edit] hashline ops for text frames. Apply ONLY against a fresh fs(read) of the frame: each op = {type, lineHash, newContent} where type is one of replace | delete | insertAfter | insertBefore, and lineHash is the FULL anchor from the read output (line number + hash, e.g. the token left of the |, like 42srt) — NOT a bare hash. delete/replace consume the target line; at most one replace/delete per line per edit (combine into one replace). If an op targets a line that changed since read it is rejected — re-read and retry. Element ops for excalidraw ({id,x,y,...}), or structured ops for office'),
   state: z.any().optional().describe('[write] app-frame state (JSON) to persist for a deployed windowType:"app" frame; the canvas hydrates the app from it on load. Max 64KB.'),
   metadata: z.any().optional().describe('[write] JSON metadata to attach to the written frame (e.g. {"tour": {title, auto?, steps}} to define a guided tour on this frame). Max 64KB.'),
-  readme: z.string().optional().describe('[write] README.md markdown — required when authoring a NEW skill at /o/<org>/skills/<slug> (the Phase 1 README gate rejects a new skill without one). Stored as a supporting skill file so the skill directory is self-documenting.'),
+  readme: z.string().optional().describe('[write] README.md markdown for a skill at /o/<org>/skills/<slug> — optional on both create and update. Stored as a supporting skill file so the skill directory renders a landing page on GitHub when exported; a skill created without one is returned with a warning, never rejected. Equivalent to a later fs(write, path="/o/<org>/skills/<slug>/README.md").'),
   recursive: z.boolean().optional().describe('[ls] recurse into subdirectories'),
   lines: z.string().optional().describe('[read] line range (e.g. "1-50") — partial read; content is hashline-annotated so a later edit stays surgical'),
   pattern: z.string().optional().describe('[ls] filter filenames (e.g. "*.html")'),
@@ -2910,16 +2949,21 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
 
   // ── Root: /skills/... ──────────────────────────────────────────
   if (p.startsWith('/skills')) {
-    const slug = p === '/skills' || p === '/skills/' ? '' : p.replace(/^\/skills\/?/, '').split('/')[0];
+    const { slug, filePath, isSkillMd } = splitSkillPath(p);
+    const fileUrl = (id) => `/api/skills/${id}/files/${filePath.split('/').map(encodeURIComponent).join('/')}`;
     if (['write', 'mv', 'rm'].includes(action)) {
       await requireBoundOrgForProjectlessMutation(org || orgFromPath);
     }
     switch (action) {
       case 'ls': {
-        // A specific slug is a targeted ls: just that skill, not the whole root.
+        // A specific slug is a targeted ls: the skill's directory — SKILL.md
+        // plus its supporting files, so a README is discoverable.
         if (slug) {
           const s = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader).catch(() => null);
-          return ok(s ? [{ slug: s.slug, name: s.name, description: s.description }] : []);
+          if (!s) return ok([]);
+          const listed = await api('GET', `/api/skills/${s.id}/files`, undefined, orgHeader).catch(() => null);
+          const files = (listed?.files || []).map((f) => f.path || f).filter((f) => f !== 'SKILL.md');
+          return ok({ slug: s.slug, name: s.name, description: s.description, files: ['SKILL.md', ...files] });
         }
         const list = await api('GET', '/api/skills', undefined, orgHeader);
         const skills = Array.isArray(list) ? list : (list?.skills || []);
@@ -2927,6 +2971,13 @@ 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>'));
+        if (!isSkillMd) {
+          const owner = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader).catch(() => null);
+          if (!owner?.id) return err(new Error(`no Drafted-authored skill "${slug}" — supporting files exist only for skills stored in Drafted; a repo-indexed skill lives in git (read its SKILL.md with fs(read, path="/skills/${slug}"))`));
+          const f = await api('GET', fileUrl(owner.id), undefined, orgHeader).catch(() => null);
+          if (f?.content == null) return err(new Error(`file not found in skill ${slug}: ${filePath} (fs(ls, path="/skills/${slug}") lists what is there)`));
+          return ok(f.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 || '');
@@ -2945,6 +2996,15 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         }
         if (!text) return err(new Error('write /skills/<slug> requires content or file_path'));
         const existing = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader).catch(() => null);
+        if (!isSkillMd) {
+          // Supporting file inside an existing skill. It can't create the skill —
+          // the skill row is what owns the file — so say what call does.
+          if (!existing?.id) {
+            return err(new Error(`skill ${slug} does not exist yet — create it first with fs(write, path="/skills/${slug}", content=<SKILL.md markdown>) (add readme=<README.md markdown> to ship a README in the same call), then write supporting files into it.`));
+          }
+          const written = await api('PUT', fileUrl(existing.id), { content: text }, orgHeader);
+          return ok(written || { slug, path: filePath, written: true });
+        }
         if (!existing) {
           const g2 = g2Block(gs);
           if (g2) return err(new Error(g2));
@@ -2953,9 +3013,14 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         // Derive a description from the slug when the agent didn't pass one
         // (the API requires a non-empty description on create).
         const description = args.description || existing?.description || `Reusable procedure: ${name.toLowerCase()}`;
-        const result = existing
-          ? await api('PUT', `/api/skills/${existing.id}`, { content: text }, orgHeader)
-          : await api('POST', '/api/skills', { slug, name, content: text, description, ...(readme ? { readme } : {}) }, orgHeader);
+        let result;
+        if (existing) {
+          result = await api('PUT', `/api/skills/${existing.id}`, { content: text }, orgHeader);
+          // A `readme` passed with an update is a README write, not a no-op.
+          if (readme) await api('PUT', `/api/skills/${existing.id}/files/README.md`, { content: readme }, orgHeader);
+        } else {
+          result = await api('POST', '/api/skills', { slug, name, content: text, description, ...(readme ? { readme } : {}) }, orgHeader);
+        }
         // Writing an archived skill restores it (update flow un-archives).
         if (result?.id && existing?.archived) {
           try { await api('POST', `/api/skills/${result.id}/restore`, undefined, orgHeader); } catch { /* best-effort */ }
@@ -2964,6 +3029,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
       }
       case 'mv': {
         if (!to || !to.startsWith('/skills')) return err(new Error('mv within /skills requires to=/skills/...'));
+        if (!isSkillMd) return err(new Error('mv moves a whole skill (/skills/<slug>), not a file inside one — rewrite the file at its new path and rm the old one'));
         const toSlug = to.replace(/^\/skills\/?/, '').split('/')[0];
         const result = await api('POST', '/api/skills/fork', { from: slug, to: toSlug, ...(org ? { org } : {}) }, orgHeader);
         return ok(result);
@@ -2971,6 +3037,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
       case 'rm': {
         const s = await api('GET', `/api/skills/slug/${slug}`, undefined, orgHeader);
         if (!s?.id) return err(new Error(`skill not found: ${slug}`));
+        if (!isSkillMd) return ok(await api('DELETE', fileUrl(s.id), undefined, orgHeader));
         return ok(await api('DELETE', `/api/skills/${s.id}`, undefined, orgHeader));
       }
       case 'search': {
@@ -2990,21 +3057,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 }));
+      }
+
+      // 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);
       }
-      return ok(active);
+      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
@@ -3200,8 +3321,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);