@hypersocial/decks-cli 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypersocial/decks-cli",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Command-line client for Hypersocial Decks live analytics and share management.",
   "type": "module",
   "main": "./src/commands.mjs",

package/skills/hyperdecks/SKILL.md

@@ -35,7 +35,48 @@ word, and wait for them:
 - voice: cloning needs them to type their consent in a terminal (`hyperdecks
   voice clone <file> --name <name>`), or to agree to the statement before you
   call `clone_voice`. Never type or confirm consent for them. `--voice dash`
-  lets D.A.S.H., a character voice, present instead.
+  lets D.A.S.H., a character voice, present instead;
+- narrator: who narrates their decks, a face plus a voice. Without one, a deck
+  in the user's own voice plays captions only. See *Narrators* below; only the
+  person picks one.
+
+### Narrators: who narrates a deck (a face plus a voice)
+
+A narrator pairs a face (one of the user's avatars) with a voice (one of their
+ready voices, or D.A.S.H.'s). D.A.S.H. is built in. A deck uses its own
+narrator, else the default: `narrate` speaks in the narrator's voice (an
+explicit `--voice` or the script's `voice:` still wins) and `release` puts its
+face on the deck. **Never add a narrator for the person**: `narrator new`
+returns a link; hand it to them, word for word, and wait.
+
+| Step | CLI | MCP |
+| --- | --- | --- |
+| List them, the default and the voices | `hyperdecks narrator --json` | `list_narrators` |
+| Add one (the person picks face and voice) | `hyperdecks narrator new --json` → `url` | `new_narrator_link` |
+| Make one the default (the person named it) | `hyperdecks narrator default <name>` | `set_default_narrator` |
+| Remove one (confirm first) | `hyperdecks narrator remove <name>` | `remove_narrator` |
+| Change its voice (the person asked) | `hyperdecks narrator voice <name> <voice>` | `set_narrator_voice` |
+| One deck's own narrator | `hyperdecks deck narrator <slug> <name\|none\|default>` | `set_deck_narrator` |
+
+### Avatars: who presents a deck in the user's voice
+
+The faces narrators wear; these commands still work as before.
+
+A deck narrated in the user's own voice is presented by their default avatar
+(a cartoon Minimoji, never a photo) from its next release; with none it plays
+captions only. D.A.S.H. presents only in its own voice. **Never pick or approve
+a face for the person.** Every command that needs a choice returns a link (and,
+for an import, a code): hand it to them, word for word, and wait.
+
+| Step | CLI | MCP |
+| --- | --- | --- |
+| List them and the default | `hyperdecks avatar --json` | `list_avatars` |
+| Pick a species and an avatar | `hyperdecks avatar new [--species cat] --json` → `pickUrl` | `new_avatar_link` |
+| A cartoon from a photo | `hyperdecks avatar from-photo [me.jpg] --json` → `reviewUrl` (or `selfieUrl`) | `avatar_from_photo` |
+| Import from Minimoji | `hyperdecks avatar connect --json` → `url` + `code` | `connect_avatar` |
+| Make one the default (the person named it) | `hyperdecks avatar default <name>` | `set_default_avatar` |
+| Remove one (confirm first) | `hyperdecks avatar remove <name>` | `remove_avatar` |
+| One deck's own presenter | `hyperdecks deck avatar <slug> <name\|none\|default>` | `set_deck_avatar` |
 
 ## Target Selection
 
@@ -92,11 +133,21 @@ Hyperdecks server; use the CLI where you have a shell and the tool otherwise.
 | Ship | `hyperdecks release decks/<slug> --to "<name>" --email <e>` | `release_deck` |
 | Share-link poster | `hyperdecks poster <slug>` | `generate_deck_poster` |
 | Import only | `hyperdecks import <file> --slug <slug>` | `import_deck_from_url` |
-| One more link | `hyperdecks share new <slug> "<name>"` | `create_share` |
+| One more link | `hyperdecks share new <slug> "<name>" [--no-forward]` | `create_share` (`allowForward`) |
+| Forwarding, one link | `hyperdecks share forward on\|off\|default <token>` | `set_share_forwarding` |
+| Forwarding, whole deck | `hyperdecks deck forward on\|off <slug>` | `set_deck_forwarding` |
 | Who watched | `hyperdecks deck stats <slug>` | `deck_stats` |
 | All activity | `hyperdecks activity --deck <slug>` | `activity_overview` |
 | What one person watched | `hyperdecks engagement "<name>" --deck <slug> --json` | `recipient_engagement` |
 
+Forwarding is on by default: a viewer can forward the deck to someone, which
+makes a child link tracked on its own ("Dana via Peter"; `share list` shows it
+indented under Peter's, `list_shares` gives `parentToken` and `forwardedBy`).
+One hop only: a forwarded link can't be forwarded again, nor can a QA link.
+Disabling the parent link (`share off`) turns off its forwards too, and
+`share forward default` (or `allowForward: null`) drops a link's own setting
+so it follows the deck's.
+
 ### 1. Ground it in the user's own material
 
 Build the deck from what you can already read in this session: files in the

package/src/avatar.mjs

@@ -0,0 +1,91 @@
+// hyperdecks avatar [list] | new [--species x] | from-photo [file] [--save-to-minimoji] | connect | default <id> | remove <id>
+//
+// The face that presents decks narrated in your own voice (convex/avatars.ts).
+// Only a person picks or approves a face: in a terminal you pick by number;
+// with --json, or without a terminal (an agent), each command returns the link
+// (and for connect, the code) to hand the person, and never chooses.
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import * as ops from "./ops.mjs";
+import { SPECIES as TABLE } from "./species.mjs";
+
+export const SPECIES = TABLE.map((s) => s.id);
+const PHOTO_TYPES = { ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png" };
+
+const interactiveOf = (opts) => !opts.json && !!process.stdin.isTTY && !!process.stdout.isTTY;
+
+export async function avatarList(opts, { log = console.log } = {}) {
+  const out = await ops.listAvatars(opts);
+  if (opts.json) return out;
+  for (const a of out.avatars) log(`${a.isDefault ? "*" : " "} ${a.name}\t${a.source}${a.species ? ` (${a.species})` : ""}\t${a.id}`);
+  log("\n* the default; decks narrated in your voice use it unless they set their own (deck avatar <slug> <id>)");
+  return out;
+}
+
+// Pick a species and one of its avatars in the terminal; s shuffles, u undoes.
+export async function avatarNew(opts, { ask, log = console.log, interactive = interactiveOf(opts) } = {}) {
+  const species = opts.species ? String(opts.species).toLowerCase() : null;
+  if (species && !SPECIES.includes(species)) throw new Error(`--species is one of ${SPECIES.join(", ")}`);
+  if (!interactive) {
+    const link = await ops.newAvatarLink(opts, species ? { species } : {});
+    if (!opts.json) log(`Pick an avatar here (only you can choose it):\n  ${link.pickUrl}`);
+    return link;
+  }
+  log(`Species: ${SPECIES.join(" ")}`);
+  let chosen = species;
+  while (!chosen) {
+    const a = (await ask("Species [human]: ")).trim().toLowerCase() || "human";
+    if (SPECIES.includes(a)) chosen = a;
+    else log(`  not a species; one of ${SPECIES.join(", ")}`);
+  }
+  const link = await ops.newAvatarLink(opts, { species: chosen });
+  log(`Preview them: ${link.pickUrl}`);
+  const seeds = [0];
+  for (;;) {
+    const page = await ops.avatarOptions(opts, chosen, seeds[seeds.length - 1]);
+    log(page.options.map((o, i) => `  ${String(i + 1).padStart(2)}  ${o.name}`).join("\n"));
+    const keys = [page.canShuffle && "s to shuffle", seeds.length > 1 && "u to undo"].filter(Boolean).join(", ");
+    const a = (await ask(`Pick 1-${page.options.length}${keys ? `, or ${keys}` : ""}: `)).trim().toLowerCase();
+    if (a === "s" && page.canShuffle) { seeds.push(seeds[seeds.length - 1] + 1); continue; }
+    if (a === "u" && seeds.length > 1) { seeds.pop(); continue; }
+    const n = Number(a);
+    const option = Number.isInteger(n) ? page.options[n - 1] : null;
+    if (!option) continue;
+    await ops.addPickedAvatar(opts, option.avatarKey);
+    log(`✓ Added ${option.name} (${chosen}). Default for decks in your voice.`);
+    return { status: "added", name: option.name, species: chosen };
+  }
+}
+
+// A face from a photo file, or (no file) a selfie in the browser. Either way the
+// person approves it on the link before it is used.
+export async function avatarFromPhoto(file, opts, { log = console.log, interactive = interactiveOf(opts) } = {}) {
+  let photo = {};
+  if (file) {
+    const contentType = PHOTO_TYPES[extname(file).toLowerCase()];
+    if (!contentType) throw new Error("the photo must be a .jpg or .png");
+    photo = { bytes: readFileSync(file), contentType };
+  }
+  const out = await ops.avatarFromPhoto(opts, photo, { onProgress: (m) => !opts.json && log(m) });
+  const url = out.reviewUrl ?? out.selfieUrl;
+  if (opts.json) return out;
+  log(file ? `✓ Drew a cartoon of you. Check it before it's used:\n  ${url}` : `No photo given. Take a selfie in your browser:\n  ${url}`);
+  if (opts["save-to-minimoji"]) log("  (tick \"Also save it to my Minimoji account\" there)");
+  if (!interactive) return out;
+  log("Waiting for you…");
+  const avatar = await ops.waitForLink(opts, out.token);
+  log(`✓ ${avatar.name} presents your decks now. Your photo was deleted.`);
+  return { status: "added", name: avatar.name };
+}
+
+export async function avatarConnect(opts, { log = console.log, interactive = interactiveOf(opts) } = {}) {
+  const out = await ops.connectAvatar(opts);
+  if (opts.json) return out;
+  log(`On any device, go to ${out.url}\nand enter ${out.code}   (expires in ${Math.round(out.expiresIn / 60)} min)`);
+  if (!interactive) return out;
+  log("Waiting for you to pick a face…");
+  const done = await ops.waitForConnect(opts, out.connectId);
+  if (done.status !== "added") throw new Error(done.status === "denied" ? "not shared on minimoji.com" : done.status === "expired" ? "the code expired; run avatar connect again" : done.error || `the import ended (${done.status})`);
+  log("✓ Presenter: your Minimoji. Your decks use it from the next release.");
+  return { status: "added", avatarId: done.avatarId };
+}

package/src/commands.mjs

@@ -87,7 +87,8 @@ function shareBase(opts) {
 
 async function shareNew(pos, opts) {
   const [slug, recipient] = pos;
-  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify]");
+  if (!slug || !recipient) throw new Error("usage: share new <slug> <recipient> [--email e] [--note n] [--require-email] [--expires iso] [--limit n] [--qa] [--no-notify] [--allow-forward|--no-forward]");
+  if (opts["allow-forward"] && opts["no-forward"]) throw new Error("pick one of --allow-forward and --no-forward");
   const { token } = await ops.createShare(opts, {
     slug,
     recipient,
@@ -96,6 +97,7 @@ async function shareNew(pos, opts) {
     requireEmail: opts["require-email"],
     qa: opts.qa || undefined,
     notify: opts["no-notify"] ? false : undefined,
+    allowForward: opts["allow-forward"] ? true : opts["no-forward"] ? false : undefined,
     expires: opts.expires,
     limit: opts.limit,
   });
@@ -112,7 +114,11 @@ async function shareList(pos, opts) {
     console.log(JSON.stringify(rows, null, 2));
     return;
   }
-  for (const r of rows) console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${r.recipient}\topens:${r.opens}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.archived ? "\t(archived)" : ""}`);
+  // Rows arrive with each link's forwards right after it; indent those.
+  for (const r of rows) {
+    const who = r.parentToken ? `  ↳ ${r.recipient} via ${r.forwardedBy ?? "?"}` : r.recipient;
+    console.log(`${r.enabled ? "on " : "off"}\t${r.token}\t${who}\topens:${r.opens}\tfwd:${r.allowForward ? "on" : "off"}${r.qa ? "\tQA (untracked)" : ""}${r.notify === false ? "\tmuted" : ""}${r.probablyForwarded ? "\tprobably forwarded" : ""}${r.archived ? "\t(archived)" : ""}`);
+  }
   if (!rows.length) console.log("(no shares)");
 }
 
@@ -126,8 +132,24 @@ async function shareToggle(pos, opts, enabled) {
 async function shareRm(pos, opts) {
   const [token] = pos;
   if (!token) throw new Error("usage: share rm <token>");
-  await ops.removeShare(opts, token);
-  console.log(`OK removed ${token}`);
+  const { removedForwards } = await ops.removeShare(opts, token);
+  console.log(`OK removed ${token}${removedForwards ? ` and ${removedForwards} forwarded link${removedForwards === 1 ? "" : "s"}` : ""}`);
+}
+
+const FORWARD = { on: true, off: false, default: null };
+
+async function shareForward(pos, opts) {
+  const [mode, token] = pos;
+  if (!Object.hasOwn(FORWARD, mode ?? "") || !token) throw new Error("usage: share forward on|off|default <token>");
+  await ops.setShareForwarding(opts, token, FORWARD[mode]);
+  console.log(`OK forwarding ${mode === "default" ? "follows the deck default" : mode} for ${token}`);
+}
+
+async function deckForward(pos, opts) {
+  const [mode, slug] = pos;
+  if ((mode !== "on" && mode !== "off") || !slug) throw new Error("usage: deck forward on|off <slug>");
+  await ops.setDeckForwarding(opts, slug, mode === "on");
+  console.log(`OK forwarding ${mode} for deck ${slug} (links with their own setting keep it)`);
 }
 
 function shareUrl(pos, opts) {
@@ -281,7 +303,9 @@ commands:
   login [--token <pat>] [--broker <url>] [--dev]
   logout [--dev]
   whoami [--json] [--dev]
-  deck list|stats|open|rm
+  deck list|stats|open|rm|forward
+  deck forward on|off <slug>
+                   whether viewers can forward the deck's links (on by default; a link's own setting wins)
   deck new <slug> "<title>" --narrated [--layouts hero,product,number,closer] [--presenter-style stage|bubble|glass|corner] [--dir <path>]
                    scaffold decks/<slug>/: index.html (8 slides, or one per layout, player/v1), script.md, evidence.md
                    layouts: hero, number, product, quote, compare, timeline, features, chart, team, closer
@@ -298,8 +322,11 @@ commands:
                    the skill, one topic at a time (what deck_guide serves)
   release <slug|deck-dir> [--to "<name>" [--email <e>]]... [--qa] [--no-notify] [--title t] [--voice v]
                    on a committed deck: check → narrate → import → share new per --to
-  share new|list|on|off|mute|unmute|rm|url
-    share new <slug> <recipient> [--qa] [--no-notify]
+  share new|list|on|off|forward|mute|unmute|rm|url
+    share new <slug> <recipient> [--qa] [--no-notify] [--allow-forward|--no-forward]
+    share forward on|off|default <token>
+                   let this link's viewer forward it as their own tracked link ("Dana via Peter",
+                   one hop); default follows the deck. share off on a link also turns off its forwards.
   recipient archive|unarchive
   import <html-or-zip-or-url> --slug <slug> [--title title] [--status draft|live]
   import-design <project-id> --serve-token <token> --entry <file.html> --slug <slug>
@@ -341,6 +368,20 @@ commands:
                    asks you to type "I consent" before anything is uploaded
   voice upload <file...>   upload recordings and print their sample ids (for the MCP clone_voice tool)
   voice rm <name|id>       delete a voice, also at the provider
+  avatar [--json]          your avatars (who presents decks in your voice) and the default
+  avatar new [--species <s>]   pick a species, then an avatar (s shuffles); --json or an agent gets a pick link
+  avatar from-photo [file] [--save-to-minimoji]
+                   draw a cartoon of you from a photo (no file: a selfie link); you approve it on a link first
+  avatar connect           import your avatar from Minimoji with a code you enter on minimoji.com
+  avatar default <name|id|dash>   make it the default
+  avatar remove <name|id>  remove it; decks already shared keep working, captions only
+  deck avatar <slug> <name|id|none|default>   the deck's own presenter (applies at its next release)
+  narrator [--json]        who narrates your decks (a face plus a voice) and the default
+  narrator new             a link where you pick a face and a voice; it becomes the default
+  narrator default <name|id|dash>   make it the default
+  narrator remove <name|id>         remove it; decks already shared keep working
+  narrator voice <name|id> <voice>  change its voice (one of yours, or dash)
+  deck narrator <slug> <name|id|none|default>   the deck's own narrator (none: captions only)
 
 global:
   --json
@@ -664,6 +705,72 @@ function commandTable(pos, rest, opts) {
       if (opts.json) return void console.log(JSON.stringify(out, null, 2));
       console.log(`OK removed voice "${out.name}"${out.removedAtProvider ? " (deleted at the provider; decks already narrated with it keep playing)" : ""}`);
     },
+    avatar: async () => {
+      const { avatarList } = await import("./avatar.mjs");
+      const out = await avatarList(opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "avatar new": async () => {
+      const { avatarNew } = await import("./avatar.mjs");
+      const { askLine } = await import("./init.mjs");
+      const out = await avatarNew(opts, { ask: askLine });
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "avatar from-photo": async () => {
+      const { avatarFromPhoto } = await import("./avatar.mjs");
+      const out = await avatarFromPhoto(rest[0], opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "avatar connect": async () => {
+      const { avatarConnect } = await import("./avatar.mjs");
+      const out = await avatarConnect(opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "avatar default": async () => {
+      if (!rest[0]) throw new Error("usage: avatar default <name|id|dash>");
+      const out = await ops.setDefaultAvatar(opts, rest.join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} is the default for decks in your voice`);
+    },
+    "avatar remove": async () => {
+      if (!rest[0]) throw new Error("usage: avatar remove <name|id>");
+      const out = await ops.removeAvatar(opts, rest.join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK removed ${out.name}; decks already shared keep working`);
+    },
+    "deck avatar": async () => {
+      if (rest.length < 2) throw new Error("usage: deck avatar <slug> <name|id|none|default>");
+      const out = await ops.setDeckAvatar(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.avatar} (applies at its next release)`);
+    },
+    narrator: async () => {
+      const { narratorList } = await import("./narrator.mjs");
+      const out = await narratorList(opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "narrator new": async () => {
+      const { narratorNew } = await import("./narrator.mjs");
+      const out = await narratorNew(opts);
+      if (opts.json) console.log(JSON.stringify(out, null, 2));
+    },
+    "narrator default": async () => {
+      if (!rest[0]) throw new Error("usage: narrator default <name|id|dash>");
+      const out = await ops.setDefaultNarrator(opts, rest.join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} narrates your decks by default`);
+    },
+    "narrator remove": async () => {
+      if (!rest[0]) throw new Error("usage: narrator remove <name|id>");
+      const out = await ops.removeNarrator(opts, rest.join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK removed ${out.name}; decks already shared keep working`);
+    },
+    "narrator voice": async () => {
+      if (rest.length < 2) throw new Error("usage: narrator voice <name|id> <voice>");
+      const out = await ops.setNarratorVoice(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.name} speaks in ${out.voice} now`);
+    },
+    "deck narrator": async () => {
+      if (rest.length < 2) throw new Error("usage: deck narrator <slug> <name|id|none|default>");
+      const out = await ops.setDeckNarrator(opts, rest[0], rest.slice(1).join(" "));
+      console.log(opts.json ? JSON.stringify(out, null, 2) : `OK ${out.slug} → ${out.narrator} (applies at its next narrate and release)`);
+    },
     "preview setup": async () => {
       const { setupCapture } = await import("./preview-capture.mjs");
       await setupCapture(rest, opts);
@@ -675,10 +782,12 @@ function commandTable(pos, rest, opts) {
     "deck stats": () => deckStats(rest, opts),
     "deck open": () => deckOpen(rest, opts),
     "deck rm": () => deckRemove(rest, opts),
+    "deck forward": () => deckForward(rest, opts),
     "share new": () => shareNew(rest, opts),
     "share list": () => shareList(rest, opts),
     "share on": () => shareToggle(rest, opts, true),
     "share off": () => shareToggle(rest, opts, false),
+    "share forward": () => shareForward(rest, opts),
     "share mute": async () => { if (!rest[0]) throw new Error("usage: share mute <token>"); await ops.setShareNotify(opts, rest[0], false); console.log(`OK muted ${rest[0]}`); },
     "share unmute": async () => { if (!rest[0]) throw new Error("usage: share unmute <token>"); await ops.setShareNotify(opts, rest[0], true); console.log(`OK notification preference requested for ${rest[0]} (QA links remain muted)`); },
     "share rm": () => shareRm(rest, opts),

package/src/init.mjs

@@ -279,6 +279,7 @@ export async function init(pos = [], opts = {}, io = {}) {
     env = process.env,
     random = () => randomBytes(2).toString("hex"),
     fetch,
+    avatars = null, // the avatar.mjs commands (tests pass fakes)
   } = io;
   if (pos.length) throw new Error(`unexpected argument(s): ${pos.join(" ")}; init takes flags only (hyperdecks init --help)`);
   for (const k of ["voice", "name", "about", "ask", "dir"]) if (k in opts && typeof opts[k] !== "string") throw new Error(`--${k} requires a value`);
@@ -335,7 +336,17 @@ export async function init(pos = [], opts = {}, io = {}) {
   const voiceStep = await chooseVoice(base, opts, { interactive, ask, voiceClone, sub, log, state, who });
   record(voiceStep);
   if (voiceStep.status === "needs-human") return finish("incomplete");
-  const { voice, presenter } = voiceStep;
+  let { voice, presenter } = voiceStep;
+
+  // 3b. Who presents a deck in your own voice: the deck stays captions-only in
+  // its source, and release puts your default avatar on it.
+  if (presenter === "self") {
+    const face = await presenterStep(base, opts, { interactive, ask, log, sub, avatars: avatars ?? (await import("./avatar.mjs")), state });
+    record(face);
+    if (face.presenter === "dash") ({ voice, presenter } = face);
+    // Asked once, unless the step could not even look (it asks again next run).
+    if (!face.warning) save({ presenterChosen: true });
+  }
 
   // 4. The first deck.
   const scaffold = await scaffoldStep(base, opts, { state, who, voice, presenter, interactive, ask, deckNew, cwd, home, random, sub, log, save });
@@ -494,6 +505,48 @@ async function chooseVoice(base, opts, { interactive, ask, voiceClone, sub, log,
   }
 }
 
+// Who narrates your decks: your own voice needs a face, or the deck plays
+// captions only. Only you pick it: without a terminal (an agent) this points
+// at `hyperdecks narrator new`.
+async function presenterStep(base, opts, { interactive, ask, log, sub, avatars, state }) {
+  let mine;
+  try {
+    mine = await ops.listAvatars(base);
+  } catch (e) {
+    const why = ops.errorText(e);
+    if (/not switched on/.test(why)) return step("presenter", "skipped", "presenter: captions only (avatars are not switched on for this account yet)");
+    return step("presenter", "skipped", `presenter: captions only for now (${why}); run init again, or \`hyperdecks avatar new\``, { warning: true });
+  }
+  const current = mine.avatars.find((a) => a.isDefault && a.source !== "dash");
+  if (current) return step("presenter", "done", `presenter: ${current.name}`);
+  if (!interactive || state.presenterChosen) {
+    return step("presenter", "skipped", "presenter: captions only; give your decks a narrator (a face plus your voice) with `hyperdecks narrator new`");
+  }
+  const io = { ask, log: sub, interactive: true };
+  for (;;) {
+    log("\nWho narrates your decks?");
+    log("  1  D.A.S.H.                our robot, in its own voice");
+    log("  2  Pick a Minimoji         choose a species, in your voice");
+    log("  3  Make one from a selfie  a cartoon of you, you approve it");
+    log("  4  Import from Minimoji    one you already have");
+    log("  5  Nobody                  captions only");
+    const pick = (await ask("Choose 1-5 [2]: ")).trim() || "2";
+    try {
+      if (pick === "1") return step("presenter", "done", "D.A.S.H. presents, in the dash character voice", { voice: "dash", presenter: "dash" });
+      if (pick === "2") { const out = await avatars.avatarNew(base, io); return step("presenter", "ran", `presenter: ${out.name}`); }
+      if (pick === "3") {
+        const file = parseDroppedPaths(await ask("Drag a photo (.jpg or .png) here, or press Enter for a selfie link: "))[0];
+        const out = await avatars.avatarFromPhoto(file, base, io);
+        return step("presenter", "ran", `presenter: ${out.name}`);
+      }
+      if (pick === "4") { await avatars.avatarConnect(base, io); return step("presenter", "ran", "presenter: your Minimoji"); }
+      if (pick === "5") return step("presenter", "skipped", "presenter: captions only; add a narrator later with `hyperdecks narrator new`");
+    } catch (e) {
+      log(`That did not finish: ${ops.errorText(e)}`);
+    }
+  }
+}
+
 async function deckOwnedBy(base, slug, who) {
   const deck = await (await client(base)).query(api.decks.get, { slug });
   return deck ? { exists: true, mine: deck.ownerId === who.subject } : { exists: false, mine: false };

package/src/narrator.mjs

@@ -0,0 +1,29 @@
+// hyperdecks narrator [list] | new | default <id> | remove <id> | voice <id> <voice>
+//
+// Who narrates your decks: a face plus a voice (convex/narrators.ts). Only a
+// person adds one: `narrator new` hands back a link where they pick the face
+// and the voice; in a terminal it waits for them, with --json (or an agent) it
+// returns the link and never chooses.
+import * as ops from "./ops.mjs";
+
+const interactiveOf = (opts) => !opts.json && !!process.stdin.isTTY && !!process.stdout.isTTY;
+
+export async function narratorList(opts, { log = console.log } = {}) {
+  const out = await ops.listNarrators(opts);
+  if (opts.json) return out;
+  for (const n of out.narrators) log(`${n.isDefault ? "*" : " "} ${n.name}\t${n.face ?? "(no face)"} · ${n.voice ? `${n.voice}${n.voiceReady ? "" : " (not ready)"}` : "(voice removed)"}\t${n.id}`);
+  if (out.note) log(`\n${out.note}`);
+  log("\n* the default; decks use it unless they set their own (deck narrator <slug> <id>)");
+  return out;
+}
+
+export async function narratorNew(opts, { log = console.log, interactive = interactiveOf(opts) } = {}) {
+  const link = await ops.newNarratorLink(opts);
+  if (opts.json) return link;
+  log(`Pick your narrator's face and voice here (only you can choose them):\n  ${link.url}`);
+  if (!interactive) return link;
+  log("Waiting for you…");
+  const narrator = await ops.waitForNarrator(opts, link.token);
+  log(`✓ Added ${narrator.name}. \`hyperdecks narrator\` shows which one is the default.`);
+  return { status: "added", ...narrator };
+}

package/src/ops.mjs

@@ -395,6 +395,14 @@ export async function listShares(opts, slug) {
     recipientEmail: r.recipientEmail ?? null,
     expiresAt: r.expiresAt ?? null,
     viewLimit: r.viewLimit ?? null,
+    // Forwarding: allowForward is the effective setting (link override, else
+    // the deck's, else on); a forwarded link carries its parent's token and the
+    // viewer who forwarded it. Rows come back with each link's forwards after it.
+    allowForward: !!r.allowForward,
+    allowForwardOverride: r.allowForwardOverride ?? null,
+    parentToken: r.parentToken ?? null,
+    forwardedBy: r.forwardedBy ?? null,
+    probablyForwarded: !!r.probablyForwarded,
   }));
 }
 
@@ -407,6 +415,7 @@ export async function createShare(opts, fields) {
   if (fields.email) args.recipientEmail = fields.email;
   if (fields.note) args.note = fields.note;
   if (fields.requireEmail) args.requireEmail = true;
+  if (fields.allowForward !== undefined) args.allowForward = !!fields.allowForward;
   if (fields.expires) {
     const t = Date.parse(fields.expires);
     if (Number.isNaN(t)) throw new Error(`expires must be an ISO date; got ${fields.expires}`);
@@ -433,8 +442,23 @@ export async function setShareNotify(opts, token, notify) {
 
 export async function removeShare(opts, token) {
   if (!token) throw new Error("token is required");
-  await (await client(opts)).mutation(api.shares.remove, { token });
-  return { token, removed: true };
+  const out = await (await client(opts)).mutation(api.shares.remove, { token });
+  return { token, removed: true, removedForwards: out?.removedForwards ?? 0 };
+}
+
+// Per-link forwarding override: true/false, or null to follow the deck default.
+export async function setShareForwarding(opts, token, allowForward) {
+  if (!token) throw new Error("token is required");
+  const value = allowForward === null || allowForward === undefined ? null : !!allowForward;
+  await (await client(opts)).mutation(api.shares.setAllowForward, { token, allowForward: value });
+  return { token, allowForward: value };
+}
+
+// The deck default for every link without its own override (on unless set off).
+export async function setDeckForwarding(opts, slug, allowForward) {
+  if (!slug) throw new Error("slug is required");
+  await (await client(opts)).mutation(api.decks.setAllowForward, { slug, allowForward: !!allowForward });
+  return { slug, allowForward: !!allowForward };
 }
 
 // Register a new deck (draft) you own. Refuses any slug that already exists:
@@ -830,3 +854,195 @@ export async function importDeckFromDesign(opts = {}, fields = {}, adapter = {})
   );
   return { ...result, fetched: files.size, missing };
 }
+
+// ---- avatars (convex/avatars.ts) --------------------------------------------
+// The face that presents decks narrated in your own voice. An agent never picks
+// or approves a face: every way that needs a choice hands back a link (and for
+// an import, a code) for the person; only an interactive terminal picks itself.
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// Your avatars, D.A.S.H. first, after following any edits or revokes made on
+// minimoji.com (best effort: a Minimoji blip still lists them).
+export async function listAvatars(opts = {}) {
+  const c = await client(opts);
+  await c.action(api.avatarsNode.refresh, {}).catch(() => {});
+  const out = await c.query(api.avatars.listAvatars, {});
+  if (!out.enabled) throw new Error("avatars are not switched on for this account yet");
+  return { default: out.defaultId, avatars: out.avatars.map(({ id, name, source, species, isDefault, linked }) => ({ id, name, source, species: species ?? null, isDefault, linked: !!linked })) };
+}
+
+export async function findAvatar(opts, ref) {
+  const want = String(ref ?? "").trim().toLowerCase();
+  if (!want) throw new Error("name an avatar (its id or name; `dash` for D.A.S.H.)");
+  const { avatars } = await listAvatars(opts);
+  const hit = avatars.find((a) => a.id === ref || a.name.toLowerCase() === want || (want === "dash" && a.source === "dash"));
+  if (!hit) throw new Error(`no avatar "${ref}" (yours: ${avatars.map((a) => a.name).join(", ")})`);
+  return hit;
+}
+
+export async function setDefaultAvatar(opts, ref) {
+  const a = await findAvatar(opts, ref);
+  await (await client(opts)).mutation(api.avatars.setDefault, { avatarId: a.id });
+  return { default: a.id, name: a.name };
+}
+
+export async function removeAvatar(opts, ref) {
+  const a = await findAvatar(opts, ref);
+  if (a.source === "dash") throw new Error("D.A.S.H. is built in and cannot be removed");
+  return { ...(await (await client(opts)).mutation(api.avatars.removeAvatar, { avatarId: a.id })), id: a.id };
+}
+
+// A deck's own presenter: an avatar, `none` (captions only) or `default`.
+export async function setDeckAvatar(opts, slug, ref) {
+  if (!slug) throw new Error("usage: deck avatar <slug> <avatar|none|default>");
+  const value = ref === "none" || ref === "default" ? ref : (await findAvatar(opts, ref)).id;
+  if (value === "dash") throw new Error("D.A.S.H. presents decks in its own voice; for an own-voice deck pick one of your avatars, none or default");
+  return (await client(opts)).mutation(api.avatars.setDeckAvatar, { slug, avatar: value });
+}
+
+// The link where the person picks one (optionally of one species).
+export async function newAvatarLink(opts, { species } = {}) {
+  const link = await (await client(opts)).mutation(api.avatars.createLink, { kind: "pick", ...(species ? { species: String(species) } : {}) });
+  return { status: "waiting", pickUrl: link.url, token: link.token, expiresAt: link.expiresAt };
+}
+
+export async function avatarOptions(opts, species, seed = 0) {
+  return (await client(opts)).action(api.avatarsNode.options, { species: String(species), seed });
+}
+
+export async function addPickedAvatar(opts, avatarKey) {
+  return (await client(opts)).mutation(api.avatars.addPicked, { avatarKey });
+}
+
+// A face from a photo. With bytes: upload and draw it, then hand back the link
+// where the person approves it (nothing is used before). Without: the link
+// where the person takes a selfie in their browser.
+export async function avatarFromPhoto(opts, { bytes, contentType } = {}, { onProgress } = {}) {
+  const c = await client(opts);
+  if (!bytes) {
+    const link = await c.mutation(api.avatars.createLink, { kind: "selfie" });
+    return { status: "waiting", selfieUrl: link.url, token: link.token, expiresAt: link.expiresAt };
+  }
+  if (!/^image\/(jpeg|png)$/.test(contentType ?? "")) throw new Error("the photo must be a .jpg or .png");
+  const storageId = await runtimeUploadBytes(c, bytes, contentType);
+  const { draftId } = await c.mutation(api.avatars.drawSelfie, { storageId });
+  onProgress?.("drawing…");
+  const draft = await pollUntil(() => c.query(api.avatars.getDraft, { draftId }), (d) => !d || d.status !== "drawing", { timeoutMs: 6 * 60_000 });
+  if (!draft) throw new Error("the drawing is gone; run the command again");
+  if (draft.status === "failed") throw new Error(draft.error || "the drawing failed; try another photo");
+  const link = await c.mutation(api.avatars.createLink, { kind: "review", draftId });
+  return { status: "waiting", reviewUrl: link.url, token: link.token, draftId, expiresAt: link.expiresAt };
+}
+
+// Import from Minimoji with a device code: the person opens `url`, enters
+// `code` and picks one there. The server watches for the answer.
+export async function connectAvatar(opts = {}) {
+  const out = await (await client(opts)).action(api.avatarsNode.startConnect, { makeDefault: true });
+  return { status: "waiting", url: out.url, code: out.userCode, expiresIn: out.expiresIn, connectId: out.connectId };
+}
+
+export async function waitForConnect(opts, connectId, { timeoutMs = 11 * 60_000 } = {}) {
+  const c = await client(opts);
+  return pollUntil(() => c.query(api.avatars.getConnect, { connectId }), (x) => x.status !== "waiting", { timeoutMs });
+}
+
+// Wait for the person to finish on a /presenter link; returns the avatar added.
+export async function waitForLink(opts, token, { timeoutMs = 60 * 60_000 } = {}) {
+  const c = await client(opts);
+  const link = await pollUntil(() => c.query(api.avatars.getLink, { token }), (l) => !!l.avatar || l.expired, { timeoutMs });
+  if (!link.avatar) throw new Error("the link expired before an avatar was added; run the command again");
+  return link.avatar;
+}
+
+export async function presenterFor(opts, slug, voice) {
+  return (await client(opts)).query(api.avatars.presenterFor, { slug, ...(voice ? { voice: String(voice) } : {}) });
+}
+
+// ---- narrators (convex/narrators.ts) ------------------------------------------
+// Who narrates your decks: a face plus a voice. D.A.S.H. is built in. As with
+// avatars, an agent never adds one: `narrator new` hands back a link.
+
+export async function listNarrators(opts = {}) {
+  const out = await (await client(opts)).query(api.narrators.list, {});
+  return {
+    default: out.defaultId,
+    ...(out.unpickedVoice ? { note: `no default narrator yet: decks narrate in your voice "${out.unpickedVoice}"` } : {}),
+    narrators: out.narrators.map((n) => ({ id: n.id, name: n.name, isDefault: n.isDefault, builtin: n.builtin, face: n.face?.name ?? null, voice: n.voice?.name ?? null, voiceReady: !!n.voice?.ready })),
+    voices: out.voices.map((x) => ({ id: x.ref, name: x.name, status: x.status, character: x.character, narrators: x.narrators })),
+  };
+}
+
+export async function findNarrator(opts, ref) {
+  const want = String(ref ?? "").trim().toLowerCase();
+  if (!want) throw new Error("name a narrator (its id or name; `dash` for D.A.S.H.)");
+  const { narrators } = await listNarrators(opts);
+  const byId = narrators.find((n) => n.id === ref || (want === "dash" && n.builtin));
+  if (byId) return byId;
+  // Names repeat ("Me" is the default): an ambiguous name never picks one.
+  const named = narrators.filter((n) => n.name.toLowerCase() === want);
+  if (named.length > 1) throw new Error(`"${ref}" matches ${named.length} narrators (ids: ${named.map((n) => n.id).join(", ")}); use the id`);
+  if (!named.length) throw new Error(`no narrator "${ref}" (yours: ${narrators.map((n) => `${n.name} ${n.id}`).join(", ")})`);
+  return named[0];
+}
+
+// The link where the person picks a face and a voice; it becomes their default.
+export async function newNarratorLink(opts = {}) {
+  const link = await (await client(opts)).mutation(api.narrators.newLink, {});
+  return { status: "waiting", url: link.url, token: link.token, expiresAt: link.expiresAt };
+}
+
+export async function waitForNarrator(opts, token, { timeoutMs = 60 * 60_000 } = {}) {
+  const c = await client(opts);
+  const link = await pollUntil(() => c.query(api.avatars.getLink, { token }), (l) => !!l.narrator || l.expired, { timeoutMs });
+  if (!link.narrator) throw new Error("the link expired before a narrator was added; run the command again");
+  return link.narrator;
+}
+
+export async function setDefaultNarrator(opts, ref) {
+  const n = await findNarrator(opts, ref);
+  await (await client(opts)).mutation(api.narrators.setDefault, { narrator: n.id });
+  return { default: n.id, name: n.name };
+}
+
+export async function removeNarrator(opts, ref) {
+  const n = await findNarrator(opts, ref);
+  if (n.builtin) throw new Error("D.A.S.H. is built in and cannot be removed");
+  return { ...(await (await client(opts)).mutation(api.narrators.remove, { narrator: n.id })), id: n.id };
+}
+
+// voice: one of your ready voices (name or id) or dash.
+export async function setNarratorVoice(opts, ref, voice) {
+  if (!voice) throw new Error("usage: narrator voice <narrator> <voice>");
+  const n = await findNarrator(opts, ref);
+  await (await client(opts)).mutation(api.narrators.setVoice, { narrator: n.id, voice: String(voice) });
+  return { narrator: n.id, name: n.name, voice: String(voice) };
+}
+
+// A deck's own narrator: a narrator, `none` (captions only) or `default`.
+export async function setDeckNarrator(opts, slug, ref) {
+  if (!slug || !ref) throw new Error("usage: deck narrator <slug> <narrator|none|default>");
+  const value = ref === "none" || ref === "default" ? ref : (await findNarrator(opts, ref)).id;
+  return (await client(opts)).mutation(api.narrators.setDeckNarrator, { slug, narrator: value });
+}
+
+// Polls `read` until `done`; a few failed reads in a row (a network blip) are
+// retried, since the person may still be finishing in the browser.
+async function pollUntil(read, done, { intervalMs = 2000, timeoutMs }) {
+  const start = Date.now();
+  let misses = 0;
+  for (;;) {
+    let value;
+    try {
+      value = await read();
+      misses = 0;
+    } catch (e) {
+      if (++misses >= 5) throw e;
+      await sleep(intervalMs);
+      continue;
+    }
+    if (done(value)) return value;
+    if (Date.now() - start > timeoutMs) throw new Error("timed out waiting; run the command again");
+    await sleep(intervalMs);
+  }
+}

package/src/presenter.mjs

@@ -0,0 +1,28 @@
+// The released deck's presenter (roadmap: avatars-pick-make-from-a-selfie-or-
+// import-your-minimoji). A deck narrated in the owner's own voice is written
+// captions-only (data-presenter="none"); at release, when the owner has an
+// avatar, its player tag gets that face instead. Shared by the hosted release
+// (convex/deckSources.ts) and the CLI's local release (release.mjs), so both
+// rewrite the tag the same way. A tag that already names a presenter (D.A.S.H.
+// on a character-voice deck, or one set by hand) is left alone.
+
+const PLAYER_TAG = /<script\b[^>]*\bsrc="[^"]*\/player\/v1\/player\.js"[^>]*>/i;
+
+const attr = (s) => String(s).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+
+// html with the player tag set to present `avatarUrl` (the /avatar/<token> doc
+// the player loads) and `imageUrl` (its still, for thumbnails and no-WebGL),
+// or html unchanged when there is no such tag or it already has a presenter.
+export function withAvatar(html, { avatarUrl, imageUrl }) {
+  const tag = PLAYER_TAG.exec(html)?.[0];
+  if (!tag || /\sdata-avatar=/.test(tag)) return html;
+  // Captions only: data-presenter="none", or no presenter at all (the player's
+  // default when there is no data-presenter-image either).
+  const none = /\sdata-presenter="none"/.test(tag);
+  const unset = !/\sdata-presenter=/.test(tag) && !/\sdata-presenter-image=/.test(tag);
+  if (!none && !unset) return html;
+  const image = imageUrl && !/\sdata-presenter-image=/.test(tag) ? ` data-presenter-image="${attr(imageUrl)}"` : "";
+  const face = ` data-presenter="head" data-avatar="${attr(avatarUrl)}"${image}`;
+  const next = none ? tag.replace(/\sdata-presenter="none"/, face) : tag.replace(/>$/, `${face}>`);
+  return html.replace(tag, () => next);
+}

package/src/release.mjs

@@ -15,6 +15,7 @@ import { readFileSync } from "node:fs";
 import { join, posix } from "node:path";
 import { zipSync } from "fflate";
 import * as ops from "./ops.mjs";
+import { withAvatar } from "./presenter.mjs";
 import { target } from "./runtime.mjs";
 import { checkDeck, localRefs, resolveDeckDir } from "./check.mjs";
 import { narrate as runNarrate } from "./narrate.mjs";
@@ -47,8 +48,11 @@ export function deckCommit(deckDir) {
 }
 
 // What import uploads: the page alone, or a zip of the page and its local files.
-export function releaseBundle(deckDir) {
-  const html = readFileSync(join(deckDir, "index.html"));
+// `presenter` (from avatars.presenterFor) puts the owner's avatar on the
+// uploaded page's player tag; the committed index.html is never changed.
+export function releaseBundle(deckDir, presenter = null) {
+  const raw = readFileSync(join(deckDir, "index.html"));
+  const html = presenter ? Buffer.from(withAvatar(raw.toString("utf8"), presenter)) : raw;
   // check has already refused refs that leave the folder or do not decode.
   const refs = [...new Set(localRefs(html.toString("utf8")).map((r) => posix.normalize(decodeURIComponent(r)).replace(/^(\.?\/)+/, "")))];
   if (!refs.length) return { bytes: html, filename: "index.html", files: ["index.html"] };
@@ -95,13 +99,22 @@ export async function release(pos, opts = {}, io = {}) {
     throw new Error(`narration changed the deck (${after.split("\n").length} file(s)):\n${after}\n` +
       `run \`hyperdecks check ${pos[0]}\`, look at it, commit (index.html and narration/), then run release again`);
   }
+  // Narrated in your own voice: the released page gets your avatar's face.
+  let presenter = null;
+  try {
+    presenter = await ops.presenterFor(opts, slug, opts.voice);
+  } catch (e) {
+    log(`⚠ could not look up your avatar (${ops.errorText(e)}); releasing captions only`);
+  }
+  const released = presenter ? releaseBundle(deckDir, presenter) : bundle;
+  if (presenter) log("✓ presented by your avatar");
   const imported = await ops.importDeckFromBytes(opts, {
     slug,
     title: opts.title,
     status: opts.status || "live",
-    bytes: bundle.bytes,
-    filename: bundle.filename,
-    htmlFile: bundle.htmlFile,
+    bytes: released.bytes,
+    filename: released.filename,
+    htmlFile: released.htmlFile,
   });
   const sha = commit(deckDir);
   log(`✓ imported "${imported.title}" as ${imported.slug} (${bundle.files.length} file(s), commit ${sha})\n  deck: ${imported.deckUrl}`);

package/src/runtime.mjs

@@ -8,7 +8,7 @@ import { fileURLToPath } from "node:url";
 import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 
-export const VERSION = "0.3.1";
+export const VERSION = "0.4.0";
 const UPLOAD_TIMEOUT_MS = 125_000;
 
 export const PROD = {
@@ -20,6 +20,32 @@ export const PROD = {
 
 export const api = {
   previews: { get: makeFunctionReference("previews:get") },
+  avatars: {
+    listAvatars: makeFunctionReference("avatars:listAvatars"),
+    setDefault: makeFunctionReference("avatars:setDefault"),
+    removeAvatar: makeFunctionReference("avatars:removeAvatar"),
+    setDeckAvatar: makeFunctionReference("avatars:setDeckAvatar"),
+    addPicked: makeFunctionReference("avatars:addPicked"),
+    drawSelfie: makeFunctionReference("avatars:drawSelfie"),
+    getDraft: makeFunctionReference("avatars:getDraft"),
+    getConnect: makeFunctionReference("avatars:getConnect"),
+    createLink: makeFunctionReference("avatars:createLink"),
+    getLink: makeFunctionReference("avatars:getLink"),
+    presenterFor: makeFunctionReference("avatars:presenterFor"),
+  },
+  narrators: {
+    list: makeFunctionReference("narrators:list"),
+    setDefault: makeFunctionReference("narrators:setDefault"),
+    remove: makeFunctionReference("narrators:remove"),
+    setVoice: makeFunctionReference("narrators:setVoice"),
+    setDeckNarrator: makeFunctionReference("narrators:setDeckNarrator"),
+    newLink: makeFunctionReference("narrators:newLink"),
+  },
+  avatarsNode: {
+    options: makeFunctionReference("avatarsNode:options"),
+    startConnect: makeFunctionReference("avatarsNode:startConnect"),
+    refresh: makeFunctionReference("avatarsNode:refresh"),
+  },
   assets: {
     generateUploadUrl: makeFunctionReference("assets:generateUploadUrl"),
     saveAsset: makeFunctionReference("assets:saveAsset"),
@@ -48,6 +74,7 @@ export const api = {
     get: makeFunctionReference("decks:get"),
     listForViewer: makeFunctionReference("decks:listForViewer"),
     remove: makeFunctionReference("decks:remove"),
+    setAllowForward: makeFunctionReference("decks:setAllowForward"),
     setHtmlStorage: makeFunctionReference("decks:setHtmlStorage"),
     upsert: makeFunctionReference("decks:upsert"),
     whoami: makeFunctionReference("decks:whoami"),
@@ -57,6 +84,7 @@ export const api = {
     deckAnalytics: makeFunctionReference("shares:deckAnalytics"),
     listForDeck: makeFunctionReference("shares:listForDeck"),
     remove: makeFunctionReference("shares:remove"),
+    setAllowForward: makeFunctionReference("shares:setAllowForward"),
     setEnabled: makeFunctionReference("shares:setEnabled"),
     setNotify: makeFunctionReference("shares:setNotify"),
   },
@@ -102,7 +130,7 @@ export const api = {
   },
 };
 
-const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open"]);
+const BOOL = new Set(["prod", "dev", "admin", "json", "require-email", "qa", "no-notify", "allow-forward", "no-forward", "help", "version", "all-agents", "global", "project", "transparent", "upload", "dry-run", "narrated", "layout", "full-page", "force", "hosted", "yes", "no-voice", "no-skill", "no-release", "no-open", "save-to-minimoji"]);
 // release's recipients, in order: each --to starts one, and an --email right
 // after it belongs to it (`--to A --email a --to B`). Collected as opts.recipients;
 // opts.email stays the last --email for the other commands (share new).

package/src/species.mjs

@@ -0,0 +1,15 @@
+// The avatar picker's species (roadmap: avatars-pick-make-from-a-selfie-or-
+// import-your-minimoji), shared by the backend (convex/lib/avatars/species.ts),
+// the CLI (avatar.mjs) and the web picker. `family` is Minimoji's character
+// family in GET /capabilities; humans have none (we deal their documents).
+export const SPECIES = [
+  { id: "human", label: "Human", family: null },
+  { id: "robot", label: "Robot", family: "dash" },
+  { id: "alien", label: "Alien", family: "alien" },
+  { id: "cat", label: "Cat", family: "cat" },
+  { id: "dog", label: "Dog", family: "dog" },
+  { id: "rabbit", label: "Rabbit", family: "rabbit" },
+  { id: "monkey", label: "Monkey", family: "monkey" },
+  { id: "penguin", label: "Penguin", family: "bird" },
+  { id: "ghost", label: "Ghost", family: "ghost" },
+];