parley-live 0.5.0 → 0.6.0

package/README.md

@@ -18,7 +18,9 @@ parley ugc-ad --product product.jpg --name "Cold Brew Kit" --actor jordan --mark
 |---|---|
 | `parley doctor [--require <version>]` | Node, server, session, credits, live engines, the `@last` outputs, whether a newer release exists, and the fix for anything missing. `--require` fails "ready" when this CLI is older than what your skills expect. Run it first; `--json` for agents. |
 | `parley voice "<text>" \| --file script.txt` | Narration as a hosted WAV. `--voice warm\|energetic\|documentary\|deep\|bright\|storyteller`, `--quality natural\|fish\|studio`, `--no-fallback`, `--out`. Natural voice: 1 credit per 1,000 characters; studio: 1 per 300. Becomes `@last` for `--narration`. `parley voices` lists personas and prices. |
-| `parley studio …` | The film pipeline without JSON: `character add\|cast\|list`, `location add\|cast\|list`, `shot add\|list`, `render <shotId> [--wait]`, `assemble`, `reels`. Every subcommand takes `--project proj_…`. |
+| `parley library …` | Everything this account has generated, newest first: `list [--kind image|video|audio] [--lane <lane>] [--favorite] [--limit] [--cursor]`, `summary`, `show <mediaId>`, `fav <mediaId> [--off]`, `rm <mediaId>`, `get <mediaId> [--out file]`. Every row carries the prompt, the model, what it cost and a public URL, so an asset that was already paid for goes straight into `--image`, `--ref` or `--beat`. Free. |
+| `parley character …` | Named people who outlive one film: `list`, `add --name X --description "…" [--ref <file|url|@last>]`, `show <id>`, `refs <id> --ref …`, `cast <id> [--count 3] [--dry-run]`, `use <id> --project proj_…`, `save <studioCharacterId>`, `rm <id>`. Casting reference images costs 3 credits each (`--dry-run` quotes it and spends nothing); attaching your own and casting a saved character into a Studio project are free. |
+| `parley studio …` | The film pipeline without JSON: `character add\|cast\|list`, `location add\|cast\|list`, `shot add\|list\|update\|reorder\|rm`, `render <shotId> [--wait]`, `assemble`, `reels`. Editing a written shot and reordering the timeline are free. Every subcommand takes `--project proj_…`. |
 | `parley deploy <dir> --name <slug>` | Ship a built static site (index.html at the root) to a live URL. Reuse `--project proj_…` to redeploy the same site at the same URL. Free. |
 | `parley lens <status|connect|build|describe|record|metrics>` | A Snap Specs Lens from a work procedure, built and tested on this computer through Lens Studio: a hands-free step-by-step guide with pinch buttons and optional voice shortcuts. `status` says exactly what to set up; `build <form.json>` is free; `describe "..."` plans the steps from prose (about a cent, billed to your credits). Every build is checked in the Lens Studio preview; what only glasses can judge is marked, never passed. |
 | `parley login [--no-browser]` | Device-code sign-in. Prints a link, you sign in once in the browser, the CLI receives a session token. `--no-browser` prints the link instead of opening it (cloud sandboxes, SSH). |
@@ -58,6 +60,14 @@ parley voice --file script.txt --voice documentary --out narration.wav
 parley youtube --beat https://…/01.png --beat https://…/02.png --narration @last --captions
 ```
 
+A later session picks the work back up from the account instead of paying for it twice:
+
+```bash
+parley library list --kind image --limit 10 --json     # what this account already has, with what it cost
+parley video "steam rises" --image https://media.parley.live/generated-media/…png   # a url from that list
+parley library get media_… --out hero.png              # pull one down; it becomes @last
+```
+
 ### A film from the terminal
 
 ```bash
@@ -67,7 +77,11 @@ parley studio shot add --project proj_letter-7f3k --order 0 --framing "Maya at a
   --directing "She unfolds the letter and reads. Clip ends with her eyes on the page." \
   --characters char_… --duration 12 --camera "arri-alexa-35, dolly-in"
 parley studio render shot_… --wait
+parley studio shot update shot_… --duration 14 --camera "arri-alexa-35, push-in"   # free, then re-render that shot
+parley studio shot reorder --project proj_letter-7f3k --shots shot_c,shot_a,shot_b   # free, no render
 parley studio assemble --project proj_letter-7f3k --title "The Letter" --synopsis "A woman reads the letter she avoided."
+parley character save char_…                            # keep Maya for the next film
+parley character use uchar_… --project proj_sequel-2b9k # cast her again, free, same face
 ```
 
 ## For agents

package/dist/index.js

@@ -11,6 +11,8 @@
  *   parley video "<prompt>" [...]        generate a clip / animate a still
  *   parley thumbnail "<title>" [...]     YouTube thumbnail variants
  *   parley ugc-ad --product <img> ...    spokesperson product ad
+ *   parley library list                  everything you have made, and what it cost
+ *   parley character list                named people who outlive one film
  *
  * Run `parley help <command>` for the flags of one command.
  */
@@ -18,7 +20,7 @@ import { readFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node
 import path from 'node:path';
 import { api, authWebUrl, backendUrl, clearCredentials, CliError, downloadTo, fileToDataUri, isUrl, loadCredentials, loadLast, openInBrowser, rememberLast, resolveRef, saveCredentials, sleep, } from './client.js';
 import { cmdLens, LensError } from './lens.js';
-const VERSION = '0.5.0';
+const VERSION = '0.6.0';
 /** Server advice written for Parley's in-app agent names its tools; a CLI user
  *  has commands instead, so the same advice is re-spoken in CLI terms. */
 function humanizeServerMessage(message) {
@@ -567,6 +569,205 @@ async function cmdVoices() {
  *   studio assemble --project P --title T [--synopsis S] [--title-text X] [--music path] [--narration url]
  *   studio reels --project P
  */
+// ── library (the account's media and named characters) ───────────────
+// Everything the lanes produce is recorded account-side, so a second
+// session can find the clip that was already paid for instead of
+// rendering it again. Library characters are the cast that outlives one
+// film: casting one into a project copies the approved sheet for free.
+const LIBRARY_KINDS = ['image', 'video', 'audio'];
+const CHARACTER_REF_CREDITS = 3;
+const CHARACTER_MAX_CAST = 6;
+function mediaLine(m) {
+    const size = m.width && m.height ? `${m.width}x${m.height}` : '';
+    const dur = m.duration_seconds ? `${Math.round(m.duration_seconds)}s` : '';
+    const cost = typeof m.credits_charged === 'number' && m.credits_charged > 0 ? `${m.credits_charged}cr` : '';
+    const when = m.created_at ? new Date(m.created_at * 1000).toISOString().slice(0, 10) : '';
+    return [m.id, String(m.kind).padEnd(5), String(m.lane || '').padEnd(10), when, size || dur, cost, m.favorite ? '*' : '', m.url]
+        .filter((x) => x !== '' && x !== undefined)
+        .join('  ');
+}
+async function cmdLibrary(p) {
+    const action = p.positionals[0] || 'list';
+    const target = p.positionals[1];
+    const out = (obj, human) => { if (JSON_MODE)
+        console.log(JSON.stringify(obj));
+    else
+        console.log(human()); };
+    const needId = (usage) => {
+        if (!target)
+            throw new CliError(usage);
+        return target;
+    };
+    if (action === 'summary') {
+        const s = await api('/api/library/media/summary');
+        return out({ ok: true, ...s }, () => `images ${s.images}  videos ${s.videos}  audio ${s.audio}`);
+    }
+    if (action === 'list') {
+        const kind = str(p.flags.kind);
+        if (kind && !LIBRARY_KINDS.includes(kind))
+            throw new CliError(`--kind must be one of ${LIBRARY_KINDS.join(', ')}.`);
+        const q = new URLSearchParams();
+        if (kind)
+            q.set('kind', kind);
+        if (p.flags.favorite === true || p.flags.favorite === 'true')
+            q.set('favorite', '1');
+        const lane = str(p.flags.lane);
+        if (lane)
+            q.set('lane', lane);
+        const cursor = str(p.flags.cursor);
+        if (cursor)
+            q.set('cursor', cursor);
+        q.set('limit', String(Math.min(Math.max(num(p.flags.limit, 20), 1), 100)));
+        const r = await api(`/api/library/media?${q.toString()}`);
+        return out({ ok: true, ...r }, () => (r.items.length
+            ? r.items.map(mediaLine).join('\n') + (r.nextCursor ? `\n(more: --cursor ${r.nextCursor})` : '')
+            : '(nothing in the library yet)'));
+    }
+    if (action === 'show') {
+        const id = needId('Usage: parley library show <mediaId>');
+        const m = await api(`/api/library/media/${encodeURIComponent(id)}`);
+        return out({ ok: true, media: m }, () => [
+            `${m.id}  ${m.kind}  ${m.lane}`,
+            `url       ${m.url}`,
+            m.model ? `model     ${m.model}` : '',
+            typeof m.credits_charged === 'number' ? `charged   ${m.credits_charged} credits` : '',
+            m.project_id ? `project   ${m.project_id}` : '',
+            m.prompt ? `prompt    ${m.prompt}` : '',
+        ].filter(Boolean).join('\n'));
+    }
+    if (action === 'fav' || action === 'favorite') {
+        const id = needId('Usage: parley library fav <mediaId> [--off]');
+        const favorite = p.flags.off !== true;
+        const m = await api(`/api/library/media/${encodeURIComponent(id)}`, { method: 'PATCH', body: { favorite } });
+        return out({ ok: true, media: m }, () => `${m.id} ${favorite ? 'marked a favourite' : 'no longer a favourite'}`);
+    }
+    if (action === 'rm' || action === 'delete') {
+        const id = needId('Usage: parley library rm <mediaId>');
+        await api(`/api/library/media/${encodeURIComponent(id)}`, { method: 'DELETE' });
+        return out({ ok: true, removed: id }, () => `${id} hidden from the library (the file itself stays reachable from the chat it came from).`);
+    }
+    if (action === 'get' || action === 'download') {
+        const id = needId('Usage: parley library get <mediaId> [--out file]');
+        const m = await api(`/api/library/media/${encodeURIComponent(id)}`);
+        const ext = m.kind === 'video' ? 'mp4' : m.kind === 'audio' ? 'wav' : 'png';
+        const outPath = str(p.flags.out) || `${id}.${ext}`;
+        const bytes = await downloadTo(m.url, outPath);
+        rememberLast(m.kind === 'video' ? 'video' : m.kind === 'audio' ? 'audio' : 'image', { file: outPath, url: m.url });
+        return out({ ok: true, file: path.resolve(outPath), url: m.url, bytes }, () => `Saved ${outPath} (${(bytes / 1024).toFixed(0)} KB) - it is @last now.`);
+    }
+    throw new CliError('Usage: parley library <list|summary|show|fav|rm|get> … (see `parley help library`)');
+}
+async function cmdCharacter(p) {
+    const action = p.positionals[0] || 'list';
+    const target = p.positionals[1];
+    const out = (obj, human) => { if (JSON_MODE)
+        console.log(JSON.stringify(obj));
+    else
+        console.log(human()); };
+    const needId = (usage) => {
+        if (!target)
+            throw new CliError(usage);
+        return target;
+    };
+    // --ref accepts a local file (uploaded as a data URI), an https URL, or @last.
+    const refs = () => list(p.flags.ref).map((r) => {
+        const resolved = resolveRef(r, 'image');
+        return isUrl(resolved) ? resolved : fileToDataUri(resolved);
+    });
+    if (action === 'list') {
+        const r = await api('/api/library/characters');
+        const items = r.characters || [];
+        return out({ ok: true, characters: items }, () => (items.length
+            ? items.map((c) => `${c.id}  ${String(c.name).padEnd(16)} refs=${(c.reference_image_paths || []).length}${c.voice_id ? `  voice=${c.voice_id}` : ''}${c.source_character_id ? '  (saved from a film)' : ''}`).join('\n')
+            : '(no named characters yet)'));
+    }
+    if (action === 'add') {
+        const name = str(p.flags.name);
+        if (!name)
+            throw new CliError('parley character add needs --name (and --description: the identity lock — age, build, face shape, hair, skin, wardrobe).');
+        const body = { name };
+        const description = str(p.flags.description);
+        if (description)
+            body.description = description;
+        const wardrobe = str(p.flags.wardrobe);
+        if (wardrobe)
+            body.wardrobe = wardrobe;
+        const tags = list(p.flags.tags);
+        if (tags.length)
+            body.personalityTags = tags;
+        const voice = str(p.flags.voice);
+        if (voice)
+            body.voiceId = voice;
+        const images = refs();
+        if (images.length)
+            body.referenceImages = images;
+        const c = await api('/api/library/characters', { body });
+        return out({ ok: true, character: c }, () => `Character ${c.name} saved to your library: ${c.id}\n${(c.reference_image_paths || []).length ? 'Reference images attached.' : `Next: parley character cast ${c.id} --count 3  (${3 * CHARACTER_REF_CREDITS} credits)`}`);
+    }
+    if (action === 'show') {
+        const id = needId('Usage: parley character show <characterId>');
+        const c = await api(`/api/library/characters/${encodeURIComponent(id)}`);
+        return out({ ok: true, character: c }, () => [
+            `${c.id}  ${c.name}`,
+            c.description ? `description  ${c.description}` : '',
+            c.wardrobe ? `wardrobe     ${c.wardrobe}` : '',
+            (c.personality_tags || []).length ? `tags         ${c.personality_tags.join(', ')}` : '',
+            c.voice_id ? `voice        ${c.voice_id}` : '',
+            `references   ${(c.reference_image_urls || []).join(' ') || '(none yet)'}`,
+        ].filter(Boolean).join('\n'));
+    }
+    if (action === 'refs') {
+        const id = needId('Usage: parley character refs <characterId> --ref <file|url|@last>…');
+        const images = refs();
+        if (!images.length)
+            throw new CliError('parley character refs needs at least one --ref <file|url|@last>.');
+        const c = await api(`/api/library/characters/${encodeURIComponent(id)}/references`, { body: { images } });
+        return out({ ok: true, character: c }, () => `${c.name} now has ${(c.reference_image_paths || []).length} reference images (free - nothing was generated).`);
+    }
+    if (action === 'cast') {
+        const id = needId('Usage: parley character cast <characterId> [--count 3] [--direction "…"]');
+        const count = Math.min(Math.max(num(p.flags.count, 3), 1), CHARACTER_MAX_CAST);
+        const body = { count };
+        const direction = str(p.flags.direction);
+        if (direction)
+            body.additionalDirection = direction;
+        const model = str(p.flags.model);
+        if (model)
+            body.model = model;
+        // --dry-run quotes the price and spends nothing: --json silences the note(),
+        // so an agent that must state the cost first has a way to read it.
+        if (p.flags['dry-run'] === true || p.flags.quote === true) {
+            const credits = count * CHARACTER_REF_CREDITS;
+            return out({ ok: true, dryRun: true, count, creditsPerReference: CHARACTER_REF_CREDITS, credits }, () => `${count} reference image${count === 1 ? '' : 's'} would cost ${credits} credits (${CHARACTER_REF_CREDITS} each). Nothing was charged.`);
+        }
+        note(`Casting ${count} reference image${count === 1 ? '' : 's'} (${count * CHARACTER_REF_CREDITS} credits)…`);
+        const r = await api(`/api/library/characters/${encodeURIComponent(id)}/cast`, { body });
+        const urls = r.character?.reference_image_urls || [];
+        const made = (r.generatedPaths || []).length;
+        return out({ ok: true, ...r }, () => `${r.character?.name || id}: ${made} new reference${made === 1 ? '' : 's'}, ${r.credits_charged ?? 0} credits charged.\nShow the user ${urls[urls.length - 1] || '(see JSON)'} and get their yes before writing shots.`);
+    }
+    if (action === 'use') {
+        const id = needId('Usage: parley character use <characterId> --project proj_…');
+        const project = str(p.flags.project);
+        if (!project || !/^proj_[A-Za-z0-9_-]{6,}$/.test(project))
+            throw new CliError('parley character use needs --project proj_… (proj_ plus at least six letters, digits, _ or -).');
+        const r = await api(`/api/library/characters/${encodeURIComponent(id)}/use-in-project/${encodeURIComponent(project)}`, { method: 'POST', body: {} });
+        const pc = r.character || r;
+        return out({ ok: true, ...r }, () => `Cast into ${project} as ${pc.id} with the approved sheet (free - no re-cast, so the face does not drift).\nUse ${pc.id} in --characters on that project's shots.`);
+    }
+    if (action === 'save') {
+        const id = needId('Usage: parley character save <studioCharacterId>   (keeps a film character for later films)');
+        const r = await api(`/api/library/characters/from-studio/${encodeURIComponent(id)}`, { method: 'POST', body: {} });
+        const c = r.character || r;
+        return out({ ok: true, ...r }, () => `${c.name} ${r.existed ? 'was already in' : 'saved to'} your library as ${c.id}.`);
+    }
+    if (action === 'rm' || action === 'delete') {
+        const id = needId('Usage: parley character rm <characterId>');
+        await api(`/api/library/characters/${encodeURIComponent(id)}`, { method: 'DELETE' });
+        return out({ ok: true, removed: id }, () => `${id} removed from your library (films that already cast them are untouched).`);
+    }
+    throw new CliError('Usage: parley character <list|add|show|refs|cast|use|save|rm> … (see `parley help character`)');
+}
 async function cmdStudio(p) {
     const [group, action, target] = p.positionals;
     const project = str(p.flags.project);
@@ -743,7 +944,46 @@ async function cmdStudio(p) {
         const items = r.reels || (Array.isArray(r) ? r : []);
         return out({ ok: true, reels: items }, () => items.map((x) => `${x.id}  ${x.public_url || x.video_path}`).join('\n') || '(no reels yet)');
     }
-    throw new CliError('Usage: parley studio <character add|cast|list | location add|cast|list | shot add|list | render <shotId> | assemble | reels> … (see `parley help studio`)');
+    // Timeline: edit a written shot instead of deleting and re-adding it, and
+    // set the playback order. Both are free; the server refuses an edit while
+    // that shot is rendering so an in-flight render never reads a half-edited row.
+    if (group === 'shot' && (action === 'update' || action === 'edit')) {
+        if (!target)
+            throw new CliError('Usage: parley studio shot update <shotId> [--framing "…"] [--directing "…"] [--duration 12] [--camera "lens look, move"]');
+        const body = {};
+        const framing = str(p.flags.framing);
+        if (framing)
+            body.framingPrompt = framing;
+        const directing = str(p.flags.directing);
+        if (directing)
+            body.directingPrompt = directing;
+        const duration = str(p.flags.duration);
+        if (duration)
+            body.durationSeconds = Number(duration);
+        const camera = str(p.flags.camera);
+        if (camera !== undefined)
+            body.cameraEmulation = camera === 'none' ? null : camera;
+        if (Object.keys(body).length === 0)
+            throw new CliError('Nothing to change: pass --framing, --directing, --duration or --camera (--camera none clears it).');
+        const s = await api(`/api/studio/shots/${target}`, { method: 'PATCH', body });
+        return out({ ok: true, shot: s }, () => `Shot #${(s.order_index ?? 0) + 1} updated (${Object.keys(body).join(', ')}). Re-render it to see the change: parley studio render ${s.id} --wait`);
+    }
+    if (group === 'shot' && (action === 'reorder' || action === 'order')) {
+        const P = needProject();
+        const shotIds = list(p.flags.shots);
+        if (shotIds.length === 0)
+            throw new CliError('Usage: parley studio shot reorder --project proj_… --shots <shotId,shotId,…>   (the new playback order, every shot listed)');
+        const r = await api(`/api/studio/projects/${P}/shots/reorder`, { body: { shotIds } });
+        const items = r.shots || [];
+        return out({ ok: true, shots: items }, () => items.map((s) => `#${(s.order_index ?? 0) + 1}  ${s.id}`).join('\n') || 'Reordered.');
+    }
+    if (group === 'shot' && (action === 'rm' || action === 'delete')) {
+        if (!target)
+            throw new CliError('Usage: parley studio shot rm <shotId>');
+        const r = await api(`/api/studio/shots/${target}`, { method: 'DELETE' });
+        return out({ ok: true, ...r }, () => `${target} removed from the shot list (a clip already rendered for it stays in your library).`);
+    }
+    throw new CliError('Usage: parley studio <character add|cast|list | location add|cast|list | shot add|list|update|reorder|rm | render <shotId> | assemble | reels> … (see `parley help studio`)');
 }
 const DEPLOY_MAX_FILES = 600;
 const DEPLOY_MAX_TOTAL_BYTES = 40 * 1024 * 1024;
@@ -993,7 +1233,9 @@ function help(topic) {
         doctor: 'parley doctor [--require <version>] [--json]\n  Node, server, session, credits, live engines, the @last outputs and whether a newer release exists, with the fix for anything missing. --require fails "ready" when this CLI is older than what your skills expect. Run this first.',
         voice: `parley voice "<text>" | --file script.txt [--voice ${VOICES.join('|')}] [--quality ${VOICE_TIERS.join('|')}] [--split] [--no-fallback] [--out narration.wav]\n  Narration as a hosted WAV (natural voice 1 credit per 1,000 characters; studio 1 per 300). Text over 5,000 characters is split at paragraph and sentence breaks and joined back into one narration. Becomes @last for --narration.`,
         voices: 'parley voices\n  The narration personas, the tiers and their prices.',
-        studio: 'parley studio character add|cast|list · location add|cast|list · shot add|list · render <shotId> [--wait] · assemble · reels\n  The film pipeline without JSON: cast characters and locations (identity locks), write shots ("lens look, move" camera), render, assemble a reel. Every subcommand takes --project proj_… and --json.',
+        studio: 'parley studio character add|cast|list · location add|cast|list · shot add|list|update|reorder|rm · render <shotId> [--wait] · assemble · reels\n  The film pipeline without JSON: cast characters and locations (identity locks), write shots ("lens look, move" camera), edit and reorder the timeline for free, render, assemble a reel. Every subcommand takes --project proj_… and --json.',
+        library: 'parley library list [--kind image|video|audio] [--lane <lane>] [--favorite] [--limit 20] [--cursor …] · summary · show <mediaId> · fav <mediaId> [--off] · rm <mediaId> · get <mediaId> [--out file]\n  Everything you have generated, newest first, with what each one cost. Look here before paying to make something again: a library url goes straight into --image, --ref or --beat.',
+        character: 'parley character list · add --name X --description "…" [--ref <file|url|@last>]… · show <id> · refs <id> --ref … · cast <id> [--count 3] [--dry-run] · use <id> --project proj_… · save <studioCharacterId> · rm <id>\n  Named people who outlive one film. Casting reference images costs 3 credits each; refs attaches your own for free; use copies the approved sheet into a Studio project for free, so the same face comes back without a re-cast.',
         login: 'parley login [--no-browser] [--backend URL]\n  Sign in once in your browser. --no-browser prints the link instead of opening it (cloud sandboxes, SSH). Stores a session token under ~/.parley (or $PARLEY_HOME).',
         image: `parley image "<prompt>" [--ratio ${Object.keys(RATIO_TO_SIZE).join('|')}] [--model gpt-image-2|gemini-3-pro-image-preview] [--quality low|medium|high] [--image-size 1K|2K|4K] [--ref <file|url|@last>]... [--out file]\n  Generate an image. --ratio sizes it for the destination; --ref passes reference images (identity / style locks).`,
         video: `parley video "<motion prompt>" --image <file|url|@last> [--look ${LOOKS.join('|')}] [--move <slug>]... [--duration 5] [--ratio 16:9|9:16|1:1] [--out clip.mp4]\n  Animate a still (@last = the image you just made) or --look photoreal for text-to-video. --move adds named camera moves; see \`parley camera-moves\`.`,
@@ -1005,7 +1247,7 @@ function help(topic) {
         engines: 'parley engines\n  Which video engines this server can run right now and their credit rates.',
         'camera-moves': 'parley camera-moves\n  The named camera-move presets accepted by `parley video --move`.',
         account: 'parley account\n  Your credit balance.',
-        lens: 'parley lens <status|connect|build|describe|record|metrics>\n  Build a Snap Specs Lens on this computer through Lens Studio: a step-by-step training guide with pinch buttons and optional voice shortcuts, tested in the preview before you see it. "describe" turns plain language into steps (about a cent, billed to your credits); "build <form.json>" is free. Run `parley lens status` first: it tells you exactly what to set up.',
+        lens: 'parley lens <status|connect|build|describe|publish|record|metrics>\n  Build a Snap Specs Lens on this computer through Lens Studio: a step-by-step training guide with pinch buttons and optional voice shortcuts, tested in the preview before you see it. "describe" turns plain language into steps (about a cent, billed to your credits); "build <form.json>" is free. Run `parley lens status` first: it tells you exactly what to set up. `publish` runs Snap\u0027s own preflight and SnapOS Package export (needs Lens Studio signed in).',
     };
     if (topic && lines[topic]) {
         console.log(lines[topic]);
@@ -1039,6 +1281,14 @@ async function main(argv) {
             case 'studio':
                 await cmdStudio(p);
                 break;
+            case 'library':
+            case 'lib':
+                await cmdLibrary(p);
+                break;
+            case 'character':
+            case 'characters':
+                await cmdCharacter(p);
+                break;
             case 'logout':
                 await cmdLogout();
                 break;

package/dist/lens.js

@@ -7,6 +7,7 @@
  *   parley lens connect --config '<json>'   Save the config Lens Studio copies (AI Assistant > MCP > Configure Server)
  *   parley lens build <form.json>           Form -> tested Lens ($0, no model call)
  *   parley lens describe "<procedure>"      Plain language -> steps (billed, about a cent) -> tested Lens
+ *   parley lens publish [<lens id>]        Snap's preflight, then Snap's SnapOS Package export
  *   parley lens record <run> [--on-glasses passed|issues] [--published submitted|published]
  *   parley lens metrics
  */
@@ -198,6 +199,35 @@ export async function cmdLens(positionals, flags, jsonMode) {
             throw new LensError('The build did not pass. Read the report.', 6);
         return;
     }
+    if (sub === 'publish') {
+        const target = positionals[1];
+        const events = await runPipeline('publish', { target }, (e) => { if (!jsonMode && e.type === 'log')
+            console.log('  ' + e.message); });
+        const r = events[events.length - 1];
+        if (r.type === 'error')
+            throw new LensError(r.error, 1);
+        out(r, () => {
+            console.log('');
+            console.log(`Lens name for Snap: ${r.lensName ?? '(unknown)'}`);
+            console.log(`Name, icon and signing key on the project: ${r.readyLocally ? 'all set' : 'incomplete'}`);
+            if (r.issues?.length)
+                for (const i of r.issues)
+                    console.log('  - ' + i);
+            if (r.ok) {
+                console.log(`\nSnapOS Package exported: ${r.spkPath}`);
+                if (r.bytes)
+                    console.log(`${r.bytes} bytes${r.checksum ? ', checksum ' + r.checksum : ''}`);
+            }
+            else if (r.stage === 'blocked_on_sign_in') {
+                console.log('\nNot packaged: Lens Studio is not signed in.');
+            }
+            for (const n of r.next ?? [])
+                console.log('\n' + n);
+        });
+        if (!r.ok)
+            throw new LensError(r.stage === 'blocked_on_sign_in' ? 'Sign in to Lens Studio, then run this again.' : 'The Lens was not packaged.', r.stage === 'blocked_on_sign_in' ? 2 : 6);
+        return;
+    }
     if (sub === 'record') {
         const run = positionals[1];
         const hw = str(flags['on-glasses']);
@@ -218,5 +248,5 @@ export async function cmdLens(positionals, flags, jsonMode) {
             console.log('No Lenses built on this computer yet.'); });
         return;
     }
-    throw new LensError(`Unknown: parley lens ${sub}. Use status | connect | build | describe | record | metrics.`, 64);
+    throw new LensError(`Unknown: parley lens ${sub}. Use status | connect | build | describe | publish | record | metrics.`, 64);
 }

package/lens-builder/build.mjs

@@ -6,6 +6,8 @@ import path from 'node:path';
 import { Bridge, ROOT, DATA } from './lib/bridge.mjs';
 import { compile } from './training/compile.mjs';
 import { verify } from './verify.mjs';
+import { prepareSubmission } from './lib/submission.mjs';
+import { tidyProjectFolder } from './lib/handoff.mjs';
 
 const MAX_ITERATIONS = 5;
 const here = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1'));
@@ -33,10 +35,16 @@ export async function build(form, { log = console.log, planner = null } = {}) {
     result.stage = 'implement';
     const bridge = new Bridge({ logPath: path.join(runDir, 'calls.jsonl') });
     await bridge.connect();
-    const project = await bridge.newProject(lens_id);
+    const project = await bridge.newProject(lens_id, { folderName: form.procedureName });
+    // Where the Lens lives, for the handoff card in chat.
+    result.project = { dir: project.dir, file: project.file };
+    result.title = plan.title;
+    result.scriptPath = scriptPath;
     log(`project: ${project.esproj}`);
+
     await bridge.specsPreview();
 
+    let submission = null;
     let report = null;
     for (let iteration = 1; iteration <= MAX_ITERATIONS; iteration++) {
       result.iterations = iteration;
@@ -44,9 +52,19 @@ export async function build(form, { log = console.log, planner = null } = {}) {
       const authored = await bridge.eecFile(path.join(here, 'training', 'author-scene.ts'), { layout, scriptPath: scriptPath.split(path.sep).join('/') }, 90000);
       log(`iteration ${iteration}: authored ${authored.created.length} objects, script ${authored.script.mode}`);
 
+      // Snap will not take a Lens without a name it accepts, an icon and a production signing key.
+      // A project copied from Snap's Base Template arrives called "SpecsBaseTemplate"; left alone, that is
+      // the name that would reach Snap. Done after authoring, not straight after the project opens:
+      // writing metadata while Snap's UIKit package is still importing left the package half-resolved
+      // (its own textures then failed to load at runtime).
+      if (!submission) {
+        submission = await prepareSubmission(bridge, { projectDir: project.dir, procedureName: form.procedureName, lensName: form.lensName });
+        log(`for Snap: name "${submission.lensName}", icon set, signing key ${submission.signingKeyCreated ? 'generated' : 'reused'}`);
+      }
+
       // ---- Verifier
       result.stage = 'verify';
-      report = await verify({ bridge, plan, form, runDir, iteration, projectDir: project.dir });
+      report = await verify({ bridge, plan, form, runDir, iteration, projectDir: project.dir, submission });
       fs.writeFileSync(path.join(runDir, 'verifier', `iteration-${iteration}.json`), JSON.stringify(report, null, 2));
       for (const c of report.checks) log(`  ${c.status.toUpperCase().padEnd(8)} ${c.item}${c.detail ? '  -> ' + String(c.detail).slice(0, 160) : ''}`);
       if (report.pass) break;
@@ -58,11 +76,15 @@ export async function build(form, { log = console.log, planner = null } = {}) {
     }
 
     await bridge.save();
+    // The person has to be able to open this folder and know what to click. Done after save so the
+    // project on disk is final, and only when it passed: a failed build is not handed over.
+    if (report?.pass) result.handoff = tidyProjectFolder(project.dir, { title: plan.title, esproj: project.esproj, steps: form.steps, completionMessage: form.completionMessage });
     result.ok = !!report?.pass;
     result.stage = result.ok ? 'done' : 'escalated';
     result.seconds = Math.round((Date.now() - started) / 1000);
     result.costUsd = planner ? planner.costUsd : 0;
-    fs.writeFileSync(path.join(runDir, 'report.md'), renderReport({ plan, form, report, result, project, planner }));
+    result.submission = submission;
+    fs.writeFileSync(path.join(runDir, 'report.md'), renderReport({ plan, form, report, result, project, planner, submission }));
     fs.writeFileSync(path.join(runDir, 'metrics.json'), JSON.stringify({ lens_id, title: plan.title, vertical: plan.vertical, source: planner ? 'prompt' : 'form', prompt: planner ? planner.prompt : null, pass: result.ok, iterations: result.iterations, seconds: result.seconds + (planner ? planner.seconds : 0), costUsd: result.costUsd, tokens: planner ? planner.usage : { input: 0, output: 0, calls: 0 }, steps: form.steps.length, hardwareItems: report.checks.filter((c) => c.status === 'hardware').length, hardwareTest: 'not tested', publishStatus: 'not published', finished_at: new Date().toISOString() }, null, 2));
     return { ...result, report };
   } catch (e) {
@@ -73,7 +95,7 @@ export async function build(form, { log = console.log, planner = null } = {}) {
   }
 }
 
-function renderReport({ plan, form, report, result, project, planner }) {
+function renderReport({ plan, form, report, result, project, planner, submission }) {
   const line = (c) => `| ${c.status === 'pass' ? 'PASS' : c.status === 'fail' ? 'FAIL' : 'NEEDS HARDWARE'} | ${c.item} | ${String(c.detail ?? '').replace(/\|/g, '/').slice(0, 220)} |`;
   const cost = planner
     ? `USD ${planner.costUsd.toFixed(4)} (${planner.usage.input} in / ${planner.usage.output} out tokens, ${planner.model}, planning took ${planner.seconds}s)`
@@ -111,12 +133,17 @@ Source: https://developers.snap.com/spectacles/get-started/start-building/publis
 **Tests performed (preview):**
 ${report.checks.filter((c) => c.status === 'pass').map((c) => `- ${c.item}`).join('\n')}
 
+**Lens name:** ${submission.lensName} (Snap accepts at most 18 characters; the full procedure name stays on the panel)
+**Lens icon:** set, 320x320 PNG
+**Signing key:** production key attached to the project
+
 **Tests Snap should repeat on device:** open the Lens, confirm "v${form.version || '1.0.0'}" shows under the buttons, pinch Done through all ${form.steps.length} step${form.steps.length === 1 ? '' : 's'} to the completion message, pinch Back once from step 2${form.voiceShortcuts !== false ? ', say "done" to advance' : ''}.
 
 ## Manual steps remaining
 - Put the Lens on glasses: pair Specs in Lens Studio, then Send to Spectacles.
 - Check frame rate and thermals on device with the Lens Performance Overlay (Snap targets 60 FPS).
-- Add a custom icon and a preview image or video in Project Info, then Publish in Lens Studio (not automated yet).
+- Sign in to Lens Studio (My Lenses > Login). That is the one thing Parley cannot do for you, and it gates Snap's preflight, the SnapOS Package export and the upload.
+- Add a preview image or video, then run the publish steps. Name, icon and signing key are already set on this project.
 `;
 }
 

package/lens-builder/cli.mjs

@@ -3,6 +3,7 @@
 //   node lens-builder/cli.mjs plan   < {"prompt":""}  -> { type:'planner', decision, form|question|reason, costUsd }
 //   node lens-builder/cli.mjs build  < {"form":{}, "planner":{}?} -> progress events, then { type:'result', ... }
 //   node lens-builder/cli.mjs metrics                -> { type:'metrics', lenses:[...] }
+//   node lens-builder/cli.mjs publish [lensId|run]     -> Snap preflight + SnapOS Package export (needs Lens Studio sign-in)
 //   node lens-builder/cli.mjs record < {"run":"","hardwareTest":"","publishStatus":"","notes":""} -> updated metrics row
 import fs from 'node:fs';
 import path from 'node:path';
@@ -75,6 +76,25 @@ try {
   if (cmd === 'status') await status();
   else if (cmd === 'metrics') metrics();
   else if (cmd === 'record') await record();
+  else if (cmd === 'lenses') {
+    const { listLenses } = await import('./lenses.mjs');
+    emit({ type: 'lenses', lenses: listLenses() });
+  }
+  else if (cmd === 'send') {
+    const { sendToGlasses } = await import('./lenses.mjs');
+    const { target } = await readStdin();
+    emit({ type: 'sent', ...(await sendToGlasses(target, (message) => emit({ type: 'log', message }))) });
+  }
+  else if (cmd === 'open') {
+    const { openLens } = await import('./lenses.mjs');
+    const { target, where } = await readStdin();
+    emit({ type: 'opened', ...(await openLens(target, where, (message) => emit({ type: 'log', message }))) });
+  }
+  else if (cmd === 'publish') {
+    const { publish } = await import('./publish.mjs');
+    const { target } = await readStdin();
+    emit({ type: 'publish', ...(await publish(target, { log: (message) => emit({ type: 'log', message }) })) });
+  }
   else if (cmd === 'plan') {
     const { planFromPrompt } = await import('./planner.mjs');
     const { prompt, auth } = await readStdin();
@@ -85,7 +105,7 @@ try {
     const { build } = await import('./build.mjs');
     const { form, planner = null } = await readStdin();
     const r = await build(form, { planner, log: (message) => emit({ type: 'log', message }) });
-    emit({ type: 'result', ok: r.ok, lens_id: r.lens_id, iterations: r.iterations, seconds: r.seconds, costUsd: r.costUsd ?? 0, stage: r.stage, error: r.error, runDir: r.runDir, checks: r.report?.checks ?? [], reportPath: r.runDir ? path.join(r.runDir, 'report.md') : null });
+    emit({ type: 'result', ok: r.ok, lens_id: r.lens_id, iterations: r.iterations, seconds: r.seconds, costUsd: r.costUsd ?? 0, stage: r.stage, error: r.error, runDir: r.runDir, checks: r.report?.checks ?? [], reportPath: r.runDir ? path.join(r.runDir, 'report.md') : null, projectDir: r.project?.dir ?? null, projectFile: r.project?.file ?? null, title: r.title ?? null, lensName: r.submission?.lensName ?? null, scriptPath: r.scriptPath ?? null });
     process.exitCode = r.ok ? 0 : 1;
   } else {
     emit({ type: 'error', error: `unknown command: ${cmd}` });