wyren-mcp 1.0.0

package/skills/wyren/rules/nodes.md

@@ -0,0 +1,112 @@
+# Nodes and Connections
+
+## Node categories
+
+### Input nodes (provide data to the pipeline)
+
+| Type         | Label       | Output socket | Purpose                                             |
+| ------------ | ----------- | ------------- | --------------------------------------------------- |
+| `textInput`  | Text Input  | text          | User-provided text (prompts, descriptions, scripts) |
+| `imageInput` | Image Input | image         | User-provided image (reference photos, logos)       |
+| `videoInput` | Video Input | video         | User-provided video (source footage)                |
+
+### AI nodes (generate content — cost credits)
+
+| Type              | Label            | Input sockets              | Output socket | Execution                                 |
+| ----------------- | ---------------- | -------------------------- | ------------- | ----------------------------------------- |
+| `textAI`          | Text AI          | text                       | text          | Sync — instant result                     |
+| `storyAI`         | Story AI         | text                       | text          | Sync — instant result                     |
+| `imageAI`         | Image AI         | text, image (optional ref) | image         | Async — background job, polls until done  |
+| `videoAI`         | Video AI         | text, image                | video         | Async — background job (can take minutes) |
+| `voiceAI`         | Voice AI         | text                       | audio         | Sync — instant result                     |
+| `websiteResearch` | Website Research | text                       | text          | Sync                                      |
+
+### Data nodes (configure and filter)
+
+| Type             | Label           | Purpose                                                   |
+| ---------------- | --------------- | --------------------------------------------------------- |
+| `globalStyle`    | Global Style    | Applies a visual style template to all connected AI nodes |
+| `gate`           | Gate            | Human-in-the-loop candidate selector — accumulates upstream runs, user picks one, downstream sees the pick |
+| `trendSelector`  | Trend Selector  | Picks trending topics from the trend database             |
+| `tiktokResearch` | TikTok Research | Analyzes TikTok trends and content                        |
+
+### Edit nodes (transform media)
+
+| Type            | Label          | Input                   | Output | Purpose                        |
+| --------------- | -------------- | ----------------------- | ------ | ------------------------------ |
+| `videoTrim`     | Video Trim     | video                   | video  | Trim start/end of a video      |
+| `videoMerge`    | Video Merge    | video (multiple)        | video  | Combine multiple videos        |
+| `videoCaptions` | Video Captions | video, audio (optional) | video  | Add captions/subtitles overlay |
+
+### Compose nodes (combine media)
+
+| Type        | Label     | Purpose                                       |
+| ----------- | --------- | --------------------------------------------- |
+| `slideshow` | Slideshow | Combine images + audio into a video slideshow |
+
+### Flow nodes (control execution)
+
+| Type            | Label          | Purpose                                                |
+| --------------- | -------------- | ------------------------------------------------------ |
+| `iterator`      | Iterator       | Loop over an array — executes body nodes for each item |
+| `closeIterator` | Close Iterator | Collects loop results back into an array               |
+
+## Socket types
+
+There are 5 socket types. Connections are only valid between compatible sockets:
+
+| Socket  | Color  | Compatible with           |
+| ------- | ------ | ------------------------- |
+| `text`  | Blue   | text, any                 |
+| `image` | Green  | image, any                |
+| `video` | Purple | video, any                |
+| `audio` | Orange | audio, any                |
+| `any`   | Gray   | text, image, video, audio |
+
+**Rule**: You can only connect an output to an input if their socket types are compatible.
+
+## Connection rules
+
+- Each input handle accepts **one** connection by default (some nodes override this via `connectionValidator`)
+- Output handles can connect to **multiple** inputs
+- No cycles allowed — the graph must be a DAG
+- Use `get_node_type_info` to check a node's exact handles and connection limits
+
+## Configuring nodes
+
+Each node has configurable fields set via `build_graph` with `dataUpdates` (partial merge). The server validates all values and returns clear error messages for out-of-range parameters — with the field's full schema in `details.fieldErrors`. Unambiguous scalar type mismatches (e.g., `"off"` for a boolean) are auto-coerced.
+
+Common fields:
+
+- **AI nodes**: `model` (model ID), `promptTemplate` (prompt template slug or "custom"), `customPrompt` (when promptTemplate is "custom"), `style` (style template slug)
+- **Text Input**: `text` (the content), `label` (display name)
+- **Image Input**: `url` (image URL — auto-normalized to internal format), `label` (display name)
+- **Video Input**: `url` (video URL), `label` (display name)
+- **Voice AI**: `model`, `presetVoiceId` (voice ID from `list_voices`), `stability`, `similarityBoost`
+- **Video AI**: `model`, `mode` (standard/pro), `duration`, `aspectRatio`
+- **Website Research**: `url`, `crawlDepth` (1/2/3), `provider` (`firecrawl` = 5 credits, screenshots + JS rendering, `standard` = 3 credits, fetch+cheerio, SSR sites only, no screenshots). Default `firecrawl`. If the user wants to spend fewer credits or the site is static HTML, set `provider: "standard"`.
+- **Gate**: `productLabel` (user-facing prompt, e.g. "Pick your hero image"), `productName` (semantic slug for `<ProductGate name="..." />` — required for custom product pages), `maxCandidates` (`"accumulate"` keeps all runs, `1` replaces), `maxRetries` / `maxRetriesUnlimited` (retry cap for product-form runs), `showOnNode` (render candidate gallery inline on canvas). Gate has ONE `any` input + ONE `any` output, max 1 incoming connection; it infers socket type from whatever's plugged in and passes the selected value straight through.
+
+Use `get_node_type_info` for the exact field schema of any node if you need to check constraints before setting values.
+
+## Handle IDs
+
+Both input and output handles use the raw ID from node definitions — no suffixes, no transformations. Use `get_node_type_info({ nodeType: "..." })` to see exact IDs for any node.
+
+**Naming convention**: Multi-input composition nodes use **plural** handle names (`videos`, `images`). Single-input nodes use **singular** names (`video`, `text`, `image`). When unsure, call `get_node_type_info` — handle IDs must be exact.
+
+Common handles:
+
+- `textInput`: output `text`
+- `textAI`: output `text`, input `text`
+- `storyAI`: outputs `scene_1`–`scene_5`, input `text`
+- `imageAI`: output `image`, inputs `text`, `image`
+- `videoAI`: output `video`, inputs `text`, `startFrame` (not all models accept startFrame — use `get_model_capabilities` to check)
+- `voiceAI`: output `audio`, input `text`
+- `websiteResearch`: outputs `brandDocument`, `colorPalette`, `screenshots`
+- `videoCaptions`: output `video`, inputs `video`, `audio`
+- `videoMerge`: outputs `video`, `duration`; input `videos` (plural — accepts up to 10 connections)
+- `videoTrim`: output `video`, input `video`
+- `audioOverlay`: output `video`, `duration`; inputs `video`, `audio` — merges audio onto video (replace or mix mode)
+- `slideshow`: output `video`, inputs `images` (plural), `audio`
+- `iterator`/`closeIterator`: output `items`/`collected`

package/skills/wyren/rules/products.md

@@ -0,0 +1,68 @@
+# Products (API Publishing)
+
+Workflows can be published as Products — REST API endpoints that external applications can call.
+
+## Publishing flow
+
+1. **Build and test the workflow** — make sure it runs correctly
+2. **Mark API inputs/outputs** with `set_product_inputs`:
+   - `product_inputs`: input nodes that callers provide values for
+   - `product_outputs`: terminal nodes whose outputs are returned to callers
+3. **Publish** with `publish_product`:
+   - Generates a URL slug and API endpoint
+   - Creates an API key if the user doesn't have one
+   - Returns: `slug`, `endpoint_url`, `schema_url`, `estimate_url`
+4. **Share the endpoint** — callers use the API key + endpoint URL
+
+## Configuring publish options
+
+`publish_product` and `republish_product` accept:
+
+- `exposed_inputs` — map of node IDs to fields that API callers can set
+- `allowed_models` — which models callers can override (with allowed list)
+- `allowed_configs` — which config fields callers can override
+- `gate_config` — per-gate behavior in API runs (`auto_approve`, `skip`, or `fail`)
+
+### Gate nodes in published workflows
+
+Gate nodes are **human-in-the-loop candidate selectors** in the studio (see [workflow-patterns.md](workflow-patterns.md) → "Human-in-the-loop gate before expensive steps"). In a published Product they behave two different ways depending on how the product is consumed:
+
+**1. Custom product pages (web form consumers).** Gates render as candidate galleries via `<ProductGate />`. Two fields on the gate node drive the rendering:
+
+- `productLabel` — user-facing heading shown above the gallery (e.g. "Pick your hero frame")
+- `productName` — semantic slug used to address the gate in a custom page: `<ProductGate name="hero-frame" />`
+
+Always set both when publishing. Without `productName`, the default page still renders the gate but custom pages can't target it by name. Without `productLabel`, the UI falls back to a generic "Gate" heading.
+
+**2. API consumers (`run_workflow` via REST).** There is no human to click — the server resolves each gate via the `gate_config` map:
+
+- `auto_approve` (default) — pass the **most recent** upstream output straight through. This is what you want for almost every API-published workflow.
+- `skip` — same pass-through behavior, softer semantic (the gate is ignored without error).
+- `fail` — hard error; the API run aborts at this node. Use only when human approval is genuinely mandatory and the workflow should not run via API.
+
+When publishing a workflow that contains gates, always explicitly set `gate_config` on every gate node — don't rely on the default map being populated by the client. Leaving a gate out of `gate_config` still falls through to `auto_approve`, but being explicit keeps behavior obvious when you come back to the workflow later.
+
+## API keys
+
+- `create_api_key` — creates a new key (raw key shown only once)
+- `list_api_keys` — shows prefix and status (not full key)
+- `revoke_api_key` — permanently disables a key
+
+First publish auto-generates a key if the user has none.
+
+## Monitoring runs
+
+- `get_run_status({ run_id })` — status, outputs, credits consumed, timing
+- `list_runs({ slug })` — recent runs for a published product
+
+## Updating a published product
+
+Use `republish_product` with the same slug — creates a new version while keeping the endpoint URL stable.
+
+## Unpublishing
+
+`unpublish_product({ slug })` — deactivates the endpoint. In-flight runs complete normally.
+
+## Schema inspection
+
+`get_product_schema({ slug })` — returns the full API contract: expected inputs, available model overrides, output structure, and endpoint URLs. Useful for building integrations.

package/skills/wyren/rules/recommendations.md

@@ -0,0 +1,297 @@
+# Budget-Aware Recommendations
+
+Load this file when the user asks an ideation question scoped to a budget — e.g., "what can I build for $2?", "what's possible with 500 credits?", "ideas for 1000 credits", "show me options under $5", "what marketing video can I build with $1", "what should I make with my budget?".
+
+Your job: return a **single ranked list of 4–6 creative concepts**. Every concept names the pipeline that realizes it — a saved user workflow, a published product, an Essential, a template, or a custom build. No buckets, no section headers. The user sees one list of ideas, each with a clear "uses X" realization line.
+
+## Step 1 — Call `discover_options` FIRST (non-skippable)
+
+Every budget question starts with exactly one call:
+
+```
+discover_options({
+  budget: <dollars or credits from user>,
+  include?: <required node types from intent>,
+  exclude?: <disallowed node types from intent>,
+})
+```
+
+**Red flag — stop and restart:** If you are about to list options, propose builds, or describe "what you could make" without having called `discover_options` in this turn, STOP. `discover_options` is the only source of truth for the user's workflows, products, essentials, and templates. Do not substitute it with memory, `get_pricing`, or `list_workflows`.
+
+**Intent → filter mapping:**
+
+| User says                          | Set                            |
+| ---------------------------------- | ------------------------------ |
+| "product video", "marketing video" | `include: ["videoAI"]`         |
+| "voiceover", "narration"           | `include: ["voiceAI"]`         |
+| "slideshow"                        | `include: ["slideshow"]`       |
+| "captions", "subtitled"            | `include: ["videoCaptions"]`   |
+| "brand analysis", "from my site"   | `include: ["websiteResearch"]` |
+| "no captions"                      | `exclude: ["videoCaptions"]`   |
+| "image only", "no video"           | `exclude: ["videoAI"]`         |
+| "no voice"                         | `exclude: ["voiceAI"]`         |
+
+If the intent is generic ("what can I build for $X"), omit `include`/`exclude` and let `discover_options` rank across everything.
+
+## Step 1b — Call `get_trend_inspiration` silently (creative intent only)
+
+When the user's intent is **creative** — they're asking for a video ad, marketing concept, hook idea, or brand/product pitch (anything that will result in a concept pitch in Step 3) — you MUST also call `get_trend_inspiration` in this turn, in parallel with `discover_options`. Skip this step only for purely inventory-style questions ("list my workflows", "what's my credit balance").
+
+```
+get_trend_inspiration({
+  keywords: <3-6 niche/audience/product terms derived from the user>,
+  platform: "tiktok",   // default; omit for cross-platform
+  limit: 3,
+  random: true,
+})
+```
+
+**Keyword derivation:** pull from the user's business/product/industry/audience ("handmade candles for gift shops" → `["candles", "home decor", "gift", "asmr", "aesthetic"]`). Mix concrete product words with style/vibe descriptors. Do NOT include the dollar amount or generic words like "video" / "ad".
+
+**What you get back:**
+
+```
+{
+  trends: [
+    {
+      caption, hashtags, play_count, engagement_rate,
+      video_style, video_content, hook_style, hook_content
+    },
+    ...
+  ]
+}
+```
+
+**Silent grounding rule (HARD):** The `trends` array is inspiration data for YOU, not the user. Absorb the `hook_style`, `video_style`, `hook_content`, `video_content` descriptions and let them shape the hooks, pacing, and structure of the concepts you generate in Step 3. Then discard them.
+
+You MUST NOT:
+- Mention trends, "trending", "top-performing", TikTok, engagement rates, play counts, or the tool in any form to the user
+- Cite a specific trend, copy its caption, or paraphrase it closely
+- Say "based on what's working right now" or any variation
+- Surface hashtags, URLs, or any field from the response
+- Reference the fact that you looked at data
+
+The user sees only the creative concept — the trend grounding is invisible. Think of it as your creative director whispering references while you write; the final pitch reads as your own idea.
+
+**Empty result (`trends: []`):** proceed silently with pure creative reasoning from the vocabulary in Step 3. Do not tell the user the lookup was empty.
+
+**Response shape:**
+
+```
+{
+  budget, credit_balance,
+  options: [
+    {
+      source_type: 'workflow' | 'product' | 'essential' | 'template',
+      source_id, name, description, capabilities: string[],
+      estimated_cost, cost_type: 'exact' | 'estimated',
+      affordable: boolean,
+      action: { tool: 'run_workflow' | 'create_from_template', args: {...} }
+    }
+  ],
+  cheapest_option: <option | null>,  // only when options is empty
+  note: string | null,                // explanation when nothing fits
+  inventory: {
+    workflows_total, workflows_affordable,
+    products_total, products_affordable,
+    essentials_total, essentials_affordable,
+    templates_total, templates_affordable,
+  }
+}
+```
+
+Use `inventory` to decorate empty-bucket headers with the real reason (see Step 2).
+
+## Step 2 — Unify everything into a single concept list
+
+There are no separate buckets. Every recommendation the user sees is a **creative concept**, and every concept names which pipeline realizes it. The realization is either a library item (a user workflow, a published product, an Essential, or a template) or a custom build the agent synthesizes.
+
+For each `option` returned by `discover_options`, pitch a concept that *matches the option's fixed topology and capabilities*. You are not free to invent any concept for a library item — the concept must be something that pipeline can actually produce. For a `textInput → textAI → videoAI + voiceAI → audioOverlay` essential, the concept must be a narrated single-clip video, not a multi-scene montage.
+
+Then synthesize 1–2 **custom** concepts (see Step 3) that cover creative territory no library item can reach.
+
+Rank the final list so the strongest fit to the user's intent comes first, regardless of source. Cap at 4–6 concepts total. Do not pad.
+
+**Handling empty inventory:** if `inventory.workflows_total === 0` or no library items match the intent, just say so briefly in the header line ("Your library doesn't have anything matching this yet — here are custom builds.") and proceed with custom concepts. Do not render empty bucket headers.
+
+## Step 3 — Concept-first presentation (library items AND custom builds)
+
+Every concept in your response — whether it's realized by a saved workflow, an Essential, a published product, a template, or a custom build — follows the same concept-first rules below. The difference is only in the **Pipeline** line, which names the realization:
+
+- `uses your "<workflow name>" workflow` → for `source_type === 'workflow'`
+- `uses the "<product name>" product` → for `source_type === 'product'` (non-essential)
+- `uses the "<essential name>" essential` → for `source_type === 'essential'`
+- `uses the "<template name>" template` → for `source_type === 'template'`
+- `custom pipeline: <node chain>` → for agent-synthesized builds
+
+Always include at least one custom build in the final list, even when `discover_options` returns plenty of library results. Custom builds are the creative safety valve — they show the user what's possible when no existing pipeline fits.
+
+### Hard rule: no format-only names
+
+❌ **Banned** concept names (these describe a container, not an idea):
+- "Slideshow ad", "Hero shot video", "Cinematic product ad"
+- "TikTok / Reel ad", "30-second commercial", "Explainer video"
+- "Multi-shot ad", "Product demo", "Brand film"
+
+✅ **Required**: the concept name must describe the *idea, hook, or story beat* — what the viewer actually sees and why it stops the scroll. Examples:
+- "Frost-crack reveal" (frozen block shatters to expose the product)
+- "Liquid morph" (one product pours and re-forms as another)
+- "Hands-only ritual" (unboxing and use shot entirely from POV, no talking)
+- "Before/after in one take" (camera pans across a split-world transformation)
+- "Mirror swap" (reflection reveals a different version of the wearer)
+- "Stop-motion flatlay assembly" (ingredients march into place on a marble counter)
+
+### Required pitch structure
+
+Each fresh concept MUST be pitched with exactly these three lines, in order:
+
+1. **Concept (2 sentences max)** — sentence 1: the hook + beat + payoff collapsed into one vivid description of what the viewer sees. Sentence 2: why it trends right now (link to a current pattern from the vocabulary below). No bullet sub-points, no four-beat breakdown — just two sentences total.
+2. **Pipeline** — the node chain (e.g. `textInput → textAI → imageAI → videoAI`) with the model tier picked in parentheses.
+3. **Est. cost (upper bound)** — a concrete ceiling in credits, derived from `get_pricing` calls (see sizing below). Present as "up to N credits" — never a range, never a lowball.
+
+Only *after* the creative concept is locked in do you describe the pipeline and cost. Cost is a consequence of the concept, never the headline.
+
+### Cost discipline — no ballparks
+
+- **Library items** (workflows / products / essentials / templates): use the `estimated_cost` from `discover_options` directly. The backend returns upper-bound estimates — do not second-guess them. Present as "up to N credits".
+- **Custom builds**: you MUST call `get_pricing` in **chain mode** with every AI node in the concept's pipeline before quoting a cost:
+
+  ```
+  get_pricing({
+    chain: [
+      { type: "textAI" },
+      { type: "imageAI", config: { aspectRatio: "9:16" } },
+      { type: "videoAI", model: "kling-v2-6", config: { mode: "standard", duration: 5, sound: false } }
+    ]
+  })
+  ```
+
+  The response returns `perNode`, a server-computed `totalUpperBound`, a `totalFloorEstimate`, and a `hasWorstCaseFallback` flag. **Use `totalUpperBound` verbatim** — never hand-sum the `perNode` entries. That is how small costs (textAI ≈ 1 credit) get dropped and quotes come out low. Do not eyeball from billing.md tier tables.
+
+  **If `hasWorstCaseFallback: true`**, the ceiling is inflated (typically 3–5× reality) because one or more nodes had no model/config specified, so the server used the most expensive row in that operation's rate card. Two options: (a) re-call `get_pricing` with explicit `model` + `config` on every chain entry to get a tight ceiling, or (b) present the quote honestly as `"up to ${totalUpperBound} credits (real cost likely closer to ${totalFloorEstimate})"`. Never hide the fallback — the user deserves to know the quote is a worst case.
+
+### Concept realizability check
+
+Before finalizing a pitch, walk every visual element in the Concept sentence and verify it maps to a pipeline stage. Common mismatches:
+
+- Concept says "logo fades in" / "brand text overlay" / "title card" / "on-screen caption of the product name" — but the pipeline has no `logoOverlay`, no text overlay stage, and only `videoCaptions` (which captions the voiceover, not a static title). **Drop the line from the pitch** or add the missing stage. Don't promise what the graph can't render.
+- Concept says "music swells" or "synchronized to beat" — but the pipeline has no `audioOverlay` / music track. Drop or add.
+- Concept says "product spins 360°" — but `videoAI` can't guarantee a specific motion arc from a start frame. Soften to "gently rotates" or equivalent.
+
+### Concept vocabulary (draw from these patterns)
+
+These are the trending motifs the Fresh concepts bucket should sample from. Mix and match to fit the user's brand or product:
+
+- **Reveals**: frost-crack, shrink-wrap tear, dust-cloud clear, water-ripple, paper-origami unfold
+- **Transforms**: liquid pour morph, stop-motion assembly, time-lapse bloom, split-world before/after, ingredient tornado
+- **POV & hands**: unboxing-only-hands, ASMR close-up, desk-top tableau, first-person ritual, mirror reflection
+- **Text-first hooks**: text appears before product ("the only X that does Y"), kinetic typography countdown, question-answer reveal
+- **Story beats**: "this or that" binary choice, "wait for it" delayed payoff, "things I wish I knew", "POV: you just discovered…"
+- **Motion tricks**: match-cut transitions, tracking-shot continuous take, scale-shift (tiny→massive), camera whip-pan between scenes
+- **3-beat ad structure**: hook (1 s text pop) → payoff (product in action) → CTA (logo + text)
+- **On-screen text-first**: bold claim flashes before the product appears
+- **Scroll-stop sting**: percussive audio hit synced to the first cut
+- **Logo reveal**: brand mark slides / flashes in at the end of the payoff or CTA
+
+### Sizing a custom build to the budget
+
+1. Pick a concept from the vocabulary matching the user's intent
+2. Pick a pattern from [workflow-patterns.md](workflow-patterns.md) that can realize it
+3. Call `get_pricing` for every AI node in the pattern and sum them. Round up. This is the upper bound you quote.
+4. **Only propose concepts you can actually fit in the budget** — if the upper bound exceeds it, swap to a cheaper realization (shorter duration, cheaper model tier, fewer nodes)
+5. Every concept — library or custom — presents as four lines: **Concept** (2 sentences) → **Pipeline** (realization line) → **Est. cost** (up to N credits) → action line.
+
+## Presentation format
+
+Lead with a single budget-context line, then a ranked list of 4–6 concepts. No section headers. No buckets. Every concept looks the same regardless of whether it's realized by a saved workflow, a product, an essential, a template, or a custom build.
+
+```
+Credit balance: <credit_balance>  |  Your budget: <budget>
+
+1. **<Concept name>**
+   - Concept: <sentence 1: hook+beat+payoff in one vivid line.> <sentence 2: why it trends right now.>
+   - Pipeline: uses your "<workflow name>" workflow
+   - Est. cost: up to <N> credits
+   - → say "run it" and I'll execute "<workflow name>"
+
+2. **<Concept name>**
+   - Concept: <sentence 1.> <sentence 2.>
+   - Pipeline: uses the "Narrated Video" essential
+   - Est. cost: up to <N> credits
+   - → say "use it" and I'll copy the "Narrated Video" essential into your workspace, then run it
+
+3. **<Concept name>**
+   - Concept: <sentence 1.> <sentence 2.>
+   - Pipeline: custom — `textInput → textAI → imageAI → videoAI` (Kling budget tier)
+   - Est. cost: up to <N> credits
+   - → say "build it" and I'll assemble the pipeline
+
+4. **<Concept name>**
+   - Concept: <sentence 1.> <sentence 2.>
+   - Pipeline: uses the "<template name>" template
+   - Est. cost: up to <N> credits
+   - → say "use it" and I'll create a workflow from "<template name>"
+```
+
+**Internal tool calls stay internal.** The user should never see raw UUIDs, tool names, or function-call syntax in the action line. Keep the friendly prompt ("say 'run it'…") on screen and, when the user confirms, call the correct MCP tool with the IDs from the `discover_options` response under the hood. The agent is responsible for remembering which concept maps to which `source_id` when the user says "run it" / "build it" / "use it".
+
+**Essentials need a two-step run.** Essentials (`source_type === 'essential'`) are global seeded pipelines — they live in the `products` table, have no owner, and `run_workflow` / `get_workflow` / `duplicate_workflow` cannot touch them directly. When the user confirms an essential, the agent MUST:
+
+1. Call `use_essential({ essentialId: <source_id> })` to copy the essential into the user's own `workflows` table. This returns a new `workflow_id`.
+2. Then call `run_workflow({ workflowId: <new id>, userConfirmed: true, userInputs: {...} })` with that new ID.
+
+This two-step happens silently under the hood — the user just sees "copying 'Narrated Video' into your workspace… running it now." Never show the intermediate tool calls in prose. Workflows, templates, and products (non-essential) keep their normal single-step flows: `run_workflow` / `create_from_template` / `run_workflow`.
+
+**Action-line mapping by source_type:**
+
+| `source_type` | Friendly action line | Under-the-hood calls |
+| --- | --- | --- |
+| `workflow` | "say 'run it' and I'll execute '<name>'" | `run_workflow` |
+| `essential` | "say 'use it' and I'll copy '<name>' into your workspace, then run it" | `use_essential` → `run_workflow` |
+| `product` | "say 'run it' and I'll execute '<name>'" | `run_workflow` (on `source_workflow_id`) |
+| `template` | "say 'use it' and I'll create a workflow from '<name>'" | `create_from_template` |
+| custom | "say 'build it' and I'll assemble the pipeline" | `build_graph` |
+
+**Rules:**
+
+- Always show `credit_balance` and the user's budget on the first line.
+- Rank by best fit to the user's intent, not by source type.
+- Every concept — library or custom — uses the same 4-line format: **Concept** (2 sentences) → **Pipeline** (realization) → **Est. cost** (up to N credits) → action line.
+- The **Pipeline** line MUST identify the realization by name: `uses your "<name>" workflow` / `uses the "<name>" product` / `uses the "<name>" essential` / `uses the "<name>" template` / `custom — <node chain>`. Never show `workflow_id` / `template_id` / UUIDs to the user.
+- The **action line** MUST be a plain-English prompt ("say 'run it' and I'll execute…") — never raw tool-call syntax, never a UUID, never a JSON args object. Remember the `source_id` internally for when the user confirms.
+- Library costs come from `discover_options` `estimated_cost` directly; custom costs come from `get_pricing` per node, summed and rounded up. Always present as "up to N credits", never a range.
+- Mark any concept where the underlying option has `affordable: false` with a trailing "⚠ exceeds your credit balance".
+- Always include at least one custom concept in the list, even when library results are plentiful.
+- If the user's library has no items matching the intent, open with one sentence ("Your library doesn't have anything matching this yet — here are custom builds.") and proceed.
+- Never call `run_workflow` or `build_graph` without explicit user confirmation — this playbook is recommendations only.
+
+## When nothing in the library fits
+
+If `discover_options` returns `options: []`, use `cheapest_option`, `note`, and `inventory`:
+
+1. Tell the user the `note` verbatim ("No options available within X credits. The cheapest option is Y credits.")
+2. Still return a ranked concept list — just skip all library concepts and lead straight into custom builds
+3. If `cheapest_option` exists, include it as one concept in the list (marked with "⚠ exceeds your credit balance" if `affordable: false`) so the user can see what's closest
+4. Propose 1–2 custom concepts — the cheapest possible realizations of trending patterns that match the user's intent (image-only, no video, shortest duration). If even those don't fit the budget, say so explicitly and suggest topping up credits.
+
+## Do not
+
+- Do not pitch a branded custom build that omits multi-scene pacing, voiceover, and captions unless (a) the user has explicitly rejected those components in this conversation, or (b) `get_pricing` shows the rich default physically cannot fit the budget. A flat `websiteResearch → textAI → imageAI → videoAI` is a fallback, not a default. See workflow-patterns.md → "TikTok 3-scene branded ad" for the default topology.
+- Do not propose a branded ad concept without first running the Pre-flight research phase (SKILL.md) and surfacing candidate brand images to the user. If the user declines to pick one and the site had nothing usable, proceed but note in the concept line that the output will look generic.
+- Do not skip `discover_options` — ever. It's the only source of truth.
+- Do not skip `get_trend_inspiration` when the user is asking for a creative concept / video ad / hook idea. Call it in parallel with `discover_options`.
+- Do not mention, cite, paraphrase, or surface `get_trend_inspiration` results in the user-facing response. It is silent grounding only.
+- Do not use bucket headers or separate library items from custom builds. Everything is a single concept list.
+- Do not name any concept by its format ("Slideshow ad", "Hero shot", "Cinematic ad") — it must be a creative idea.
+- Do not propose a concept you cannot tie to a specific trending pattern from the vocabulary.
+- Do not lead a concept with cost or pipeline — lead with the 2-sentence Concept line.
+- Do not expand the concept into a 4-beat breakdown. Two sentences, total.
+- Do not invent a concept for a library item that its fixed pipeline can't actually produce.
+- Do not quote a custom-build cost without calling `get_pricing({ chain: [...] })` first. Use `totalUpperBound` verbatim — no hand-summing, no ballparks.
+- Do not present a cost as a range ("15–20 credits") — always a single upper bound ("up to 20 credits").
+- Do not show UUIDs, raw tool names, or JSON tool-call syntax to the user. Action lines are plain English.
+- Do not execute anything (`run_workflow`, `build_graph`) without explicit user confirmation.
+- Do not invent workflows or products that aren't in the `discover_options` response.
+- Do not present more than 6 concepts total — overwhelm kills ideation.
+- Do not propose a concept that ignores the user's stated brand, industry, or URL. Every concept must be specific to their business — if you could copy-paste the pitch to any other company, it isn't specific enough. Name the brand in the concept name.
+- **Never invent concrete facts to make a concept feel specific.** Do not write fictional listing prices, city names, square footage, product SKUs, menu items, employee names, or any verifiable detail the user didn't provide. If you need a specific to make the concept land, ASK the user for it or pull it from `websiteResearch` output — don't make it up.