@yojahny/wp-design-library 1.1.1 → 1.2.0

package/README.md

@@ -151,6 +151,20 @@ same as `add`, not first at `save`. Output is one JSON line per file:
 exits 1 if any file was refused. `--inbox` never saves — every draft still
 waits for a tagging session and `library save`.
 
+For a hosted server, stage a local recording through its authenticated upload endpoint:
+
+```bash
+LIBRARY_TOKEN=… node bin/library.mjs upload ~/Desktop/acme.webm \
+  --server https://wp-design-library.example \
+  --source public-site \
+  --url https://acme.example \
+  --license "description only, no redistribution of the source"
+```
+
+The token is read only from the environment. The server writes the recording and an
+optional metadata sidecar into `<data>/inbox`; duplicate filenames are refused. HTTP MCP
+tools may then refer to the returned bare filename. Uploads default to a 512 MiB limit.
+
 ### From a Claude Code session: `/mcp__wp-design-library__add-entry`
 
 With the server registered in a session (the `claude-wp-builder` plugin registers it,
@@ -181,6 +195,11 @@ server's record of what it measured. `get_vocab` returns the controlled terms, a
 interrupted run stopped. Editing `entries/<slug>/entry.md` by hand remains available in
 a local checkout and does the same thing.
 
+For a reviewed batch, use `get_draft` to inspect each unsaved strip, submit judgement
+fields in chunks with `set_fields_batch`, then call `save_batch` once. Invalid entries are
+reported independently, and the search index rebuilds once for all valid slugs. The MCP
+prompt `/mcp__wp-design-library__add-batch` walks an agent through the complete workflow.
+
 What goes where, with the values checked against `vocab.yaml`:
 
 | Field | What to write |
@@ -260,11 +279,12 @@ node bin/library.mjs check         # validate every entry, 1 line per problem
 node bin/library.mjs check --remote  # + confirm every recorded artifact key resolves in R2
 ```
 
-Over MCP, seven tools: `search` (keyword + facet filters, aliases resolved),
-`get_entry` (pass `detail: "summary"` for just the body's first paragraph, instead of
-the default `"full"`), `similar`, `recommend` (turns a brief into a per-role reference
-set in one call), `add` (pass `attach` to add a second capture — a video beside a live
-URL — to an existing entry instead of refusing it), `refresh`, `save_entry`. `search` and `similar` carry
+Over MCP, the read tools are `search` (keyword + facet filters, aliases resolved),
+`get_entry` (pass `detail: "summary"` for the first prose paragraph), `get_draft`,
+`get_motion`, `similar`, `recommend`, and `get_vocab`. Authoring uses `add`, `add_batch`,
+`set_fields`, `set_fields_batch`, `save_entry`, `save_batch`, and `refresh`. Pass `attach`
+to `add` to add a second capture — a video beside a live URL — without replacing the
+existing entry. `search` and `similar` carry
 `arms` (which retrieval arms ran; `["fts"]` in Phase 1); any tool may instead respond
 with `refused` and the reason.
 
@@ -334,6 +354,7 @@ skipped to stderr.
 | `LIBRARY_DATA` | repo root | where `entries/` and the index live (the volume in Docker) |
 | `LIBRARY_SEED` | `<repo>/entries` | entries copied into `LIBRARY_DATA` on start when missing |
 | `LIBRARY_TOKEN` | none | required for `--http`; the server refuses to start without it |
+| `LIBRARY_UPLOAD_MAX_BYTES` | `536870912` | maximum body accepted by authenticated `PUT /inbox/<filename>` |
 | `PORT` | `4180` | HTTP port |
 | `LIBRARY_EMBED` | none (real embedder if models present, else skipped) | `stub` for the offline deterministic embedder, `off` to skip the `vec` arm |
 | `LIBRARY_MODELS` | `<data>/models` | where the `@huggingface/transformers` model files live |

package/bin/library.mjs

@@ -12,6 +12,7 @@ const cmds = {
   save: () => import('../src/cli/save.mjs'),
   export: () => import('../src/cli/export.mjs'),
   ui: () => import('../src/cli/ui.mjs'),
+  upload: () => import('../src/cli/upload.mjs'),
 };
 // Refero discovery is a repository-maintenance tool. The npm package deliberately
 // omits its module, so it is only available from a checkout that contains it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Design reference corpus and MCP server for claude-wp-builder",
   "repository": {
     "type": "git",
@@ -65,6 +65,7 @@
     "src/cli/refresh.mjs",
     "src/cli/save.mjs",
     "src/cli/serve.mjs",
+    "src/cli/upload.mjs",
     "src/cli/ui.mjs",
     "src/entry.mjs",
     "src/index/",

package/src/cli/upload.mjs

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+
+function opt(args, name) {
+  const i = args.indexOf(name);
+  return i === -1 ? undefined : args[i + 1];
+}
+
+export async function uploadFile({ file, server, token, source, license, url, title, fetcher = fetch }) {
+  if (!file) throw new Error('usage: library upload <file> --server <url> [--source kind --license text --url source-url --title title]');
+  if (!server) throw new Error('--server or LIBRARY_SERVER is required');
+  if (!token) throw new Error('LIBRARY_TOKEN is required');
+  if (!fs.existsSync(file) || !fs.statSync(file).isFile()) throw new Error(`file does not exist: ${file}`);
+  if ((source && !license) || (!source && license)) throw new Error('--source and --license must be provided together');
+
+  const name = path.basename(file);
+  const endpoint = new URL(`/inbox/${encodeURIComponent(name)}`, server);
+  if (!['http:', 'https:'].includes(endpoint.protocol)) throw new Error('--server must be an HTTP(S) URL');
+  const headers = {
+    authorization: `Bearer ${token}`,
+    'content-type': 'application/octet-stream',
+    'content-length': String(fs.statSync(file).size),
+  };
+  if (source) headers['x-library-source'] = source;
+  if (license) headers['x-library-license'] = license;
+  if (url) headers['x-library-url'] = url;
+  if (title) headers['x-library-title'] = title;
+
+  const response = await fetcher(endpoint, {
+    method: 'PUT', headers,
+    body: Readable.toWeb(fs.createReadStream(file)),
+    duplex: 'half',
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`upload refused (${response.status}): ${text}`);
+  return JSON.parse(text);
+}
+
+export async function run(args) {
+  try {
+    const result = await uploadFile({
+      file: args[0],
+      server: opt(args, '--server') ?? process.env.LIBRARY_SERVER,
+      token: process.env.LIBRARY_TOKEN,
+      source: opt(args, '--source'),
+      license: opt(args, '--license'),
+      url: opt(args, '--url'),
+      title: opt(args, '--title'),
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return 0;
+  } catch (err) {
+    process.stderr.write(`${err.message}\n`);
+    return 1;
+  }
+}

package/src/ingest/save.mjs

@@ -1,11 +1,33 @@
+import path from 'node:path';
 import { parseEntry, validateEntry } from '../entry.mjs';
 import { buildIndex } from '../index/build.mjs';
 
 export async function saveEntry({ dir, vocab, indexPath, entriesDir, models, p }) {
-  const e = parseEntry(dir);
-  const r = validateEntry(e, vocab);
-  if (!r.ok) return { ok: false, slug: e.slug, errors: r.errors, refused: r.errors.join('; ') };
-  // Phase 1: a full rebuild is cheap; single-entry upsert arrives with the vector arms.
-  await buildIndex({ entriesDir, indexPath, vocab, models, p });
-  return { ok: true, slug: e.slug, errors: [] };
+  const batch = await saveEntries({ dirs: [dir], vocab, indexPath, entriesDir, models, p });
+  return batch.results[0];
+}
+
+export async function saveEntries({ dirs, vocab, indexPath, entriesDir, models, p }) {
+  const seen = new Set();
+  const results = dirs.map((dir) => {
+    const requested = path.basename(dir);
+    if (seen.has(requested)) {
+      return { ok: false, slug: requested, errors: ['duplicate slug in batch'], refused: 'duplicate slug in batch' };
+    }
+    seen.add(requested);
+    try {
+      const e = parseEntry(dir);
+      const r = validateEntry(e, vocab);
+      if (!r.ok) return { ok: false, slug: e.slug, errors: r.errors, refused: r.errors.join('; ') };
+      return { ok: true, slug: e.slug, errors: [] };
+    } catch (err) {
+      return { ok: false, slug: requested, errors: [err.message], refused: err.message };
+    }
+  });
+
+  const saved = results.filter((r) => r.ok).length;
+  // A batch rebuilds once after every draft has been validated. Rebuilding after each
+  // slug makes a 2,000-entry approval quadratic even though the final index is identical.
+  if (saved) await buildIndex({ entriesDir, indexPath, vocab, models, p });
+  return { results, saved, refused: results.length - saved };
 }

package/src/ingest/upload.mjs

@@ -0,0 +1,110 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+
+export const MEDIA_EXTENSIONS = new Set(['.webp', '.gif', '.mp4', '.mov', '.webm', '.mkv']);
+export const DEFAULT_UPLOAD_MAX_BYTES = 512 * 1024 * 1024;
+
+export class UploadError extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+}
+
+function oneLine(value, name) {
+  if (value == null || value === '') return undefined;
+  if (typeof value !== 'string' || /[\r\n]/.test(value)) throw new UploadError(400, `${name} must be one line`);
+  return value;
+}
+
+export function uploadMetadata(headers) {
+  const kind = oneLine(headers['x-library-source'], 'x-library-source');
+  const license = oneLine(headers['x-library-license'], 'x-library-license');
+  const title = oneLine(headers['x-library-title'], 'x-library-title');
+  const url = oneLine(headers['x-library-url'], 'x-library-url');
+
+  if ((kind && !license) || (!kind && license)) {
+    throw new UploadError(400, 'x-library-source and x-library-license must be provided together');
+  }
+  if (kind && !['own', 'open', 'paid', 'public-site'].includes(kind)) {
+    throw new UploadError(400, 'x-library-source must be own, open, paid, or public-site');
+  }
+  if (url) {
+    try {
+      const parsed = new URL(url);
+      if (!['http:', 'https:'].includes(parsed.protocol)) throw new Error();
+    } catch {
+      throw new UploadError(400, 'x-library-url must be a full HTTP(S) URL');
+    }
+  }
+  return kind ? { kind, license, ...(title ? { title } : {}), ...(url ? { url } : {}) } : null;
+}
+
+export function uploadFilename(raw) {
+  let filename;
+  try { filename = decodeURIComponent(raw); } catch { throw new UploadError(400, 'invalid encoded filename'); }
+  if (!filename || filename !== path.basename(filename) || filename === '.' || filename === '..' || /[\0\r\n]/.test(filename)) {
+    throw new UploadError(400, 'filename must be one file name without a path');
+  }
+  if (!MEDIA_EXTENSIONS.has(path.extname(filename).toLowerCase())) {
+    throw new UploadError(415, `unsupported media extension; use ${[...MEDIA_EXTENSIONS].join(', ')}`);
+  }
+  return filename;
+}
+
+export async function receiveInboxUpload({ req, dataDir, rawFilename, maxBytes = DEFAULT_UPLOAD_MAX_BYTES }) {
+  const filename = uploadFilename(rawFilename);
+  const metadata = uploadMetadata(req.headers);
+  const declared = Number(req.headers['content-length']);
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new UploadError(413, `upload exceeds ${maxBytes} byte limit`);
+  }
+
+  const inbox = path.join(dataDir, 'inbox');
+  const destination = path.join(inbox, filename);
+  const sidecar = `${destination}.json`;
+  fs.mkdirSync(inbox, { recursive: true });
+  if (fs.existsSync(destination) || fs.existsSync(sidecar)) {
+    throw new UploadError(409, `${filename} already exists in inbox`);
+  }
+
+  const temporary = path.join(inbox, `.${filename}.${randomUUID()}.upload`);
+  const handle = await fs.promises.open(temporary, 'wx');
+  const digest = createHash('sha256');
+  let bytes = 0;
+  try {
+    for await (const chunk of req) {
+      bytes += chunk.length;
+      if (bytes > maxBytes) throw new UploadError(413, `upload exceeds ${maxBytes} byte limit`);
+      digest.update(chunk);
+      await handle.write(chunk);
+    }
+    if (bytes === 0) throw new UploadError(400, 'upload body is empty');
+    await handle.sync();
+    await handle.close();
+
+    // link() publishes atomically and refuses a concurrent upload with the same name.
+    try {
+      await fs.promises.link(temporary, destination);
+    } catch (err) {
+      if (err.code === 'EEXIST') throw new UploadError(409, `${filename} already exists in inbox`);
+      throw err;
+    }
+    if (metadata) {
+      try {
+        await fs.promises.writeFile(sidecar, `${JSON.stringify(metadata)}\n`, { flag: 'wx' });
+      } catch (err) {
+        await fs.promises.unlink(destination).catch(() => {});
+        if (err.code === 'EEXIST') throw new UploadError(409, `${filename}.json already exists in inbox`);
+        throw err;
+      }
+    }
+    await fs.promises.unlink(temporary);
+    return { ok: true, file: filename, bytes, sha256: digest.digest('hex'), sidecar: Boolean(metadata) };
+  } catch (err) {
+    await handle.close().catch(() => {});
+    await fs.promises.unlink(temporary).catch(() => {});
+    throw err;
+  }
+}

package/src/mcp/http.mjs

@@ -7,6 +7,7 @@ import { paths } from '../paths.mjs';
 import { openIndex } from '../index/query.mjs';
 import { getEmbedder } from '../index/embed.mjs';
 import { serveFile } from '../ui/serve.mjs';
+import { receiveInboxUpload, UploadError, DEFAULT_UPLOAD_MAX_BYTES } from '../ingest/upload.mjs';
 
 function authorized(header, token) {
   const want = Buffer.from(`Bearer ${token}`), got = Buffer.from(header ?? '');
@@ -41,6 +42,26 @@ async function handle(req, res, p, token, embedder) {
     res.writeHead(200, { 'content-type': 'application/json' });
     return res.end(JSON.stringify({ ok: true, entries, arms, artifacts, version: p.version }));
   }
+  if (url.pathname.startsWith('/inbox/')) {
+    if (!authorized(req.headers.authorization, token)) { res.writeHead(401); return res.end('unauthorized'); }
+    if (req.method !== 'PUT') { res.writeHead(405, { allow: 'PUT' }); return res.end('method not allowed'); }
+    const configured = Number(process.env.LIBRARY_UPLOAD_MAX_BYTES);
+    const maxBytes = Number.isSafeInteger(configured) && configured > 0 ? configured : DEFAULT_UPLOAD_MAX_BYTES;
+    try {
+      const result = await receiveInboxUpload({
+        req,
+        dataDir: p.data,
+        rawFilename: url.pathname.slice('/inbox/'.length),
+        maxBytes,
+      });
+      res.writeHead(201, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify(result));
+    } catch (err) {
+      if (!(err instanceof UploadError)) throw err;
+      res.writeHead(err.status, { 'content-type': 'application/json' });
+      return res.end(JSON.stringify({ ok: false, refused: err.message }));
+    }
+  }
   if (url.pathname === '/mcp') {
     if (!authorized(req.headers.authorization, token)) { res.writeHead(401); return res.end('unauthorized'); }
     // ponytail: SDK 1.30's stateless transport (sessionIdGenerator: undefined)

package/src/mcp/prompts.mjs

@@ -23,24 +23,31 @@ session did not make.
 
 ## Order of operations
 
-1. **Arguments.** \`path\` must exist; pass it as an absolute path. Animated webp and gif
-   always work; video (mp4/mov/webm/mkv) needs ffmpeg on the server's PATH. If \`add\`
-   returns \`refused\` starting with \`ffmpeg\`, relay the message and stop. \`source\` is
+1. **Arguments.** \`input\` may be a live HTTP(S) page or an animated webp/gif/video
+   (mp4/mov/webm/mkv). A local file uses an absolute path. Video needs ffmpeg on the
+   server's PATH. If \`add\` returns \`refused\` starting with \`ffmpeg\`, relay the
+   message and stop. \`source\` is
    one of ${list(v.source)}. Derive \`slug\` from the file name when absent (lowercase,
    dashes, no extension) and confirm it with the user; derive \`title\` from the slug and
    confirm. \`url\` must be a full URL with scheme. \`license\` defaults by kind: own →
    "own work"; open → ask for the licence name; paid and public-site → "description
    only, no redistribution of the source".
-2. **Ingest.** Call the \`add\` tool with those values. If it returns \`refused\` because
+2. **Stage when hosted.** A hosted server cannot read a path on the caller's machine.
+   Upload it first with \`LIBRARY_TOKEN\` configured locally: \`library upload
+   <absolute-path> --server <server-origin> --source <kind> --license "<licence>"
+   [--url <source-url>] [--title <title>]\`. Use returned \`file\` name as the \`add\`
+   input; hosted MCP resolves a bare name inside its inbox. Never print or pass the token as an argument.
+   Live page URLs need no upload.
+3. **Ingest.** Call the \`add\` tool with those values. If it returns \`refused\` because
    the slug exists, ask before calling again with \`force: true\`; a forced re-add resets
    the draft. Over a hosted (HTTP) server \`add\` can only read files already in the server's
    inbox; if the refusal mentions \`inbox\`, say so and stop.
-3. **Read.** Open the returned \`strip\`. Read \`media.duration_ms\` from the draft at
+4. **Read.** Open the returned \`strip\`. Read \`media.duration_ms\` from the draft at
    \`<dir>/entry.md\`; if it is above 10000, call \`add\` again with \`force: true\` and
    \`frames: 36\` before tagging. The server caps at 36 frames; beyond about 18 seconds a
    section can still be missed, so build a denser sheet yourself from the source file
    before writing the motion note.
-4. **Tag.** Fill every field in the returned \`blanks\` list, per the rubric below. Write
+5. **Tag.** Fill every field in the returned \`blanks\` list, per the rubric below. Write
    the motion note last, after the roster. Two ways, same result: call \`set_fields\` with
    those field names — this needs **no filesystem** and is the only way that works against
    a hosted server — or, in a local checkout, edit \`<dir>/entry.md\` directly.
@@ -48,11 +55,11 @@ session did not make.
    anything, so a refusal never leaves a half-filled draft. It writes judgement fields
    only; provenance is refused. \`get_vocab\` returns the terms if you did not read them
    above.
-5. **Approve.** Show the draft to the user and **show the draft and wait for a yes** before
+6. **Approve.** Show the draft to the user and **show the draft and wait for a yes** before
    anything else. Apply their edits.
-6. **Save.** Call \`save_entry\`. On \`refused\`, show the field names, fix, and call again;
+7. **Save.** Call \`save_entry\`. On \`refused\`, show the field names, fix, and call again;
    **never remove a field to make it pass**.
-7. **Offer the git step.** The library checkout is the directory that contains the
+8. **Offer the git step.** The library checkout is the directory that contains the
    \`bin/library.mjs\` this server runs; if that is not a git checkout (the \`npx\` case), ask
    the user for the path to their clone. If the \`dir\` returned by \`add\` is not inside the
    checkout, first \`cp -r <dir> <checkout>/entries/\`. Then, only with \`git -C <checkout>\`
@@ -102,6 +109,46 @@ and \`public-site\` are inspiration only and \`save_entry\` refuses \`tier: port
 - Never run git in the current project.`;
 }
 
+export function addBatchPrompt(ctx, a) {
+  const v = ctx.vocab.facets;
+  const given = Object.entries(a).filter(([, value]) => value).map(([key, value]) => `- ${key}: ${value}`).join('\n');
+  return `# Add a batch of design references to wp-design-library
+
+Arguments given:
+${given || '- (none)'}
+
+Use the hosted workflow end to end; do not edit the server filesystem.
+
+1. **Stage files.** If recordings are on this machine, run \`library upload\` once per file
+   with \`--server\`, \`--source\`, \`--license\`, and optional \`--url\`/\`--title\`.
+   Authentication comes from \`LIBRARY_TOKEN\`; never print it or put it in an argument.
+   Files already in the server inbox need no upload.
+2. **Draft.** Call \`add_batch\` once, passing the supplied source/licence as defaults for
+   files without sidecars. It resumes interrupted work, skips an existing slug,
+   and reports a refusal per bad file while continuing the rest. Report refusals, then keep
+   processing every drafted slug.
+3. **Inspect.** Call \`get_vocab\` once. For every drafted slug call \`get_draft\`; inspect
+   every returned strip image. Long recordings may need another capture before the motion
+   note can honestly cover every section.
+4. **Tag in chunks.** Build \`set_fields_batch.entries\` records and submit chunks of at
+   most 25 so results remain reviewable. Fill every blank. Roles must come from
+   ${list(v.role)}; feel from ${list(v.feel)}; motion devices from ${list(v.motion)}.
+   Each body has \`## What it does\`, \`## Section roster\`, and \`## Why it works\`.
+   Motion notes begin with the sampled-frame limitation and describe sections in order.
+   A refused item does not undo the others; fix it and resubmit only that slug.
+5. **Review.** Show a compact table containing slug, roles, feel, palette, motion devices,
+   and any refusal. Wait for the user's approval of the batch and apply requested changes.
+6. **Save once.** Call \`save_batch\` with all approved slugs. It validates each entry,
+   isolates failures, and rebuilds the index once. Fix and resubmit refused slugs without
+   repeating successful ones.
+7. **Ship.** Run \`library check --remote\`. For a hosted volume, use
+   \`library export --saved-only\` to bring entries into a checkout, then create one content
+   branch and PR for the batch.
+
+Never infer a visual field without inspecting its strip, never write provenance through
+\`set_fields_batch\`, and never drop a field merely to pass validation.`;
+}
+
 // brief-from-library turns a client brief into a reference set: one `recommend` call,
 // then `get_entry` on what survives, then a `## References` block the session fills in
 // with the slugs it actually used. The per-role `search` fan-out is kept as a fallback
@@ -157,7 +204,8 @@ export function registerPrompts(server, ctx) {
     {
       description: 'Add a design reference to the library: ingest a recording, tag it in this session per the rubric, approve the draft, save it, offer the PR.',
       argsSchema: {
-        path: z.string().describe('absolute path to an animated webp/gif or a video file'),
+        input: z.string().optional().describe('live page URL, inbox filename, or absolute local media path'),
+        path: z.string().optional().describe('legacy alias for an absolute local media path'),
         source: z.string().describe('own | open | paid | public-site'),
         slug: z.string().optional().describe('lowercase, digits and dashes'),
         title: z.string().optional(),
@@ -167,4 +215,17 @@ export function registerPrompts(server, ctx) {
     },
     async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: addEntryPrompt(ctx, a) } }] }),
   );
+
+  server.registerPrompt(
+    'add-batch',
+    {
+      description: 'Ingest, inspect, tag, review, and save every recording in the hosted inbox with batch tools and isolated failures.',
+      argsSchema: {
+        source: z.string().optional().describe('default own | open | paid | public-site when sidecars omit it'),
+        license: z.string().optional().describe('default licence text when sidecars omit it'),
+        server: z.string().optional().describe('hosted library origin used by library upload'),
+      },
+    },
+    async (a) => ({ messages: [{ role: 'user', content: { type: 'text', text: addBatchPrompt(ctx, a) } }] }),
+  );
 }

package/src/mcp/tools.mjs

@@ -43,7 +43,7 @@ function resolveFilters(vocab, filters = {}) {
 // (the operator running the CLI already has that file access), so it stays
 // unrestricted there. Shared by `add` (input) and `similar` (image).
 function confineToInbox(ctx, inputPath) {
-  if (ctx.transport !== 'http') return null;
+  if (ctx.transport !== 'http') return { path: inputPath, refused: null };
   // Realpath the inbox root itself (when it exists) so a symlinked <data>/inbox still
   // confines correctly: inputPath's own realpath resolves through that symlink too, and
   // comparing against the unresolved join would then never match.
@@ -53,9 +53,12 @@ function confineToInbox(ctx, inputPath) {
   // existsSync is false for a dangling symlink too, not just a missing path: refuse
   // both explicitly instead of falling through to path.resolve, which would let a
   // dangling symlink under inbox pass confinement on its unresolved path alone.
-  if (!fs.existsSync(inputPath)) return 'input does not exist';
-  const real = fs.realpathSync(inputPath);
-  return real.startsWith(inbox) ? null : 'over http, the path must be a file under <data>/inbox';
+  const candidate = path.isAbsolute(inputPath) ? inputPath : path.join(inboxRoot, inputPath);
+  if (!fs.existsSync(candidate)) return { path: candidate, refused: 'input does not exist' };
+  const real = fs.realpathSync(candidate);
+  return real.startsWith(inbox)
+    ? { path: real, refused: null }
+    : { path: real, refused: 'over http, the path must be a file under <data>/inbox' };
 }
 
 export function makeTools(ctx) {
@@ -129,6 +132,51 @@ export function makeTools(ctx) {
         return { ...out, body: first.trim(), detail: 'summary' };
       }),
     },
+    {
+      name: 'get_draft',
+      description: 'Return a saved or unsaved draft directly from the corpus volume, including blank judgement fields and every strip as paths, public URLs, and MCP image content. Use after add_batch because drafts are not searchable until saved.',
+      schema: z.object({ slug: z.string().regex(/^[a-z0-9-]+$/) }),
+      handler: async ({ slug }) => {
+        const dir = path.join(ctx.paths.entries, slug);
+        if (!fs.existsSync(path.join(dir, 'entry.md'))) return { refused: `no draft with slug ${slug}` };
+        const entry = parseEntry(dir);
+        const captures = entry.fm?.captured?.captures ?? [];
+        let config = null;
+        try { config = readConfig(); } catch { config = null; }
+        const strips = [];
+        const stripUrls = [];
+        for (const capture of captures) {
+          const artifact = (capture.artifacts ?? []).find((a) => a?.key?.endsWith('/strip.webp'));
+          if (!artifact) { strips.push(null); stripUrls.push(null); continue; }
+          let local = null;
+          try { local = await artifactFile(ctx.paths, artifact); } catch { local = null; }
+          strips.push(local);
+          stripUrls.push(config ? objectUrl(config, artifact.key) : null);
+        }
+        const { REQUIRED_BLANKS } = await import('../entry.mjs');
+        const view = { ...entry.fm, body: entry.body };
+        const valueAt = (dotted) => dotted.split('.').reduce((o, key) => (o == null ? undefined : o[key]), view);
+        const blanks = REQUIRED_BLANKS.filter((field) => {
+          const value = valueAt(field);
+          return value == null || value === '' || (Array.isArray(value) && value.length === 0);
+        });
+        return { ...entry, blanks, strip: strips[0] ?? null, strips, strip_url: stripUrls[0] ?? null, strip_urls: stripUrls };
+      },
+      content: (out) => {
+        if (out.refused) return [];
+        return (out.strips ?? []).flatMap((strip, index) => {
+          if (!strip) return [];
+          try {
+            return [
+              { type: 'text', text: `Capture ${index + 1} strip for ${out.fm.slug}` },
+              { type: 'image', mimeType: 'image/webp', data: fs.readFileSync(strip).toString('base64') },
+            ];
+          } catch {
+            return [{ type: 'text', text: `Capture ${index + 1} strip for ${out.fm.slug} became unavailable` }];
+          }
+        });
+      },
+    },
     {
       name: 'get_motion',
       description: 'Inspect one motion clip at original playback speed. Returns video URL when published, provenance, observed motion notes, and timestamped frames as native images by default. Use clip to select from available clips; timestamps are relative to the clip. A video URL alone does not provide video understanding.',
@@ -165,8 +213,9 @@ export function makeTools(ctx) {
       handler: withDb(async (db, a) => {
         if (!!a.slug === !!a.image) return { refused: 'similar needs exactly one of slug or image' };
         if (a.image) {
-          const refusal = confineToInbox(ctx, a.image);
-          if (refusal) return { refused: refusal };
+          const confined = confineToInbox(ctx, a.image);
+          if (confined.refused) return { refused: confined.refused };
+          a = { ...a, image: confined.path };
         }
         return similar(db, { ...a, embedder: ctx.embedder, embedderReason: ctx.embedderReason });
       }),
@@ -241,8 +290,9 @@ export function makeTools(ctx) {
           const refusal = await refuseUnsafeUrl(a.input, { transport: ctx.transport });
           if (refusal) return { refused: refusal };
         } else {
-          const refusal = confineToInbox(ctx, a.input);
-          if (refusal) return { refused: refusal };
+          const confined = confineToInbox(ctx, a.input);
+          if (confined.refused) return { refused: confined.refused };
+          a = { ...a, input: confined.path };
         }
         return (await import('../cli/add.mjs')).addEntry(a);
       },
@@ -282,6 +332,24 @@ export function makeTools(ctx) {
         return saveEntry({ dir: path.join(ctx.paths.entries, slug), vocab: ctx.vocab, indexPath: ctx.paths.index, entriesDir: ctx.paths.entries, models: ctx.paths.models, p: ctx.paths });
       },
     },
+    {
+      name: 'save_batch',
+      description: 'Validate and save many reviewed drafts, isolating invalid entries and rebuilding the index once for every valid slug. Returns one result per slug plus saved/refused counts.',
+      schema: z.object({
+        slugs: z.array(z.string().regex(/^[a-z0-9-]+$/)).min(1).max(2000),
+      }),
+      handler: async ({ slugs }) => {
+        const { saveEntries } = await import('../ingest/save.mjs');
+        return saveEntries({
+          dirs: slugs.map((slug) => path.join(ctx.paths.entries, slug)),
+          vocab: ctx.vocab,
+          indexPath: ctx.paths.index,
+          entriesDir: ctx.paths.entries,
+          models: ctx.paths.models,
+          p: ctx.paths,
+        });
+      },
+    },
     {
       name: 'set_fields',
       description: "Fill a draft's judgement fields: roles, feel, motion.devices, motion.notes, palette, type, body, tier, ported_from — never provenance. Vocabulary terms are resolved through aliases and an unknown one is refused by name with nothing written, so a refusal never leaves a half-filled draft. Returns the fields still blank. This is the step between add and save_entry, and it is the only one that does not need a filesystem.",
@@ -294,6 +362,34 @@ export function makeTools(ctx) {
         return setFields({ dir: path.join(ctx.paths.entries, slug), fields, vocab: ctx.vocab });
       },
     },
+    {
+      name: 'set_fields_batch',
+      description: 'Fill judgement fields for many drafts in one call. Each entry is isolated: an unknown term, provenance field, or missing slug refuses only that item and never partially writes it. Use chunks small enough to inspect, then save_batch after review.',
+      schema: z.object({
+        entries: z.array(z.object({
+          slug: z.string().regex(/^[a-z0-9-]+$/),
+          fields: z.record(z.any()),
+        })).min(1).max(200),
+      }),
+      handler: async ({ entries }) => {
+        const { setFields } = await import('../ingest/fields.mjs');
+        const seen = new Set();
+        const results = entries.map(({ slug, fields }) => {
+          if (seen.has(slug)) return { ok: false, slug, written: [], refused: ['duplicate slug in batch'] };
+          seen.add(slug);
+          try {
+            return setFields({ dir: path.join(ctx.paths.entries, slug), fields, vocab: ctx.vocab });
+          } catch (err) {
+            return { ok: false, slug, written: [], refused: [err.message] };
+          }
+        });
+        return {
+          results,
+          updated: results.filter((r) => r.ok).length,
+          refused: results.filter((r) => !r.ok).length,
+        };
+      },
+    },
   ];
 }