drafted 1.8.6 → 1.10.0

package/cli/drafted.mjs

@@ -1200,6 +1200,13 @@ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
 // as the body only (name/description/triggerPatterns are columns), so we prepend
 // YAML frontmatter — JSON scalars are valid YAML — for Causeway's projection and
 // Claude's native loader to read.
+// normalizeSetup mirrors the server (server/lib/skill-hash.mjs) — keep in lockstep.
+function normalizeSetup(setup) {
+  if (setup == null) return [];
+  const arr = Array.isArray(setup) ? setup : [setup];
+  return arr.filter((s) => typeof s === 'string' && s.trim().length > 0);
+}
+
 function synthesizeSkillMd(skill) {
   const lines = ['---', `name: ${JSON.stringify(skill.name || skill.slug || '')}`];
   if (skill.description) lines.push(`description: ${JSON.stringify(skill.description)}`);
@@ -1208,6 +1215,15 @@ function synthesizeSkillMd(skill) {
     lines.push('triggerPatterns:');
     for (const t of triggers) lines.push(`  - ${JSON.stringify(t)}`);
   }
+  // `setup` emitted ONLY when present, so a skill without it produces the exact
+  // SKILL.md (and hash) it did before the field existed. Must match the server.
+  const setup = normalizeSetup(skill.setup);
+  if (setup.length === 1 && typeof skill.setup === 'string') {
+    lines.push(`setup: ${JSON.stringify(setup[0])}`);
+  } else if (setup.length) {
+    lines.push('setup:');
+    for (const s of setup) lines.push(`  - ${JSON.stringify(s)}`);
+  }
   lines.push('---', '');
   return lines.join('\n') + (skill.content || '');
 }
@@ -1233,6 +1249,63 @@ async function unresolvableReason(res, org) {
   return why;
 }
 
+function unquoteYaml(s) {
+  s = s.trim();
+  if (s[0] === '"' && s[s.length - 1] === '"') { try { return JSON.parse(s); } catch { return s.slice(1, -1); } }
+  if (s[0] === "'" && s[s.length - 1] === "'") return s.slice(1, -1);
+  return s;
+}
+
+// Parse the `setup:` block from a SKILL.md YAML frontmatter. Handles an inline
+// scalar (`setup: "cmd"` / `setup: cmd`), an inline JSON array (`setup: ["a","b"]`),
+// and a block list (`setup:` then indented `- cmd` lines). Returns string[].
+function parseSetupFromFrontmatter(md) {
+  const fm = md.match(/^---\n([\s\S]*?)\n---/);
+  if (!fm) return [];
+  const lines = fm[1].split('\n');
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^setup:(.*)$/);
+    if (!m) continue;
+    const rest = m[1].trim();
+    if (rest) {
+      if (rest.startsWith('[')) {
+        try { const arr = JSON.parse(rest); if (Array.isArray(arr)) out.push(...arr.map(String)); } catch { /* malformed inline array */ }
+      } else {
+        out.push(unquoteYaml(rest));
+      }
+    } else {
+      for (let j = i + 1; j < lines.length; j++) {
+        const item = lines[j].match(/^\s+-\s+(.*)$/);
+        if (item) out.push(unquoteYaml(item[1].trim()));
+        else if (lines[j].trim() === '') continue;
+        else break;
+      }
+    }
+    break; // only the first setup: key
+  }
+  return out.filter((s) => s && s.trim());
+}
+
+// Run a source-only skill's setup commands in <dir>, in order. Offline-safe: a
+// failure is reported and the loop stops, but the source in <dir> is never deleted
+// (the caller decides whether to keep or discard). Trusted-by-pinning — adding a
+// skill is the consent, same as cloning a repo and running its install; no per-cmd gate.
+function runSkillSetup(dir) {
+  const skillMd = join(dir, 'SKILL.md');
+  if (!existsSync(skillMd)) return { ok: false, skipped: true, reason: 'no SKILL.md' };
+  let setup;
+  try { setup = parseSetupFromFrontmatter(readFileSync(skillMd, 'utf8')); }
+  catch (e) { return { ok: false, error: `parse SKILL.md: ${(e && e.message) || e}` }; }
+  if (!setup.length) return { ok: true, skipped: true, ran: [] };
+  const ran = [];
+  for (const cmd of setup) {
+    try { execSync(cmd, { cwd: dir, stdio: 'inherit' }); ran.push(cmd); }
+    catch (e) { return { ok: false, failed: cmd, ran, error: String((e && e.message) || e) }; }
+  }
+  return { ok: true, ran };
+}
+
 async function syncOneSkill(ref, outDir, org) {
   const at = ref.lastIndexOf('@');
   const idOrSlug = at > 0 ? ref.slice(0, at) : ref;
@@ -1259,7 +1332,9 @@ async function syncOneSkill(ref, outDir, org) {
     const fdata = await fr.json();
     files[p] = typeof fdata === 'string' ? fdata : (fdata.content || '');
   }
-  const hash = bundleHash(files);
+  // Drafted is the hash authority — prefer the server-reported hash; fall back to
+  // local bundle compute only for older servers that don't return one.
+  const hash = skill.hash || bundleHash(files);
 
   const base = join(outDir, slug);
   for (const [rel, content] of Object.entries(files)) {
@@ -1277,6 +1352,7 @@ skillCmd
   .option('--ref <ref>', 'skill ref slug[@hash] (repeatable)', (v, acc) => { acc.push(v); return acc; }, [])
   .requiredOption('--out <dir>', 'output directory for bundles')
   .option('--org <org>', 'resolve against this Drafted org (id or name); scopes per-request without switching the session')
+  .option('--no-setup', 'do not run each skill\'s setup after materializing (default: run setup so source-only skills are runnable)')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     requireLogin();
@@ -1287,6 +1363,16 @@ skillCmd
     for (const ref of refs) {
       try {
         const r = await syncOneSkill(ref, opts.out, opts.org);
+        // Run setup by default so a synced source-only skill builds and is
+        // immediately runnable. Hash was computed over the source BEFORE setup, so
+        // node_modules/dist from setup never affect it. Offline-safe: a setup
+        // failure is reported but the materialized source stays put (sync is still
+        // `ok` — the bytes are there, just not built).
+        if (r.status === 'ok' && opts.setup !== false) {
+          const s = runSkillSetup(join(opts.out, r.slug));
+          r.setup = s.skipped ? 'none' : (s.ok ? 'ok' : 'failed');
+          if (!s.ok && !s.skipped) r.setupError = s.failed ? `${s.failed}: ${s.error}` : s.error;
+        }
         results.push(r);
         if (r.status !== 'ok') allOk = false;
       } catch (err) {
@@ -1298,7 +1384,8 @@ skillCmd
       console.log(JSON.stringify(results));
     } else {
       for (const r of results) {
-        console.log(`${r.status}\t${r.ref}\t${r.slug}\t${r.hash}${r.error ? '\t' + r.error : ''}`);
+        const setupCol = r.setup ? `\tsetup:${r.setup}` : '';
+        console.log(`${r.status}\t${r.ref}\t${r.slug}\t${r.hash}${setupCol}${r.error ? '\t' + r.error : ''}`);
       }
     }
     process.exit(allOk ? 0 : 1);
@@ -1332,44 +1419,73 @@ skillCmd
     const server = getServerUrl().replace(/\/$/, '');
     const res = await authFetch(`${server}/api/skills`, {
       method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ name: p.name, description: p.description, content: p.content, tags: p.tags, triggerPatterns: p.triggerPatterns }),
+      body: JSON.stringify({ name: p.name, description: p.description, content: p.content, tags: p.tags, triggerPatterns: p.triggerPatterns, setup: p.setup }),
     });
     const data = await res.json().catch(() => ({}));
     if (!res.ok) {
       emitSkillResult(opts.format, { status: res.status === 409 ? 'conflict' : 'error', error: data.error || `HTTP ${res.status}` });
       process.exit(1);
     }
-    emitSkillResult(opts.format, { status: 'ok', slug: data.slug, id: data.id, hash: bundleHash({ 'SKILL.md': synthesizeSkillMd(data) }) });
+    emitSkillResult(opts.format, { status: 'ok', slug: data.slug, id: data.id, hash: data.hash || bundleHash({ 'SKILL.md': synthesizeSkillMd(data) }) });
   });
 
 skillCmd
   .command('update')
-  .description('Update a Drafted skill (--id or --slug) from stdin JSON {description?,content?,triggerPatterns?,tags?}')
+  .description('Update a Drafted skill (--id or --slug) from stdin JSON {name?,description?,content?,triggerPatterns?,tags?,setup?}; auto-forks into your org if the target is read-only (global/other-org)')
   .option('--id <id>', 'skill id')
   .option('--slug <slug>', 'skill slug (resolved to id)')
+  .option('--org <org>', 'fork into / resolve against this Drafted org (id or name)')
   .option('--format <fmt>', 'output format: json or text', 'text')
   .action(async (opts) => {
     requireLogin();
     let p;
     try { p = readStdinJSON(); } catch { console.error('invalid JSON on stdin'); process.exit(1); }
     const server = getServerUrl().replace(/\/$/, '');
+    const orgHeaders = opts.org ? { 'X-Drafted-Org': opts.org } : {};
     let id = opts.id;
+    let slug = opts.slug;
     if (!id && opts.slug) {
-      const lookup = await authFetch(`${server}/api/skills/slug/${encodeURIComponent(opts.slug)}`);
+      const lookup = await authFetch(`${server}/api/skills/slug/${encodeURIComponent(opts.slug)}`, { headers: orgHeaders });
       if (!lookup.ok) { emitSkillResult(opts.format, { status: 'unresolvable', error: `slug ${opts.slug}: HTTP ${lookup.status}` }); process.exit(1); }
-      id = (await lookup.json().catch(() => ({}))).id;
+      const lj = await lookup.json().catch(() => ({}));
+      id = lj.id; slug = lj.slug;
     }
     if (!id) { emitSkillResult(opts.format, { status: 'error', error: 'update requires --id or --slug' }); process.exit(1); }
-    const res = await authFetch(`${server}/api/skills/${id}`, {
-      method: 'PUT', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ name: p.name, description: p.description, content: p.content, tags: p.tags, triggerPatterns: p.triggerPatterns }),
-    });
+    const payload = JSON.stringify({ name: p.name, description: p.description, content: p.content, tags: p.tags, triggerPatterns: p.triggerPatterns, setup: p.setup });
+    const putSkill = (sid) => authFetch(`${server}/api/skills/${sid}`, { method: 'PUT', headers: { 'Content-Type': 'application/json', ...orgHeaders }, body: payload });
+
+    const res = await putSkill(id);
     const data = await res.json().catch(() => ({}));
-    if (!res.ok) {
-      emitSkillResult(opts.format, { status: res.status === 404 ? 'unresolvable' : 'error', error: data.error || `HTTP ${res.status}` });
-      process.exit(1);
+    if (res.ok) {
+      emitSkillResult(opts.format, { status: 'ok', forked: false, slug: data.slug, id: data.id, orgId: data.orgId, hash: data.hash || bundleHash({ 'SKILL.md': synthesizeSkillMd(data) }) });
+      return;
+    }
+    // Auto-fork: the target is read-only (global/system or another org). Fork it into
+    // our org, then write the copy — a single `update` transparently forks-then-writes.
+    // The raw PUT stayed strict (403 skill_read_only); auto-fork is a tool convenience.
+    if (res.status === 403 && data.code === 'skill_read_only') {
+      const forkRes = await authFetch(`${server}/api/skills/${id}/fork`, { method: 'POST', headers: { 'Content-Type': 'application/json', ...orgHeaders } });
+      let forkId;
+      if (forkRes.ok) {
+        forkId = (await forkRes.json().catch(() => ({}))).id;
+      } else if (forkRes.status === 409) {
+        // Org already owns a copy of this slug — update that one (still "forked").
+        const ownSlug = data.slug || slug;
+        const own = await authFetch(`${server}/api/skills/slug/${encodeURIComponent(ownSlug)}`, { headers: orgHeaders });
+        if (!own.ok) { emitSkillResult(opts.format, { status: 'error', error: `resolve existing fork ${ownSlug}: HTTP ${own.status}` }); process.exit(1); }
+        forkId = (await own.json().catch(() => ({}))).id;
+      } else {
+        const fe = await forkRes.json().catch(() => ({}));
+        emitSkillResult(opts.format, { status: 'error', error: `fork failed: ${fe.error || 'HTTP ' + forkRes.status}` }); process.exit(1);
+      }
+      const up = await putSkill(forkId);
+      const ud = await up.json().catch(() => ({}));
+      if (!up.ok) { emitSkillResult(opts.format, { status: 'error', error: `update fork failed: ${ud.error || 'HTTP ' + up.status}` }); process.exit(1); }
+      emitSkillResult(opts.format, { status: 'ok', forked: true, slug: ud.slug, id: ud.id, orgId: ud.orgId, hash: ud.hash || bundleHash({ 'SKILL.md': synthesizeSkillMd(ud) }), forkedFrom: ud.forkedFrom });
+      return;
     }
-    emitSkillResult(opts.format, { status: 'ok', slug: data.slug, id: data.id, hash: bundleHash({ 'SKILL.md': synthesizeSkillMd(data) }) });
+    emitSkillResult(opts.format, { status: res.status === 404 ? 'unresolvable' : 'error', error: data.error || `HTTP ${res.status}` });
+    process.exit(1);
   });
 
 // check reports the current canonical hash for refs WITHOUT materializing — the
@@ -1387,6 +1503,10 @@ async function checkOneSkill(ref, org) {
   if (res.status === 404 || res.status === 403) return { ref, slug: '', hash: '', status: 'unresolvable', error: await unresolvableReason(res, org) };
   if (!res.ok) return { ref, slug: '', hash: '', status: 'error', error: `HTTP ${res.status}` };
   const skill = await res.json();
+  // Drafted is the hash authority — when the server reports a hash, trust it and
+  // skip the per-file fetches entirely (cheap freshness probe). Older servers
+  // without a reported hash fall back to local bundle compute.
+  if (skill.hash) return { ref, slug: skill.slug, hash: skill.hash, status: 'ok', updatedAt: skill.updatedAt };
   const files = { 'SKILL.md': synthesizeSkillMd(skill) };
   for (const p of Array.isArray(skill.files) ? skill.files : []) {
     if (typeof p !== 'string' || p.includes('..')) continue;
@@ -1415,6 +1535,25 @@ skillCmd
     else for (const r of results) console.log(`${r.status}\t${r.ref}\t${r.slug}\t${r.hash}`);
   });
 
+skillCmd
+  .command('setup')
+  .description('Run a source-only skill\'s setup commands (from <dir>/SKILL.md frontmatter) in <dir> — local, offline-safe')
+  .requiredOption('--dir <dir>', 'skill directory containing SKILL.md')
+  .option('--format <fmt>', 'output format: json or text', 'text')
+  .action((opts) => {
+    const r = runSkillSetup(resolve(opts.dir));
+    if (opts.format === 'json') {
+      console.log(JSON.stringify(r));
+    } else if (r.skipped) {
+      console.log(`skipped\t${r.reason || 'no setup'}`);
+    } else if (r.ok) {
+      console.log(`ok\tran ${r.ran.length}`);
+    } else {
+      console.log(`failed\t${r.failed || ''}\t${r.error || ''}`);
+    }
+    process.exit(r.ok ? 0 : 1);
+  });
+
 skillCmd
   .command('remove')
   .description('Delete a Drafted skill by --id (used to clean up throwaway skills)')
@@ -1432,4 +1571,96 @@ skillCmd
     emitSkillResult(opts.format, { status: 'ok', id: opts.id });
   });
 
+// Resolve --slug -> id (honoring --org), shared by fork/push. Returns id or null.
+async function resolveSkillId(opts, server, orgHeaders) {
+  if (opts.id) return opts.id;
+  if (!opts.slug) return null;
+  const lookup = await authFetch(`${server}/api/skills/slug/${encodeURIComponent(opts.slug)}`, { headers: orgHeaders });
+  if (!lookup.ok) return null;
+  return (await lookup.json().catch(() => ({}))).id || null;
+}
+
+skillCmd
+  .command('fork')
+  .description('Fork a skill into your org so you can edit it (block-then-fork; system/other-org skills are read-only)')
+  .option('--id <id>', 'source skill id')
+  .option('--slug <slug>', 'source skill slug (resolved to id)')
+  .option('--org <org>', 'fork into / resolve against this Drafted org (id or name)')
+  .option('--format <fmt>', 'output format: json or text', 'text')
+  .action(async (opts) => {
+    requireLogin();
+    const server = getServerUrl().replace(/\/$/, '');
+    const orgHeaders = opts.org ? { 'X-Drafted-Org': opts.org } : {};
+    const id = await resolveSkillId(opts, server, orgHeaders);
+    if (!id) { emitSkillResult(opts.format, { status: 'unresolvable', error: opts.slug ? `slug ${opts.slug} not found` : 'fork requires --id or --slug' }); process.exit(1); }
+    const res = await authFetch(`${server}/api/skills/${id}/fork`, { method: 'POST', headers: { 'Content-Type': 'application/json', ...orgHeaders } });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) {
+      const status = res.status === 409 ? 'conflict' : (res.status === 404 || res.status === 403 ? 'unresolvable' : 'error');
+      emitSkillResult(opts.format, { status, slug: data.slug, error: data.error || `HTTP ${res.status}` });
+      process.exit(1);
+    }
+    emitSkillResult(opts.format, { status: 'ok', slug: data.slug, id: data.id, hash: data.hash });
+  });
+
+// collectSkillTree walks a local source tree for `skill push`, pre-filtering heavy
+// dirs and any local .skillignore as a convenience so we don't ship a node_modules
+// tree over the wire. The SERVER re-runs the authoritative hygiene pipeline.
+function collectSkillTree(dir) {
+  const root = resolve(dir);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`not a directory: ${dir}`);
+  const SKIP_DIRS = new Set(['node_modules', '.git', '.venv', 'venv', '__pycache__', 'dist', 'build', '.next', 'target', 'coverage', '.cache', '.turbo', '.gradle', 'Pods', '.terraform']);
+  let ignore = () => false;
+  const ignPath = join(root, '.skillignore');
+  if (existsSync(ignPath)) {
+    const pats = readFileSync(ignPath, 'utf8').split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+    ignore = (rel) => pats.some((p) => { const d = p.replace(/\/$/, ''); return rel === d || rel.startsWith(d + '/') || rel.split('/').pop() === d; });
+  }
+  const out = [];
+  const walk = (abs, rel) => {
+    for (const name of readdirSync(abs)) {
+      const childAbs = join(abs, name);
+      const childRel = rel ? `${rel}/${name}` : name;
+      const st = statSync(childAbs);
+      if (st.isDirectory()) { if (SKIP_DIRS.has(name) || ignore(childRel)) continue; walk(childAbs, childRel); }
+      else if (st.isFile()) {
+        if (ignore(childRel)) continue;
+        const content = readFileSync(childAbs, 'utf8');
+        if (content.includes('\x00')) continue; // skip binary; server rejects it anyway
+        out.push({ path: childRel, content });
+      }
+    }
+  };
+  walk(root, '');
+  return out;
+}
+
+skillCmd
+  .command('push')
+  .description('Push a local source tree into a skill (bulk ingest; server strips artifacts + enforces caps)')
+  .option('--id <id>', 'skill id')
+  .option('--slug <slug>', 'skill slug (resolved to id)')
+  .requiredOption('--dir <dir>', 'local source tree to push')
+  .option('--org <org>', 'resolve against this Drafted org (id or name)')
+  .option('--delete-missing', 'remove stored files not present in the pushed tree')
+  .option('--format <fmt>', 'output format: json or text', 'text')
+  .action(async (opts) => {
+    requireLogin();
+    const server = getServerUrl().replace(/\/$/, '');
+    const orgHeaders = opts.org ? { 'X-Drafted-Org': opts.org } : {};
+    const id = await resolveSkillId(opts, server, orgHeaders);
+    if (!id) { emitSkillResult(opts.format, { status: 'unresolvable', error: opts.slug ? `slug ${opts.slug} not found` : 'push requires --id or --slug' }); process.exit(1); }
+    let files;
+    try { files = collectSkillTree(opts.dir); }
+    catch (e) { emitSkillResult(opts.format, { status: 'error', error: String((e && e.message) || e) }); process.exit(1); }
+    const res = await authFetch(`${server}/api/skills/${id}/files/bulk`, {
+      method: 'POST', headers: { 'Content-Type': 'application/json', ...orgHeaders },
+      body: JSON.stringify({ files, deleteMissing: !!opts.deleteMissing }),
+    });
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) { emitSkillResult(opts.format, { status: 'error', id, error: data.error || `HTTP ${res.status}` }); process.exit(1); }
+    if (opts.format === 'json') console.log(JSON.stringify({ status: 'ok', id, hash: data.hash, count: data.count, stripped: data.stripped, files: data.files }));
+    else console.log(`ok\t${id}\t${data.hash}\tpushed ${data.count}${data.stripped ? `, stripped ${data.stripped}` : ''}`);
+  });
+
 program.parse();

package/mcp/server.mjs

@@ -10,7 +10,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { execFile } from 'child_process';
 import { createHash } from 'node:crypto';
-import { readFileSync, existsSync, realpathSync, writeFileSync, mkdirSync, unlinkSync, appendFileSync } from 'fs';
+import { readFileSync, existsSync, realpathSync, writeFileSync, mkdirSync, unlinkSync, appendFileSync, readdirSync, statSync } from 'fs';
 import { join, dirname, basename, extname, resolve } from 'path';
 import { homedir, platform, release as osRelease, arch as osArch } from 'os';
 import { fileURLToPath } from 'url';
@@ -719,13 +719,13 @@ const MIME_MAP = {
 };
 function mimeFromExt(ext) { return MIME_MAP[ext?.toLowerCase()] || 'application/octet-stream'; }
 
-async function api(method, path, body, _retried) {
+async function api(method, path, body, extraHeaders = {}, _retried = false) {
   await ensureSession();
   const pid = getState().projectId;
   const sep = path.includes('?') ? '&' : '?';
   const scopedPath = pid ? `${path}${sep}projectId=${pid}` : path;
   const url = `${getServerUrl()}${scopedPath}`;
-  const headers = { ...getAuthHeaders() };
+  const headers = { ...getAuthHeaders(), ...extraHeaders };
   const opts = { method, headers };
 
   if (body !== undefined) {
@@ -743,7 +743,7 @@ async function api(method, path, body, _retried) {
     getState().sessionId = null;
     const approved = await consumePendingDeviceCode();
     if (!approved) await cloneSession();
-    return api(method, path, body, true);
+    return api(method, path, body, extraHeaders, true);
   }
 
   let data;
@@ -783,7 +783,12 @@ async function api(method, path, body, _retried) {
         `Active project cleared. Call project(action="open") to set a new one, or proceed without one for org-scoped tools (wiki, skill).`
       );
     }
-    throw new Error(msg);
+    // Attach the structured body so callers can key off machine-readable fields
+    // (e.g. `code:"skill_read_only"` to drive auto-fork) instead of matching prose.
+    const apiErr = new Error(msg);
+    apiErr.status = res.status;
+    if (data && typeof data === 'object') { apiErr.code = data.code; apiErr.body = data; }
+    throw apiErr;
   }
   return data;
 }
@@ -2612,10 +2617,45 @@ tool('layout', 'Auto-arrange frames using graph layout algorithm. Positions conn
 
 // ── Skill library tool ───────────────────────────────────────────
 
-tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. Dispatch by `action`: search/load/list for discovery; add/update/remove for org skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory.', {
+// Walk a local source tree for `skill action=push` with dir, pre-filtering heavy
+// dirs + any .skillignore as a convenience so we don't ship a node_modules tree
+// over the wire. The SERVER re-runs the authoritative hygiene pipeline. Mirrors the
+// CLI's collectSkillTree.
+function collectSkillTreeForPush(dir) {
+  const root = resolve(dir);
+  if (!existsSync(root) || !statSync(root).isDirectory()) throw new Error(`not a directory: ${dir}`);
+  const SKIP = new Set(['node_modules', '.git', '.venv', 'venv', '__pycache__', 'dist', 'build', '.next', 'target', 'coverage', '.cache', '.turbo', '.gradle', 'Pods', '.terraform']);
+  const NUL = String.fromCharCode(0);
+  let ignore = () => false;
+  const ign = join(root, '.skillignore');
+  if (existsSync(ign)) {
+    const pats = readFileSync(ign, 'utf8').split(/\r?\n/).map((l) => l.trim()).filter((l) => l && !l.startsWith('#'));
+    ignore = (rel) => pats.some((p) => { const d = p.replace(/\/$/, ''); return rel === d || rel.startsWith(d + '/') || rel.split('/').pop() === d; });
+  }
+  const out = [];
+  const walk = (abs, rel) => {
+    for (const name of readdirSync(abs)) {
+      const childAbs = join(abs, name);
+      const childRel = rel ? `${rel}/${name}` : name;
+      const st = statSync(childAbs);
+      if (st.isDirectory()) { if (SKIP.has(name) || ignore(childRel)) continue; walk(childAbs, childRel); }
+      else if (st.isFile()) {
+        if (ignore(childRel)) continue;
+        const content = readFileSync(childAbs, 'utf8');
+        if (content.includes(NUL)) continue; // skip binary; server rejects it anyway
+        out.push({ path: childRel, content });
+      }
+    }
+  };
+  walk(root, '');
+  return out;
+}
+
+tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/guidelines agents can load and follow. Dispatch by `action`: search/load/list for discovery; add/update/remove for org skills; fork/push for source-only skills; attach/detach for project binding; favorite/unfavorite for personal pins; read_file/update_file for supporting files inside a skill directory.', {
   action: z.enum([
     'search', 'load', 'list',
     'add', 'update', 'remove',
+    'fork', 'push',
     'attach', 'detach',
     'favorite', 'unfavorite',
     'read_file', 'update_file',
@@ -2632,6 +2672,11 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
   content: z.string().optional().describe('[add|update] root SKILL.md content; [update_file] file content'),
   triggerPatterns: z.array(z.string()).optional().describe('[add|update] patterns that suggest this skill'),
   path: z.string().optional().describe('[read_file|update_file] relative path inside skill directory (e.g. "examples/react.md")'),
+  org: z.string().optional().describe('[fork|push|update] resolve/fork into this Drafted org (id or name); scopes the request without switching the session'),
+  setup: z.array(z.string()).optional().describe('[add|update] setup command(s) (in order) run on materialize to build a source-only skill, e.g. ["npm ci","npm run build"]'),
+  files: z.array(z.object({ path: z.string(), content: z.string() })).optional().describe('[push] source files to push (path + UTF-8 content); server strips artifacts + enforces caps'),
+  dir: z.string().optional().describe('[push] local directory to push instead of files[]; walked locally (heavy dirs + .skillignore pre-filtered), server re-enforces'),
+  deleteMissing: z.boolean().optional().describe('[push] remove stored files not present in the pushed set'),
 }, async (args) => {
   try {
     const { action } = args;
@@ -2703,30 +2748,85 @@ tool('skill', 'Manage the Drafted skill library. Skills are reusable prompts/gui
       case 'add': {
         const g2 = g2Block(getSessionState().gates);
         if (g2) return err(new Error(g2));
-        const { name, description, content, tags, triggerPatterns } = args;
+        const { name, description, content, tags, triggerPatterns, setup } = args;
         if (!name || !description || !content) throw new Error('name, description, content required for action=add');
         const body = { name, description, content };
         if (tags) body.tags = tags;
         if (triggerPatterns) body.triggerPatterns = triggerPatterns;
+        if (setup !== undefined) body.setup = setup;
         return ok(await api('POST', '/api/skills', body));
       }
       case 'update': {
-        const { skillId, name, description, content, tags, triggerPatterns } = args;
-        if (!skillId) throw new Error('skillId required for action=update');
+        // Auto-fork-on-update (tool behavior): if the target is read-only (global/
+        // system or another org), the server returns 403 {code:"skill_read_only"};
+        // we fork into the caller's org and write the copy, returning forked:true.
+        // The raw PUT stays strict — this composition lives in the tool, mirroring
+        // the CLI verbatim so consumers treat CLI and MCP identically.
+        const { skillId, skill: slugArg, name, description, content, tags, triggerPatterns, setup, org } = args;
+        const extra = org ? { 'X-Drafted-Org': org } : {};
+        let id = skillId;
+        let slug = slugArg;
+        if (!id && slugArg) { const s = await api('GET', `/api/skills/slug/${slugArg}`, undefined, extra); id = s.id; slug = s.slug; }
+        if (!id) throw new Error('skillId or skill (slug) required for action=update');
         const body = {};
         if (name !== undefined) body.name = name;
         if (description !== undefined) body.description = description;
         if (content !== undefined) body.content = content;
         if (tags !== undefined) body.tags = tags;
         if (triggerPatterns !== undefined) body.triggerPatterns = triggerPatterns;
+        if (setup !== undefined) body.setup = setup;
         if (Object.keys(body).length === 0) throw new Error('At least one field is required for action=update');
-        return ok(await api('PUT', `/api/skills/${skillId}`, body));
+        try {
+          const r = await api('PUT', `/api/skills/${id}`, body, extra);
+          return ok({ ...r, forked: false });
+        } catch (e) {
+          if (e.code !== 'skill_read_only') throw e;
+          let forkId;
+          try {
+            forkId = (await api('POST', `/api/skills/${id}/fork`, {}, extra)).id;
+          } catch (fe) {
+            if (fe.status !== 409) throw fe;
+            const ownSlug = (fe.body && fe.body.slug) || (e.body && e.body.slug) || slug;
+            forkId = (await api('GET', `/api/skills/slug/${ownSlug}`, undefined, extra)).id;
+          }
+          const r2 = await api('PUT', `/api/skills/${forkId}`, body, extra);
+          return ok({ ...r2, forked: true });
+        }
       }
       case 'remove': {
         const { skillId } = args;
         if (!skillId) throw new Error('skillId required for action=remove');
         return ok(await api('DELETE', `/api/skills/${skillId}`));
       }
+      case 'fork': {
+        // Block-then-fork: copy a readable (global/other-org) skill into the
+        // caller's org so it can be edited. Mirrors `drafted skill fork` verbatim.
+        const { skillId, skill: slugArg, org } = args;
+        const extra = org ? { 'X-Drafted-Org': org } : {};
+        let id = skillId;
+        if (!id && slugArg) { const s = await api('GET', `/api/skills/slug/${slugArg}`, undefined, extra); id = s.id; }
+        if (!id) throw new Error('skillId or skill (slug) required for action=fork');
+        try {
+          return ok(await api('POST', `/api/skills/${id}/fork`, {}, extra));
+        } catch (e) {
+          if (e.status === 409) return ok({ status: 'conflict', error: e.message }); // org already owns this slug
+          throw e;
+        }
+      }
+      case 'push': {
+        // Source-tree ingest. Pass files:[{path,content}] (the usual MCP shape) or a
+        // local dir (walked here, server re-enforces the §3 ingest guards). Mirrors
+        // `drafted skill push`.
+        const { skillId, skill: slugArg, files, dir, deleteMissing, org } = args;
+        const extra = org ? { 'X-Drafted-Org': org } : {};
+        let id = skillId;
+        if (!id && slugArg) { const s = await api('GET', `/api/skills/slug/${slugArg}`, undefined, extra); id = s.id; }
+        if (!id) throw new Error('skillId or skill (slug) required for action=push');
+        let fileList = files;
+        if (!fileList && dir) fileList = collectSkillTreeForPush(dir);
+        if (!Array.isArray(fileList) || fileList.length === 0) throw new Error('files[] (non-empty) or dir required for action=push');
+        return ok(await api('POST', `/api/skills/${id}/files/bulk`, { files: fileList, deleteMissing: !!deleteMissing }, extra));
+      }
       case 'attach': {
         const { skillId } = args;
         if (!skillId) throw new Error('skillId required for action=attach');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "drafted",
-  "version": "1.8.6",
+  "version": "1.10.0",
   "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": [