@officexapp/vidfarm-devcli 0.21.42 → 0.21.45

package/dist/src/cli.js

@@ -29,7 +29,7 @@ import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
 import { runSkillsCommand } from "./devcli/skills.js";
-import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
+import { AmbiguousDocRef, DEFAULT_PACK, bundledPackDir, listPackDocs, listPackTopics, loadAngleBank, loadAwarenessLadder, loadIdeaBank, readPackDoc, readPackTopic, resolvePackTopic, searchPackDocs } from "./devcli/skill-docs.js";
 import { initTelemetry, reportCliCrash } from "./devcli/telemetry.js";
 import { resolveLocalDataDir, localBackendAvailable, LocalModeUnavailableError, localApiRequest } from "./devcli/local-backend.js";
 import { startLocalFrontendServer, serveShellsPresent } from "./devcli/local-frontend-server.js";
@@ -37,6 +37,8 @@ import { readStoredAuth, writeStoredAuth, clearStoredAuth, hostsMatch } from "./
 import { CostModeBlockedError, assertBilledAllowed, clearStoredCostMode, costModeExplainer, costModeSummaryLine, normalizeCostMode, resolveCostMode, writeStoredCostMode, COST_MODE_BLURB, COST_MODE_DISPLAY_LIST, costModeDisplayName } from "./devcli/cost-mode.js";
 import { INTERACTION_MODES, INTERACTION_MODE_BLURB, clearStoredInteractionMode, interactionModeExplainer, interactionModeSummaryLine, interactiveOfferLine, normalizeInteractionMode, resolveInteractionMode, writeStoredInteractionMode } from "./devcli/interaction-mode.js";
 import { buildImageHandoff, buildRawsHandoff, formatHandoff } from "./devcli/handoff.js";
+import { buildConsultBrief, CONSULT_ARTIFACTS, consultContextState, consultCountRange, defaultConsultCount, findOfferFile, formatConsultBrief, looksLikeOfferPath, planConsultation, resolveConsultStep, resolveOfferPath } from "./devcli/consult.js";
+import { resolveRootFileCandidates } from "./lib/package-root.js";
 import { STORYBOARD_FILENAME, readStoryboard, renderStoryboardScaffold, storyboardStage } from "./devcli/storyboard.js";
 import { CORE_METRICS, DEFAULT_FORMAT, DEFAULT_METRIC, EASY_FORMATS, EXPERIMENTS_FILENAME, EXPERIMENT_MODES, analyzeRound, appendResult, appendRound, capacityOf, epochsNeeded, findRoundIndex, lintDiary, markPosted, readDiary, renderDiaryScaffold, writeDiary } from "./devcli/experiments.js";
 // vidfarm-devcli — command-line bridge for the Vidfarm video studio. The
@@ -120,6 +122,34 @@ Account (persisted login — points the CLI + \`serve\` at cloud prod):
                             download (a downloader SEARCH, not a rotting link), and
                             the vidfarm clipper / raws scan follow-up. Try browser control
                             or "vidfarm raws scan" first.
+  consult [step]            THE CONSULTATION / BRAINSTORM CHAIN, KEYLESS AND LOCAL.
+                            The cloud runs these as brainstorm/* primitives that need
+                            a provider key or wallet credits. This prints the IDENTICAL
+                            prompt for YOU (the agent already in this terminal) to
+                            answer — $0, no key, no network. Bare "consult" = the map
+                            of the four steps + which artifacts already exist.
+                            Every step reads and updates CONTEXT.md in --dir, the
+                            durable answer file, so a later session starts warm.
+                            Run the whole chain from ONE working folder.
+                            OFFER "vidfarm ideas" FIRST — 20+ video ideas for one
+                            line of input is an easier first win than an interview,
+                            and the picks make the interview answers better.
+                            (aliases: consultation, brainstorm)
+    coldstart [--short]     The interview → OFFER.md. Ask the human the questions a
+                            few at a time; never invent their answers. --short is a
+                            fixed 6-question form for a director in a hurry, and it
+                            still feeds every later step. (alias: interview)
+    awareness               Which awareness stage to sell to → awareness-levels.md
+    angles                  Persuasive angles → persuasive-angles.md
+                            [--problem-awareness problem_unaware|problem_aware]
+                            [--solution-awareness solution_unaware|solution_aware]
+    hooks                   Openings to test → ad-hooks.md (grade them before showing)
+    placement --video <p>   Native product-placement moments in an existing video
+    --offer <text|path>     The offer. Auto-reads OFFER.md / OFFER_<NAME>.md from --dir.
+    --count <n>             How many questions/angles/hooks (default 12)
+    --refs                  Inline the full SELLING_*.md references, exactly as the
+                            cloud prompt does. Off by default: ~34KB of your context.
+    --json                  The brief as data (prompt, steps, artifact, next)
   storyboard [dir]          The PLAN pass: read the project's STORYBOARD.md (ordered
                             frames + duration/status/src/scene/voiceover, plus SCRIPT.md).
                             The editor renders this file in its Storyboard view — a
@@ -700,6 +730,31 @@ Speech (TTS/STT) — LOCAL-FIRST on your own AI key; --cloud is the explicit bac
                             key adds photos/vectors/stock video.
     --provider <p>            Force pixabay|openverse|iconify|iconscout
     --limit <n> | --json
+  video-search "<query>"    GOOGLE VIDEO SEARCH — find the actual SHOT anywhere on the web
+                            (TikTok, YouTube, Pexels/Pixabay/Mixkit, news, archive.org).
+                            This is how you SOURCE raws: take a result url straight into
+                            'vidfarm raws scan <url>' (mine clips) or 'download-video <url>'
+                            (collect the file). Search the SHOT, not the topic:
+                            [subject]+[action]+[shot/style]+[quality/orientation], e.g.
+                            "office worker typing laptop close up 4K". Google operators work:
+                            site:pexels.com/videos · site:tiktok.com · "exact phrase" · -dance
+                            PAID PLANS ONLY · flat $0.0003 per call whatever the result count,
+                            so ask for a WIDE page instead of paging twice.
+    --limit <n>               Results (default 25, max 50)
+    --fresh <d|w|m|y>         Only the last day/week/month/year
+    --duration <d>            short|medium|long   --resolution high|standard
+    --region <r>              wt-wt (default)|us-en|ph-en|…   --json
+  image-search "<query>"    GOOGLE IMAGE SEARCH — reference stills, textures, logos, product
+                            shots. Same operators. PAID PLANS ONLY · flat $0.0003 per call.
+                            For licence-checked, royalty-free assets prefer 'vidfarm media'
+                            (free): image-search returns LINKS with no licence attached.
+    --limit <n> (default 25, max 100)  --type-image photo|clipart|gif|transparent
+    --color <c> --size <s> --layout Square|Tall|Wide --region <r> --json
+  news-search "<query>"     GOOGLE NEWS — recent real events to build TIMELY content on.
+                            News finds the STORY; run video-search after for the VISUALS.
+                            PAID PLANS ONLY · flat $0.0003 per call.
+                            Method: https://vidfarm.cc/experimental/google-news-to-video.md
+    --limit <n> (default 25, max 100)  --fresh <d|w|m|y>  --region <r>  --json
   iconscout "<query>"       DESIGNER icons, STICKERS, illustrations, 3D and Lottie —
                             THE CHEAP ALTERNATIVE TO AI IMAGE GENERATION. Reach for this
                             BEFORE 'generate' / 'image': an AI sticker costs cents per
@@ -894,6 +949,9 @@ Approve & schedule (publish a finished MP4 as a shareable post):
   approve                   Approve media into a preview/share page      → POST /api/v1/approved/posts
     --video <url|file>      Primary MP4 (URL, /files path, or local file → durable My Files)
     --media <url|file>      Extra media (repeatable; local files → durable My Files)
+    --thumbnail <url|file>  Poster image for the share link's social card. Omit it and
+                            the server extracts a frame (~1s in) from --video and files
+                            it under /files/approved
     --folder <path>         Destination subfolder for uploaded local files (default: approved)
     --temp                  Upload local files to the 30-day TEMP store instead of
                             durable My Files (throwaway preview; share video dies at day 30)
@@ -929,18 +987,28 @@ Account:
                             (iconscout takes BOTH values as one secret: <client_id>:<client_secret>)
 
 Agent skill (the director knowledge — a full copy SHIPS INSIDE this CLI):
-  ideas [topic]             "What should I post?" — the 50-frame ANGLE BANK  (local — offline, free, no AI)
-                            (the rise of · what everyone gets wrong · then vs
-                            now · one decision that changed everything · …).
-                            One offer poured into 50 frames is 50 DIFFERENT
-                            videos, not 50 rewrites of one. It hands over the
-                            frames; you fill them with the director's offer,
-                            then write hook/loop/payoff/bait per pick
+  ideas [topic]             "What should I post?" — the THREE IDEA BANKS    (local — offline, free, no AI)
+                            50 frames (the rise of · then vs now · …), 5
+                            AWARENESS STAGES (what the viewer already knows,
+                            and what the video may ask for), and 44 PROBLEM
+                            ANGLES (which side of the problem it comes from).
+                            An idea is one point in that grid; vary TWO axes
+                            and 30 videos never read as repeats. It hands over
+                            the banks — you fill them with the director's
+                            offer, then write hook/loop/payoff/bait per pick.
+                            RUN THIS BEFORE "consult" — one line of input buys
+                            20+ ideas, and it is the easiest first win a new
+                            director can get. The interview comes after.
     --topic "<offer>"         Print each frame already filled with your topic
-    --family <name>           One family only (arc, contrast, pivot, …)
-    --families                List the families and their sizes
+    --family <name>           One frame family only (arc, contrast, pivot, …)
+    --families                List the frame families and their sizes
+    --stages                  The awareness ladder — all 5 stages in full
+    --stage <name|n>          One stage (unaware · problem-aware · … · most-aware)
+    --angles                  The 44 problem angles, by family
+    --angle <name>            One angle family or one named angle
+    --grid                    Stage × angle × frame — one row per video
     --count <n>               Sample N, spread across families (default 20 with --topic)
-    --json                    Machine-readable frames (+ starter lines)
+    --json                    Machine-readable banks (+ starter lines)
   skill topics              The craft this pack knows, by SPOKEN name —       (local — offline, no account)
                             meme-recaption, product-explainer, captions,
                             first-frame, blurred-plate, density, avatar, …
@@ -1052,6 +1120,12 @@ Marketplace (paid, cloud-only — the bazaar never renders locally):
   directory save-url <url>  Save a durable media URL INTO My Files at a folder → POST /api/v1/user/me/attachments/from-url
     --folder <path>         Destination folder under /files (e.g. inpaints, promos)
     --as <name>             Name the saved file · --notes <text> vector-embedded notes
+  directory share <path>    Mint a PUBLIC link onto one subfolder (any root)  → POST /api/v1/user/me/directory/shares
+    --mode read|upload|edit read = browse + vector search · upload = + add files (never delete) · edit = + rename/delete
+    --label <text>          Name the link. PAID to mint; visiting one needs no account.
+  directory shares [path]   List your share links                             → GET  /api/v1/user/me/directory/shares
+  directory share-update <token>  --mode/--label/--disable/--enable           → PATCH /api/v1/user/me/directory/shares/:token
+  directory unshare <token> Delete a share link for good                      → DELETE /api/v1/user/me/directory/shares/:token
     (alias: dir · save-url|from-url|import-url — CLI twin of the "Save to Files" picker)
   put-file / get-file / files / annotate-file are the My Files (persistent) set;
   upload is the throwaway temp store for dropping media into a composition.
@@ -1120,9 +1194,8 @@ Publish-mode options:
   --message <text>    Message attached to the published version snapshot
   --no-snapshot       Only update the working copy; skip the version snapshot
 `;
-// ANSI palette — declared BEFORE main() is invoked because command handlers may
-// reference these synchronously (before their first await) while the rest of
-// this module is still evaluating.
+// ANSI palette. (Its position no longer matters — main() now runs as the last
+// statement in this file — but it stays up here because everything below reads it.)
 const FRONTEND = "\x1b[1m\x1b[36m"; // bold cyan — reserved for openable URLs
 const BOLD = "\x1b[1m";
 const DIM = "\x1b[2m";
@@ -1130,24 +1203,16 @@ const GREEN = "\x1b[32m";
 const YELLOW = "\x1b[33m";
 const RED = "\x1b[31m";
 const RESET = "\x1b[0m";
-// Referenced by runMarketplaceCommand's SYNCHRONOUS browse path, so it must be
-// initialized before `void main()` starts dispatching below.
+// Referenced by runMarketplaceCommand's SYNCHRONOUS browse path.
 const DOLLARPLATOON_SKILL_HINT = `Gig inbox / proofs / payouts live on Dollar Platoon's own API — grab the skill:
   npx skills add https://github.com/OfficeXApp/dollarplatoon-skill
   (or from the vidfarm mirror: vidfarm skills add dollarplatoon-skill)`;
-void main().catch(async (error) => {
-    // Deliberate, expected user-facing conditions (e.g. local mode in the
-    // published cloud-only CLI) print just the message — no stack, no crash report.
-    if (error instanceof LocalModeUnavailableError || error instanceof CostModeBlockedError) {
-        console.error(error.message);
-        process.exit(1);
-    }
-    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
-    // Report only unexpected crashes (bugs), never the deliberate user-facing
-    // `throw new Error(...)` above; no-op unless a devcli DSN is configured.
-    await reportCliCrash(error);
-    process.exit(1);
-});
+// main() is INVOKED AT THE BOTTOM OF THIS FILE, not here. Command handlers read
+// module-level `const`s (help texts, tables, palettes) synchronously, and a
+// const declared below the invocation point is still in its temporal dead zone
+// when the handler runs — `vidfarm directory help` used to die with "Cannot
+// access 'DIRECTORY_HELP' before initialization". Starting main() last means
+// every declaration in this module is initialized before any command dispatches.
 // AI agents habitually save credentials to a project-local .env instead of
 // exporting them, so honor VIDFARM_API_KEY (and VIDFARM_TARGET/VIDFARM_HOST)
 // from ./.env when the variable isn't already in the environment. Real env
@@ -1296,6 +1361,22 @@ async function main() {
         case "media":
             await runMediaCommand(rest);
             return;
+        case "video-search":
+        case "videosearch":
+        case "search-video":
+            await runWebSearchCommand("video", rest);
+            return;
+        case "image-search":
+        case "imagesearch":
+        case "search-image":
+            await runWebSearchCommand("image", rest);
+            return;
+        case "news-search":
+        case "newssearch":
+        case "news":
+        case "search-news":
+            await runWebSearchCommand("news", rest);
+            return;
         case "iconscout":
         case "icons":
         case "stickers":
@@ -1396,6 +1477,13 @@ async function main() {
         case "hand-off":
             await runHandoffCommand(rest);
             return;
+        // The brainstorm chain with no AI key: the prompt goes to the agent that is
+        // already here, not to a provider. "consultation" is the director's word.
+        case "consult":
+        case "consultation":
+        case "brainstorm":
+            await runConsultCommand(rest);
+            return;
         case "storyboard":
         case "plan":
             await runStoryboardCommand(rest);
@@ -2582,6 +2670,7 @@ Rules:
 - REVIEW THE WHOLE VIDEO AS ONE OBJECT — AND NEVER JUDGE IT BY ONE FRAME. Assume your own finished video has a defect you cannot see: across a 32-video batch, EVERY first-pass video had a real defect its own author had already reported as "verified, looks good". The cause is structural — you build scene by scene, each scene correct while it is the whole world, so every scene passes alone and the video fails as a SEQUENCE: margins shift between beats, headline sizes drift, the accent color wanders, one asset is flat vector and the next is photographic, every beat is the same length, a join lands like a slap. Nobody watches a scene; they watch the sequence. So before you call anything done, tile ~12 stills into ONE contact sheet and READ IT AS AN IMAGE — one command: \`vidfarm stills . --sheet\` (add \`--at 0,2,4,…\` to pick timestamps; writes stills/contact-sheet.png). Check: visual balance (no dead band under top-anchored content), consistent spacing/margins, ONE type scale, ONE accent color, ONE illustration style, deliberate pacing rather than N identical beats, nothing jarring at the joins, no frame where two elements compete for the eye — and the summary question, does it look like one person made it in one sitting? Fix drift by defining the SYSTEM (type scale, margin, palette, default beat) and applying it to every scene, not by patching the one scene that stood out. The defects that actually ship, in observed frequency order: large flat dead regions · a placeholder empty state that reads as a failed render · two contradictory numbers in one frame · a CTA still building at the last frame (settle it >=2s before the end) · two headlines superimposed at a scene handoff (exit at nextIn-0.18, duration 0.24, ease power2.out) · type colliding with a busy background exactly as it is spoken. If a frame looks empty, sample 0.2s apart to see whether it RESTS there — a transient wipe frame is fine, >0.5s is a hole. AND ALWAYS COMPARE TWO FRAMES FROM DIFFERENT SCENES: a frozen render (an overlay/watermark pass missing \`-loop 1\`, or assets outside the composition root so the timeline never runs) makes every frame identical while duration, frame count and audio hash all still pass, and frame 0 looks perfect. Verify audio by MEASUREMENT, never "it sounds fine" (you cannot hear it): ~12-15 dB speech-over-bed separation across the actual word spans, peak <0 dBFS. Never \`adelay\` the VO — whisper word timings and every caption built from them are relative to the raw vo.wav; use apad+atrim. Report what you MEASURED separately from what you JUDGED. Full method: the vidfarm skill's references/reviewing-renders.md.
 - THE HARNESS IS A FIRST-CLASS ARTIFACT — KNOW THE THREE PHRASINGS. A HARNESS.md is the reusable AI harness for ONE format or template: what makes it special, written down so an agent reproduces it without the director in the room. "Create me a harness" → \`vidfarm harness init short-form --out ./HARNESS.md\` (bases: short-form, hooks, ugc-testimonial, explainer, product-demo, product-explainer), then EDIT it with them. "Update the harness for this format" → open the file and write the new rule in WITH ITS REASON on the same line. "Give me the harness for this template_id" → they mean the DECOMPOSITION: \`vidfarm harness derive <forkId>\` distils this fork's viral/visual/structural/audio/build DNA into an editable HARNESS.md, keyed the same way the decompose JSON is (\`## Viral DNA\` → \`viral_dna\`, …); \`vidfarm harness show <ref> --dna visual\` prints one strand. \`vidfarm qa .\` picks up ./HARNESS.md automatically; \`--harness <name|path>\` adds more (they stack, and any file of theirs anywhere is valid). Its \`checks:\` are machine-settled; its \`- [ ]\` items come back for YOU to answer honestly in your report — never claim a pass on the half the CLI can't judge. ONE-TIME OR BULK? Ask before you build: if the director wants volume (daily posting, N variants, hook tests), that's SCRIPTING MODE — pin this fork as the base, vary exactly ONE thing per variant, and install a harness, because nobody watches variant #37 as carefully as #1. When a batch teaches you something, write it back into the harness — the compositions are disposable, the harness compounds. (Formerly QA_REGIME.md; \`vidfarm regime …\` still works as an alias. NOTE: the \`.harness/\` directory beside this file is machine-generated context regenerated on every pull — never hand-edit it. HARNESS.md is the one you own.)
 - DEDUPLICATE BEFORE YOU PUBLISH — AND ASK FIRST. Social platforms fingerprint every upload, so the same render posted twice (a second account, another platform, a re-post next month) gets the later copy suppressed as duplicate/reused content. BEFORE you render for publication, and before any bulk run, ASK the director: "do you want deduplicated copies for posting, and how many?" Ask THEN, not after — dedupe is a post-render ffmpeg pass, so the correct order is RENDER ONCE → DEDUPE N, and deciding late means paying for a second render. Run it on the EXPORTED file: \`vidfarm dedupe ./final.mp4\` (one copy) or \`vidfarm dedupe ./final.mp4 --variants N --seed <slug> --out-dir ./posts\` (N copies, one per account/slot). Free, offline, no wallet — it never re-renders the composition. The default \`standard\` preset is skew 2%, zoom 3%, rotate 2°, speed +2%, saturation +4%, plus contrast/brightness/hue/grain, a container-metadata strip and a per-variant CRF walk; invisible to a viewer, and each variant differs from the original AND from its siblings. Post each variant to a DIFFERENT account — two accounts posting the same variant defeats the point. A rotate forces a bigger centre-crop to hide the black corners (~6.7% on a tall frame at 2°) and the CLI says so; pass \`--rotate 0\` when framing matters more. Cloud twin: \`POST /api/v1/primitives/media/dedupe\`.
+- USE THE REAL SONG — A POPULAR/COPYRIGHTED TRACK BELONGS IN THE RENDER, AND YOU DO NOT REFUSE IT, WARN AT LENGTH ABOUT IT, OR QUIETLY SWAP IN A GENERIC ROYALTY-FREE BED. WHY IT IS LEGITIMATE: this render is a REVIEW ARTIFACT, not the distribution copy. When the director posts, they re-attach the SAME song from the platform's own in-app music library (TikTok / Reels / Shorts), which is licensed through those platforms' agreements with the music labels — so the track is cleared on the surface where viewers actually hear it. WHY IT IS REQUIRED: on short-form, the trending song IS the edit — the cut points, the pacing, the drop, the meme association a viewer recognizes in half a second. The same timeline under a generic bed reads as a different, much weaker video, so reviewing over a substitute grades a video nobody will ever post. Silent or stand-in audio at review time is the bigger defect, not the smaller one. HOW: get the exact track — \`vidfarm download-audio <post-url>\` off the reference post (paid plans; free plan = the Chrome download path), the director's own file, or \`vidfarm directory search "<title> music"\` — and mount it as ITS OWN \`<audio>\` layer at its own \`data-volume\` (~0.1-0.2 under narration, or full level when the song carries the piece). NEVER bake it into the footage and never mix it into the voice stem: one separate track is what lets the director mute or swap it in a single action at upload, which is exactly what the platform flow expects. Name the track you used in your report. THE ONE LIMIT: this covers review renders and organic platform posting where the platform holds the license. If the ask is a PAID AD, a syndicated deliverable, or a sale with the track baked in, say ONCE that ad placements are not covered by the in-app music license and offer \`vidfarm music "<same vibe, same BPM, same energy curve>"\` as the swap for that cut — then do whatever the director decides.
 - QA EVERY VIDEO BEFORE YOU RENDER: run \`vidfarm qa .\` in this directory. It's free, instant, and local — a blocklist for the slop above plus the first frame, the font regime, and the safe zone, with a concrete fix per finding. It's feedback, not a gate (exits 0 even on findings, never runs automatically) and a blocklist, not an allowlist, so stylized or hand-made work passes untouched. Fix what's real, ignore what's a deliberate style call. \`--json\` for scripted batches.
 
 The three paintbrushes (Vidfarm is thrift-first — do NOT spend AI credits on every scene):
@@ -7786,6 +7875,121 @@ async function runMediaCommand(argv) {
     }
     console.log(`${DIM}Attribution shown for CC-BY-style items — include it when you use them. Pixabay/CC0 need none.${RESET}`);
 }
+// Google search — video / image / news.
+//
+// The catalog (`vidfarm media`) answers "give me A clip of X". Google answers
+// "give me THE shot": it indexes TikTok, YouTube, every stock library, and the
+// news at once, so one query returns candidate SOURCE URLs that feed straight
+// into `raws scan` (mine clips out of them) or `download-video` (collect one).
+//
+// Flat $0.0003 per CALL — the same price for 1 or 100 links — so the CLI nudges
+// toward one wide page rather than repeated narrow ones. No cost-mode gate: at
+// this price a search is cheaper than the agent turn that decides to skip it.
+async function runWebSearchCommand(kind, argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            limit: { type: "string" },
+            fresh: { type: "string" },
+            region: { type: "string" },
+            duration: { type: "string" },
+            resolution: { type: "string" },
+            color: { type: "string" },
+            size: { type: "string" },
+            "type-image": { type: "string" },
+            layout: { type: "string" },
+            safesearch: { type: "string" }
+        }
+    });
+    const positionals = parsed.positionals.slice();
+    if (positionals[0] && ["search", "find"].includes(positionals[0].toLowerCase()))
+        positionals.shift();
+    const query = positionals.join(" ").trim();
+    if (!query) {
+        console.error(`${RED}${kind}-search: a search query is required${RESET}`);
+        if (kind === "video") {
+            console.error(`${DIM}Search the SHOT, not the topic: vidfarm video-search "office worker typing laptop close up 4K"${RESET}`);
+            console.error(`${DIM}Operators work: site:pexels.com/videos · site:tiktok.com "packing orders" -dance${RESET}`);
+        }
+        else if (kind === "news") {
+            console.error(`${DIM}e.g. vidfarm news-search "AI startup funding announced" --fresh w${RESET}`);
+        }
+        else {
+            console.error(`${DIM}e.g. vidfarm image-search "warehouse interior wide shot" --limit 40${RESET}`);
+        }
+        process.exit(2);
+    }
+    const ctx = commonContext(parsed.values);
+    const maxCap = kind === "video" ? 50 : 100;
+    const limit = Math.min(Math.max(Number(parsed.values.limit ?? "25") || 25, 1), maxCap);
+    const qs = new URLSearchParams({ q: query, max_results: String(limit) });
+    if (parsed.values.region)
+        qs.set("region", String(parsed.values.region));
+    if (parsed.values.fresh)
+        qs.set("timelimit", String(parsed.values.fresh));
+    if (parsed.values.safesearch)
+        qs.set("safesearch", String(parsed.values.safesearch));
+    if (kind === "video") {
+        if (parsed.values.duration)
+            qs.set("duration", String(parsed.values.duration));
+        if (parsed.values.resolution)
+            qs.set("resolution", String(parsed.values.resolution));
+    }
+    if (kind === "image") {
+        if (parsed.values.color)
+            qs.set("color", String(parsed.values.color));
+        if (parsed.values.size)
+            qs.set("size", String(parsed.values.size));
+        if (parsed.values["type-image"])
+            qs.set("type_image", String(parsed.values["type-image"]));
+        if (parsed.values.layout)
+            qs.set("layout", String(parsed.values.layout));
+    }
+    const res = await apiRequest({
+        method: "GET", host: ctx.host, path: `/api/v1/primitives/${kind}-search?${qs.toString()}`, auth: ctx.auth
+    });
+    assertApiOk(res, `${kind} search`);
+    const body = (res.json ?? {});
+    if (ctx.json) {
+        printJson(body);
+        return;
+    }
+    const results = Array.isArray(body.results) ? body.results : [];
+    console.log(`${DIM}${results.length} ${kind} result(s) for "${query}" · $${body.charged_usd ?? 0} this call${RESET}`);
+    if (!results.length) {
+        console.log(`${DIM}No results. Loosen the query — a site: filter plus a long phrase often returns nothing. Try fewer operators, or drop --fresh.${RESET}`);
+        return;
+    }
+    for (const item of results) {
+        if (kind === "image") {
+            console.log(`${GREEN}${item.image_url}${RESET}`);
+            const dims = item.width && item.height ? ` · ${item.width}x${item.height}` : "";
+            console.log(`${DIM}  ${item.title}${dims}${item.source_page ? ` · ${item.source_page}` : ""}${RESET}`);
+            continue;
+        }
+        if (kind === "news") {
+            console.log(`${GREEN}${item.url}${RESET}`);
+            console.log(`${DIM}  ${item.title}${item.source ? ` · ${item.source}` : ""}${item.date ? ` · ${item.date}` : ""}${RESET}`);
+            continue;
+        }
+        console.log(`${GREEN}${item.url}${RESET}`);
+        const meta = [item.duration, item.publisher, item.uploader].filter(Boolean).join(" · ");
+        console.log(`${DIM}  ${item.title}${meta ? ` · ${meta}` : ""}${RESET}`);
+    }
+    if (kind === "video") {
+        console.log(`${DIM}Next: 'vidfarm raws scan <url>' mines clips out of a source · 'vidfarm download-video <url>' collects the file.${RESET}`);
+        console.log(`${RED}A public video is NOT a licensed video — check rights before you reuse anything. Licence-checked free footage: 'vidfarm media search "<meaning>" --type video'.${RESET}`);
+    }
+    else if (kind === "news") {
+        console.log(`${DIM}News finds the STORY. Run 'vidfarm video-search "<event> footage"' for the VISUALS — searching both at once finds neither.${RESET}`);
+        console.log(`${DIM}Method: https://vidfarm.cc/experimental/google-news-to-video.md${RESET}`);
+    }
+    else {
+        console.log(`${RED}These are LINKS with no licence attached. For royalty-free assets use 'vidfarm media search "<meaning>" --type image' instead.${RESET}`);
+    }
+}
 // IconScout — designer icons / STICKERS / illustrations / 3D / Lottie.
 //
 // This is the CHEAP path, and the CLI says so loudly: an AI image attempt costs
@@ -8862,6 +9066,7 @@ async function runApproveCommand(argv) {
             ...commonOptions(),
             video: { type: "string" },
             media: { type: "string", multiple: true },
+            thumbnail: { type: "string" },
             caption: { type: "string" },
             title: { type: "string" },
             pinned: { type: "string" },
@@ -8903,6 +9108,11 @@ async function runApproveCommand(argv) {
         media.push({ url: await resolveApproveMedia(String(parsed.values.video)), kind: "video", role: "primary" });
     for (const url of parsed.values.media ?? [])
         media.push({ url: await resolveApproveMedia(String(url)) });
+    // The social-card poster of the share page. Omit it and the server extracts a
+    // frame (~1s in) from --video and files it under /files/approved.
+    if (parsed.values.thumbnail) {
+        media.push({ url: await resolveApproveMedia(String(parsed.values.thumbnail)), kind: "image", role: "thumbnail" });
+    }
     if (media.length === 0) {
         console.warn(`${DIM}[vidfarm] no --video / --media given; approving a text-only post.${RESET}`);
     }
@@ -9819,6 +10029,147 @@ async function runHandoffCommand(argv) {
     }
     throw new Error('handoff needs a kind: `vidfarm handoff image --theme "…" --items "a,b,c"` (free web image gen → sticker pack) or `vidfarm handoff raws --keywords "…"` (manual clip sourcing).');
 }
+// `vidfarm consult [step]` — the consultation / brainstorm chain, run KEYLESS
+// and LOCAL. The cloud version of each step is a `brainstorm/*` primitive that
+// needs a provider key or wallet credits; this prints the identical prompt for
+// the agent in this terminal to answer itself, for $0.
+async function runConsultCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            offer: { type: "string" },
+            message: { type: "string" },
+            video: { type: "string" },
+            count: { type: "string" },
+            dir: { type: "string" },
+            "problem-awareness": { type: "string" },
+            "solution-awareness": { type: "string" },
+            refs: { type: "boolean", default: false },
+            short: { type: "boolean", default: false }
+        }
+    });
+    const json = Boolean(parsed.values.json);
+    const dir = parsed.values.dir ?? ".";
+    const rawStep = (parsed.positionals[0] ?? "").trim();
+    // Bare `vidfarm consult` = the map, not a wall of prompt. A director who says
+    // "give me a consultation" needs to see the four steps and where they land.
+    if (!rawStep) {
+        const plan = planConsultation(dir);
+        const context = consultContextState(dir);
+        if (json)
+            return printJson({ ok: true, dir: path.resolve(dir), plan, context });
+        console.log(`${BOLD}Vidfarm consultation${RESET} ${DIM}— keyless and local. No provider key, no wallet, no network.${RESET}`);
+        console.log(`${DIM}Each step prints the same prompt the cloud brainstorm primitive would send. YOU answer it.${RESET}\n`);
+        for (const row of plan) {
+            const mark = row.done ? `${GREEN}✓${RESET}` : `${DIM}·${RESET}`;
+            console.log(`  ${mark} ${row.command.padEnd(28)} ${DIM}→ ${row.artifact}${row.done ? " (exists)" : ""}${RESET}`);
+        }
+        const first = plan.find((row) => !row.done) ?? plan[0];
+        console.log(`\n  ${context.exists ? `${GREEN}✓${RESET}` : `${DIM}·${RESET}`} ${"saved answers".padEnd(28)} ${DIM}→ ${context.file}${context.exists ? " (read it before you ask anything)" : " (written by the first step)"}${RESET}`);
+        // The easier win comes first. A director who has seen 20 titled ideas
+        // answers the interview better than one asked to think cold.
+        console.log(`\nBefore the interview: ${BOLD}vidfarm ideas --topic "<your offer in one line>"${RESET}`);
+        console.log(`${DIM}20+ video ideas, offline and free, for one sentence of input → content-ideas.md. Do that first.${RESET}`);
+        console.log(`\nThen here: ${BOLD}${first.command}${RESET}`);
+        console.log(`${DIM}In a hurry: vidfarm consult coldstart --short  (6 fixed questions instead of the full interview)${RESET}`);
+        console.log(`${DIM}Run every step from ONE working folder (--dir), so the artifacts and ${context.file} stay together.${RESET}`);
+        console.log(`${DIM}Also: vidfarm consult placement --video <path|url>  (native product placement inside an existing video)${RESET}`);
+        return;
+    }
+    const step = resolveConsultStep(rawStep);
+    if (!step) {
+        throw new Error(`Unknown consult step "${rawStep}". Use one of: coldstart, awareness, angles, hooks, placement — or bare \`vidfarm consult\` for the map.`);
+    }
+    // coldstart is the step that PRODUCES the offer document, so it is the only
+    // one that runs without one.
+    let offer = "";
+    if (step !== "coldstart") {
+        const inline = parsed.values.offer?.trim();
+        // --offer takes either a path or the offer text itself. A real file wins; a
+        // string that READS like a path but resolves to nothing is an error, never
+        // offer text — otherwise a typo silently consults on the filename.
+        if (inline && !resolveOfferPath(dir, inline) && !looksLikeOfferPath(inline)) {
+            offer = inline;
+        }
+        else {
+            const found = findOfferFile(dir, inline);
+            if ("error" in found) {
+                throw new Error(found.error);
+            }
+            offer = found.text;
+        }
+        if (offer.trim().length < 10) {
+            throw new Error("The offer text is too thin to consult on (under 10 characters). Fill in OFFER.md, or pass --offer \"<a paragraph about the offer>\".");
+        }
+    }
+    const awarenessValue = (raw, allowed, flag) => {
+        if (raw === undefined)
+            return undefined;
+        const value = raw.trim().toLowerCase();
+        if (!allowed.includes(value)) {
+            throw new Error(`${flag} must be one of: ${allowed.join(", ")}.`);
+        }
+        return value;
+    };
+    // --short is a fixed six-question set, so it belongs to the interview only.
+    // On the other steps the equivalent knob is --count, and silently ignoring the
+    // flag would let a director believe they ran a shorter angles pass.
+    const short = Boolean(parsed.values.short);
+    if (short && step !== "coldstart") {
+        throw new Error(`--short is the short-form interview, so it only applies to \`vidfarm consult coldstart\`. For a shorter ${step} run, use --count.`);
+    }
+    const countRaw = parsed.values.count;
+    const range = consultCountRange(step);
+    if (!range && countRaw !== undefined) {
+        throw new Error("consult awareness takes no --count — it returns one markdown recommendation, not a list.");
+    }
+    if (short && countRaw !== undefined) {
+        throw new Error("--short is a fixed six-question set, so it takes no --count. Drop one of the two.");
+    }
+    const count = countRaw === undefined ? defaultConsultCount(step) : Number(countRaw);
+    if (range && (!Number.isInteger(count) || count < range.min || count > range.max)) {
+        throw new Error(`--count for ${step} must be a whole number between ${range.min} and ${range.max} (the cloud primitive enforces the same range).`);
+    }
+    const brief = buildConsultBrief({
+        step,
+        offer,
+        userMessage: parsed.values.message,
+        videoRef: parsed.values.video,
+        count,
+        problemAwareness: awarenessValue(parsed.values["problem-awareness"], ["problem_unaware", "problem_aware"], "--problem-awareness"),
+        solutionAwareness: awarenessValue(parsed.values["solution-awareness"], ["solution_unaware", "solution_aware"], "--solution-awareness"),
+        references: parsed.values.refs ? readSellingReferences() : undefined,
+        dir,
+        short
+    });
+    if (json) {
+        return printJson({ ok: true, keyless: true, cost_usd: 0, artifact_name: CONSULT_ARTIFACTS[step], ...brief });
+    }
+    console.log(formatConsultBrief(brief, { bold: BOLD, dim: DIM, reset: RESET }));
+}
+// The two selling documents the CLOUD prompt inlines. Only read on --refs: they
+// are ~34KB together, which is real context spend for the local agent.
+function readSellingReferences() {
+    const read = (name) => {
+        for (const candidate of resolveRootFileCandidates(path.join("src", "assets", name))) {
+            try {
+                return readFileSync(candidate, "utf8");
+            }
+            catch {
+                continue;
+            }
+        }
+        return undefined;
+    };
+    const hooks = read("SELLING_WITH_HOOKS.md");
+    const awareness = read("SELLING_AWARENESS_STAGES.md");
+    if (!hooks && !awareness) {
+        throw new Error("--refs needs the bundled selling references (src/assets/SELLING_*.md) and neither was found in this install. Drop --refs to use the skill-pack reference instead.");
+    }
+    return { hooks, awareness };
+}
 async function runProviderKeysCommand(argv) {
     const parsed = parseArgs({ args: argv, allowPositionals: false, options: commonOptions() });
     const ctx = commonContext(parsed.values);
@@ -10562,6 +10913,30 @@ const DIRECTORY_HELP = `vidfarm directory — browse the unified file tree (/fil
     e.g. vidfarm directory save-url "https://…/inpaint-out.png" --folder inpaints --as hero.png
     (server fetches the URL — handles cross-origin S3; the CLI twin of the pop-panel "Save to Files")
 
+  directory share <path>           Mint a PUBLIC link onto one subfolder          → POST /api/v1/user/me/directory/shares
+    --mode read|upload|edit        read = browse + vector search (default) · upload = + add files/folders,
+                                   never delete · edit = + rename & delete. Scoped to <path> and everything
+                                   under it — never a sibling or a parent.
+    --label <text>                 Name the link so you can tell your links apart
+    --json                         Raw JSON response
+    Works on ANY root (/files·/temp·/raws·/approved; /projects is read-only so it takes --mode read).
+    Only /files and /temp accept uploads — the other roots have no plain-upload backend, so an upload
+    link there only creates folders. PAID: minting a link needs a paid plan; VISITING one needs no account.
+    e.g. vidfarm directory share /files/crowdsourced --mode upload --label "Contributor drop box"
+         vidfarm directory share /raws/b-roll --mode read --label "Editor library"
+
+  directory shares [path]          List your share links (optionally for one folder) → GET /api/v1/user/me/directory/shares
+    --path <path> --json
+
+  directory share-update <token>   Change or switch off a link                    → PATCH /api/v1/user/me/directory/shares/:token
+    --mode read|upload|edit        Re-scope what holders can do
+    --label <text>                 Rename the link
+    --disable | --enable           Cut off access instantly (reversible — the token survives)
+    --json
+
+  directory unshare <token>        Delete a link for good                         → DELETE /api/v1/user/me/directory/shares/:token
+    --json                         (to keep the record, prefer share-update --disable)
+
   Aliases: directory | dir  (move|mv · copy|cp)   ·   Auth: --api-key <key> or VIDFARM_API_KEY, --host <url>`;
 async function runDirectoryCommand(argv) {
     const sub = argv[0];
@@ -10585,6 +10960,14 @@ async function runDirectoryCommand(argv) {
         case "from-url":
         case "import-url":
             return runDirectorySaveUrl(rest);
+        case "shares":
+            return runDirectorySharesList(rest);
+        case "share":
+            return runDirectoryShareCreate(rest);
+        case "share-update":
+            return runDirectoryShareUpdate(rest);
+        case "unshare":
+            return runDirectoryShareDelete(rest);
         case undefined:
         case "help":
         case "--help":
@@ -10758,6 +11141,140 @@ async function runDirectoryCopy(argv) {
     const suffix = typeof copied === "number" ? ` ${DIM}(${copied} file${copied === 1 ? "" : "s"})${RESET}` : "";
     console.log(`${GREEN}✓${RESET} Copied to ${BOLD}${newPath}${RESET}${suffix} ${DIM}[${space}]${RESET}`);
 }
+// ── directory share tokens ───────────────────────────────────────────────────
+// Public links onto ONE subfolder of any root. Three modes: read (browse +
+// vector search), upload (+ add files/folders, never delete), edit (+ rename &
+// delete). Minting a link is a PAID action; visiting one needs no account at
+// all. Shares live in the cloud directory, so these never fan out to --both.
+// A hoisted function, not a const: main() runs at module top-level ABOVE this
+// point, so a `const` declared down here is still in its temporal dead zone
+// when a command handler reads it.
+function shareModes() {
+    return ["read", "upload", "edit"];
+}
+function shareLine(share) {
+    const mode = String(share?.mode ?? "read");
+    const state = share?.disabled ? `${DIM}(disabled)${RESET}` : "";
+    const label = share?.label ? `${BOLD}${share.label}${RESET}  ` : "";
+    return [
+        `${label}${DIM}${share?.path ?? ""}${RESET}  [${mode}] ${state}`,
+        `  ${share?.url ?? ""}`,
+        `  ${DIM}${share?.token ?? ""}${RESET}`
+    ].join("\n");
+}
+async function runDirectorySharesList(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions(), path: { type: "string" } } });
+    const ctx = commonContext(parsed.values);
+    const pathFilter = parsed.values.path ?? parsed.positionals[0];
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "GET", path: "/api/v1/user/me/directory/shares", query: pathFilter ? { path: pathFilter } : {} }, space);
+    assertApiOk(result, "directory shares");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const shares = (result.json?.shares ?? []);
+    if (!shares.length) {
+        console.log(`${DIM}No share links${pathFilter ? ` for ${pathFilter}` : ""}. Create one: vidfarm directory share <path> --mode read${RESET}`);
+        return;
+    }
+    console.log(shares.map(shareLine).join("\n\n"));
+    console.log(`\n${DIM}${shares.length} link${shares.length === 1 ? "" : "s"}${RESET}`);
+}
+async function runDirectoryShareCreate(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: { ...commonOptions(), mode: { type: "string" }, label: { type: "string" } }
+    });
+    const ctx = commonContext(parsed.values);
+    const targetPath = parsed.positionals[0];
+    if (!targetPath) {
+        throw new Error('directory share requires a folder path: vidfarm directory share <path> [--mode read|upload|edit] [--label <text>]\n  e.g. vidfarm directory share /files/crowdsourced --mode upload --label "Contributor drop box"\n       vidfarm directory share /raws/b-roll --mode read --label "Editor library"');
+    }
+    const mode = parsed.values.mode ?? "read";
+    if (!shareModes().includes(mode)) {
+        throw new Error(`--mode must be ${shareModes().join(" | ")} (got "${mode}")`);
+    }
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, {
+        method: "POST",
+        path: "/api/v1/user/me/directory/shares",
+        body: { path: targetPath, mode, ...(parsed.values.label ? { label: String(parsed.values.label) } : {}) }
+    }, space);
+    assertApiOk(result, "directory share");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const share = result.json?.share ?? {};
+    console.log(`${GREEN}✓${RESET} Shared ${BOLD}${share.path ?? targetPath}${RESET} as ${BOLD}${mode}${RESET} ${DIM}[${space}]${RESET}`);
+    console.log(`  ${share.url ?? ""}`);
+    console.log(`  ${DIM}${share.token ?? ""}  ·  disable it with: vidfarm directory share-update ${share.token ?? "<token>"} --disable${RESET}`);
+}
+async function runDirectoryShareUpdate(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            mode: { type: "string" },
+            label: { type: "string" },
+            disable: { type: "boolean" },
+            enable: { type: "boolean" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    const token = parsed.positionals[0];
+    if (!token) {
+        throw new Error('directory share-update requires a token: vidfarm directory share-update <token> [--mode read|upload|edit] [--label <text>] [--disable|--enable]');
+    }
+    const mode = parsed.values.mode;
+    if (mode && !shareModes().includes(mode)) {
+        throw new Error(`--mode must be ${shareModes().join(" | ")} (got "${mode}")`);
+    }
+    if (parsed.values.disable && parsed.values.enable) {
+        throw new Error("Pass --disable or --enable, not both.");
+    }
+    const body = {};
+    if (mode)
+        body.mode = mode;
+    if (parsed.values.label !== undefined)
+        body.label = String(parsed.values.label);
+    if (parsed.values.disable)
+        body.disabled = true;
+    if (parsed.values.enable)
+        body.disabled = false;
+    if (!Object.keys(body).length) {
+        throw new Error("Nothing to change — pass --mode, --label, --disable or --enable.");
+    }
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "PATCH", path: `/api/v1/user/me/directory/shares/${encodeURIComponent(token)}`, body }, space);
+    assertApiOk(result, "directory share-update");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    const share = result.json?.share ?? {};
+    const state = share.disabled ? `${BOLD}disabled${RESET}` : `${BOLD}live${RESET}`;
+    console.log(`${GREEN}✓${RESET} Share ${DIM}${token}${RESET} is ${state} as ${BOLD}${share.mode ?? "read"}${RESET} ${DIM}[${space}]${RESET}`);
+}
+async function runDirectoryShareDelete(argv) {
+    const parsed = parseArgs({ args: argv, allowPositionals: true, options: { ...commonOptions() } });
+    const ctx = commonContext(parsed.values);
+    const token = parsed.positionals[0];
+    if (!token) {
+        throw new Error('directory unshare requires a token: vidfarm directory unshare <token>\n  (to keep the record but cut off access, use: vidfarm directory share-update <token> --disable)');
+    }
+    const space = targetSpaces(ctx.target)[0];
+    const result = await dispatch(ctx, { method: "DELETE", path: `/api/v1/user/me/directory/shares/${encodeURIComponent(token)}` }, space);
+    assertApiOk(result, "directory unshare");
+    if (ctx.json) {
+        printJson(result.json ?? result.text);
+        return;
+    }
+    console.log(`${GREEN}✓${RESET} Deleted share ${DIM}${token}${RESET} ${DIM}[${space}]${RESET}`);
+}
 // Save a durable media URL (e.g. a finished job's output) INTO My Files at a
 // folder — the CLI twin of the pop-panel "Save to Files" picker. Server fetches
 // the URL (handles cross-origin S3), so no local download round-trip needed.
@@ -11921,7 +12438,12 @@ async function runIdeasCommand(argv) {
             family: { type: "string" },
             topic: { type: "string" },
             count: { type: "string" },
-            families: { type: "boolean", default: false }
+            families: { type: "boolean", default: false },
+            angles: { type: "boolean", default: false },
+            angle: { type: "string" },
+            stages: { type: "boolean", default: false },
+            stage: { type: "string" },
+            grid: { type: "boolean", default: false }
         }
     });
     const json = Boolean(parsed.values.json);
@@ -11929,6 +12451,139 @@ async function runIdeasCommand(argv) {
     const { frames, families } = loadIdeaBank();
     if (!frames.length)
         throw new Error("No bundled content-ideas reference found next to this devcli install. Fetch it with `vidfarm skills add vidfarm`.");
+    // The three axes of an idea live in one reference, so they live behind one
+    // command. A director who only ever sees the frames posts 30 videos at one
+    // awareness stage from one angle, which is the exact failure this expansion
+    // exists to prevent — so the stage and angle banks are flags here, not a
+    // separate command nobody discovers.
+    const ladder = loadAwarenessLadder();
+    const angleBank = loadAngleBank();
+    if (parsed.values.stages || parsed.values.stage) {
+        const wanted = String(parsed.values.stage ?? "").trim().toLowerCase();
+        const picked = wanted
+            ? ladder.filter((entry) => entry.stage.toLowerCase().includes(wanted) || String(entry.index) === wanted)
+            : ladder;
+        if (wanted && !picked.length) {
+            throw new Error(`No awareness stage matches "${wanted}". Stages: ${ladder.map((entry) => `${entry.index} ${entry.stage}`).join(", ")}.`);
+        }
+        if (json)
+            return printJson({ ok: true, offline: true, topic: topic || null, stages: picked });
+        console.log(`${BOLD}The awareness ladder${RESET} ${DIM}(${picked.length} of ${ladder.length} stages · what the viewer already knows)${RESET}\n`);
+        for (const entry of picked) {
+            console.log(`  ${GREEN}${entry.index} · ${entry.stage}${RESET} ${DIM}— ${entry.summary}${RESET}`);
+            for (const field of entry.fields)
+                console.log(`      ${BOLD}${field.label}:${RESET} ${field.value}`);
+            console.log("");
+        }
+        console.log(`${DIM}The stage decides the first ten seconds AND the ask. Do not sell at stage 1 or 2.${RESET}`);
+        console.log(`${DIM}A month of posts should cover the ladder — default mix + the grid: vidfarm skill show content-ideas${RESET}`);
+        console.log(`${DIM}Angles for a stage: vidfarm ideas --angles   ·   pair them up: vidfarm ideas --grid --topic "<offer>"${RESET}`);
+        return;
+    }
+    if (parsed.values.angles || parsed.values.angle) {
+        const wanted = String(parsed.values.angle ?? "").trim().toLowerCase();
+        const picked = wanted
+            ? angleBank.angles.filter((entry) => entry.family.toLowerCase().includes(wanted) || entry.frame.toLowerCase().includes(wanted))
+            : angleBank.angles;
+        if (wanted && !picked.length) {
+            throw new Error(`No angle matches "${wanted}". Angle families: ${angleBank.families.join(", ")} (see \`vidfarm ideas --angles\`).`);
+        }
+        if (json) {
+            return printJson({
+                ok: true,
+                offline: true,
+                topic: topic || null,
+                total_angles: angleBank.angles.length,
+                families: angleBank.families,
+                angles: picked,
+                method: "references/content-ideas.md"
+            });
+        }
+        console.log(`${BOLD}Problem angles${RESET} ${DIM}(${picked.length} of ${angleBank.angles.length} · which side of the problem the video comes from)${RESET}`);
+        if (topic)
+            console.log(`${DIM}Topic: ${RESET}${topic}`);
+        console.log("");
+        let angleGroup = "";
+        for (const entry of picked) {
+            if (entry.family !== angleGroup) {
+                angleGroup = entry.family;
+                console.log(`  ${BOLD}${angleGroup}${RESET}`);
+            }
+            console.log(`    ${GREEN}${entry.frame}${RESET}${entry.note ? ` ${DIM}— ${entry.note}${RESET}` : ""}`);
+        }
+        console.log("");
+        console.log(`${DIM}"I already covered that topic" → hold the frame, change the angle. Same research, new video.${RESET}`);
+        console.log(`${DIM}Pair angles with frames and stages: vidfarm ideas --grid --topic "<offer>"${RESET}`);
+        return;
+    }
+    if (parsed.values.grid) {
+        // The grid is the honest answer to "give me 30 videos": vary TWO axes.
+        // Walking frames, angles and stages at different strides keeps every row a
+        // different combination instead of 30 rows of one frame family.
+        const rows = Number(parsed.values.count ?? 20);
+        const total = Number.isFinite(rows) && rows > 0 ? Math.min(rows, 200) : 20;
+        if (!angleBank.angles.length || !ladder.length) {
+            throw new Error("The bundled content-ideas reference has no angle or awareness bank. Update it with `vidfarm skills add vidfarm`.");
+        }
+        // Stage order is not round-robin: this ten-row cycle reproduces the default
+        // monthly mix from the reference (3 unaware, 3 problem-aware, 2 solution-
+        // aware, 1 product-aware, 1 most-aware), so a 30-row grid is already a
+        // balanced month instead of six videos of each.
+        const mixCycle = [1, 2, 1, 3, 2, 4, 1, 2, 3, 5];
+        // Each stage names the frames and angles it can actually carry. Pairing
+        // "the price objection" with a stage-1 video would hand the director a row
+        // the reference itself calls wrong, so draw from the stage's own lists and
+        // fall back to the full banks only if a list is missing.
+        const listed = (stage, label) => (stage.fields.find((field) => field.label.toLowerCase().startsWith(label))?.value ?? "")
+            .split(" · ").map((item) => item.trim().toLowerCase()).filter(Boolean);
+        const gridSeen = new Set();
+        const grid = Array.from({ length: total }, (_, i) => {
+            const stage = ladder.find((entry) => entry.index === mixCycle[i % mixCycle.length]) ?? ladder[i % ladder.length];
+            const round = Math.floor(i / mixCycle.length);
+            const fitFrames = listed(stage, "frames");
+            const fitAngles = listed(stage, "angles");
+            const framePool = frames.filter((entry) => fitFrames.includes(entry.frame.toLowerCase()));
+            const anglePool = angleBank.angles.filter((entry) => fitAngles.includes(entry.frame.toLowerCase()));
+            const usableFrames = framePool.length ? framePool : frames;
+            const usableAngles = anglePool.length ? anglePool : angleBank.angles;
+            // Strides alone collide once a pool size divides one of them, and a grid
+            // that prints the same row twice is exactly the repetition this command
+            // sells against — so walk forward until the triple is new.
+            let frame = usableFrames[(i + round) % usableFrames.length];
+            let angle = usableAngles[(i * 3 + round) % usableAngles.length];
+            for (let bump = 0; bump < usableFrames.length * usableAngles.length; bump += 1) {
+                if (!gridSeen.has(`${stage.index}|${frame.frame}|${angle.frame}`))
+                    break;
+                angle = usableAngles[(i * 3 + round + bump + 1) % usableAngles.length];
+                if ((bump + 1) % usableAngles.length === 0)
+                    frame = usableFrames[(i + round + bump + 1) % usableFrames.length];
+            }
+            gridSeen.add(`${stage.index}|${frame.frame}|${angle.frame}`);
+            return {
+                stage: `${stage.index} · ${stage.stage}`,
+                angle: angle.frame,
+                angle_family: angle.family,
+                frame: frame.frame,
+                frame_family: frame.family,
+                starter: topic ? joinIdeaFrame(frame.frame, topic) : null
+            };
+        });
+        if (json)
+            return printJson({ ok: true, offline: true, topic: topic || null, rows: grid, method: "references/content-ideas.md" });
+        console.log(`${BOLD}Idea grid${RESET} ${DIM}(${total} combinations · stage × angle × frame · offline, free, no AI call)${RESET}`);
+        if (topic)
+            console.log(`${DIM}Topic: ${RESET}${topic}`);
+        console.log("");
+        for (const row of grid) {
+            console.log(`  ${DIM}${row.stage.padEnd(18)}${RESET}${GREEN}${row.angle}${RESET}`);
+            console.log(`    ${row.starter ?? row.frame}`);
+        }
+        console.log("");
+        console.log(`${DIM}Each row is a DIFFERENT video, not a rewrite — the stage and the angle both moved.${RESET}`);
+        console.log(`${DIM}Sharpen each into a real title, keep the stage label on it, then write hook/loop/payoff/bait.${RESET}`);
+        console.log(`${DIM}Method, the monthly stage mix, and a worked example: vidfarm skill show content-ideas${RESET}`);
+        return;
+    }
     if (parsed.values.families) {
         if (json)
             return printJson({ ok: true, families, frames: frames.length });
@@ -11976,6 +12631,9 @@ async function runIdeasCommand(argv) {
             total_frames: frames.length,
             families,
             frames: picked.map((entry) => ({ frame: entry.frame, family: entry.family, starter: topic ? joinIdeaFrame(entry.frame, topic) : null })),
+            total_angles: angleBank.angles.length,
+            angle_families: angleBank.families,
+            awareness_stages: ladder.map((entry) => ({ index: entry.index, stage: entry.stage, summary: entry.summary })),
             method: "references/content-ideas.md"
         });
     }
@@ -11999,9 +12657,18 @@ async function runIdeasCommand(argv) {
     else {
         console.log(`${DIM}Pour ONE topic into a frame to get a video: 'the rise of' + your niche. Add --topic "<offer>" to see it.${RESET}`);
     }
+    console.log(`${DIM}A frame is only ONE axis. The other two are here too, and a set that freezes them repeats:${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --stages    ${RESET}${ladder.length} awareness stages ${DIM}— what the viewer knows, and what you may ask for${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --angles    ${RESET}${angleBank.angles.length} problem angles ${DIM}— which side of the problem the video comes from${RESET}`);
+    console.log(`${DIM}  vidfarm ideas --grid --topic "<offer>"${RESET} ${DIM}— stage × angle × frame, one row per video${RESET}`);
     console.log(`${DIM}Method + frame→format notes: vidfarm skill show content-ideas   ·   families: vidfarm ideas --families${RESET}`);
     console.log(`${DIM}Never ship a frame as a hook — the four charges still apply: vidfarm skill show hooks${RESET}`);
     console.log(`${DIM}Producing the whole set is a batch: vidfarm skill show bulk (one frame per video).${RESET}`);
+    // The natural upsell, in the right order: ideas are the easy win, and the
+    // interview is what a director opts into once they want the strategy behind
+    // the list. Offering it here means it never has to be asked for cold.
+    console.log(`${DIM}Save the picks as content-ideas.md in your working folder. Want the strategy behind them${RESET}`);
+    console.log(`${DIM}(who to sell to, which angle, which hook)? That is the interview: vidfarm consult coldstart --short${RESET}`);
 }
 async function runSkillDocsCommand(sub, argv) {
     const parsed = parseArgs({
@@ -12169,4 +12836,21 @@ async function runUpdateSkillCommand(argv) {
         ...(ctx.json ? ["--json"] : [])
     ]);
 }
+// ── entry point ──────────────────────────────────────────────────────────────
+// Last statement in the file ON PURPOSE: see the note where this used to live.
+// Every module-level declaration above is initialized by the time a command
+// handler reads it, so late-declared help texts and tables are safe.
+void main().catch(async (error) => {
+    // Deliberate, expected user-facing conditions (e.g. local mode in the
+    // published cloud-only CLI) print just the message — no stack, no crash report.
+    if (error instanceof LocalModeUnavailableError || error instanceof CostModeBlockedError) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+    // Report only unexpected crashes (bugs), never the deliberate user-facing
+    // `throw new Error(...)` above; no-op unless a devcli DSN is configured.
+    await reportCliCrash(error);
+    process.exit(1);
+});
 //# sourceMappingURL=cli.js.map