drafted 1.18.2 → 1.18.4

package/cli/drafted.mjs

@@ -1679,7 +1679,7 @@ function emitSkillResult(format, obj) {
 
 skillCmd
   .command('add')
-  .description('Create a skill in Drafted from stdin JSON {name,description,content,readme,tags?,triggerPatterns?} — a README.md (readme field) is required (Phase 1 gate)')
+  .description('Create a skill in Drafted from stdin JSON {name,description,content,readme?,tags?,triggerPatterns?} — readme is optional; omitting it returns the skill with a warning, not an error')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     requireLogin();

package/mcp/server.mjs

@@ -273,6 +273,31 @@ 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).
+// Search matches every TERM in the query, not the raw phrase. A whole-string
+// substring test means a natural multi-word search ("tool surface parity MCP")
+// never hits a project whose name/slug/description contains each of those words
+// — while the single word "parity" does. That reads as "no such project" for a
+// project that is right there. Pure + exported (asserted in mcp/test-search-terms.mjs).
+export function matchesAllTerms(parts, query) {
+  const terms = String(query || '').toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return false;
+  const hay = parts.map((v) => String(v || '')).join(' ').toLowerCase();
+  return terms.every((t) => hay.includes(t));
+}
+
+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
@@ -1543,8 +1568,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 {}
     }
   });
 
@@ -2759,7 +2787,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")'),
@@ -2933,16 +2961,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 || []);
@@ -2950,6 +2983,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 || '');
@@ -2968,6 +3008,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));
@@ -2976,9 +3025,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 */ }
@@ -2987,6 +3041,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);
@@ -2994,6 +3049,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': {
@@ -3050,10 +3106,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
       // 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))
-      );
+      const hitProjects = rows.filter(x => matchesAllTerms([x.name, x.slug, x.description], q));
       let frames = [];
       let frameError = null;
       try {
@@ -3080,6 +3133,12 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         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)`);
+      } else {
+        // Say the frame leg ran and found nothing. Printing only the project leg
+        // leaves "frames were never searched" and "no frame matched" looking the
+        // same, and frame search matches LABELS only — so a term that lives in
+        // frame content is a miss, not an absence.
+        out.push(`\nNo frame label matches "${q}" (frame search matches labels, not frame content).`);
       }
       return ok(out.join('\n'));
     }
@@ -3287,7 +3346,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
           // 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}".`);
+          if (!frames.length) return ok(`No frames matching "${q}" (frame search matches labels, not frame content).`);
           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, '/')
           );

package/mcp/test-search-terms.mjs

@@ -0,0 +1,42 @@
+// Regression for fs(search) term matching on /projects.
+// Run: `node mcp/test-search-terms.mjs`. No framework — asserts the pure core.
+//
+// Why this exists: search used to substring-test the WHOLE query against each
+// field, so `query="tool surface parity MCP Flow"` missed a project whose
+// description says "tool surface" and "parity" — while `query="parity"` hit it.
+// An agent reads that miss as "the project does not exist" and stops looking.
+import assert from 'node:assert/strict';
+import { matchesAllTerms } from './server.mjs';
+
+const proj = [
+  'Flow AI MCP Server Feature Card',
+  'flow-ai-mcp-server-feature-card',
+  'Covers the BEO-2527 parity guard for the agent tool surface.',
+];
+
+// The reported failure: a natural multi-word query spanning name AND description.
+assert.equal(matchesAllTerms(proj, 'tool surface parity MCP Flow'), true);
+// The single word that did work must keep working.
+assert.equal(matchesAllTerms(proj, 'parity'), true);
+// Terms match across fields and across a hyphenated slug.
+assert.equal(matchesAllTerms(proj, 'flow feature card'), true);
+assert.equal(matchesAllTerms(proj, 'BEO-2527'), true);
+// Case and surrounding whitespace are irrelevant.
+assert.equal(matchesAllTerms(proj, '  PARITY   Guard '), true);
+
+// AND, not OR: one unmatched term is a miss. An OR would return most of the org.
+assert.equal(matchesAllTerms(proj, 'parity kubernetes'), false);
+assert.equal(matchesAllTerms(proj, 'kubernetes'), false);
+
+// An empty query never matches — the caller rejects it before this, and
+// "every term" over zero terms would otherwise be vacuously true for every row.
+assert.equal(matchesAllTerms(proj, ''), false);
+assert.equal(matchesAllTerms(proj, '   '), false);
+assert.equal(matchesAllTerms(proj, undefined), false);
+
+// Null/undefined fields don't throw or match a stray "null"/"undefined" term.
+assert.equal(matchesAllTerms([null, undefined, 'alpha'], 'alpha'), true);
+assert.equal(matchesAllTerms([null, undefined, 'alpha'], 'null'), false);
+
+console.log('search term matching ok — every term must hit, across fields, never vacuously');
+process.exit(0);

package/mcp/test-skill-paths.mjs

@@ -0,0 +1,29 @@
+// Regression for the /skills path split used by fs(ls|read|write|rm).
+// Run: `node mcp/test-skill-paths.mjs`. No framework — asserts the pure core.
+//
+// Why this exists: a skill is a directory. Before this split the handler kept
+// only the first segment, so `fs(write, path="/skills/<slug>/README.md")` wrote
+// SKILL.md instead — the agent's README landed on top of the skill body and the
+// create-time README gate stayed unsatisfiable. isSkillMd is the load-bearing
+// bit: true routes to the skills row, false routes to skill_files.
+import assert from 'node:assert/strict';
+import { splitSkillPath } from './server.mjs';
+
+// Root and bare slug — no file, so the skill row itself.
+assert.deepEqual(splitSkillPath('/skills'), { slug: '', filePath: '', isSkillMd: true });
+assert.deepEqual(splitSkillPath('/skills/'), { slug: '', filePath: '', isSkillMd: true });
+assert.deepEqual(splitSkillPath('/skills/my-skill'), { slug: 'my-skill', filePath: '', isSkillMd: true });
+assert.deepEqual(splitSkillPath('/skills/my-skill/'), { slug: 'my-skill', filePath: '', isSkillMd: true });
+
+// SKILL.md is the skill body, addressed explicitly — same destination as the bare slug.
+assert.deepEqual(splitSkillPath('/skills/my-skill/SKILL.md'), { slug: 'my-skill', filePath: 'SKILL.md', isSkillMd: true });
+
+// Everything else is a supporting file, and the subpath survives.
+assert.deepEqual(splitSkillPath('/skills/my-skill/README.md'), { slug: 'my-skill', filePath: 'README.md', isSkillMd: false });
+assert.deepEqual(splitSkillPath('/skills/my-skill/references/api.md'), { slug: 'my-skill', filePath: 'references/api.md', isSkillMd: false });
+
+// Case matters: readme.md is a different file from README.md, and neither is SKILL.md.
+assert.equal(splitSkillPath('/skills/s/skill.md').isSkillMd, false);
+
+console.log('skill path split ok — SKILL.md routes to the skill row, everything else to skill files');
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.18.2",
+  "version": "1.18.4",
   "description": "Drafted — visual thinking surface for humans and AI agents. Renders HTML, markdown, images, and code as frames on a zoomable canvas, with MCP tools for AI agents and real-time sync for humans.",
   "type": "module",
   "files": [

package/plugin/skills/drafted/SKILL.md

@@ -80,7 +80,7 @@ These bookend the loop. Prime/feed at the start, deposit at the end.
 ## Skill authoring
 
 - **Git is the source of truth for skills; Drafted renders, indexes, and searches.** When a repo is connected to a folder, the skills under `.agents/skills/` in that repo ARE the skills for that folder — authoring happens by committing to git, not by writing into Drafted. Drafted write paths for a repo-owned skill return `409 repo_owned` naming the repo, branch, and path to commit to. Use `repo(action="rescan")` after a push so the index reflects the change.
-- **For a folder with NO connected repo, author skills in Drafted** with `fs(write, path="/o/<org>/skills/<slug>", content=..., readme=...)` (G2 gate first). A `README.md` is required (the `readme` param) so the skill directory is self-documenting. `fs(mv, path="/o/<org>/skills/<old>", to="/o/<org>/skills/<new>")` renames.
+- **For a folder with NO connected repo, author skills in Drafted** with `fs(write, path="/o/<org>/skills/<slug>", content=..., readme=...)` (G2 gate first). A `README.md` (the `readme` param) is optional but recommended — it is what renders for the skill directory on GitHub if the skill is ever exported; omitting it creates the skill with a warning. A skill is a directory: `fs(write, path="/o/<org>/skills/<slug>/README.md", content=...)` and any other supporting file work once the skill exists, and `fs(ls, path="/o/<org>/skills/<slug>")` lists them. `fs(mv, path="/o/<org>/skills/<old>", to="/o/<org>/skills/<new>")` renames.
 - **Knowledge goes in the wiki, procedure in skills.** Drafted owns org knowledge (wiki pages via `fs` under `/o/<org>/wiki/`); git owns reusable procedure (skills under `.agents/skills/`). Don't put a skill body in a wiki page or a knowledge doc in a SKILL.md.
 - **Machine-specific build output is never portable.** Build `node_modules`, downloaded browsers, compiled binaries into a `.skillinstall/` directory inside the skill — Drafted always strips it on push and skill push auto-gitignores it, so the rebuildable bundle stays local while the method and recipe live in git/Drafted.
 - **Improve skills when you find a better way.** Fix or distill a skill that underperformed rather than leaving it stale.