@yojahny/wp-design-library 1.1.1 → 1.3.0

package/entries/vana/entry.md

@@ -0,0 +1,100 @@
+---
+slug: vana
+title: 'Vana: personal data infrastructure'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://www.vana.com/
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: both
+  at: '2026-09-24'
+  tool: wp-design-library@1.2.0
+  captures:
+    - method: frames
+      input: https://images.refero.design/styles/refero.design/video/a3563017-dcef-4a36-bd07-9f638e3e4fdf.mp4
+      artifacts:
+        - key: entries/vana/1/strip.webp
+          bytes: 129848
+          sha256: 3ed79e491c42f46490b0aee20cec99e99b83319c848a2c307b794610e755d7f2
+          uploaded: true
+      frames: 18
+      duration_ms: 8783
+    - method: both
+      input: https://www.vana.com/
+      artifacts:
+        - key: entries/vana/2/strip.webp
+          bytes: 261970
+          sha256: 0a1eb61643cfe6475cb92a903344deb022bb44e30d53b408946a1d14969097d3
+          uploaded: true
+        - key: entries/vana/2/measure.json
+          bytes: 1554
+          sha256: ad5962af583cfc2489fee5073cd43acb5a3e6fc3712857381715b0367bc75af2
+          uploaded: true
+        - key: entries/vana/2/screen-1440.png
+          bytes: 509200
+          sha256: 35e85bd7c81da6402dc39c9f07100b9174c50ea1c54c38c2b8acbd5f3cf19b12
+          uploaded: true
+        - key: entries/vana/2/screen-390.png
+          bytes: 353891
+          sha256: cfda7194da8a0482b9e58a3d40dc06edf62fbe2ed37f9c5bea362c3a8cb004e2
+          uploaded: true
+media:
+  frames: 18
+  duration_ms: 8783
+roles:
+  - hero
+  - explainer
+  - capability
+  - feature
+  - proof
+  - closing
+  - footer
+feel:
+  - dark
+  - cold
+  - saas
+  - depth
+  - premium
+palette:
+  canvas: '#090a13'
+  ink: '#f1f1fc'
+  accent: '#6959ff'
+type:
+  display: large neutral sans, tight leading
+  body: compact neutral sans, technical data measure
+motion:
+  devices:
+    - reveal
+    - pan
+    - stagger
+    - spotlight
+  notes: >-
+    Eyeballed from 18 sampled frames, not measured. The Refero recording opens on a dark globe and purple data points,
+    then pans through ownership cards, a developer stack diagram, and a bright protocol chapter. The current site at
+    vana.org has a lavender hero and redesigned content grid. Exact map dynamics, card interactions, pointer response,
+    and reduced-motion behavior are not measurable from sampled frames.
+ported_from: null
+---
+
+## What it does
+
+An archived data-ownership infrastructure story that argues people should control and reuse the information they create. Dark global imagery and modular cards visualize an otherwise invisible data layer.
+
+## Section roster
+
+1. Dark globe and AI ownership claim.
+2. Personal data use cases.
+3. Developer and participation paths.
+4. Protocol stack diagram.
+5. Open-data chapter and closing.
+
+## Why it works
+
+The globe and layered cards turn a policy-like subject into a spatial system, while a bright final chapter gives the technical story a clear turn. The cost is that abstract imagery and small labels need plain-language support and strong contrast.
+
+## Sources
+
+- [Refero style page](https://styles.refero.design/style/2a3cdb2e-effe-406b-932e-37e4dc88ab1d) and its [recorded MP4](https://images.refero.design/styles/refero.design/video/a3563017-dcef-4a36-bd07-9f638e3e4fdf.mp4) supply the sampled motion and section sequence.
+- The live capture at https://vana.org/ supplies current copy, responsive screenshots, and measured layout.
+- The submitted vana.com redirects to vana.org. The live site is a substantial lavender redesign, so trust the recording for this archived dark visual system and vana.org for current positioning.

package/entries/veed/entry.md

@@ -0,0 +1,98 @@
+---
+slug: veed
+title: 'VEED: AI video creation platform'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://www.veed.io/
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: both
+  at: '2026-09-24'
+  tool: wp-design-library@1.2.0
+  captures:
+    - method: frames
+      input: https://images.refero.design/styles/refero.design/video/78c29fbf-be4e-4fc4-ad25-b377b1c6c751.mp4
+      artifacts:
+        - key: entries/veed/1/strip.webp
+          bytes: 239780
+          sha256: d18b9392525a700aadb1a55172390c8cfd55706e7035a1a093915653f097cede
+          uploaded: true
+      frames: 23
+      duration_ms: 11267
+    - method: both
+      input: https://www.veed.io/
+      artifacts:
+        - key: entries/veed/2/strip.webp
+          bytes: 389818
+          sha256: a203e2016d1ed93a2ca3f51297f0f2151d8f4fb18b6724269c5fbeb4001ed120
+          uploaded: true
+        - key: entries/veed/2/measure.json
+          bytes: 5957
+          sha256: 68777c4b3c38d474c2a5cebccabff6b0c76ab507ff3d446a1af02d781c4a2ded
+          uploaded: true
+        - key: entries/veed/2/screen-1440.png
+          bytes: 372084
+          sha256: d3d62a04e1adb830c125804e298e3df6ffc0f0ae56bfe6afe7e1c3ee1cb6514e
+          uploaded: true
+        - key: entries/veed/2/screen-390.png
+          bytes: 90686
+          sha256: 166d40b1f9597e84a82d89cc1994e168052df2eda906a570c3aafca1fd7ec255
+          uploaded: true
+media:
+  frames: 23
+  duration_ms: 11267
+roles:
+  - hero
+  - proof
+  - feature
+  - capability
+  - closing
+  - footer
+feel:
+  - light
+  - dark
+  - saas
+  - playful
+  - depth
+palette:
+  canvas: '#ffffff'
+  ink: '#111111'
+  accent: '#9cff39'
+type:
+  display: bold neutral sans, compact leading
+  body: neutral sans, concise product measure
+motion:
+  devices:
+    - reveal
+    - pan
+    - stack
+    - stagger
+  notes: >-
+    Eyeballed from 23 sampled frames, not measured. A sparse AI-video hero gives way to a moving row of creator
+    portraits and generated-video previews. Dark product panels stack examples, then editor controls and use-case cards
+    reveal in sequence before testimonial and footer content.
+ported_from: null
+---
+
+## What it does
+
+A video creation platform landing page that demonstrates social-ready output before explaining the AI generation and editing workflow. Creator faces and sample videos make the abstract promise tangible.
+
+## Section roster
+
+1. AI-video hero and creation action.
+2. Creator portraits and team proof.
+3. Generated video examples.
+4. Editing and brand controls.
+5. Use-case cards and closing action.
+
+## Why it works
+
+Showing sample output early makes the offer credible, while the restrained white canvas and green accent keep product UI easy to read. The cost is that video previews and dense editing controls need efficient loading and accessible alternatives.
+
+## Sources
+
+- [Refero style page](https://styles.refero.design/style/fff821ec-a3bf-41a5-aea2-626185bcd227) and its [recorded MP4](https://images.refero.design/styles/refero.design/video/78c29fbf-be4e-4fc4-ad25-b377b1c6c751.mp4) supply the sampled motion and section sequence.
+- The live capture at https://www.veed.io/ supplies current copy, responsive screenshots, and measured layout.
+- The sources share the same AI-video direction. Trust the recording for example-card movement and the live site for current tools and pricing.

package/entries/webflow/entry.md

@@ -0,0 +1,108 @@
+---
+slug: webflow
+title: 'Webflow: layered website-experience platform'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://webflow.com/
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: both
+  at: '2026-09-22'
+  tool: wp-design-library@1.2.0
+  captures:
+    - method: frames
+      input: 'https://images.refero.design/styles/refero.design/video/4271252f-7d14-4594-8489-b8c23a843bd9.mp4'
+      artifacts:
+        - key: entries/webflow/1/strip.webp
+          bytes: 367942
+          sha256: c2c5e860ff83f814d4db8c7a9e83a9a6c0a2b2aca69171dd984cea4540846a97
+          uploaded: true
+      frames: 36
+      duration_ms: 29320
+    - method: both
+      input: https://webflow.com/
+      artifacts:
+        - key: entries/webflow/2/strip.webp
+          bytes: 316688
+          sha256: 4ae2299a39d0f8f06ce898d9dafc7ef75bcf172eeba99d582f4018ed9037902b
+          uploaded: true
+        - key: entries/webflow/2/measure.json
+          bytes: 5564
+          sha256: 01dde97a6e81d37aed1aa3684707be2b6cc0b0cea3193243e0d194a94dbe4077
+          uploaded: true
+        - key: entries/webflow/2/screen-1440.png
+          bytes: 284671
+          sha256: 326c76e7779a2ce13eb2687ad017d7709cc3f34e21b79108dd075c26cc275404
+          uploaded: true
+        - key: entries/webflow/2/screen-390.png
+          bytes: 54072
+          sha256: 03b140fef199644dafdd8aa1576769a5fcce2c9c57bf2761a7919c821897f16f
+          uploaded: true
+media:
+  frames: 36
+  duration_ms: 29320
+roles:
+  - hero
+  - feature
+  - proof
+  - capability
+  - testimonial
+  - explainer
+  - closing
+  - footer
+feel:
+  - light
+  - saas
+  - premium
+  - minimal
+  - depth
+palette:
+  canvas: '#ffffff'
+  ink: '#080808'
+  accent: '#146ef5'
+type:
+  display: bold modern sans, heavy weight, tight tracking
+  body: neutral sans, regular weight, open product-marketing measure
+motion:
+  devices:
+    - reveal
+    - pin
+    - pan
+    - parallax
+    - stagger
+    - stack
+    - tabs
+  notes: >-
+    Eyeballed from 36 sampled frames, not measured. The recorded hero layers a blue gradient bed behind product-choice
+    cards, then pins a browser canvas while Webflow UI panels pan and stack around a live site preview. Capability
+    sections reveal as staggered image-and-metric columns, customer proof advances through portrait cards, and later AI
+    and collaboration canvases slide into place before updates, community work, and the footer. The current live page
+    has changed its hero and carries a persistent cookie panel; exact tab, carousel, and pointer behavior cannot be
+    established from sampled frames.
+ported_from: null
+---
+
+## What it does
+
+Webflow presents its website-experience platform through a choice-led hero, visual building canvas, publishing and optimization capabilities, customer outcomes, AI-assisted workflows, recent updates, and community-made work.
+
+## Section roster
+
+1. Product-choice hero and primary conversion actions.
+2. Layered builder canvas showing design and code workflows.
+3. Build, publish, and optimize feature columns.
+4. Brand-scale proof and customer outcome cards.
+5. Agentic web-marketing and collaboration explanation.
+6. AI knowledge and business workflow canvas.
+7. Updates, conference material, Made in Webflow gallery, and footer.
+
+## Why it works
+
+Large direct typography and real product canvases explain a technically broad platform without hiding the interface, while blue accents keep conversion and navigation obvious across a long page. The cost to weigh is that stacked UI screenshots, customer cards, and changing campaign content create a heavy page that can age quickly and compete for attention.
+
+## Sources
+
+- The [Refero style page](https://styles.refero.design/style/31471407-598a-45fd-a505-d921980d8855) and its MP4 supply the earlier growth-engine hero, builder-canvas choreography, feature stacking, customer-card sequence, and complete scroll narrative.
+- The live capture at https://webflow.com/ supplies the current Build for what’s next hero, present campaign content, navigation, responsive screenshots, and measured layout.
+- The hero and some downstream campaign sections differ materially; the live page is trusted for current structure and copy, while the recording is retained as the motion reference for the captured design version.

package/entries/zkpass/entry.md

@@ -0,0 +1,103 @@
+---
+slug: zkpass
+title: 'zkPass: cryptographic trust-network landing'
+tier: inspiration
+source:
+  kind: public-site
+  url: https://zkpass.org/
+  license: Captured from a Refero-hosted recording and the live site; description only, no redistribution of the source.
+captured:
+  method: both
+  at: '2026-09-24'
+  tool: wp-design-library@1.2.0
+  captures:
+    - method: frames
+      input: https://images.refero.design/styles/refero.design/video/225d4ed7-26d4-4495-b8d3-c6b32d9af232.mp4
+      artifacts:
+        - key: entries/zkpass/1/strip.webp
+          bytes: 246594
+          sha256: 35b485103534d1ac10bc1116b644e19eb41cdbb066d381f366de71b9295b3d63
+          uploaded: true
+      frames: 36
+      duration_ms: 20717
+    - method: both
+      input: https://zkpass.org/
+      artifacts:
+        - key: entries/zkpass/2/strip.webp
+          bytes: 264812
+          sha256: 473a2275e5161b08fca4d61ac72d3f2507589197e9e32a09e66a1ea48619e296
+          uploaded: true
+        - key: entries/zkpass/2/measure.json
+          bytes: 4020
+          sha256: 2bbe4c4567883a5b1e1d3ef48dc51cf2a981837fb654dd5c87ea2adbfe61cc43
+          uploaded: true
+        - key: entries/zkpass/2/screen-1440.png
+          bytes: 450714
+          sha256: c5d496cde94be116f563652bb4fb9c6ada3506383d6102f0fd758191fdfd246b
+          uploaded: true
+        - key: entries/zkpass/2/screen-390.png
+          bytes: 68539
+          sha256: 6adc33d258808e9085e2db57ac09f88eb774287440db9048ea8226b987be6a1a
+          uploaded: true
+media:
+  frames: 36
+  duration_ms: 20717
+roles:
+  - hero
+  - explainer
+  - capability
+  - proof
+  - feature
+  - closing
+  - footer
+feel:
+  - dark
+  - brutalist
+  - cold
+  - premium
+  - depth
+palette:
+  canvas: '#050605'
+  ink: '#eeeee8'
+  accent: '#c4ff35'
+type:
+  display: high-contrast editorial serif and technical sans
+  body: compact technical sans, dense protocol measure
+motion:
+  devices:
+    - reveal
+    - wipe
+    - pan
+    - stagger
+    - spotlight
+  notes: >-
+    Eyeballed from 36 sampled frames, not measured. A black particle field and neon green symbol open the page.
+    Oversized Proof and Credit statements wipe between dark product panels; verification flows, code-like diagrams, and
+    principle rows reveal in sequence before the green closing mark. Exact particle simulation, verification demo
+    behavior, pointer response, and reduced-motion behavior are not measurable from sampled frames.
+ported_from: null
+---
+
+## What it does
+
+A privacy and verification protocol landing page that organizes a technical product around proof, credit, and reusable trust. Near-black surfaces and acid-green signals make the system feel cryptographic while large headings give dense material a readable hierarchy.
+
+## Section roster
+
+1. Particle-field hero and privacy claim.
+2. Proof and credit product framing.
+3. Three verification methods.
+4. Human and agent audience paths.
+5. Technical primitives and protocol principles.
+6. Product diagrams and dispatches.
+7. Closing proof statement and footer.
+
+## Why it works
+
+The green signal color guides attention through otherwise dense technical panels, while oversized serif assertions make each concept memorable. The cost is that small diagram labels and low-light UI require strong contrast and responsive simplification.
+
+## Sources
+
+- [Refero style page](https://styles.refero.design/style/3a398f82-579e-4ec4-a442-9962bf007edf) and its [recorded MP4](https://images.refero.design/styles/refero.design/video/225d4ed7-26d4-4495-b8d3-c6b32d9af232.mp4) supply the opening particle field, product transitions, verification panels, protocol chapters, and closing.
+- The live capture at https://zkpass.org/ supplies current terminology, responsive screenshots, and measured layout.
+- The sources agree closely. Trust the recording for transition continuity and the live page for current protocol claims.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yojahny/wp-design-library",
-  "version": "1.1.1",
+  "version": "1.3.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)