@vibeframe/cli 0.83.0 → 0.84.0

package/dist/index.js

@@ -35865,8 +35865,9 @@ var init_video = __esm({
 // src/commands/_shared/cost-tier.ts
 function applyTier(cmd, tier) {
   cmd[COST_TIER_KEY] = tier;
+  const colored = TIER_COLOR[tier](`Cost: ${tier} (${TIER_DESCRIPTION[tier]})`);
   cmd.addHelpText("after", `
-Cost: ${tier} (${TIER_DESCRIPTION[tier]})
+${colored}
 `);
   return cmd;
 }
@@ -35879,16 +35880,23 @@ function applyTiers(parent, tiers) {
     if (tier) applyTier(cmd, tier);
   }
 }
-var TIER_DESCRIPTION, COST_TIER_KEY;
+var TIER_DESCRIPTION, TIER_COLOR, COST_TIER_KEY;
 var init_cost_tier = __esm({
   "src/commands/_shared/cost-tier.ts"() {
     "use strict";
+    init_source();
     TIER_DESCRIPTION = {
       "free": "FFmpeg only, no API call",
       "low": "$0.01\u2013$0.10 per call",
       "high": "$1\u2013$5 per call",
       "very-high": "$5\u2013$50+ per call"
     };
+    TIER_COLOR = {
+      "free": source_default.green,
+      "low": source_default.cyan,
+      "high": source_default.yellow,
+      "very-high": source_default.red
+    };
     COST_TIER_KEY = Symbol.for("@vibeframe/cli.costTier");
   }
 });
@@ -51025,7 +51033,7 @@ function listWalkthroughs() {
 function isWalkthroughTopic(value) {
   return typeof value === "string" && WALKTHROUGH_TOPICS.includes(value);
 }
-var SCENE_WALKTHROUGH, PIPELINE_WALKTHROUGH, META, CONTENT, WALKTHROUGH_TOPICS;
+var SCENE_WALKTHROUGH, PIPELINE_WALKTHROUGH, ARCHITECTURE_WALKTHROUGH, META, CONTENT, WALKTHROUGH_TOPICS;
 var init_walkthroughs = __esm({
   "src/commands/_shared/walkthroughs/walkthroughs.ts"() {
     "use strict";
@@ -51265,6 +51273,59 @@ When the user has a working shell sequence, extract steps:
 
 The \`compose\` action is the catch-all assembly step (audio mux, video
 overlay, etc.) \u2014 useful at the tail of a pipeline.
+`;
+    ARCHITECTURE_WALKTHROUGH = `# vibe agent / build / run \u2014 when to pick which
+
+The CLI has three orchestrating commands that coordinate other primitives:
+\`vibe agent\`, \`vibe build\`, \`vibe run\`. New users routinely ask which one
+they want for a given task. The full audit lives in
+[\`docs/cli-architecture.md\`](../../../docs/cli-architecture.md); this
+walkthrough is the operator-facing summary.
+
+## TL;DR
+
+| | \`vibe agent\` | \`vibe build\` | \`vibe run\` |
+|---|---|---|---|
+| **Driving input** | natural-language prompt | \`STORYBOARD.md\` | YAML pipeline file |
+| **Interactivity** | REPL or one-shot | one-shot | one-shot |
+| **Reproducibility** | none | high (idempotent) | highest (checkpointed) |
+| **Budget caps** | per-session max-turns | none | \`--budget-usd\`, \`--budget-tokens\`, \`--max-errors\` |
+| **Resume after crash** | no | re-invoke | \`--resume\` |
+| **Best for** | exploration | finished script | repeatable workflows |
+
+## Decision tree
+
+- "I want to play, I'll know it when I see it" \u2192 \`vibe agent\`
+- "I have a finished script + visual identity" \u2192 \`vibe build\`
+- "I want this to run again next month" \u2192 \`vibe run\`
+
+If two seem to fit, pick the rightmost one \u2014 more reproducible, less surprise.
+
+## Cost-tier awareness (v0.83+)
+
+Every primitive subcommand carries a cost tier (\`free\` / \`low\` / \`high\` /
+\`very-high\`). \`vibe schema --list\` exposes the tier as JSON, and each
+\`vibe <group> <sub> --help\` page shows it as a colored footer. Use
+\`vibe doctor --test-keys\` before kicking off any high-cost orchestrator \u2014
+a single bad key wastes time and money.
+
+## Cross-command primitives
+
+All three commands ultimately call the same primitives:
+\`generate\` / \`edit\` / \`audio\` / \`inspect\` / \`detect\` / \`remix\`. The
+agent calls them through a tool manifest; \`build\` calls a curated subset
+(TTS + image + compose + render); \`run\` exposes 55+ actions one per primitive.
+
+## Known overlap
+
+- \`vibe build\` is conceptually a 4-step pipeline; \`vibe run\` could express
+  the same flow but build's STORYBOARD.md input + opinionated defaults are
+  the value-add.
+- \`vibe agent\`'s tool registry currently exposes primitives, not
+  orchestrators. Adding \`vibe.build\` / \`vibe.run\` as agent tools is on the
+  table for a future major.
+- \`vibe run --resume\` has no analog in build/agent; build's idempotent
+  re-invoke covers the common case.
 `;
     META = {
       scene: {
@@ -51303,13 +51364,32 @@ overlay, etc.) \u2014 useful at the tail of a pipeline.
           "vibe schema --list",
           "vibe doctor"
         ]
+      },
+      architecture: {
+        title: "vibe agent / build / run \u2014 when to pick which",
+        summary: "Compare the three orchestrating commands on the dimensions that actually decide the choice",
+        steps: [
+          "Pick agent for exploration (NL prompt, REPL, no checkpoints).",
+          "Pick build for STORYBOARD.md \u2192 MP4 with opinionated defaults.",
+          "Pick run for repeatable, budget-capped, checkpointed YAML pipelines.",
+          "Run `vibe doctor --test-keys` before any high-cost orchestrator to validate keys upfront.",
+          "Use `vibe schema --list` (cost field, v0.84) to plan the budget per step before kicking off `vibe run --budget-usd`."
+        ],
+        relatedCommands: [
+          "vibe agent",
+          "vibe build",
+          "vibe run",
+          "vibe doctor",
+          "vibe schema --list"
+        ]
       }
     };
     CONTENT = {
       scene: SCENE_WALKTHROUGH,
-      pipeline: PIPELINE_WALKTHROUGH
+      pipeline: PIPELINE_WALKTHROUGH,
+      architecture: ARCHITECTURE_WALKTHROUGH
     };
-    WALKTHROUGH_TOPICS = ["scene", "pipeline"];
+    WALKTHROUGH_TOPICS = ["scene", "pipeline", "architecture"];
   }
 });
 
@@ -62745,7 +62825,7 @@ init_source();
 // package.json
 var package_default = {
   name: "@vibeframe/cli",
-  version: "0.83.0",
+  version: "0.84.0",
   description: "VibeFrame CLI - natural language video editing from the terminal",
   private: false,
   license: "MIT",
@@ -65086,15 +65166,18 @@ function listCommands(program3) {
     if (subCmds.length === 0) {
       const desc = group.description() || "";
       if (desc.toLowerCase().includes("deprecated")) continue;
-      commands.push({ path: name, description: desc });
+      const cost = getCostTier(group);
+      commands.push({ path: name, description: desc, ...cost ? { cost } : {} });
       continue;
     }
     for (const sub of subCmds) {
       const desc = sub.description() || "";
       if (desc.toLowerCase().includes("deprecated")) continue;
+      const cost = getCostTier(sub);
       commands.push({
         path: `${name}.${sub.name()}`,
-        description: desc
+        description: desc,
+        ...cost ? { cost } : {}
       });
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeframe/cli",
-  "version": "0.83.0",
+  "version": "0.84.0",
   "description": "VibeFrame CLI - natural language video editing from the terminal",
   "private": false,
   "license": "MIT",
@@ -183,8 +183,8 @@
     "tsx": "^4.21.0",
     "typescript": "^5.3.3",
     "vitest": "^1.2.2",
-    "@vibeframe/ai-providers": "0.83.0",
-    "@vibeframe/core": "0.83.0"
+    "@vibeframe/ai-providers": "0.84.0",
+    "@vibeframe/core": "0.84.0"
   },
   "engines": {
     "node": ">=20"