drafted 1.24.3 → 1.24.4

package/README.md

@@ -1,51 +1,32 @@
 # Drafted
 
-Multi-tenant shared surface for AI-human collaboration. Drafted organizes agent-produced work into **projects** (frames on a zoomable real-time surface), **skills** (reusable operating procedures agents load), and a **wiki** (durable org knowledge) — with MCP tools for agents and a browser UI for humans.
-
-- Product vision and positioning: [PRODUCT.md](PRODUCT.md)
-- Architecture, development, and operations: [AGENTS.md](AGENTS.md)
-- Live: [drafted.live](https://drafted.live)
-
-## OKF-native
-
-Drafted is a native producer and consumer of the **Open Knowledge Format (OKF) v0.1** ([GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)):
-
-- **The org wiki is an OKF v0.1 bundle.** Every page carries conformant YAML frontmatter (required `type`, one-line `description`, `tags`, synthesized `timestamp`; unknown keys preserved). `index.md` at every level is synthesized, `log.md` keeps the date-grouped change history, links resolve with or without `.md`, and broken links are legal. The wiki UI shows a live OKF conformance badge.
-- **Bundle exchange everywhere.** Export/import the wiki (`GET /api/wiki/export.tar.gz`, `POST /api/wiki/import`), the skill library (`skills/<slug>/SKILL.md` layout), and whole projects (`<layer>/<lane>/<file>.md` concepts; markdown links round-trip as connectors) — via HTTP or the MCP `wiki`, `skill`, and `project` tools, with dry-run reports.
+Shared surface for AI-human collaboration. MCP server and CLI for organizing agent work into projects, skills, and durable knowledge.
 
 ## Install
 
-**Claude Code, Codex, or any MCP client** — installs the MCP server, the Drafted skill, *and* the eight slash commands (into `~/.claude/commands/drafted/` and `~/.codex/prompts/drafted/`):
-
 ```bash
-# macOS / Linux — download, then run the local file:
-curl -fsSL https://drafted.live/install.sh -o /tmp/install-drafted.sh
-bash /tmp/install-drafted.sh
-
-# Windows (PowerShell) — download, then run the local file:
-Invoke-WebRequest https://drafted.live/install.ps1 -OutFile $env:TEMP\drafted-install.ps1
-powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\drafted-install.ps1
+npm install -g drafted
 ```
 
-> **Why not `curl | bash` / `irm | iex`?** Heuristic antivirus (Norton IDP, SmartScreen) flags the pipe-to-shell pattern as download-and-execute malware. Downloading the installer to a local file and running it avoids the false-positive block.
+## Usage
 
-> Adding the MCP server on its own (e.g. `claude mcp add`) gives you the tools without the skill or the commands.
+### As an MCP server (for Claude Desktop, Claude Code, Codex, Cursor)
 
-**Claude on the web (claude.ai) and Cowork** — install the plugin, not the bare connector. The plugin bundles the Drafted connector *plus* the Drafted skill and the eight slash commands (`/drafted:onboard-drafted`, `/drafted:create-project`, `/drafted:create-skill`, `/drafted:ingest`, `/drafted:extract`, `/drafted:improve-wiki`, `/drafted:improve-skill`, `/drafted:improve-project-harness`); adding the connector URL on its own gives you the tools with none of the guidance.
+The MCP server is automatically available after install:
 
-> 1. Settings → Customize plugins → Add → Add marketplace → `https://github.com/ddfourtwo/drafted-web` → install **Drafted**.
-> 2. Settings → Connectors → find **Drafted** → **Connect**, then approve the sign-in.
->
-> Both halves matter: the plugin carries the skill and commands, the connector carries the tools. Installing the plugin does not sign you in to the connector.
+```bash
+drafted-mcp
+```
 
-## Quick start (developing Drafted itself)
+### As a CLI
 
 ```bash
-npm install && npm run dev   # Docker services + schema + server with hot reload
+drafted login
+drafted ls
+drafted write designs/default/hero.html < design.html
 ```
 
-- App: http://localhost:3477
-- Email inbox (magic links): http://localhost:8025
-- MinIO console: http://localhost:9001
+## Links
 
-Sign in with any email and grab the magic link from Mailpit.
+- **App**: https://drafted.live
+- **Docs**: https://drafted.live

package/cli/drafted.mjs

@@ -1270,7 +1270,7 @@ function resolveWindowType(source, options, layer) {
 // Command: add
 program
   .command('add <source>')
-  .description('Add frame (upload file or URL to server)')
+  .description('Add frame (upload file or URL to server). Text files (.html/.md/.txt) are stored as inline frames through the same write path a normal save takes — not as binary assets.')
   .option('--label <label>', 'Display label')
   .option('--layer <layer>', 'Layer override (e.g., brand-assets, wireframes, designs)')
   .option('--width <width>', 'Frame width in pixels')

package/mcp/chunked-write.mjs

@@ -0,0 +1,178 @@
+/**
+ * Chunked `fs write` assembly.
+ *
+ * A remote-transport MCP session has no `file_path`: the server cannot read the
+ * caller's disk, so the param is stripped from the advertised schema. That left
+ * exactly one route for a large text frame (a ~1 MB app-frame .html): inline
+ * `content`, i.e. ONE tool call carrying the whole file. A model cannot emit
+ * that in a single call (output-token limit) and clients cap tool-argument
+ * size, so agents hand-rolled authenticated HTTP against /api/fs instead.
+ *
+ * This buffers bounded chunks in the MCP process and hands the joined text to
+ * the ONE normal write, so nothing changes about what the server stores: the
+ * frame is never half-served, version history stays one row, app-frame
+ * detection (looksLikeAppFrame) sees the whole document, and
+ * `expectedUpdatedAt` is enforced once — on the write that actually lands.
+ *
+ * Additive: with no chunk params the fs write handler behaves exactly as
+ * before, and stdio callers keep `file_path`.
+ *
+ * Kept out of server.mjs so it can be tested without importing the MCP server
+ * (which opens a WebSocket at module scope and pins the event loop).
+ */
+
+// One chunk is a tool argument, so it is bounded on purpose: 8 MB is ~8x a
+// 1 MB frame split into a handful of calls and still far under the server's
+// 50 MB JSON body limit. A bigger single chunk gets a clear error instead of a
+// request a client may silently truncate.
+export const MAX_CHUNK_BYTES = 8 * 1024 * 1024;
+// A whole assembled frame: generous for an app frame, small enough that a runaway
+// loop of uploads cannot creep toward the process heap.
+export const MAX_UPLOAD_BYTES = 32 * 1024 * 1024;
+export const MAX_CHUNKS = 1024;
+// An upload nobody finished is garbage after half an hour. Every chunk sweeps,
+// so an abandoned upload costs nothing beyond that window.
+export const IDLE_TTL_MS = 30 * 60 * 1000;
+// Process-wide budget across all in-flight uploads. Per-upload caps alone let
+// N sessions each hold MAX_UPLOAD_BYTES; this is the real ceiling.
+export const MAX_BUFFERED_BYTES = 64 * 1024 * 1024;
+
+/** key -> { total, chunks: Map<index, string>, bytes, opts, content|null, touchedAt } */
+const uploads = new Map();
+
+/** Test seam: an emptied store between cases. */
+export function resetChunkedWrites() {
+  uploads.clear();
+}
+
+export function bufferedBytes() {
+  let total = 0;
+  for (const u of uploads.values()) total += u.bytes;
+  return total;
+}
+
+export function dropUpload(key) {
+  uploads.delete(key);
+}
+
+export function inFlightCount() {
+  return uploads.size;
+}
+
+function byteLength(text) {
+  return Buffer.byteLength(String(text ?? ''), 'utf8');
+}
+
+function sweep(now) {
+  for (const [key, entry] of uploads) {
+    if (now - entry.touchedAt > IDLE_TTL_MS) uploads.delete(key);
+  }
+}
+
+function receivedLabel(entry) {
+  const indexes = [...entry.chunks.keys()].sort((a, b) => a - b);
+  return indexes.length ? indexes.join(', ') : 'none';
+}
+
+function missingIndexes(entry) {
+  const missing = [];
+  for (let i = 0; i < entry.total; i += 1) if (!entry.chunks.has(i)) missing.push(i);
+  return missing;
+}
+
+/**
+ * Accept one chunk. Throws on a chunk that cannot belong to this upload (so the
+ * caller reports it loudly and nothing is written); returns
+ * `{ ready: false, received, total }` while more are needed, and
+ * `{ ready: true, content, opts }` once every index is present.
+ *
+ * Ordering is deliberately tolerant — chunks may arrive in any order, because a
+ * retried call is cheaper than a whole upload restarted — but gaps are NOT
+ * papered over: the final chunk with anything missing throws, naming the
+ * missing indexes. A duplicate index throws too (only an identical re-sent
+ * FINAL chunk is accepted, so a failed commit — a 409 on expectedUpdatedAt,
+ * say — can be retried without re-sending the file).
+ *
+ * opts (metadata, state, expectedUpdatedAt) are merged across chunks: an agent
+ * that just read the frame can put expectedUpdatedAt on the first chunk and it
+ * still applies to the write, which happens at the end.
+ */
+export function acceptChunk({ key, index, total, content, opts = {}, now = Date.now() }) {
+  if (!key) throw new Error('chunked write needs a session + path');
+  if (!Number.isInteger(index) || index < 0) throw new Error('chunkIndex must be a non-negative integer');
+  if (!Number.isInteger(total) || total < 1) throw new Error('chunkTotal must be a positive integer');
+  if (total > MAX_CHUNKS) throw new Error(`chunkTotal ${total} exceeds the ${MAX_CHUNKS}-chunk limit — send larger chunks`);
+  if (index >= total) throw new Error(`chunkIndex ${index} is out of range for a ${total}-chunk write (indexes are 0..${total - 1})`);
+  if (typeof content !== 'string') throw new Error('each chunk needs its slice of the file in content');
+
+  sweep(now);
+
+  // chunk 0 always starts over, so an agent whose upload went wrong can restart
+  // by re-sending the first chunk instead of waiting out the TTL.
+  let entry = index === 0 ? null : uploads.get(key);
+  if (!entry) {
+    entry = { total, chunks: new Map(), bytes: 0, opts: {}, content: null, touchedAt: now };
+    uploads.set(key, entry);
+  } else if (entry.total !== total) {
+    throw new Error(`chunkTotal changed mid-upload (${entry.total} → ${total}) — resend chunk 0 to restart`);
+  }
+
+  // Every index is in: this is a repeat of a final chunk whose commit failed
+  // (a 409 on expectedUpdatedAt, a gate). The assembled text is unchanged, so
+  // re-attempting the write costs no re-upload.
+  if (entry.content !== null) {
+    if (index === entry.total - 1) {
+      for (const [k, v] of Object.entries(opts)) if (v !== undefined) entry.opts[k] = v;
+      return { ready: true, content: entry.content, opts: entry.opts, retried: true };
+    }
+    throw new Error(`this upload already completed (all ${entry.total} chunks received) — chunk ${index} is not part of it. Nothing was written; resend chunk 0 to start a new upload.`);
+  }
+
+  if (entry.chunks.has(index)) {
+    throw new Error(
+      `chunk ${index} was already received (chunks so far: ${receivedLabel(entry)} of ${entry.total}). `
+      + 'Send the chunks that are still missing, or resend chunk 0 to restart the upload. Nothing was written.',
+    );
+  }
+
+  const size = byteLength(content);
+  if (size > MAX_CHUNK_BYTES) {
+    throw new Error(`chunk ${index} is ${size} bytes, over the ${MAX_CHUNK_BYTES}-byte chunk limit — split it into smaller chunks`);
+  }
+  if (entry.bytes + size > MAX_UPLOAD_BYTES) {
+    throw new Error(`this file is over the ${MAX_UPLOAD_BYTES}-byte chunked-write limit (${entry.bytes + size} bytes so far) — chunked writes are for text frames, not bulk media`);
+  }
+  if (bufferedBytes() + size > MAX_BUFFERED_BYTES) {
+    throw new Error('the server is holding too many in-flight chunked writes right now — finish or abandon one and retry');
+  }
+
+  entry.chunks.set(index, content);
+  entry.bytes += size;
+  entry.touchedAt = now;
+  for (const [k, v] of Object.entries(opts)) if (v !== undefined) entry.opts[k] = v;
+
+  if (index !== entry.total - 1) {
+    return { ready: false, received: entry.chunks.size, total: entry.total };
+  }
+
+  const missing = missingIndexes(entry);
+  if (missing.length) {
+    const plural = missing.length > 1;
+    throw new Error(
+      `chunked write is missing chunk${plural ? 's' : ''} ${missing.join(', ')} of ${entry.total} `
+      + `(received: ${receivedLabel(entry)}). Nothing was written — send the missing chunk${plural ? 's' : ''}, `
+      + `then resend chunk ${entry.total - 1} to finish.`,
+    );
+  }
+
+  const parts = [];
+  for (let i = 0; i < entry.total; i += 1) parts.push(entry.chunks.get(i));
+  const joined = parts.join('');
+  // Keep the joined text (not the chunk slices) so a retried commit is cheap;
+  // the slices are dropped here, halving what a finished upload holds.
+  entry.content = joined;
+  entry.chunks = new Map();
+  entry.bytes = byteLength(joined);
+  entry.touchedAt = now;
+  return { ready: true, content: joined, opts: entry.opts };
+}

package/mcp/server.mjs

@@ -19,13 +19,14 @@ 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 '../src/shared/constants.mjs';
+import { LAYERS } from '../shared/constants.mjs';
 import { liftFolderScope, normalizeFolder, rootEntries, splitFolderScope, subfolderEntries } from '../src/shared/folder-path.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, formatProjectIndex, charWindow, READ_PAGE_CHARS, projectPath, PROJECT_CONTEXT_BUDGET_CHARS } from './gates.mjs';
 import { loadPersistedProject, savePersistedProject } from './active-project-store.mjs';
 import { probeRepo, resolveAddress, addressNote } from './repo-address.mjs';
+import { acceptChunk, dropUpload } from './chunked-write.mjs';
 
 // Node 18+ only (global fetch). A GUI client that resolves an old Node (Claude
 // Desktop put nvm v16 first on its PATH, 2026-10-06) otherwise fails every tool call
@@ -1698,6 +1699,28 @@ async function resolveFolderQualifiedProject(parts, orgHint = null) {
   return null;
 }
 
+/**
+ * The system project behind a /tasks root, as the project meta every resolver
+ * hands out.
+ *
+ * POST /api/tasks/project is the ONLY endpoint that can READ that row: a tasks
+ * root is a project with kind='tasks', and /api/projects excludes system
+ * projects by design (`userProjectsOnly`) because a tasks root is not an
+ * entry in the /projects grammar. So resolveProjectRef — which resolves by
+ * LISTING /api/projects — can never find one, and /tasks used to work only
+ * because of a bare-key cache entry seeded moments earlier. An org-addressed
+ * path bypassed that rung by using a different cache key (`<org>|<id>`), which
+ * is why /o/<org>/tasks answered `project not found: <uuid>/tasks` with a uuid
+ * the caller never typed, while `/o/<org>` listed `tasks` as a directory.
+ * Measured on prod 2026-10-21 from a session working in another org.
+ *
+ * Keep the row in hand and pass it on: a lookup here is guaranteed to miss.
+ */
+function tasksProjectMeta(sys) {
+  if (!sys?.id) return null;
+  return { id: sys.id, slug: sys.slug || null, name: sys.name || null, orgId: sys.orgId || null, orgSlug: sys.orgSlug || null, folder: sys.folder || '' };
+}
+
 /**
  * Resolve a project argument to its meta, accepting the pseudo-filesystem path
  * form (/projects/<name> or /projects/<folder>/<name>) OR a bare slug / name /
@@ -1751,12 +1774,14 @@ async function resolveFsFramePath(path) {
   // path that this tool rejects is the worst kind of dead end. Checked after the
   // /projects form so the raw `/projects/tasks/tasks/...` URL still works.
   const taskForm = !urlForm && (p.match(/^\/o\/([^/]+)\/(?:(.+?)\/)?tasks\/(.+)$/) || p.match(/^()()\/tasks\/(.+)$/));
+  let taskMeta = null;
   if (taskForm) {
     const sys = await api('POST', '/api/tasks/project', { create: false }, {
       ...(taskForm[1] ? { 'X-Drafted-Org': decodeURIComponent(taskForm[1]) } : {}),
       ...(taskForm[2] ? { 'X-Drafted-Folder': taskForm[2] } : {}),
     }).catch((e) => (e.status === 404 ? null : Promise.reject(e)));
     if (!sys?.id) throw new Error(`Not found: ${path} — this org has no tasks yet.`);
+    taskMeta = tasksProjectMeta(sys);
     fsPath = `/projects/${sys.id}/tasks/${taskForm[3]}`;
   }
   if (!fsPath.startsWith('/projects')) {
@@ -1783,7 +1808,9 @@ async function resolveFsFramePath(path) {
       throw new Error('Path must include a file: /projects/<project>/<layer>/<lane>/<file>');
     }
   }
-  const meta = await resolveProjectRef(projectRef);
+  // Same rule as the fs tool's /projects branch: the tasks row is already in
+  // hand, and it is not in any listing resolveProjectRef could read.
+  const meta = (taskMeta && projectRef === taskMeta.id) ? taskMeta : await resolveProjectRef(projectRef);
   if (!meta) throw new Error(`Project not found: ${projectRef}`);
   const filePath = lane
     ? `${encodeURIComponent(layer)}/${encodeURIComponent(lane)}/${encodeURIComponent(filename)}`
@@ -3432,14 +3459,16 @@ server.resource('info', 'drafted://info', {
   };
 });
 
-tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. `drafted:assignee:` is a REFERENCE: write a member\'s email or userId (look them up with the `members` tool), or `agent:<name>` to assign an agent. A bare name is resolved against members by unique email local-part; an unknown or ambiguous one is REJECTED with the candidate list, never stored as free text. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: todo, in_progress, in_review, done, canceled -- the Linear set minus Backlog, which this product deliberately does not have (a Backlog column only ever accumulates). The names this system used to store -- open, scheduled, needs_review, needs_decision, failed, backlog -- are still ACCEPTED and normalised (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task. `read` also projects `drafted:id:` (BEO-42), the org-scoped handle a human says out loud: READ-ONLY and server-allocated, so writing or inventing one is silently dropped rather than stored. Quote it back to the user; it resolves at /o/<org>/t/<id> and survives a rename or a move.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move — at THREE scopes, same as `rm`: a FILE path moves one frame; a LANE or LAYER path (`/<layer>/<lane>`, `/<layer>`) moves the whole set in one call, in-project or into another project, carrying frame ids, version history, connectors and assets; a PROJECT path (`/o/<org>/projects/<project>`) renames the project, with `to` as the new display name — the slug and every existing URL stay put), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/o/<org>")` fans out across wiki + skills + projects in one call. SEARCH MUST NAME ITS ORG — put it in the path, or pass org=. If you belong to more than one org an unaddressed search is REFUSED rather than silently scoped, because "no matches" from one org is indistinguishable from "nowhere" and you would stop looking. Search several orgs with one call each; every result says which org it came from), `link` / `unlink` / `links` (ONE link graph across wiki pages, skills, frames, tasks, projects and urls: `link` relates any wiki page, skill or frame to any other node or to a url; `links` on a wiki page, skill or frame lists its edges plus its backlinks from every kind of node, and on a project path lists the tasks linked to that project. Links written IN content are edges too, parsed on every write — markdown links (relative wiki links, or `/o/<org>/...` addresses from any wiki page, skill or frame), HTML `<a href>` addresses, OKF `related:` frontmatter; a bare address in prose is not a link; `unlink` removes only declared ones, so edit the content to drop a written link. A link is stored by ID, so `mv` never breaks it; a link to a page not written yet is stored by path and connects when the page is written). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, `.skillinstall/` is stripped on skill push. ANCHORED SKILLS are enforced by the server on every content write (frames, wiki pages, skills) in the scope they are anchored to — an org, a folder or a project: a write from a session that has not read them is refused with HTTP 428 `anchor_gate`, and the refusal carries the rule text and the `fs(read)` path of each skill; read them, then retry. Anchored FRAMES are not enforced — they are suggested reading only.', {
+tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single container and the org is the folder at depth 0: `fs(ls, path="/")` lists the orgs you can address, `/o/<org>` is that org, and every folder level — the org included — carries the SAME four roots:\n\n- `<folder>/wiki/<path>` — knowledge pages (markdown, OKF; free nesting; `index.md` at any level is synthesized and read-only)\n- `<folder>/skills/<slug>` — reusable procedures (flat: one dir per skill slug, `SKILL.md` + supporting files inside; slugs stay unique per ORG, so a skill resolves by slug from anywhere)\n- `<folder>/tasks/<lane?>/<file>` — work items. A task IS a frame: `read` renders its `drafted:status:`/`drafted:assignee:` as front matter and `write`/`edit` parse them back into columns, so they are never stored in the body. `drafted:assignee:` is a REFERENCE: write a member\'s email or userId (look them up with the `members` tool), or `agent:<name>` to assign an agent. A bare name is resolved against members by unique email local-part; an unknown or ambiguous one is REJECTED with the candidate list, never stored as free text. The keys are namespaced so an ordinary `status:` in your own front matter is left alone. Valid statuses: todo, in_progress, in_review, done, canceled -- the Linear set minus Backlog, which this product deliberately does not have (a Backlog column only ever accumulates). The names this system used to store -- open, scheduled, needs_review, needs_decision, failed, backlog -- are still ACCEPTED and normalised (an empty `drafted:status:` clears it). Status is a column, not a location — a task moved out of /tasks stays a task. `read` also projects `drafted:id:` (BEO-42), the org-scoped handle a human says out loud: READ-ONLY and server-allocated, so writing or inventing one is silently dropped rather than stored. Quote it back to the user; it resolves at /o/<org>/t/<id> and survives a rename or a move.\n- `<folder>/projects/<project>/<layer>/<lane>/<file>` — producible frames (then exactly layer → lane → file)\n\nFolders nest arbitrarily: `/o/<org>/engineering/backend/wiki/deploy`. The ROOT KEYWORD IS THE SEPARATOR — everything before `wiki`/`skills`/`tasks`/`projects` is the folder chain, everything after is the path inside that root, so `/o/<org>/wiki/engineering/foo` (the org wiki, nested page) and `/o/<org>/engineering/wiki/foo` (the engineering folder\'s wiki) are different pages. The four names are therefore RESERVED: a folder cannot be called one. `fs(ls, path="/o/<org>/<folder>")` shows a folder\'s four roots plus the folders inside it; `fs(mkdir, path="/o/<org>/<folder>")` creates one.\n\n(Bare `/wiki`, `/skills`, `/tasks`, `/projects` roots still resolve via the session\'s working org, at that org\'s root.)\n\nVerbs: `ls` (list a directory), `read` (file content — hashline-annotated for text so `edit` stays surgical), `write` (create/overwrite; extension + layer classify the type: .html design, .md document, .excalidraw diagram, .xlsx/.docx office, images/videos media, .pdf asset, .google-doc/.google-sheet/.google-slide create native Google Workspace files), `edit` (hashline ops for text, element ops for excalidraw, structured ops for office), `mv` (rename/move — at THREE scopes, same as `rm`: a FILE path moves one frame; a LANE or LAYER path (`/<layer>/<lane>`, `/<layer>`) moves the whole set in one call, in-project or into another project, carrying frame ids, version history, connectors and assets; a PROJECT path (`/o/<org>/projects/<project>`) renames the project, with `to` as the new display name — the slug and every existing URL stay put), `rm` (delete), `search` (frames are searched by label AND content, with the matching line returned as a snippet; `fs(search, path="/o/<org>")` fans out across wiki + skills + projects in one call. SEARCH MUST NAME ITS ORG — put it in the path, or pass org=. If you belong to more than one org an unaddressed search is REFUSED rather than silently scoped, because "no matches" from one org is indistinguishable from "nowhere" and you would stop looking. Search several orgs with one call each; every result says which org it came from), `link` / `unlink` / `links` (ONE link graph across wiki pages, skills, frames, tasks, projects and urls: `link` relates any wiki page, skill or frame to any other node or to a url; `links` on a wiki page, skill or frame lists its edges plus its backlinks from every kind of node, and on a project path lists the tasks linked to that project. Links written IN content are edges too, parsed on every write — markdown links (relative wiki links, or `/o/<org>/...` addresses from any wiki page, skill or frame), HTML `<a href>` addresses, OKF `related:` frontmatter; a bare address in prose is not a link; `unlink` removes only declared ones, so edit the content to drop a written link. A link is stored by ID, so `mv` never breaks it; a link to a page not written yet is stored by path and connects when the page is written). `mkdir` creates a project only: use `/projects/<project>` or `/projects/<folder>/<project>`, never a layer path. To create a layer, write its first frame at `/projects/<project>/<new-layer>/<lane>/<file>`.\n\nThe project is resolved from the path itself — no separate "open" step. Guardrails are server-side and unchanged: the org in the path must be the project\'s own org (project paths under /o/<org>/ validate it), the G1 wiki-search gate fires before project mutations, `.skillinstall/` is stripped on skill push. ANCHORED SKILLS are enforced by the server on every content write (frames, wiki pages, skills) in the scope they are anchored to — an org, a folder or a project: a write from a session that has not read them is refused with HTTP 428 `anchor_gate`, and the refusal carries the rule text and the `fs(read)` path of each skill; read them, then retry. Anchored FRAMES are not enforced — they are suggested reading only.\n\nLARGE WRITES (chunked): when the content is too big for ONE tool call — a ~1 MB app-frame .html, or any text write from a remote transport, which has no access to a local file — write it in ordered chunks: fs(write, path=…, chunkIndex=0, chunkTotal=N, content=<slice 0>), then 1, … N-1. Each chunk is a contiguous slice of the final file and every chunk carries the same chunkTotal. NOTHING is written until the final chunk (N-1), which performs the one ordinary write: no half-uploaded frame is ever served, no intermediate version is created, app-frame detection sees the whole document, and expectedUpdatedAt is enforced on that single write. A missing index fails at the final chunk with the missing indexes named; a duplicate index fails loudly; chunk 0 restarts a broken upload. Prefer a handful of large chunks (~64–256 KB each) over hundreds of tiny ones. Reading a big frame back is paged — see the read action chars window and nextChars.', {
   action: z.enum(['ls', 'read', 'write', 'edit', 'mv', 'rm', 'mkdir', 'search', 'link', 'unlink', 'links']).describe('Filesystem verb.'),
   path: z.string().describe('Drafted path: /o/<org>[/<folder…>]/wiki/... | .../skills/... | .../tasks/... | .../projects/... — a folder chain may precede any root (bare /wiki, /skills, /tasks, /projects also work; for mv: source)'),
   to: z.string().optional().describe('[mv] destination — a frame path for a frame, a container path (/<layer> or /<layer>/<lane>, optionally prefixed /o/<org>/projects/<other-project>/… to move across projects) for a lane or layer, or the NEW NAME when the source path is a project; [link/unlink] target path — a wiki page (/o/<org>[/<folder>]/wiki/<page>), a skill (/o/<org>/skills/<slug>), a task, a frame path, or a project path (/o/<org>/projects/<project>) to link a task to a project'),
   url: z.string().optional().describe('[link/unlink] external target URL, instead of `to` (a link is internal-by-id OR external-by-url, never both)'),
   query: z.string().optional().describe('[search] term to match against names/content. The path must name an org (/o/<org>) unless you belong to exactly one.'),
-  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). 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.'),
+  content: z.string().optional().describe('[write] inline HTML/markdown/text. Too large for one tool call (a ~1 MB app-frame .html, or any write on a remote transport, which has no local path)? Send it in chunks: add chunkIndex + chunkTotal; each chunk carries one slice in content.'),
+  file_path: z.string().optional().describe('[write] absolute path to a local file (stdio only — a remote transport runs on the server and cannot see your disk, so this param is not advertised there; send content= instead, chunked with chunkIndex/chunkTotal when it is too big for one call). TEXT goes through the NORMAL write path, not an asset upload: .html/.md/.txt/.json are treated like an inline save, so an HTML carrying the drafted:frame-type=app marker still becomes windowType:"app", with version history, metadata and expectedUpdatedAt all applying exactly as usual. Only genuinely binary files (images, PDFs, office documents, video) are stored as assets in object storage.'),
+  chunkIndex: z.number().int().min(0).optional().describe('[write] chunked large-content write: 0-based index of THIS chunk. Pair it with chunkTotal on every chunk. Every chunk must be a contiguous slice of the final file, in order, and chunk 0 starts a fresh assembly (so a broken upload restarts by re-sending chunk 0). Only the final chunk (chunkTotal-1) writes the frame — earlier chunks store nothing, so a half-uploaded frame is never served and no intermediate version is created. Chunks may arrive out of order, but a gap fails at the final chunk with the missing indexes named, and a duplicate index fails loudly. metadata, state and expectedUpdatedAt ride on any chunk and are applied to the one write.'),
+  chunkTotal: z.number().int().min(1).optional().describe('[write] chunked large-content write: total number of chunks in this write, the same value on every chunk.'),
   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'),
@@ -3454,10 +3483,59 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
   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")'),
   readonly: z.boolean().optional().describe('[link] read-only frame link (symlink): mirror the SOURCE frame named by `to` (a frame UUID or /projects/<other-project>/<layer>/<lane>/<file>) into the CURRENT project, displayed read-only. The source project stays the single writer.'),
-  org: z.string().optional().describe('Org (id or name) for bare /wiki and /skills paths (org-scoped /o/<org>/... paths don\'t need it). Per-request only; project paths self-derive org from the project row.'),
+  org: z.string().optional().describe('Org (id or name) for bare /wiki, /skills and /tasks paths (org-scoped /o/<org>/... paths don\'t need it). Per-request only; project paths self-derive org from the project row.'),
   projectId: PROJECT_OVERRIDE_PARAM,
 }, async (args) => {
-  const { action, path: rawPath, to: rawTo, query, content, file_path, base64, googleType, title, ops, state, metadata, expectedUpdatedAt, readme, recursive, pattern, lines, org } = args;
+  const { action, path: rawPath, to: rawTo, query, file_path, base64, googleType, title, ops, readme, recursive, pattern, lines, org, chunkIndex, chunkTotal } = args;
+  // content / state / metadata / expectedUpdatedAt are reassigned by a chunked
+  // write below (the assembled file replaces the per-call slice).
+  let { content, state, metadata, expectedUpdatedAt } = args;
+  // ── Chunked large-content write (./chunked-write.mjs) ───────────
+  // A remote transport has no `file_path` (stripped from the schema — the server
+  // cannot read the caller's disk) and a model cannot emit a ~1 MB app frame in
+  // one tool call, so large text was previously only writable by hand-rolling
+  // authenticated HTTP against /api/fs. Bounded chunks are buffered here and the
+  // joined text goes through the ONE ordinary write below: the frame is never
+  // half-served, version history stays one row, app-frame detection sees the whole
+  // document, and expectedUpdatedAt is enforced once, on the write that lands.
+  // Additive: with no chunk params the handler is unchanged, and stdio keeps file_path.
+  let chunkKey = null;
+  if (action === 'write' && (chunkIndex !== undefined || chunkTotal !== undefined)) {
+    if (chunkIndex === undefined || chunkTotal === undefined) {
+      return err(new Error('a chunked write needs both chunkIndex and chunkTotal on every chunk'));
+    }
+    if (googleType || /\.google-(doc|sheet|slide)$/i.test(String(rawPath))) {
+      return err(new Error('chunked writes fill text frames and wiki/skill pages — a Google Workspace file takes its whole content in one call'));
+    }
+    // Session-scoped so two sessions writing the same path can never assemble each
+    // other's bytes. Hashed because it is a session token; the key is only ever a
+    // map key and is never echoed into a response or an error.
+    const sessionPart = createHash('sha256').update(String(getState().sessionId || (getSessionState()._stdio ? '__stdio__' : 'unbound'))).digest('hex').slice(0, 16);
+    chunkKey = `${sessionPart}\n${stripUrlOrigin(String(rawPath))}`;
+    try {
+      const chunk = acceptChunk({
+        key: chunkKey,
+        index: chunkIndex,
+        total: chunkTotal,
+        content,
+        opts: { metadata, state, expectedUpdatedAt },
+      });
+      if (!chunk.ready) {
+        return ok({
+          path: rawPath,
+          chunked: true,
+          committed: false,
+          received: chunk.received,
+          total: chunk.total,
+          note: `Chunk ${chunkIndex} stored (${chunk.received}/${chunk.total}). Nothing has been written yet — the frame is only written when the final chunk (chunkIndex ${chunk.total - 1}) arrives, so a half-uploaded frame is never served.`,
+        });
+      }
+      content = chunk.content;
+      metadata = chunk.opts.metadata;
+      state = chunk.opts.state;
+      expectedUpdatedAt = chunk.opts.expectedUpdatedAt;
+    } catch (e) { return err(e); }
+  }
   // Org-scoped path (Shape A): /o/<org>/<root>/... — strip the org segment here,
   // carry it as the per-request org scope (orgHeader), validate per-root below.
   // The PATH is the address; the org= param is legacy for bare roots only, and a
@@ -3815,6 +3893,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
         const result = existing
           ? await api('PUT', `/api/wiki/page?path=${encodeURIComponent(canonPath)}`, { content: text }, orgHeader)
           : await api('POST', '/api/wiki/pages', body, orgHeader);
+        if (chunkKey) dropUpload(chunkKey);
         return ok(result || { path: canonPath, written: true });
       }
       case 'edit': {
@@ -3927,6 +4006,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
             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);
+          if (chunkKey) dropUpload(chunkKey);
           return ok(written || { slug, path: filePath, written: true });
         }
         if (!existing) {
@@ -3949,6 +4029,7 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
         if (result?.id && existing?.archived) {
           try { await api('POST', `/api/skills/${result.id}/restore`, undefined, orgHeader); } catch { /* best-effort */ }
         }
+        if (chunkKey) dropUpload(chunkKey);
         return ok(result || { slug, written: true });
       }
       case 'mv': {
@@ -3982,6 +4063,9 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
   // status/assignee live in COLUMNS (projected as front matter by read/write),
   // so a task moved out of here stays a task.
   const isTasksPath = (x) => x === '/tasks' || x === '/tasks/' || String(x || '').startsWith('/tasks/');
+  // The row /api/tasks/project just returned, kept so the /projects branch below
+  // does not try to look it up again (see tasksProjectMeta).
+  let tasksMeta = null;
   if (isTasksPath(p) || isTasksPath(to)) {
     if (['write', 'edit', 'mv', 'rm', 'link', 'unlink'].includes(action)) {
       // Project-less: the org cannot be guessed (same guard as /wiki and /skills).
@@ -4005,9 +4089,8 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
       if (readOnly) return err(new Error(`Not found: ${p} — this org has no tasks yet.`));
       return err(new Error('could not resolve the tasks project for this org'));
     }
-    // Seed the cache by id so the /projects branch resolves it without a lookup
-    // (its /api/projects listing is not org-scoped).
-    projectRefCache.set(sys.id, { id: sys.id, slug: sys.slug, name: sys.name, orgId: sys.orgId, orgSlug: sys.orgSlug });
+    tasksMeta = tasksProjectMeta(sys);
+    projectRefCache.set(sys.id, tasksMeta);
     const rewrite = (x) => `/projects/${sys.id}/tasks${x === '/tasks' || x === '/tasks/' ? '' : x.slice('/tasks'.length)}`;
     if (isTasksPath(p)) p = rewrite(p);
     if (isTasksPath(to)) to = rewrite(to);
@@ -4127,7 +4210,13 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
     let lookupError = null;
     // The org from the path rides the lookup: without it a project in another
     // org was invisible and every write to it answered "project not found".
-    let pathProject = await resolveProjectRef(projectRef, orgFromPath || org || null).catch((e) => { lookupError = e; return null; });
+    // A /tasks root is the ONE exception: it was already resolved above from the
+    // only endpoint that can read it, so it must not be looked up again here —
+    // /api/projects excludes system projects, so this lookup is guaranteed to
+    // miss (and used to, which the caller saw as "project not found: <uuid>/tasks").
+    let pathProject = (tasksMeta && projectRef === tasksMeta.id)
+      ? tasksMeta
+      : await resolveProjectRef(projectRef, orgFromPath || org || null).catch((e) => { lookupError = e; return null; });
     if (!pathProject?.id && parts.length > 1) {
       const found = await resolveFolderQualifiedProject(parts, orgFromPath || org || null);
       if (found) { projectRef = parts[found.index]; tail = parts.slice(found.index + 1); pathProject = found.meta; }
@@ -4329,10 +4418,23 @@ tool('fs', 'Navigate Drafted like a local filesystem. A FOLDER is the single con
           else return err(new Error('write requires one of content / file_path / base64 / googleType / state'));
           if (metadata !== undefined) body.metadata = metadata;
           if (expectedUpdatedAt) body.expectedUpdatedAt = expectedUpdatedAt;
-          const result = await api('PUT', `/api/fs/${filePath}`, body, orgHeader);
+          let result;
+          try {
+            result = await api('PUT', `/api/fs/${filePath}`, body, orgHeader);
+          } catch (e) {
+            // A chunked write keeps its assembly here: a refusal at finalize (a
+            // stale expectedUpdatedAt → 409 "conflict", an anchor gate) is
+            // reported plainly, and re-sending the final chunk retries the write
+            // rather than the whole upload.
+            if (chunkKey) return err(e);
+            throw e;
+          }
           if (state !== undefined && result?.id) {
             try { await api('POST', `/api/file/${result.id}/state`, { state }); } catch { /* state best-effort */ }
           }
+          // Only now is the assembly spent: re-sending the final chunk after a
+          // refusal retries the write instead of the whole upload.
+          if (chunkKey) dropUpload(chunkKey);
           return ok(result);
         }
         case 'edit': {

package/package.json

@@ -1,44 +1,38 @@
 {
   "name": "drafted",
-  "version": "1.24.3",
-  "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.",
+  "version": "1.24.4",
+  "description": "Shared surface for AI-human collaboration — MCP server and CLI",
   "type": "module",
   "bin": {
     "drafted": "./cli/drafted.mjs",
     "drafted-mcp": "./mcp/server.mjs"
   },
   "files": [
-    "cli/",
     "mcp/",
-    "server/lib/umami.mjs",
-    "src/shared/",
-    "agent-instructions/",
-    "plugin/skills/",
-    "plugin/commands/",
-    "install-mcp.sh"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ddfourtwo/drafted.git"
-  },
-  "keywords": [
-    "design",
-    "canvas",
-    "preview",
-    "html",
-    "claude"
+    "cli/",
+    "shared/",
+    "skills/",
+    "README.md"
   ],
   "dependencies": {
-    "@modelcontextprotocol/ext-apps": "^1.6.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "commander": "^11.1.0",
     "qrcode-terminal": "^0.12.0",
-    "ws": "^8.21.3",
-    "yaml": "^2.8.3",
+    "ws": "^8.16.0",
     "zod": "^4.3.6"
   },
-  "scripts": {
-    "postpublish": "bash ../scripts/sync-plugin.sh \"chore: sync plugin to v$npm_package_version\" && bash ../scripts/sync-web-plugin.sh \"chore: sync web-plugin to v$npm_package_version\""
-  }
+  "keywords": [
+    "drafted",
+    "design",
+    "mcp",
+    "claude",
+    "ai",
+    "canvas"
+  ],
+  "author": "ddfourtwo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ddfourtwo/drafted.git"
+  },
+  "license": "MIT"
 }