drafted 1.17.16 → 1.17.18

package/mcp/server.mjs

@@ -129,6 +129,37 @@ export function runWithRequestState(initial, fn) {
 // Stripped from the advertised schema on remote transports.
 const LOCAL_ONLY_PARAMS = ['file_path'];
 
+/**
+ * Read a local file as UTF-8 text for a `file_path` write to /wiki or /skills.
+ *
+ * Those roots are markdown — they take `content`, not bytes — so this is a
+ * different seam from the /projects upload path, which base64s the file and
+ * sends a contentType. Without this, writing a page or a SKILL.md that already
+ * exists on disk means pasting the whole file through the caller's context,
+ * which for anything sizeable is both slow and lossy.
+ *
+ * stdio only: `file_path` is stripped from the advertised schema on remote
+ * transports (LOCAL_ONLY_PARAMS), because the server has no access to the
+ * caller's filesystem.
+ *
+ * Exported for `mcp/test-file-path-text.mjs`.
+ */
+export function textFromLocalFile(filePath) {
+  let resolved = filePath;
+  try { resolved = resolve(filePath); } catch { /* keep as-is */ }
+  if (!existsSync(resolved)) throw new Error(`file not found: ${filePath}`);
+  if (statSync(resolved).isDirectory()) {
+    throw new Error(`${filePath} is a directory — pass a file`);
+  }
+  const buf = readFileSync(resolved);
+  // A NUL byte means this is not text. Writing it would store mojibake that
+  // only shows up much later, when someone reads the page back.
+  if (buf.includes(0)) {
+    throw new Error(`${filePath} looks binary — /wiki and /skills take text (markdown)`);
+  }
+  return buf.toString('utf8');
+}
+
 // Per-tool params whose value is arbitrary / deeply-nested JSON. Zod renders
 // these (z.any(), z.array(z.any()), z.object({}).passthrough()) as an UNTYPED
 // schema — an empty `{}` or an array whose `items` has no `type`. ChatGPT's
@@ -2697,7 +2728,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
   to: z.string().optional().describe('[mv] destination path'),
   query: z.string().optional().describe('[search] term to match against names/content'),
   content: z.string().optional().describe('[write] inline HTML/markdown/text'),
-  file_path: z.string().optional().describe('[write] absolute path to a local file to upload (stdio only)'),
+  file_path: z.string().optional().describe('[write] absolute path to a local file to upload (stdio only). Under /projects it uploads bytes (images, PDFs, office files); under /wiki and /skills it reads the file as UTF-8 text, so a markdown file on disk can be written straight to a page or a SKILL.md without pasting it.'),
   base64: z.string().optional().describe('[write] base64-encoded binary content'),
   googleType: z.enum(['google-doc', 'google-sheet', 'google-slide']).optional().describe('[write] explicit Google Workspace type (also derived from .google-* filename extension)'),
   title: z.string().optional().describe('[write + googleType] title for a new native file'),
@@ -2808,7 +2839,11 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         return ok(page.content);
       }
       case 'write': {
-        if (!content) return err(new Error('write to /wiki/... requires content'));
+        let text = content;
+        if (text === undefined && file_path) {
+          try { text = textFromLocalFile(file_path); } catch (e) { return err(e); }
+        }
+        if (!text) return err(new Error('write to /wiki/... requires content or file_path'));
         // OKF boundary rule: /a/b.md ≡ a/b — strip a trailing .md so both spellings work.
         const canonPath = wikiPath.replace(/\.md$/, '');
         const existing = await api('GET', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, undefined, orgHeader).catch(() => null);
@@ -2817,9 +2852,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         // here silently forced every MCP-created page to type "Page" and a
         // path-segment title, discarding the author's frontmatter. The server
         // lifts both from the preamble and falls back to the path segment.
-        const body = { path: canonPath, content };
+        const body = { path: canonPath, content: text };
         const result = existing
-          ? await api('PUT', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, { content }, orgHeader)
+          ? await api('PUT', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, { content: text }, orgHeader)
           : await api('POST', '/api/wiki/pages', body, orgHeader);
         return ok(result || { path: canonPath, written: true });
       }
@@ -2894,7 +2929,12 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         return ok(s?.content || '');
       }
       case 'write': {
-        if (!slug || !content) return err(new Error('write /skills/<slug> requires content'));
+        if (!slug) return err(new Error('write /skills/<slug> requires a slug'));
+        let text = content;
+        if (text === undefined && file_path) {
+          try { text = textFromLocalFile(file_path); } catch (e) { return err(e); }
+        }
+        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 (!existing) {
           const g2 = g2Block(gs);
@@ -2905,8 +2945,8 @@ tool('fs', 'Navigate Drafted like a local filesystem. An org is the top folder:
         // (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 }, orgHeader)
-          : await api('POST', '/api/skills', { slug, name, content, description }, orgHeader);
+          ? await api('PUT', `/api/skills/${existing.id}`, { content: text }, orgHeader)
+          : await api('POST', '/api/skills', { slug, name, content: text, description }, 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 */ }

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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.17.16",
+  "version": "1.17.18",
   "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": [
@@ -72,7 +72,7 @@
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "sharp": "^0.34.5",
-    "ws": "^8.16.0",
+    "ws": "^8.21.3",
     "yaml": "^2.8.3",
     "zod": "^4.3.6"
   },

package/plugin/commands/create-project.md

@@ -8,13 +8,13 @@ Spin up a project on the surface, or generalize one into a reusable template. Go
 First ask: **a new project, or a reusable template?** (This command does both.)
 
 Search before creating (also satisfies the gates):
-1. `fs(search, path/o/<org>/wiki", query="<terms>")` for relevant knowledge. [G1]
-2. `fs(search, path/o/<org>/skills", query="<topic>")` for procedures that should be attached. [G2/G3]
+1. `fs(search, path="/o/<org>/wiki", query="<terms>")` for relevant knowledge. [G1]
+2. `fs(search, path="/o/<org>/skills", query="<topic>")` for procedures that should be attached. [G2/G3]
 
 Then:
-- Create the project — a project is a folder: `fs(mkdir, path/o/<org>/projects/<name>")`. It starts with **no layers**; you define them by writing into them.
-- `fs(write, path/o/<org>/projects/<name>/<layer>/<lane>/brief.md", content=...)` a real brief at the earliest layer (goal, audience, constraints — 6-12 lines, not a placeholder). The layer + lane auto-create.
+- Create the project — a project is a folder: `fs(mkdir, path="/o/<org>/projects/<name>")`. It starts with **no layers**; you define them by writing into them.
+- `fs(write, path="/o/<org>/projects/<name>/<layer>/<lane>/brief.md", content=...)` a real brief at the earliest layer (goal, audience, constraints — 6-12 lines, not a placeholder). The layer + lane auto-create.
 - Attach the relevant skills you found via the skill gates.
-- `fs(ls, path/o/<org>/projects/<name>")` to confirm the structure, and hand the user the `projectUrl` from the response.
+- `fs(ls, path="/o/<org>/projects/<name>")` to confirm the structure, and hand the user the `projectUrl` from the response.
 
 For a **template**: build the layer structure + anchored guidance, then note how to fork it next time. Don't speculatively fill downstream frames — wait for direction.

package/plugin/commands/create-skill.md

@@ -6,8 +6,8 @@ argument-hint: <what the procedure is for>
 Turn a repeatable way of working into a Drafted skill so every future agent in the org follows it. Procedure: $ARGUMENTS
 
 Do the searches first (they also satisfy the gates):
-1. `fs(search, path/o/<org>/wiki", query="<terms>")` for relevant org knowledge the procedure should reference. [G1]
-2. `fs(search, path/o/<org>/skills", query="<topic>")` for prior art — an existing skill to improve instead of duplicating. [G2 — also enforced on writing a new skill.] If a close match exists, prefer `/drafted:improve-skill`.
+1. `fs(search, path="/o/<org>/wiki", query="<terms>")` for relevant org knowledge the procedure should reference. [G1]
+2. `fs(search, path="/o/<org>/skills", query="<topic>")` for prior art — an existing skill to improve instead of duplicating. [G2 — also enforced on writing a new skill.] If a close match exists, prefer `/drafted:improve-skill`.
 
 Then define a PROPER procedure, not a vague note:
 - a clear trigger ("when to use this"),
@@ -15,4 +15,4 @@ Then define a PROPER procedure, not a vague note:
 - success criteria / what "done right" looks like,
 - written in the second person so any agent can follow it directly. Keep it sharp (~40 lines).
 
-Show the draft to the user with a proposed `name` (Title Case), one-line `description`, `tags` (3-5), and `triggerPatterns`. After approval, write it with `fs(write, path/o/<org>/skills/<slug>", content=...)` — the slug is derived from the name. Confirm with the slug and note it will auto-surface on matching tasks.
+Show the draft to the user with a proposed `name` (Title Case), one-line `description`, `tags` (3-5), and `triggerPatterns`. After approval, write it with `fs(write, path="/o/<org>/skills/<slug>", content=...)` — the slug is derived from the name. Confirm with the slug and note it will auto-surface on matching tasks.

package/plugin/commands/extract.md

@@ -7,7 +7,7 @@ Session-end deposit. Harvest what's durable from this conversation back into the
 
 Review the session, then **present the user options for which store(s) to deposit into** — don't auto-decide. Offer any that apply:
 
-- **Knowledge → wiki** — durable facts, decisions, or findings worth keeping. Search first (`fs(search, path/o/<org>/wiki", ...)`) to avoid fragmenting, then `fs(write, path/o/<org>/wiki/<path>", ...)`.
+- **Knowledge → wiki** — durable facts, decisions, or findings worth keeping. Search first (`fs(search, path="/o/<org>/wiki", ...)`) to avoid fragmenting, then `fs(write, path="/o/<org>/wiki/<path>", ...)`.
 - **Procedure → skill** — a repeatable way of working that emerged. Follow `/drafted:create-skill`.
 - **Template → surface** — a reusable project structure that emerged. Build it as a project via `fs(mkdir, ...)` + frames.
 

package/plugin/commands/improve-project-harness.md

@@ -7,8 +7,8 @@ When the user had to correct the work in this project, codify the correction so
 
 1. Identify the recurring correction(s) or standing rule from this session.
 2. Choose the right Drafted-side gate per correction (each counts toward the project's context budget):
-   - **Project anchor** — a brief, constraint, or style guide that must be in context project-wide: `fs(write, path/o/<org>/projects/<project>/<layer>/<lane>/<file>", content=...)` it, then anchor it so it surfaces on open. [G5]
-   - **Attached skill** — a procedure that must be loaded before work: `/drafted:create-skill` (or `fs(search, path/o/<org>/skills", ...)` for an existing one), then attach it to the project. [G4]
+   - **Project anchor** — a brief, constraint, or style guide that must be in context project-wide: `fs(write, path="/o/<org>/projects/<project>/<layer>/<lane>/<file>", content=...)` it, then anchor it so it surfaces on open. [G5]
+   - **Attached skill** — a procedure that must be loaded before work: `/drafted:create-skill` (or `fs(search, path="/o/<org>/skills", ...)` for an existing one), then attach it to the project. [G4]
    - **Layer rule** — a standing instruction for one stage: set that layer's rules so work in it is gated. [G6]
 3. Propose which mechanism for each correction, confirm with the user, then apply.
 4. Confirm what is now enforced — the next session in this project will be gated on it automatically.

package/plugin/commands/improve-skill.md

@@ -5,10 +5,10 @@ argument-hint: <which skill, and what's off>
 
 Improve an existing org skill when it underperformed in practice. Skill / issue: $ARGUMENTS
 
-1. `fs(search, path/o/<org>/skills", query="<slug>")` then `fs(read, path/o/<org>/skills/<slug>")` the skill in question — read it fully.
+1. `fs(search, path="/o/<org>/skills", query="<slug>")` then `fs(read, path="/o/<org>/skills/<slug>")` the skill in question — read it fully.
 2. Pinpoint the inefficiency: a missing step, a wrong instruction, an ambiguous trigger, or a step that wastes effort.
 3. Propose the specific edit to the user — show before/after of the changed steps.
-4. After approval, `fs(write, path/o/<org>/skills/<slug>", content=<updated>)` — writing an existing skill updates it (the version bumps automatically). If it was archived, writing restores it.
+4. After approval, `fs(write, path="/o/<org>/skills/<slug>", content=<updated>)` — writing an existing skill updates it (the version bumps automatically). If it was archived, writing restores it.
 5. Confirm what changed so the next agent benefits.
 
 Skills are the org's stable processes — every fix compounds across everyone who uses them.

package/plugin/commands/improve-wiki.md

@@ -5,10 +5,10 @@ argument-hint: <what's wrong, or the topic to clean up>
 
 Improve the org wiki when knowledge has drifted. Issue/topic: $ARGUMENTS
 
-1. `fs(search, path/o/<org>/wiki", query="<terms>")` (3-5 paraphrased queries) and `fs(read, path/o/<org>/wiki/<path>")` the affected pages — don't trust titles, open them.
+1. `fs(search, path="/o/<org>/wiki", query="<terms>")` (3-5 paraphrased queries) and `fs(read, path="/o/<org>/wiki/<path>")` the affected pages — don't trust titles, open them.
 2. Diagnose: duplicate pages, a stale fact, a contradiction, or knowledge fragmented across pages.
 3. Propose the fix to the user: consolidate duplicates, correct the fact, reconcile the contradiction, or re-link fragments.
-4. Apply with `fs(write, path/o/<org>/wiki/<path>", content=<updated>)` (hashline `edit` for surgical changes) or `fs(mv, path/o/<org>/wiki/<from>", to/o/<org>/wiki/<to>")` (which rewrites inbound links). Check what links to a page before moving or archiving it.
-5. Never hard-delete — `fs(rm, path/o/<org>/wiki/<path>")` moves a page to the archive folder.
+4. Apply with `fs(write, path="/o/<org>/wiki/<path>", content=<updated>)` (hashline `edit` for surgical changes) or `fs(mv, path="/o/<org>/wiki/<from>", to="/o/<org>/wiki/<to>")` (which rewrites inbound links). Check what links to a page before moving or archiving it.
+5. Never hard-delete — `fs(rm, path="/o/<org>/wiki/<path>")` moves a page to the archive folder.
 
 Leave the wiki more coherent than you found it — fewer, sharper, better-linked pages.

package/plugin/commands/ingest.md

@@ -12,9 +12,9 @@ First decide WHAT to ingest. If it's obvious from the conversation (a research r
 3. **Interrogate the user** (grill-me) — when the knowledge is in their head. Interview relentlessly, walking ONE branch of the decision tree at a time and proposing your recommended answer at each step, until you reach shared understanding. Then structure what you captured.
 
 Then deposit:
-- `fs(search, path/o/<org>/wiki", query="<terms>")` first (3-5 paraphrased queries) so you don't fragment existing pages.
+- `fs(search, path="/o/<org>/wiki", query="<terms>")` first (3-5 paraphrased queries) so you don't fragment existing pages.
 - Propose the page set to the user before writing.
-- Write with `fs(write, path/o/<org>/wiki/<path>", content=...)` per page. Cross-link related pages.
+- Write with `fs(write, path="/o/<org>/wiki/<path>", content=...)` per page. Cross-link related pages.
 - Confirm what landed where, with the page links.
 
 The wiki is the org's durable knowledge — write for the next agent and teammate, not just this session.