parley-live 0.5.1 → 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.1';
+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\`.`,
@@ -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/lens-builder/build.mjs

@@ -7,6 +7,7 @@ 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'));
@@ -34,7 +35,11 @@ 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();
@@ -71,6 +76,9 @@ 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);

package/lens-builder/cli.mjs

@@ -76,6 +76,20 @@ 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();
@@ -91,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}` });

package/lens-builder/lenses.mjs

@@ -0,0 +1,113 @@
+// The Lenses a person has made, and getting back to one.
+//
+// A build used to end with the files somewhere only the pipeline knew about. These two calls are what
+// make a finished Lens something the person owns: a list they can see, and a way back into Lens Studio.
+import fs from 'node:fs';
+import path from 'node:path';
+import { Bridge, DATA, PROJECTS } from './lib/bridge.mjs';
+
+/** Every Lens on this computer, newest first, with where it lives and how its last build went. */
+export function listLenses() {
+  if (!fs.existsSync(PROJECTS)) return [];
+  const runs = readRuns();
+  return fs.readdirSync(PROJECTS, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && d.name !== '_templates')
+    .map((d) => {
+      const dir = path.join(PROJECTS, d.name);
+      const esproj = fs.readdirSync(dir).find((f) => f.toLowerCase().endsWith('.esproj'));
+      if (!esproj) return null;
+      const run = runs.find((r) => sameName(r.title, d.name) || sameName(r.lens_id, d.name)) ?? null;
+      return {
+        name: run?.title || d.name,
+        folder: d.name,
+        dir,
+        file: path.join(dir, esproj),
+        builtAt: run?.finished_at ?? fs.statSync(path.join(dir, esproj)).mtime.toISOString(),
+        steps: run?.steps ?? null,
+        passed: run?.pass ?? null,
+        reportPath: run?.reportPath ?? null,
+      };
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.builtAt).localeCompare(String(a.builtAt)));
+}
+
+/**
+ * Put a Lens back in front of the person.
+ *   where 'lens_studio' (default) opens it in Lens Studio, which is where Send to Spectacles lives.
+ *   where 'folder' only resolves the path; revealing a folder belongs to the app, not to this process.
+ */
+export async function openLens(target, where = 'lens_studio', log = () => {}) {
+  const { resolveProject, openProject } = await import('./publish.mjs');
+  const file = resolveProject(target || '');
+  if (!file) {
+    const known = listLenses().map((l) => l.name);
+    throw new Error(`No Lens called "${target}" on this computer.${known.length ? ` Built so far: ${known.join(', ')}.` : ' Nothing has been built yet.'}`);
+  }
+  const dir = path.dirname(file);
+  if (where === 'folder') return { file, dir, opened: 'folder' };
+  log(`opening ${path.basename(file)} in Lens Studio`);
+  const bridge = new Bridge();
+  await bridge.connect();
+  await openProject(bridge, file);
+  return { file, dir, opened: 'lens_studio' };
+}
+
+function readRuns() {
+  const runsDir = path.join(DATA, 'runs');
+  if (!fs.existsSync(runsDir)) return [];
+  return fs.readdirSync(runsDir)
+    .map((name) => {
+      const metrics = path.join(runsDir, name, 'metrics.json');
+      if (!fs.existsSync(metrics)) return null;
+      try {
+        const m = JSON.parse(fs.readFileSync(metrics, 'utf8'));
+        return { ...m, reportPath: path.join(runsDir, name, 'report.md') };
+      } catch { return null; }
+    })
+    .filter(Boolean)
+    .sort((a, b) => String(b.finished_at).localeCompare(String(a.finished_at)));
+}
+
+const sameName = (a, b) => String(a ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '') === String(b ?? '').toLowerCase().replace(/[^a-z0-9]+/g, '');
+
+/**
+ * Put a Lens on the paired Spectacles: the "Send to Spectacles" step, done by Parley.
+ *
+ * Snap exposes it over MCP as push_leaf_lens, which pushes whatever project is open, so the Lens is
+ * opened first. The execution target has to be switched to the device or the push goes to the
+ * preview and reports success, which would be a lie. On failure the target is put back, so Lens
+ * Studio is left the way it was found.
+ */
+export async function sendToGlasses(target, log = () => {}) {
+  const { resolveProject, openProject } = await import('./publish.mjs');
+  const file = resolveProject(target || '');
+  if (!file) throw new Error(`No Lens called "${target}" on this computer.`);
+  // Nobody should sit and watch a spinner for four minutes to learn their glasses are not on.
+  const bridge = new Bridge({ timeoutMs: 90000 });
+  await bridge.connect();
+  log('opening the Lens in Lens Studio');
+  await openProject(bridge, file);
+  await bridge.call('open_leaf_panel', {});
+  log('pointing Lens Studio at your Spectacles');
+  const aimed = await bridge.call('set_leaf_execution_target', { onDevice: true });
+  if (!aimed || aimed.target !== 'device') {
+    await bridge.call('set_leaf_execution_target', { onDevice: false }).catch(() => {});
+    throw new Error('Lens Studio would not switch to the glasses. Pair your Spectacles in Lens Studio first.');
+  }
+  log('sending it across');
+  try {
+    const pushed = await bridge.call('push_leaf_lens', {});
+    if (!pushed || pushed.pushed !== true || pushed.target !== 'device') {
+      throw new Error(`The Lens went to the ${pushed && pushed.target ? pushed.target : 'preview'} instead of the glasses.`);
+    }
+    return { file, dir: path.dirname(file), sent: true, target: 'device' };
+  } catch (e) {
+    await bridge.call('set_leaf_execution_target', { onDevice: false }).catch(() => {});
+    // Snap's message for "nothing answered" is about a lens not starting; say what it means.
+    const notThere = /did not start on the device|no device|not paired|timed out|timeout|abort/i.test(e.message);
+    throw new Error(notThere
+      ? 'No Spectacles answered. Put them on and wake them, pair them in Lens Studio, and keep them on the same Wi-Fi as this computer, then ask again.'
+      : e.message);
+  }
+}

package/lens-builder/lib/handoff.mjs

@@ -0,0 +1,88 @@
+// Make the project folder something a person can open without being told which file to click.
+//
+// A Lens Studio project is a developer's folder: Assets, Packages, Cache, Workspaces, and the
+// agent-tooling files Snap's template ships (.clad, .cursor, AGENTS.md and friends). Someone who
+// asked for a training guide opens that and has no idea what any of it is. So after a build the
+// folder is cut down to the two things that mean something to them: the Lens itself, and a note
+// telling them what to do. Everything else is marked hidden. Nothing is deleted or moved, so Lens
+// Studio still finds every file exactly where it expects.
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const README = 'Open me first.txt';
+
+/** Hide Lens Studio's working files on Windows. Everywhere else this is a no-op. */
+function hide(dir, names) {
+  if (process.platform !== 'win32' || !names.length) return 0;
+  const sysRoot = process.env.SystemRoot || process.env.windir || 'C:\\Windows';
+  const attrib = path.join(sysRoot, 'System32', 'attrib.exe');
+  if (!fs.existsSync(attrib)) return 0;
+  let hidden = 0;
+  for (const name of names) {
+    try { execFileSync(attrib, ['+H', path.join(dir, name)], { stdio: 'pipe', windowsHide: true }); hidden++; }
+    catch { /* a file Lens Studio holds open can refuse; it stays visible, which is not worth failing a build over */ }
+  }
+  return hidden;
+}
+
+function readmeText({ title, esprojName, steps, completionMessage }) {
+  const lines = [
+    title,
+    '='.repeat(title.length),
+    '',
+    'This folder is your Lens: the step-by-step guide Parley built for you.',
+    '',
+    'TO OPEN IT',
+    `  Double-click "${esprojName}". That opens it in Lens Studio.`,
+    '  Or just ask Parley to open it. You do not have to come here at all.',
+    '',
+    'TO PUT IT ON YOUR GLASSES',
+    '  Wake your Spectacles, make sure they are paired in Lens Studio and on',
+    '  the same Wi-Fi as this computer, then ask Parley to send it to your',
+    '  glasses. It does the rest.',
+    '  By hand instead: open it in Lens Studio and press "Send to Spectacles".',
+    '',
+    'TO CHANGE IT',
+    '  Tell Parley what to change, in your own words. It rebuilds the whole',
+    '  Lens and tests it again. You do not edit anything in here by hand.',
+    '',
+    `WHAT IT GUIDES (${steps.length} step${steps.length === 1 ? '' : 's'})`,
+    ...steps.map((s, i) => `  ${i + 1}. ${s.instruction}${s.warning ? `\r\n     Caution: ${s.warning}` : ''}`),
+  ];
+  if (completionMessage) lines.push('', `AT THE END, THE WEARER SEES`, `  ${completionMessage}`);
+  lines.push(
+    '',
+    'THE REST OF THIS FOLDER',
+    '  Lens Studio keeps its own working files here. They are hidden because',
+    '  you never need to touch them. Do not move or rename anything: the Lens',
+    '  stops opening if you do.',
+    '',
+    `Built by Parley on ${new Date().toLocaleDateString(undefined, { year: 'numeric', month: 'long', day: 'numeric' })}.`,
+    '',
+  );
+  return lines.join('\r\n');
+}
+
+/**
+ * Leave the project folder in a state a non-developer can use.
+ * Returns what it did, so the build report and the app can say so.
+ */
+export function tidyProjectFolder(projectDir, { title, esproj, steps = [], completionMessage = '' } = {}) {
+  const out = { readme: null, hidden: 0, esproj: esproj ? path.basename(esproj) : null };
+  if (!projectDir || !fs.existsSync(projectDir)) return out;
+  const esprojName = out.esproj || fs.readdirSync(projectDir).find((f) => f.toLowerCase().endsWith('.esproj')) || '';
+  out.esproj = esprojName || null;
+
+  const readmePath = path.join(projectDir, README);
+  try {
+    fs.writeFileSync(readmePath, readmeText({ title: title || esprojName.replace(/\.esproj$/i, ''), esprojName, steps, completionMessage }), 'utf8');
+    out.readme = readmePath;
+  } catch { /* a read-only folder is not a reason to fail a build that otherwise passed */ }
+
+  // Everything except the Lens and the note. Lens Studio reads hidden files exactly as before.
+  const keep = new Set([esprojName.toLowerCase(), README.toLowerCase()]);
+  const clutter = fs.readdirSync(projectDir).filter((n) => !keep.has(n.toLowerCase()));
+  out.hidden = hide(projectDir, clutter);
+  return out;
+}

package/lens-builder/publish.mjs

@@ -12,7 +12,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Bridge, DATA } from './lib/bridge.mjs';
+import { Bridge, DATA, PROJECTS } from './lib/bridge.mjs';
 import { readSubmissionState } from './lib/submission.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
@@ -21,17 +21,35 @@ const fwd = (p) => p.split(path.sep).join('/');
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 
 /** The .esproj for a lens id, a run folder name, or an explicit path. */
+/**
+ * A Lens can be asked for by its id, by the folder the person sees in Documents, or by the name they
+ * gave the procedure. All three have to find it, because the name in chat is rarely the id.
+ */
+function findProjectDir(lensId) {
+  if (!fs.existsSync(PROJECTS)) return null;
+  // Never hand back the caller's spelling: Windows matches paths case-insensitively, so "espresso
+  // machine" would resolve and then be shown to the person instead of the folder they actually have.
+  const dirs = fs.readdirSync(PROJECTS, { withFileTypes: true }).filter((d) => d.isDirectory() && d.name !== '_templates');
+  const exact = dirs.find((d) => d.name === lensId);
+  if (exact) return path.join(PROJECTS, exact.name);
+  const want = String(lensId).toLowerCase().replace(/[^a-z0-9]+/g, '');
+  const hit = dirs.find((d) => d.name.toLowerCase().replace(/[^a-z0-9]+/g, '') === want)
+    || dirs.find((d) => d.name.toLowerCase().replace(/[^a-z0-9]+/g, '').includes(want) && want.length > 3);
+  return hit ? path.join(PROJECTS, hit.name) : null;
+}
+
 export function resolveProject(target) {
   if (!target) return null;
   if (/\.esproj$/i.test(target) && fs.existsSync(target)) return path.resolve(target);
   const asRun = path.join(DATA, 'runs', target, 'metrics.json');
   const lensId = fs.existsSync(asRun) ? JSON.parse(fs.readFileSync(asRun, 'utf8')).lens_id : target;
-  const dir = path.join(DATA, 'lens-projects', lensId);
-  const esproj = path.join(dir, `${lensId}.esproj`);
-  return fs.existsSync(esproj) ? esproj : null;
+  const dir = findProjectDir(lensId);
+  if (!dir) return null;
+  const esproj = fs.readdirSync(dir).find((f) => f.toLowerCase().endsWith('.esproj'));
+  return esproj ? path.join(dir, esproj) : null;
 }
 
-async function openProject(bridge, esproj) {
+export async function openProject(bridge, esproj) {
   const current = await bridge.projectInfo().catch(() => null);
   if (current && fwd(current.file).toLowerCase() === fwd(esproj).toLowerCase()) return current;
   await bridge.eec(`const E: any = (globalThis as any).Editor; const model: any = pluginSystem.findInterface(E.Model.IModel);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "parley-live",
-  "version": "0.5.1",
-  "description": "Generate images, video clips with named camera moves, narration, YouTube thumbnails, product ads, complete videos and Studio films, deploy static sites, and build Snap Specs Lenses through Lens Studio, from the terminal with Parley. Built for coding agents: every command has a --json mode.",
+  "version": "0.6.0",
+  "description": "Generate images, video clips with named camera moves, narration, YouTube thumbnails, product ads, complete videos and Studio films, reuse them from your account library, deploy static sites, and build Snap Specs Lenses through Lens Studio, from the terminal with Parley. Built for coding agents: every command has a --json mode.",
   "license": "MIT",
   "type": "module",
   "bin": {