makaron-persona-look-cli 0.4.1

package/LICENSE

@@ -0,0 +1 @@
+All rights reserved.

package/README.md

@@ -0,0 +1,84 @@
+# Makaron Persona + Look CLI
+
+`makaron-persona-look-cli` keeps stable character identity (`Persona`) separate from styling (`Look`). It provides owner-local administration plus a Worker-backed library that an Agent can search and download as a selected image reference pack. It never generates an image or submits a paid render.
+
+## What an Agent gets
+
+`preview` downloads the selected Persona source/approved auxiliary views and the Look source, plus a safe `selection.json` render brief. It is intentionally a **source-reference pack**, not a synthesized image: the Persona is the only identity reference and the Look image's face must be excluded from any later render.
+
+The raw `private-library/` is ignored by Git and is never included in the npm package. D1 holds catalog metadata, private R2 holds approved source bytes, and a Worker issues an individual credential to each enrolling Agent. The individual credential is stored only in the Agent's local mode-600 config file and is never printed by the CLI.
+
+## One-command Agent setup
+
+After the Worker has been deployed, the reviewed library has been synced, and the released package contains that HTTPS Worker URL in `personlib.default_api_url`, any Agent can run:
+
+```bash
+npx -y makaron-persona-look-cli setup
+```
+
+That command installs the CLI and the `makaron-persona-look` Skill globally, creates a per-Agent Worker credential through open self-registration, and saves it locally. No registration token needs to be handed to the Agent.
+
+For a pre-release or a Worker URL that is not yet embedded in the package, use the same command with an explicit endpoint:
+
+```bash
+npx -y makaron-persona-look-cli setup --api-url https://your-worker.example
+personlib remote doctor --json
+personlib remote preview --brief '为一个20秒 K-pop 女团舞台视频找冷感、银黑未来街头造型人物参考图' --output-dir ./personlib-selection --json
+```
+
+The Worker is deployed at `https://personlib-agent.bzz0309.workers.dev` and its HTTPS URL is embedded in this release's `package.json`. `prepublishOnly` blocks an accidental npm release if that endpoint is removed. npm publication is a separate final step.
+
+## Owner deployment
+
+See [the Worker deployment guide](cloudflare-worker/README.md). The owner must first create the private R2 bucket and D1 database, deploy the Worker with `OPEN_ENROLLMENT="true"`, supply a private `OWNER_SYNC_TOKEN`, and synchronize the reviewed library:
+
+```bash
+personlib remote sync --library ./private-library --dry-run --json
+personlib remote sync --library ./private-library --json
+```
+
+`remote sync` remains owner-only. Open enrollment authorizes Agents to receive their own credentials, but does not expose an anonymous catalog or direct R2 object URLs.
+
+## Agent natural-language route
+
+Once setup and `remote doctor` succeed, an Agent can fulfill a request such as “按这段文案获取对应图” with:
+
+```bash
+personlib remote preview --brief '20 秒嘻哈说唱女 rapper 舞台视频，红黑街头风、宽松工装、强节奏' --output-dir ./personlib-selection --json
+```
+
+The result contains the selected original reference images. If the intended result is a brand-new generated image, connect a separate Makaron rendering adapter after an explicit credit/submit authorization; this CLI deliberately stops before that paid/external action.
+
+## Local owner-admin commands
+
+```bash
+node bin/personlib.mjs list --library ./private-library --json
+node bin/personlib.mjs show --persona P-001 --library ./private-library --json
+node bin/personlib.mjs show --look L-001 --library ./private-library --json
+node bin/personlib.mjs recommend --brief '请使用人物资产库，为一个 15 秒高端美妆广告找一位 25 岁左右、东亚、干净冷感的女性人物。' --library ./private-library --json
+node bin/personlib.mjs fetch --brief '请为一个 15 秒成年女性地铁皮夹克通勤广告找一套都市造型。' --output-dir ./selection --library ./private-library --json
+node bin/personlib.mjs compose --persona P-003 --look L-011 --library ./private-library --json
+node bin/personlib.mjs validate --library ./private-library --json
+```
+
+To intake a new owner-authorized reference:
+
+```bash
+node bin/personlib.mjs intake \
+  --image /absolute/path/to/reference.png \
+  --reference /absolute/path/to/second-face-view.png \
+  --reference /absolute/path/to/third-face-view.png \
+  --into persona \
+  --rights authorized \
+  --library ./private-library --json
+```
+
+`intake` records neither facial nor styling assertions automatically. A human/vision-review step adds Persona or Look fields. A Look always carries a source-face exclusion and brand-sanitization rule.
+
+## Test
+
+```bash
+npm test
+npm run test:remote
+npm pack --dry-run --json
+```

package/bin/personlib.mjs

@@ -0,0 +1,495 @@
+#!/usr/bin/env node
+
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, extname, join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { runBootstrapSetup, runRemote } from "../lib/remote-client.mjs";
+
+const argv = process.argv.slice(2);
+const command = argv[0];
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const bundledLibraryRoot = join(packageRoot, "private-library");
+
+function fail(message) {
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+}
+
+function option(name) {
+  const index = argv.indexOf(name);
+  return index === -1 ? undefined : argv[index + 1];
+}
+
+function options(name) {
+  const values = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    if (argv[index] === name && argv[index + 1]) values.push(argv[index + 1]);
+  }
+  return values;
+}
+
+function has(name) {
+  return argv.includes(name);
+}
+
+function rootPath() {
+  return resolve(option("--library") || process.env.PERSONLIB_LIBRARY || (existsSync(bundledLibraryRoot) ? bundledLibraryRoot : ".personlib"));
+}
+
+function manifestPath(root) {
+  return join(root, "manifest.json");
+}
+
+function readManifest(root) {
+  const path = manifestPath(root);
+  if (!existsSync(path)) throw new Error(`library manifest not found: ${path}`);
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function saveManifest(root, manifest) {
+  mkdirSync(root, { recursive: true });
+  writeFileSync(manifestPath(root), `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+function sha256(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function output(payload, forceJson = has("--json")) {
+  if (forceJson) console.log(JSON.stringify(payload, null, 2));
+  else console.log(typeof payload === "string" ? payload : JSON.stringify(payload, null, 2));
+}
+
+function nextId(manifest, collection) {
+  const prefix = collection === "looks" ? "L-" : "P-";
+  const largest = (manifest[collection] || []).reduce((max, record) => {
+    const number = Number.parseInt(record.id.replace(new RegExp(`^${prefix}`), ""), 10);
+    return Number.isFinite(number) ? Math.max(max, number) : max;
+  }, 0);
+  return `${prefix}${String(largest + 1).padStart(3, "0")}`;
+}
+
+function validate(manifest, root) {
+  const errors = [];
+  if (manifest.schema_version !== "0.1") errors.push("unsupported schema_version");
+  const personaIds = new Set();
+  for (const persona of manifest.personas || []) {
+    if (!/^P-\d{3,}$/.test(persona.id || "")) errors.push(`invalid persona id: ${persona.id}`);
+    if (personaIds.has(persona.id)) errors.push(`duplicate persona id: ${persona.id}`);
+    personaIds.add(persona.id);
+    if (!["private-staged", "intake-review"].includes(persona.status)) errors.push(`${persona.id}: unexpected status`);
+    if (persona.provenance?.rights !== "owner-confirmed") errors.push(`${persona.id}: missing owner-confirmed rights`);
+    const sourcePath = join(root, persona.source?.relative_path || "");
+    if (!existsSync(sourcePath)) errors.push(`${persona.id}: source missing`);
+    else if (sha256(sourcePath) !== persona.source.sha256) errors.push(`${persona.id}: source checksum mismatch`);
+    for (const reference of persona.identity_references || []) {
+      const referencePath = join(root, reference.relative_path || "");
+      if (!reference.relative_path || !reference.sha256) errors.push(`${persona.id}: malformed identity reference`);
+      else if (!existsSync(referencePath)) errors.push(`${persona.id}: identity reference missing`);
+      else if (sha256(referencePath) !== reference.sha256) errors.push(`${persona.id}: identity reference checksum mismatch`);
+    }
+    const identity = persona.identity || {};
+    if (persona.status === "private-staged") {
+      for (const field of ["face_shape", "brows", "eyes", "nose", "mouth", "skin", "stable_marks"]) {
+        if (!identity[field]) errors.push(`${persona.id}: missing identity.${field}`);
+      }
+    } else if (identity.review_state !== "needs-structured-review") {
+      errors.push(`${persona.id}: intake-review records must declare identity.review_state`);
+    }
+    for (const forbidden of ["hair", "makeup", "wardrobe", "accessories"]) {
+      if (Object.hasOwn(identity, forbidden)) errors.push(`${persona.id}: identity may not contain ${forbidden}`);
+    }
+  }
+  const lookIds = new Set();
+  for (const lookRecord of manifest.looks || []) {
+    if (!/^L-\d{3,}$/.test(lookRecord.id || "")) errors.push(`invalid look id: ${lookRecord.id}`);
+    if (lookIds.has(lookRecord.id)) errors.push(`duplicate look id: ${lookRecord.id}`);
+    lookIds.add(lookRecord.id);
+    if (!["private-staged", "intake-review"].includes(lookRecord.status)) errors.push(`${lookRecord.id}: unexpected status`);
+    if (lookRecord.provenance?.rights !== "owner-confirmed") errors.push(`${lookRecord.id}: missing owner-confirmed rights`);
+    const sourcePath = join(root, lookRecord.source?.relative_path || "");
+    if (!existsSync(sourcePath)) errors.push(`${lookRecord.id}: source missing`);
+    else if (sha256(sourcePath) !== lookRecord.source.sha256) errors.push(`${lookRecord.id}: source checksum mismatch`);
+    if (lookRecord.identity_policy !== "do-not-use-source-face") errors.push(`${lookRecord.id}: missing source-face restriction`);
+    if (lookRecord.status === "private-staged") {
+      for (const field of ["family", "silhouette", "garments", "palette", "materials", "accessories", "scene"]) {
+        if (!lookRecord.look?.[field]) errors.push(`${lookRecord.id}: missing look.${field}`);
+      }
+      if (lookRecord.brand_policy !== "replace-source-logos-and-wordmarks") errors.push(`${lookRecord.id}: missing brand-sanitization rule`);
+    } else if (lookRecord.look?.review_state !== "needs-structured-review") {
+      errors.push(`${lookRecord.id}: intake-review records must declare look.review_state`);
+    }
+  }
+  return errors;
+}
+
+function intake() {
+  const root = rootPath();
+  const image = option("--image");
+  const referenceImages = options("--reference");
+  const into = option("--into");
+  const rights = option("--rights");
+  if (!image || !["persona", "look"].includes(into) || rights !== "authorized") {
+    throw new Error("usage: personlib intake --image PATH [--reference PATH ...] --into <persona|look> --rights authorized [--id ID] [--name NAME]");
+  }
+  const approvedExtensions = new Set([".png", ".jpg", ".jpeg", ".webp"]);
+  for (const inputImage of [image, ...referenceImages]) {
+    if (!existsSync(inputImage)) throw new Error(`image not found: ${inputImage}`);
+    if (!approvedExtensions.has(extname(inputImage).toLowerCase())) throw new Error(`unsupported image type: ${extname(inputImage).toLowerCase()}`);
+  }
+  const manifest = existsSync(manifestPath(root)) ? readManifest(root) : {
+    schema_version: "0.1",
+    library_id: "private-persona-library",
+    visibility: "private",
+    personas: [],
+    looks: []
+  };
+  manifest.personas ||= [];
+  manifest.looks ||= [];
+  const collection = into === "persona" ? "personas" : "looks";
+  const id = option("--id") || nextId(manifest, collection);
+  if (manifest[collection].some((record) => record.id === id)) throw new Error(`${into} already exists: ${id}`);
+  const targetDir = join(root, collection, id);
+  mkdirSync(targetDir, { recursive: true });
+  const copySource = (sourceImage, filename) => {
+    const target = join(targetDir, filename);
+    copyFileSync(sourceImage, target);
+    return {
+      original_filename: basename(sourceImage),
+      relative_path: `${collection}/${id}/${filename}`,
+      sha256: sha256(target)
+    };
+  };
+  const source = copySource(image, `source${extname(image).toLowerCase()}`);
+  const identityReferences = into === "persona" ? referenceImages.map((referenceImage, index) => (
+    copySource(referenceImage, `reference-${index + 1}${extname(referenceImage).toLowerCase()}`)
+  )) : [];
+  const common = {
+    id,
+    display_name: option("--name") || `${into === "persona" ? "Persona" : "Look"} ${id.slice(2)}`,
+    status: "intake-review",
+    provenance: {
+      type: "user-provided",
+      rights: "owner-confirmed",
+      imported_at: new Date().toISOString()
+    },
+    source,
+    cloud_sync: "not-started"
+  };
+  const record = into === "persona" ? {
+    ...common,
+    identity: { review_state: "needs-structured-review" },
+    identity_references: identityReferences,
+    look_observations: []
+  } : {
+    ...common,
+    look: { review_state: "needs-structured-review" },
+    identity_policy: "do-not-use-source-face",
+    brand_policy: "needs-brand-sanitization"
+  };
+  manifest[collection].push(record);
+  saveManifest(root, manifest);
+  output({ ok: true, [into]: record });
+}
+
+function buildRenderBrief(persona, look) {
+  const identity = persona.identity;
+  const identityLock = [
+    identity.face_shape,
+    identity.brows,
+    identity.eyes,
+    identity.nose,
+    identity.mouth,
+    identity.skin,
+    identity.stable_marks,
+    identity.body_evidence
+  ].filter(Boolean).join("; ");
+  return [
+    `Original ${identity.presentation || "adult"} character.`,
+    `Identity lock: ${identityLock}.`,
+    `Keep this Persona's facial structure, apparent adult age, natural skin traits, and stable marks; do not replace them with any Look-reference identity.`,
+    `Look direction: ${look.family}. ${look.silhouette}. Garments: ${look.garments}.`,
+    `Palette: ${look.palette}. Materials: ${look.materials}. Accessories: ${look.accessories}.`,
+    `Scene: ${look.scene}.`,
+    `Use original, generic design language: replace source logos, watermarks, wordmarks, celebrity likenesses, and recognizable brand elements.`
+  ].join(" ");
+}
+
+function scorePersonaForBrief(persona, brief) {
+  const query = brief.toLowerCase();
+  const identity = Object.values(persona.identity || {}).join(" ").toLowerCase();
+  let score = persona.identity?.presentation === "feminine adult" ? 2 : 0;
+  if (/干净|clean|beauty|美妆/.test(query)) {
+    for (const signal of ["fine", "soft", "natural", "even", "neutral", "low-contrast"]) {
+      if (identity.includes(signal)) score += 2;
+    }
+  }
+  if (/冷感|cool|冷调|高端|luxury/.test(query)) {
+    for (const signal of ["narrow", "long", "straight", "low-contrast", "calm", "slim"]) {
+      if (identity.includes(signal)) score += 2;
+    }
+  }
+  return score;
+}
+
+function scoreLookForBrief(lookRecord, brief) {
+  const query = brief.toLowerCase();
+  const lookText = Object.values(lookRecord.look || {}).join(" ").toLowerCase();
+  let score = 0;
+  const addSignals = (requestPattern, signals) => {
+    if (!requestPattern.test(query)) return;
+    for (const [signal, weight] of signals) {
+      if (lookText.includes(signal)) score += weight;
+    }
+  };
+  addSignals(/美妆|beauty|cosmetic|skincare|护肤/, [["beauty", 4], ["skincare", 4], ["serum", 3], ["fragrance", 2], ["treatment", 2]]);
+  addSignals(/高端|luxury|premium|prestige/, [["luxury", 3], ["premium", 3], ["prestige", 3], ["sculptural", 2], ["metallic", 2], ["gold", 2], ["silver", 2]]);
+  addSignals(/干净|clean|minimal/, [["clean", 3], ["white", 2], ["minimal", 2], ["bright", 1], ["soft", 1]]);
+  addSignals(/冷感|cool|冷调/, [["silver", 2], ["graphite", 2], ["grey", 2], ["icy", 2], ["black", 1], ["violet", 1]]);
+  addSignals(/y2k|千禧/, [["y2k", 6]]);
+  addSignals(/学院|校园|collegiate|academic/, [["collegiate", 5], ["academic", 5], ["campus", 3]]);
+  addSignals(/哥特|gothic|暗黑|grunge/, [["gothic", 4], ["grunge", 4], ["dark", 2]]);
+  addSignals(/街头|street/, [["street", 4], ["cargo", 2], ["denim", 1]]);
+  addSignals(/地铁|metro|subway|transit/, [["transit", 5], ["metro", 4], ["commuter", 3], ["urban", 1]]);
+  addSignals(/机车夹克|皮夹克|moto|leather jacket/, [["leather", 4], ["moto", 11], ["black", 1], ["grey", 1]]);
+  addSignals(/中性|男女同款|unisex|androgynous|gender[- ]?neutral/, [["unisex", 5], ["gender-neutral", 5], ["oversized", 2], ["cargo", 2], ["long short", 2], ["knit", 1]]);
+  addSignals(/嘻哈|说唱|hip[- ]?hop|rap(?:per)?/, [["hip-hop", 5], ["rap", 5], ["street", 3], ["baggy", 2], ["cargo", 2], ["jersey", 2], ["chain", 2], ["camo", 3], ["wide", 1]]);
+  addSignals(/通勤|office|职场|workwear|商务|上班|commute/, [["office", 4], ["commute", 4], ["workwear", 4], ["tailored", 2], ["suit", 2], ["blazer", 2]]);
+  addSignals(/极简轻奢|quiet luxury|成熟通勤|mature commute/, [["quiet luxury", 6], ["mature commute", 6], ["trench", 3], ["tailored", 2], ["minimal", 2], ["wool", 1]]);
+  addSignals(/杂志|magazine|editorial|时尚大片/, [["magazine", 4], ["editorial", 4], ["studio", 1], ["tailored", 1]]);
+  addSignals(/晚宴|gala|black-tie|formal/, [["gala", 4], ["evening", 3], ["formal", 3], ["gown", 2], ["soiree", 2]]);
+  addSignals(/红毯|red carpet/, [["red carpet", 6], ["gala", 3], ["carpet", 2], ["train", 2], ["gown", 2]]);
+  addSignals(/高级派对|party|cocktail|after-party/, [["party", 4], ["cocktail", 3], ["soiree", 3], ["crystal", 1], ["sequin", 1], ["gown", 1]]);
+  addSignals(/运动休闲|athleisure|运动|sport|sportswear|健身|球类|篮球|网球|跑步|track|训练/, [["athleisure", 5], ["sport", 4], ["track", 3], ["running", 2], ["tennis", 2], ["basketball", 2], ["technical", 1], ["fleece", 1], ["hoodie", 1]]);
+  addSignals(/度假|海岛|resort|beach|holiday|pool|yacht|sailing|夏日/, [["resort", 5], ["beach", 5], ["island", 4], ["pool", 4], ["sailing", 4], ["summer", 3], ["linen", 2], ["swim", 2], ["nautical", 2]]);
+  return score;
+}
+
+function catalogLookForBrief(manifest, brief) {
+  const candidates = (manifest.looks || [])
+    .filter((lookRecord) => lookRecord.status === "private-staged")
+    .map((lookRecord) => ({ lookRecord, score: scoreLookForBrief(lookRecord, brief) }))
+    .sort((a, b) => b.score - a.score || a.lookRecord.id.localeCompare(b.lookRecord.id));
+  const top = candidates[0];
+  if (!top || top.score < 6) return undefined;
+  const durationMatch = brief.match(/(?:^|\D)(\d{1,3})\s*(?:秒|s|sec|second)/i);
+  return {
+    source: "catalog-match",
+    score: top.score,
+    look: {
+      id: top.lookRecord.id,
+      display_name: top.lookRecord.display_name,
+      status: top.lookRecord.status,
+      ...top.lookRecord.look,
+      duration_seconds: durationMatch ? Number.parseInt(durationMatch[1], 10) : undefined,
+      identity_policy: "persona-is-the-only-identity-reference",
+      brand_policy: "original-unbranded-design-only"
+    }
+  };
+}
+
+function temporaryLookFromBrief(brief) {
+  const beautyRequest = /美妆|beauty|cosmetic|skincare/i.test(brief);
+  const coolRequest = /冷感|cool|冷调/i.test(brief);
+  const highEndRequest = /高端|luxury|premium/i.test(brief);
+  const durationMatch = brief.match(/(?:^|\D)(\d{1,3})\s*(?:秒|s|sec|second)/i);
+  const idHash = createHash("sha256").update(brief).digest("hex").slice(0, 8).toUpperCase();
+  return {
+    id: `TEMP-L-${idHash}`,
+    display_name: beautyRequest ? "Temporary Clean Cool Beauty" : "Temporary Text-Derived Look",
+    status: "temporary-not-saved",
+    source: "generated-from-user-brief",
+    family: beautyRequest ? "high-end clean beauty" : "brief-derived original styling",
+    silhouette: "minimal architectural neckline with an uncluttered shoulder line",
+    garments: highEndRequest ? "original ivory architectural halter top, no visible branding" : "original unbranded minimal styling",
+    palette: coolRequest ? "pearl, ice blue-grey, muted cool rose, soft ivory" : "clean neutral palette derived from the request",
+    materials: "satin, sheer beauty textures, frosted glass, soft studio surfaces",
+    accessories: "minimal or none; no trademarked elements",
+    scene: beautyRequest ? "premium beauty studio with a frosted blue-grey gradient and soft reflective surfaces" : "minimal studio scene derived from the request",
+    duration_seconds: durationMatch ? Number.parseInt(durationMatch[1], 10) : undefined,
+    identity_policy: "persona-is-the-only-identity-reference",
+    brand_policy: "original-unbranded-design-only"
+  };
+}
+
+function recommendationForBrief(manifest, brief) {
+  const candidates = (manifest.personas || [])
+    .filter((persona) => persona.status === "private-staged")
+    .map((persona) => ({ persona, score: scorePersonaForBrief(persona, brief) }))
+    .sort((a, b) => b.score - a.score || a.persona.id.localeCompare(b.persona.id));
+  if (!candidates.length) throw new Error("no staged Persona records available for recommendation");
+  const selected = candidates[0].persona;
+  const catalogMatch = catalogLookForBrief(manifest, brief);
+  const selectedLook = catalogMatch?.look || temporaryLookFromBrief(brief);
+  const ageRequested = /(?:25\s*岁|25\s*year|twenty[- ]?five)/i.test(brief);
+  const eastAsiaRequested = /东亚|east\s*asian/i.test(brief);
+  return {
+    request: brief,
+    persona: {
+      id: selected.id,
+      display_name: selected.display_name,
+      match_reason: "Selected from explicit adult Persona metadata and structure-level clean/cool signals; style is not used as identity evidence."
+    },
+    alternatives: candidates.slice(1, 3).map(({ persona, score }) => ({ id: persona.id, display_name: persona.display_name, score })),
+    look: selectedLook,
+    look_match: catalogMatch ? { source: catalogMatch.source, score: catalogMatch.score } : { source: "temporary-text-derived", score: 0 },
+    constraints_not_verified_from_portrait: [
+      ...(ageRequested ? ["exact age is not stored; the selected Persona is only recorded as an adult"] : []),
+      ...(eastAsiaRequested ? ["East Asian identity is not inferred from the portrait; it requires explicit owner-provided metadata before it can be a hard filter"] : [])
+    ],
+    render_brief: buildRenderBrief(selected, selectedLook),
+    preview: {
+      status: "ready-for-authorized-image-renderer",
+      source_face_policy: "use-selected-persona-only",
+      temporary_look_policy: catalogMatch ? "not-applicable-catalog-look-selected" : "do-not-save-unless-owner-promotes-it",
+      output: "one unbranded vertical preview image"
+    }
+  };
+}
+
+function recommend() {
+  const root = rootPath();
+  const brief = option("--brief");
+  if (!brief) throw new Error("usage: personlib recommend --brief TEXT --library PATH");
+  const manifest = readManifest(root);
+  const errors = validate(manifest, root);
+  if (errors.length) throw new Error(`library validation failed: ${errors.join("; ")}`);
+  output({ ok: true, recommendation: recommendationForBrief(manifest, brief) });
+}
+
+function fetchReferencePack() {
+  const root = rootPath();
+  const brief = option("--brief");
+  const outputDir = option("--output-dir");
+  if (!brief || !outputDir) throw new Error("usage: personlib fetch --brief TEXT --output-dir PATH [--overwrite] --library PATH");
+  const manifest = readManifest(root);
+  const errors = validate(manifest, root);
+  if (errors.length) throw new Error(`library validation failed: ${errors.join("; ")}`);
+  const recommendation = recommendationForBrief(manifest, brief);
+  if (recommendation.look.status !== "private-staged") {
+    throw new Error("no catalog Look matched this brief; fetch only returns an existing reference pack");
+  }
+  const persona = (manifest.personas || []).find((entry) => entry.id === recommendation.persona.id);
+  const lookRecord = (manifest.looks || []).find((entry) => entry.id === recommendation.look.id);
+  if (!persona || !lookRecord) throw new Error("selected records are unavailable for fetch");
+
+  const destination = resolve(outputDir);
+  mkdirSync(destination, { recursive: true });
+  const copyReference = (source, role, index = 0) => {
+    const extension = extname(source.original_filename || source.relative_path) || ".png";
+    const filename = `${role}${index ? `-${index}` : ""}${extension}`;
+    const target = join(destination, filename);
+    if (existsSync(target) && !has("--overwrite")) throw new Error(`refusing to overwrite ${target}; pass --overwrite to replace it`);
+    copyFileSync(join(root, source.relative_path), target);
+    return { role, filename };
+  };
+  const files = [copyReference(persona.source, "persona")];
+  for (const [index, source] of (persona.identity_references || []).entries()) {
+    files.push(copyReference(source, "persona-reference", index + 1));
+  }
+  files.push(copyReference(lookRecord.source, "look"));
+  const selectionFilename = "selection.json";
+  const selectionPath = join(destination, selectionFilename);
+  if (existsSync(selectionPath) && !has("--overwrite")) throw new Error(`refusing to overwrite ${selectionPath}; pass --overwrite to replace it`);
+  writeFileSync(selectionPath, `${JSON.stringify({
+    schema_version: "0.1",
+    kind: "persona-look-reference-pack",
+    generated_at: new Date().toISOString(),
+    recommendation: {
+      request: recommendation.request,
+      persona: { ...recommendation.persona, identity: persona.identity },
+      look: recommendation.look,
+      look_match: recommendation.look_match,
+      render_brief: recommendation.render_brief,
+      source_face_policy: "persona-is-the-only-identity-reference",
+      image_status: "source-reference-pack-not-a-generated-composite"
+    },
+    files
+  }, null, 2)}\n`, "utf8");
+  output({
+    ok: true,
+    retrieval: {
+      kind: "persona-look-reference-pack",
+      image_status: "source-reference-pack-not-a-generated-composite",
+      output_dir: destination,
+      files: [...files, { role: "selection", filename: selectionFilename }],
+      persona: recommendation.persona,
+      look: { id: recommendation.look.id, display_name: recommendation.look.display_name },
+      render_brief: recommendation.render_brief
+    }
+  });
+}
+
+function compose() {
+  const root = rootPath();
+  const personaId = option("--persona");
+  const lookId = option("--look");
+  if (!personaId || !lookId) {
+    throw new Error("usage: personlib compose --persona P-001 --look L-001 --library PATH");
+  }
+  const manifest = readManifest(root);
+  const errors = validate(manifest, root);
+  if (errors.length) throw new Error(`library validation failed: ${errors.join("; ")}`);
+  const persona = (manifest.personas || []).find((entry) => entry.id === personaId);
+  const lookRecord = (manifest.looks || []).find((entry) => entry.id === lookId);
+  if (!persona) throw new Error(`persona not found: ${personaId}`);
+  if (!lookRecord) throw new Error(`look not found: ${lookId}`);
+  if (persona.status !== "private-staged") throw new Error(`persona is not ready for composition: ${personaId}`);
+  if (lookRecord.status !== "private-staged") throw new Error(`look is not ready for composition: ${lookId}`);
+
+  const look = lookRecord.look;
+  output({
+    ok: true,
+    composition: {
+      persona: { id: persona.id, display_name: persona.display_name, identity: persona.identity },
+      look: { id: lookRecord.id, display_name: lookRecord.display_name, ...look },
+      policies: {
+        use_persona_as_only_identity_reference: true,
+        look_source_face: "excluded",
+        source_logos_and_wordmarks: "replace-with-original-generic-design"
+      },
+      render_brief: buildRenderBrief(persona, look),
+      render_status: "brief-only-no-generation-submitted"
+    }
+  });
+}
+
+try {
+  const root = rootPath();
+  if (command === "setup") await runBootstrapSetup(argv.slice(1), { output });
+  else if (command === "remote") await runRemote(argv.slice(1), { output, readManifest });
+  else if (command === "intake") intake();
+  else if (command === "recommend") recommend();
+  else if (command === "fetch") fetchReferencePack();
+  else if (command === "compose") compose();
+  else if (command === "list") {
+    const manifest = readManifest(root);
+    const type = option("--type");
+    if (type && !["persona", "look"].includes(type)) throw new Error("--type must be persona or look");
+    const payload = { ok: true, library_id: manifest.library_id };
+    if (!type || type === "persona") payload.personas = (manifest.personas || []).map(({ id, display_name, status }) => ({ id, display_name, status }));
+    if (!type || type === "look") payload.looks = (manifest.looks || []).map(({ id, display_name, status }) => ({ id, display_name, status }));
+    output(payload);
+  } else if (command === "show") {
+    const personaId = option("--persona");
+    const lookId = option("--look");
+    if (Boolean(personaId) === Boolean(lookId)) throw new Error("usage: personlib show --persona P-001 | --look L-001 --library PATH");
+    const manifest = readManifest(root);
+    const collection = personaId ? "personas" : "looks";
+    const type = personaId ? "persona" : "look";
+    const id = personaId || lookId;
+    const record = (manifest[collection] || []).find((entry) => entry.id === id);
+    if (!record) throw new Error(`${type} not found: ${id}`);
+    output({ ok: true, [type]: record });
+  } else if (command === "validate") {
+    const errors = validate(readManifest(root), root);
+    output({ ok: errors.length === 0, errors });
+    if (errors.length) process.exitCode = 1;
+  } else {
+    output("Usage: personlib <setup|intake|list|show|recommend|fetch|compose|validate|remote> [--library PATH] [--json]");
+    process.exitCode = command ? 1 : 0;
+  }
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}

package/cloudflare-worker/README.md

@@ -0,0 +1,37 @@
+# Private Worker deployment
+
+This Worker serves the owner-authorized Persona + Look library to individually enrolled Agents. D1 stores sanitized record metadata and hashes of Agent credentials; R2 stores approved source-reference bytes. There is no anonymous catalog or asset route.
+
+The owner has elected open self-registration: any Agent can call `POST /v1/agents/setup` and receive a unique credential, but must still authenticate each later recommendation, composition, doctor, and asset request. The credential is sent once to the local CLI and saved only in a mode-600 local config file.
+
+Run these commands only in the owner's Cloudflare account after installing/authenticating Wrangler. Do not place secret values in a command, a file, or shell history.
+
+```bash
+cd cloudflare-worker
+npx wrangler d1 create personlib
+npx wrangler r2 bucket create personlib-assets
+```
+
+Copy the returned D1 database id into `wrangler.toml`, set `OPEN_ENROLLMENT = "true"`, then create the schema and owner secret:
+
+```bash
+npx wrangler d1 execute personlib --remote --file schema.sql
+npx wrangler secret put OWNER_SYNC_TOKEN
+npx wrangler deploy
+```
+
+The owner then uses an ephemeral `PERSONLIB_REMOTE_ENDPOINT` plus `PERSONLIB_OWNER_SYNC_TOKEN` to upload the reviewed source library from the project root:
+
+```bash
+personlib remote sync --library ./private-library --dry-run --json
+personlib remote sync --library ./private-library --json
+```
+
+After deployment, put the resulting **HTTPS Worker URL** in `package.json` under `personlib.default_api_url`; `npm publish` is intentionally blocked until this value is present. A released CLI then supports the expected Agent bootstrap:
+
+```bash
+npx -y makaron-persona-look-cli setup
+personlib remote doctor --json
+```
+
+To restrict enrollment again, set `OPEN_ENROLLMENT` to `false`, create `AGENT_REGISTRATION_TOKEN` as a Worker secret, and provide the matching registration token only through the Agent's secret manager. This is not the current requested policy.

package/cloudflare-worker/schema.sql

@@ -0,0 +1,26 @@
+CREATE TABLE IF NOT EXISTS agents (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  token_hash TEXT NOT NULL UNIQUE,
+  created_at TEXT NOT NULL,
+  revoked_at TEXT
+);
+
+CREATE TABLE IF NOT EXISTS persona_records (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL,
+  record_json TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS look_records (
+  id TEXT PRIMARY KEY,
+  display_name TEXT NOT NULL,
+  record_json TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS assets (
+  id TEXT PRIMARY KEY,
+  object_key TEXT NOT NULL UNIQUE,
+  sha256 TEXT NOT NULL,
+  mime_type TEXT NOT NULL
+);