voxflow 1.14.0 → 1.15.1

package/skills/podcast/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: podcast
+description: Use when the user wants to produce a multi-speaker AI podcast from a topic, URL, or script — covers the full CLI workflow from LLM dialogue generation to per-speaker TTS synthesis and final audio export (MP3/WAV).
+---
+
+# VoxFlow Podcast Skill
+
+Generate multi-speaker AI podcasts entirely from the command line. Sister skills:
+
+- Simple TTS / narration / voice search → `voxflow` (hub)
+- Short videos / AI clips / knowledge cards → `voxflow:video`
+- Transcribe / translate subtitles / dub → `voxflow:transcribe`
+
+## Prerequisites
+
+- Node.js `^20.19.0 || >=22.12.0`
+- `npm install -g voxflow` then `voxflow login`
+- VoxFlow account (free tier: 10K quota/month)
+
+**No API keys needed** — all auth goes through `voxflow login`.
+
+## Quick Start
+
+```bash
+# 1. Login (one-time, opens browser)
+voxflow login
+
+# 2. Generate a podcast
+voxflow podcast --topic "AI 时代的程序员出路"
+
+# 3. Output: podcast-2026-03-20T12-00-00.wav + .txt
+```
+
+## Full Workflow
+
+### Step 1: Generate Script Only
+
+```bash
+voxflow podcast \
+  --topic "量子计算入门" \
+  --template tutorial \
+  --colloquial medium \
+  --speakers 2 \
+  --language zh-CN \
+  --format json \
+  --no-tts
+```
+
+Outputs: `podcast-<ts>.txt` + `podcast-<ts>.podcast.json`
+
+### Step 2: Review & Edit
+
+Open `.podcast.json` — it contains structured dialogue, speaker info, quality scores, and voice mappings. Edit as needed.
+
+### Step 3: Synthesize from File
+
+```bash
+voxflow podcast --input podcast-2026-03-20.podcast.json --output final.wav
+```
+
+### One-Shot (generate + synthesize)
+
+```bash
+voxflow podcast \
+  --topic "Web3 的未来" \
+  --engine ai-sdk \
+  --colloquial high \
+  --speakers 3 \
+  --output web3-podcast.wav
+```
+
+## Parameters
+
+| Flag | Values | Default | Description |
+|------|--------|---------|-------------|
+| `--topic` | text | tech trends | Podcast topic or prompt |
+| `--engine` | auto, legacy, ai-sdk | auto (→ ai-sdk) | Generation engine |
+| `--template` | interview, discussion, news, story, tutorial | interview | Podcast template |
+| `--colloquial` | low, medium, high | medium | Conversational tone level |
+| `--speakers` | 1, 2, 3 | 2 | Number of speakers |
+| `--language` | zh-CN, en, ja | zh-CN | Output language |
+| `--length` | short, medium, long | medium | Script length |
+| `--format` | json | — | Also output .podcast.json |
+| `--input` | file path | — | Load .podcast.json for synthesis |
+| `--no-tts` | flag | false | Script only, skip TTS |
+| `--speed` | 0.5-2.0 | 1.0 | TTS playback speed |
+| `--silence` | 0-5.0 | 0.5 | Gap between segments (sec) |
+| `--output` | file path | auto | Output file path |
+
+## Engine Comparison
+
+| Feature | legacy | ai-sdk |
+|---------|--------|--------|
+| Structured output | No | Yes (JSON) |
+| Quality scoring | No | Yes (1-10) |
+| Colloquial control | No | 3 levels |
+| Intent tagging | No | Yes |
+| Speaker metadata | Partial | Full |
+| Multi-language | Chinese only | zh/en/ja |
+
+## Templates
+
+- **interview** — Host + Guest deep conversation
+- **discussion** — Roundtable multi-person discussion
+- **news** — Professional news briefing
+- **story** — Multi-character story narration
+- **tutorial** — Teacher + Student educational dialogue
+
+## Quota Cost
+
+| Operation | Cost |
+|-----------|------|
+| Script generation (medium, ~16 turns) | 2,000 |
+| TTS per turn (native pause voice) | 50 |
+| TTS per chunk (splice fallback voice) | 50 |
+
+**Per-turn TTS call count depends on voice**: voices flagged `nativePauseSupported: true` (most podcast voices) take 1 TTS call per turn — TRTC honors `<|break|>` / `<|s_break|>` markers natively (~250-430ms inserted). Voices that haven't been verified (e.g. 旁白 narration voices) fall back to client-side splice = N calls per turn.
+
+Typical medium podcast (16 turns, all native voices) ≈ 16 × 50 + 2,000 = 2,800 quota — Free tier (10K/month) covers ~3 medium podcasts. **Tip**: if you already have a script, pass `--script my.json` to skip the 2,000 LLM step entirely. Mixed-voice podcasts cost slightly more if they include non-native voices.
+
+## Examples
+
+```bash
+# English tech podcast
+voxflow podcast --topic "AI ethics debate" --language en --template discussion
+
+# Quick news briefing (short)
+voxflow podcast --topic "本周科技新闻" --template news --length short
+
+# Casual chat with high colloquial level
+voxflow podcast --topic "程序员加班那些事" --colloquial high
+
+# JSON export for editing
+voxflow podcast --topic "创业故事" --format json --no-tts
+
+# Synthesize edited script
+voxflow podcast --input edited-podcast.podcast.json --speed 1.1
+```
+
+## Rules
+
+1. **Check quota first** — medium podcast ≈ 5K. Run `voxflow status` before generation.
+2. **Iterate on the script** — use `--no-tts --format json` to inspect dialogue before paying for TTS.
+3. **Voice mapping** — for ai-sdk engine, the .podcast.json includes per-speaker voice IDs. Edit them before re-running with `--input`.
+4. **Auto-play** when done: `open podcast-*.wav`.
+

package/skills/slice/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: slice
+description: "Use when the user wants to turn a long article / note / report into a vertical 1080×1920 card video — VoxFlow Slice. 13 themes — paper-slide (纸面), editorial-mag (编辑刊), bold-poster (大字海报), notion-card (Notion 卡), brutalist (粗野), glass-dark (玻璃夜), editorial-stencil (编辑·海报), broadsheet (财经刊), blueprint (蓝晒图), daisy-pastel (雏菊), showa-catalog (昭和目录), photo-feature (摄影刊), atmospheric (深夜刊). Triggers — Slice / slice video / 切片视频 / 文章转视频 / 知识卡片视频 / 抖音知识号 / 小红书图文转视频 / 知乎长文转视频 / 公众号转视频 / PaperSlide / paperslide / paper-slide (legacy name)."
+---
+
+# Slice Skill
+
+Turn an article, note, paper, or rough topic into a vertical 1080×1920 card video — narrated, paginated to TTS rhythm, with 13 visual themes covering 抖音 / 小红书 / 知乎 / X / 公众号 / 飞书 / TikTok / LinkedIn / 雪球 / 微博 / 即刻 / B 站 / 播客.
+
+> **Renamed from `paper-slide` → `slice`.** The product is now called **Slice** (`voxflow.studio/apps/slice`); the legacy slug is no longer registered. `paper-slide` survives only as one of the 13 theme ids.
+
+## Pick the Route
+
+| Context | Route | Notes |
+|---|---|---|
+| User wants the deck JSON (no render) — fast, scriptable, pipeable | **CLI**: `voxflow slice <article.md> --theme <id>` | Hits `/api/slice/deck` directly (200 quota; renamed from `/api/paper-slide/slice` in #3307 Deploy 2). Returns the canonical 5–8 card deck JSON validated by the same backend the web app uses, all 13 themes accepted. No mp4 — pipe `--json` into custom tools, the local Remotion composition (contributors), or paste into the web app for rendering. |
+| User is iterating on a deck — multi-round edits to copy/structure before committing to a render | **CLI**: `voxflow slice stage <deck.json>` | Boots a localhost preview page (no quota cost) that hot-reloads on every save of the deck JSON. Useful loop: `voxflow slice ... -o deck.json` → `voxflow slice stage deck.json` → tweak prompt → re-run slice → preview updates instantly. See **Stage Route** below. |
+| User wants a finished mp4 + cover (default consumer flow) | **Web app**: `https://voxflow.studio/apps/slice` | The only place that runs the **exact** 6 Slice themes end-to-end. Free tier ships 9:16 mp4 + multi-aspect cover (9:16/3:4/1:1). |
+| User wants a similar-looking video offline via CLI but the deck-only `voxflow slice` isn't enough | `voxflow present` or `voxflow picstory --style sketchnote` | **Approximation only.** Different visual schemes; cannot output Slice's `editorial-mag` / `notion-card` / `brutalist` / `glass-dark` themes. See **CLI Approximation** below. |
+| Local checkout has `video-present/src/compositions/PaperSlide` (VoxFlow contributors only) | Local Remotion experiment script | See **Local Remotion Route**. Note: experiment script only exercises the original `paper-slide` composition; other 12 themes render via cloud worker only. |
+| User only wants strategy or copy | Produce the deck JSON via `voxflow slice` (or by hand following the schema); tell them which renderer to use. | The deck schema is renderer-agnostic; same JSON renders in any theme. |
+| User asks to open-source / package | Keep private APIs, tokens, generated audio, MP4 outputs out of the skill package. | |
+
+## Workflow
+
+1. **Pick a theme that matches the platform.** Read `references/themes.md` once — it lists all 13 themes, their visual signature, and which platform / content type each one fits. Don't default to `paper-slide` for everything.
+2. **Pick a scenario.** Concrete use case beats generic filler: paper digest, product update, meeting closeout, career advice, founder lesson, market commentary, incident review.
+3. **Write a tight deck.** 4-6 cards: one title + 3-5 body. One idea per body card. Captions short enough to fit one line.
+4. **Choose visuals from controlled keywords.** Don't search the web or generate random images at render time — pick a canonical `figureKeyword`; the renderer maps it to a local hand-drawn scene / pose / icon. (See `references/deck-schema.md`.)
+5. **Render via the chosen route.** Web app for exact themes; CLI for approximation; local script for contributors.
+6. **Verify the artifact.** Check duration, dimensions (1080×1920), and at least one title frame + one body frame before reporting done.
+7. **Report paths.** Absolute paths to MP4 / posters / props.
+
+Read `references/deck-schema.md` when writing deck JSON, picking keywords, or debugging layout. Read `references/example-decks.md` for seed decks. Read `references/themes.md` when picking a theme or explaining theme tradeoffs.
+
+## Web App Route (default — works for everyone)
+
+```
+https://voxflow.studio/apps/slice
+```
+
+Workflow:
+
+1. Paste the article / note into the hero composer.
+2. AI slices it into 5–8 cards.
+3. Pick a theme (13 options — see `references/themes.md`) + a voice (6 production voices: 男主播 / 霸总男声 / 闲聊男声 / 小美 / 小心 / 小徐).
+4. Render → 1080×1920 mp4 + multi-aspect cover (9:16 / 3:4 / 1:1).
+
+Tell the user this is the **only** route that produces the exact Slice render for all 13 themes — they're private Remotion compositions, not shipped with the CLI.
+
+## CLI Deck Route (`voxflow slice`)
+
+For users who want the structured deck JSON without the render — fast (one round-trip, 200 quota), pipeable, theme-aware. Hits the same `/api/slice/deck` backend the web app uses, so the deck shape is canonical.
+
+```bash
+voxflow slice article.md                                  # default theme: paper-slide
+voxflow slice article.md --theme editorial-mag -o deck.json
+voxflow slice --text "long article ..." --theme bold-poster --json | jq .deck
+```
+
+When to use this route:
+
+- The user wants to inspect / iterate on the AI's slicing quality before committing to a render.
+- The user wants to paste the deck into the web app's "import deck" flow to render with a different theme.
+- The user is a contributor with the private `video-present/src/compositions/PaperSlide` Remotion composition and wants to render the deck locally — `voxflow slice ... --json -o props.json` then feed `props.json` into the experiment script.
+- The user is building automation that needs structured output (e.g. publishing knowledge cards as text on Twitter / 即刻 from `deck.cards[*].caption + narration`).
+
+Limits:
+
+- No mp4. The cloud renderer that produces the 1080×1920 video lives in the web app.
+- No TTS. Pair `voxflow slice` with `voxflow narrate` if you want per-card audio without rendering.
+
+## Stage Route — `voxflow slice stage` (iteration preview)
+
+For the human-in-the-loop iteration phase **before** committing to a cloud render. Stage spins up a localhost HTTP server with hot reload — every save of the deck JSON updates the page instantly. No quota cost, no network round-trip.
+
+```bash
+voxflow slice deck.md -o deck.json     # 1. produce a deck (200 quota)
+voxflow slice stage deck.json          # 2. open localhost preview (free)
+                                       # 3. edit deck.json by hand or re-run slice
+                                       # 4. preview hot-reloads on save
+```
+
+Want a no-quota, no-login starter? Use the bundled sample directly:
+
+```bash
+voxflow slice stage examples/11-slice-stage/sample-deck.json
+```
+
+Flags:
+
+```
+voxflow slice stage <deck.json> [--port <n>] [--theme <id>] [--no-open]
+  --port      Default 5180. Auto-skips +1 up to 5189 on conflict.
+  --theme     Lock the preview to one theme (must be one of the 13 valid ids).
+  --no-open   Don't auto-launch the browser (CI / SSH / agent environments).
+```
+
+When to use Stage:
+
+- The user is in a multi-round editing loop — copy tweaks, card re-ordering, theme A/B — and reopening the mp4 each iteration is expensive friction.
+- The user wants to publish individual cards as plain text on text-first platforms (X / Twitter / 即刻 / Threads / Mastodon / blog comments). Stage gives each card a "Copy text" button (title + caption + narration), and the deck-level toolbar offers "Copy JSON / Download .json / Copy as Markdown" for pasting into Notion / blog / 飞书. Image / carousel exports for 小红书 / 微博 / 公众号 头图 land in a future Phase once per-card stills are available.
+- AI-driven loops where the agent regenerates `deck.json` and the human reviews via browser — the page updates without the agent having to re-print paths.
+
+### Text export utilities (Phase 1.4 text-only)
+
+The Stage UI ships text-first export controls so cards can be reused on text-only platforms without paying for a full render:
+
+- **Per-card "Copy text"** — click the small button on any card → clipboard gets `{title}\n\n{caption (if distinct)}\n\n{narration}` (trimmed). Drop into a tweet, 即刻 post, blog snippet.
+- **Deck toolbar — "Copy JSON"** — copies the full deck JSON to clipboard (for piping into custom tools / sharing with another agent / saving a snapshot).
+- **Deck toolbar — "Download .json"** — saves the deck as `<seriesTitle>.json` (filename auto-sanitised, capped at 60 chars + `.json`).
+- **Deck toolbar — "Copy as Markdown"** — formats the whole deck as Markdown (H1 = seriesTitle, H2 per card, narration as blockquote). Paste into Notion / blog editor / 飞书 docs.
+
+Formatters live in `lib/stage-core/deck-format.js` (`formatCardAsText`, `formatDeckAsMarkdown`, `suggestDeckFilename`) and are unit-tested in `tests/deck-format.test.js`. Their source is stringified into the served HTML via `Function.prototype.toString()` so the browser executes the *same* code the tests cover — single source of truth, no double maintenance.
+
+**Image / MP4 carousel exports** for 小红书 / 微博 / 公众号 头图 are NOT in Phase 1.4 text-only. Those land in a future Phase once `renderStill` per-card thumbnails are available (they require a backend Remotion endpoint that doesn't exist yet).
+
+What Stage is NOT:
+
+- Not a full Remotion preview yet. MVP shows deck structure (cards + JSON); cloud-rendered theme thumbnails arrive in Phase 1.3 via `renderStill`.
+- Not a substitute for the full render's pixels — themes are server-side compositions. Stage previews the **deck text**, not the final video frames.
+
+### Edit-with-AI loop (the actual iteration workflow)
+
+Stage doesn't try to be Cursor — it's a **visual feedback closer** that hands prompts to whatever AI tool the user already has open (Claude Code, Cursor, ChatGPT, anything). Two affordances cover the whole edit loop:
+
+| Intent | UX | Output |
+|---|---|---|
+| Whole-card rewrite ("regen this card, keep the rest") | Hover the card → corner button **Edit with AI** | Modal with a prompt: file path + `cards[N]` JSON snippet + `<your instruction>` slot |
+| Local phrase rewrite ("just this phrase is off") | Select text inside a card → floating **Edit selection with AI** button appears | Modal with a prompt: file path + the exact selected substring quoted + full card JSON for context |
+
+The user types the instruction (e.g. "shorten to 12 chars, more visceral"), clicks **Copy prompt**, pastes into their AI. The AI uses its native file-edit tools (Claude Code's Edit, Cursor's Apply, etc.) to rewrite the file. Stage's SSE watcher hot-reloads the preview within ~150 ms. Loop until satisfied.
+
+Why this design and not an embedded chat / MCP server: see [#3330](https://github.com/VoxFlowStudio/FlowStudio/issues/3330) for the full design rationale (universal copy-paste vs. Claude Code-only MCP, cost vs. coverage tradeoff, future MCP upgrade path conditional on usage telemetry).
+
+## CLI Approximation Route (full mp4 fallback)
+
+If the user **must** have an mp4 from the CLI alone (no web app, no contributor Remotion access), fall back to `voxflow present` or `voxflow picstory` — they cover the same article-to-video shape but with their own visual schemes, not the exact 13 Slice themes.
+
+```bash
+voxflow present --text "paste article or summary" --style editorial --output slice-approx.mp4
+voxflow picstory --topic "topic" --style sketchnote --scenes 4 --output slice-sketch.mp4
+```
+
+Closest CLI scheme per Slice theme:
+
+| Slice theme | Closest CLI route |
+|---|---|
+| paper-slide | `voxflow picstory --style sketchnote` |
+| editorial-mag | `voxflow present --style editorial` |
+| bold-poster | `voxflow present --style brutalist` (closest weight) |
+| notion-card | `voxflow present --style minimal` |
+| brutalist | `voxflow present --style brutalist` |
+| glass-dark | `voxflow present --style noir` or `--style aurora` |
+| editorial-stencil | `voxflow present --style editorial` (no letterbox / dual-tone equivalent) |
+| broadsheet | `voxflow present --style editorial` (no FT salmon palette) |
+| blueprint | `voxflow picstory --style chalkboard` (closest grid/diagram feel) |
+| daisy-pastel | `voxflow picstory --style sketchnote` (no pastel illustration equivalent) |
+| showa-catalog | `voxflow picstory --style vintage_newspaper` (no city-pop equivalent) |
+| photo-feature | `voxflow picstory --style photo` (photo-feature needs imageUrl per card — see deck-schema) |
+| atmospheric | `voxflow present --style noir` |
+
+Always tell the user: "This is a Slice-adjacent draft. The exact 13-theme renderer lives on `voxflow.studio/apps/slice`."
+
+## Local Remotion Route (contributors only)
+
+**Skip if `video-present/src/compositions/PaperSlide` is not in your checkout** — it's private code; npm / skills users don't have it.
+
+From the contributor checkout root:
+
+```bash
+cd video-present
+node scripts/paper-slide-experiments.mjs
+```
+
+Render a subset:
+
+```bash
+cd video-present
+PAPER_SLIDE_EXPERIMENT_FILTER=research-reading node scripts/paper-slide-experiments.mjs
+```
+
+Verify outputs:
+
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,duration \
+  -of default=nw=1 out/paper-slide-experiments/research-reading.mp4
+
+ffmpeg -y -hide_banner -loglevel error -ss 9 \
+  -i out/paper-slide-experiments/research-reading.mp4 \
+  -frames:v 1 -q:v 2 out/paper-slide-experiments/research-reading-body.jpg
+```
+
+Expected: `1080×1920`, 20-35 seconds, no black flashes, no caption overflow, figure not clipped.
+
+## Deck Writing Rules (apply across all 13 themes)
+
+- **Title card**: hook, contrast, or promise. Avoid abstract labels like "Introduction".
+- **Body card**: one idea only. Caption usually under 16 Chinese chars or 7 English words.
+- **Narration**: conversational, 25-60 Chinese chars per body card.
+- **Scene keywords** (prefer when they fit): `problem-framing`, `evidence-board`, `customer-pain`, `timeline-review`, `owner-deadline`, `risk-guardrail`, `cashflow-ledger`, `team-alignment`, `before-after`, `learning-loop`, `decision-fork`, `growth-system`.
+- **Figure / icon keywords** (visual accents): `thinking`, `running`, `climbing`, `stuck`, `celebrating`, `briefcase`, `users`, `target`, `clock`, `flame`, `lightbulb`, `chart-bar`.
+- **Vary adjacent visuals.** Don't use `thinking` on every card.
+- **Theme is independent of deck content** — the same deck JSON renders in any of the 13 themes; pick the theme based on platform / mood, not content. Exception: `photo-feature` and `atmospheric` use each card's `imageUrl` as a backdrop and degrade to an SVG stub when missing — see `references/deck-schema.md`.

package/skills/slice/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Slice"
+  short_description: "Article → vertical card video (13 themes spanning editorial / poster / brutalist / glass / blueprint / pastel / showa / photo / atmospheric)"
+  default_prompt: "Use $slice to turn this article into a Slice card video — pick a theme that fits the platform (抖音 / 知乎 / X / 公众号 / 飞书 / TikTok / LinkedIn / 雪球 / 微博 / 即刻 / B 站 / 播客)."

package/skills/slice/references/deck-schema.md

@@ -0,0 +1,183 @@
+# Slice Deck Schema
+
+Use this reference when writing or validating a Slice deck (any of the 13 themes — `paper-slide` / `editorial-mag` / `bold-poster` / `notion-card` / `brutalist` / `glass-dark` / `editorial-stencil` / `broadsheet` / `blueprint` / `daisy-pastel` / `showa-catalog` / `photo-feature` / `atmospheric`).
+
+The deck shape is **theme-agnostic**: same JSON renders in any theme. Pick the theme based on platform / mood, not content. See `themes.md` for theme picker.
+
+## Shape
+
+```json
+{
+  "theme": "paper-slide",
+  "header": "shared top sticker text, <= 22 Chinese chars",
+  "seriesTitle": "series name, no brackets, <= 10 Chinese chars",
+  "seriesTagline": "bottom italic promise, <= 22 Chinese chars",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["line 1 <= 14 Chinese chars", "line 2 <= 14 Chinese chars"],
+      "narration": "opening voiceover"
+    },
+    {
+      "kind": "body",
+      "caption": "one-line punchy caption",
+      "figureKeyword": "canonical keyword",
+      "narration": "spoken explanation",
+      "imageUrl": "https://… (optional, photo-feature / atmospheric only)"
+    }
+  ]
+}
+```
+
+### `imageUrl` (optional body-card field)
+
+Public HTTPS URL of a photograph used as the card's backdrop. Read by the `photo-feature` and `atmospheric` themes; ignored by every other theme.
+
+- If omitted on a `photo-feature` / `atmospheric` card, the renderer falls back to an SVG stub — usable but visually weak. The full per-card photo-upload plumbing (cloud-render side) is still in progress; until it ships, prefer `paper-slide` / `editorial-mag` when you cannot supply a photograph.
+- Other themes treat `imageUrl` as no-op. Safe to include; the validator does not strip it.
+
+For Remotion render props, the worker/local script converts this to:
+
+```json
+{
+  "cards": [
+    {
+      "slide": {
+        "kind": "body",
+        "header": "...",
+        "title": [],
+        "caption": "...",
+        "figureKeyword": "target",
+        "seriesTitle": "...",
+        "seriesTagline": "...",
+        "voiceoverSrc": "paper-slide-experiments/demo/1.mp3"
+      },
+      "durationSec": 5.2
+    }
+  ]
+}
+```
+
+## Keyword Map
+
+Prefer canonical values. Free-form Chinese may work in some local setups, but canonical values make the deck portable and testable.
+
+The LLM does not search the web for visuals in the normal PaperSlide flow. It chooses a controlled `figureKeyword`; the renderer maps that keyword to a local SVG scene, stick-figure pose, or icon. This keeps output deterministic, open-source friendly, and safe to render in CI.
+
+### Scene Keywords
+
+Use these first when the card needs a richer, more literal visual.
+
+| Keyword | Use for |
+|---|---|
+| `problem-framing` | problem definition, real demand, goals, target |
+| `evidence-board` | data, research method, proof, metrics |
+| `customer-pain` | customer/user pain, audience needs |
+| `timeline-review` | timeline, incident review, retrospective |
+| `owner-deadline` | owner, responsibility, delivery date |
+| `risk-guardrail` | risk, warning, limitation, guardrail |
+| `cashflow-ledger` | cash flow, budget, pricing, value |
+| `team-alignment` | team coordination, collaboration, alignment |
+| `before-after` | visible change, product update, comparison |
+| `learning-loop` | learning, output, feedback loop, reuse |
+| `decision-fork` | choice, tradeoff, next step |
+| `growth-system` | growth system, scale, repeatable operating model |
+
+### Figure And Icon Keywords
+
+Use these when a simple visual accent is enough.
+
+| Keyword | Use for |
+|---|---|
+| `climbing` | growth, journey, long-term progress |
+| `thinking` | decisions, reflection, judgment |
+| `stuck` | blockers, failure, bottlenecks |
+| `running` | execution, speed, action |
+| `celebrating` | success, result, victory |
+| `briefcase` | manager, leadership, business |
+| `users` | teams, audience, users, responsibility |
+| `target` | goals, focus, problem framing |
+| `trending-up` | growth, improvement, metrics |
+| `dollar-sign` | money, budget, pricing |
+| `clock` | deadline, time, cadence |
+| `message-circle` | communication, feedback, conversation |
+| `flame` | warning, risk, urgency |
+| `lightbulb` | idea, insight, product change |
+| `chart-bar` | research methods, data, evidence |
+| `rocket` | momentum, launch, motivation |
+| `bell` | reminder, alert, attention |
+
+## Scenario Recipes
+
+### Research / Paper Digest
+
+- Hook: "读一篇论文，先抓这3个问题"
+- Body: problem → method → limitation
+- Good keywords: `problem-framing`, `evidence-board`, `risk-guardrail`
+
+### Product Update
+
+- Hook: "产品更新文案，先回答这3件事"
+- Body: user pain → visible change → next action
+- Good keywords: `customer-pain`, `before-after`, `decision-fork`
+
+### Meeting Closeout
+
+- Hook: "一场有效会议，结尾必须有3样东西"
+- Body: owner → deadline → risk
+- Good keywords: `owner-deadline`, `timeline-review`, `risk-guardrail`
+
+### Career / Management
+
+- Hook: contrast or hidden rule
+- Body: principle → mistake → action
+- Good keywords: `problem-framing`, `timeline-review`, `team-alignment`, `learning-loop`
+
+### Incident Review
+
+- Hook: "事故复盘，别急着追责"
+- Body: timeline → root cause → mechanism owner → warning
+- Good keywords: `timeline-review`, `risk-guardrail`, `owner-deadline`, `evidence-board`
+
+### Sales Enablement
+
+- Hook: "销售话术，别先讲功能"
+- Body: customer pain → proof → pricing/value → next step
+- Good keywords: `customer-pain`, `evidence-board`, `cashflow-ledger`, `decision-fork`
+
+### Founder / Startup Lesson
+
+- Hook: "创业早期，别急着扩张"
+- Body: real demand → cash flow → team pace → system before growth
+- Good keywords: `problem-framing`, `cashflow-ledger`, `team-alignment`, `growth-system`
+
+### Learning Loop
+
+- Hook: "学新东西，别只收藏"
+- Body: question → output → feedback → next action
+- Good keywords: `problem-framing`, `learning-loop`, `risk-guardrail`, `decision-fork`
+
+## Prompt Pattern
+
+Ask the model for strict JSON only:
+
+```text
+把下面内容拆成 PaperSlide 竖屏知识短视频脚本。输出严格 JSON，不要 Markdown。
+要求：1 张 title 卡 + 3 张 body 卡；caption 短、有冲击，不带标点；
+narration 口语化；figureKeyword 从 canonical keyword 表里选，且相邻不重复。
+
+内容：
+---
+...
+---
+```
+
+## Common Failures
+
+| Failure | Fix |
+|---|---|
+| Caption overflows | Shorten to one idea; remove modifiers. |
+| All visuals look the same | Force unique adjacent `figureKeyword`. |
+| Video feels like PPT | Use spoken narration, not bullet summaries. |
+| Product/research content feels generic | Anchor body cards to user pain, method, evidence, risk, or next action. |
+| Open-source package too heavy | Exclude generated media; keep only instructions and small references. |

package/skills/slice/references/example-decks.md

@@ -0,0 +1,108 @@
+# PaperSlide Example Decks
+
+Use these as seed decks. Keep generated videos shorter than 35 seconds unless the user asks for a longer format.
+
+## Research Digest
+
+```json
+{
+  "header": "读一篇论文，先抓这3个问题",
+  "seriesTitle": "论文速读法",
+  "seriesTagline": "把复杂研究，拆成可复述的判断",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["读一篇论文", "先抓这3个问题"],
+      "narration": "读一篇论文，先不要急着看结论，先抓这三个问题。"
+    },
+    {
+      "kind": "body",
+      "caption": "它到底想解决什么问题",
+      "figureKeyword": "problem-framing",
+      "narration": "第一个问题，它到底想解决什么问题。问题错了，后面的模型再漂亮也没用。"
+    },
+    {
+      "kind": "body",
+      "caption": "方法决定结论能不能信",
+      "figureKeyword": "evidence-board",
+      "narration": "第二个问题，方法靠不靠谱。样本、变量和评估方式，决定结论能不能信。"
+    },
+    {
+      "kind": "body",
+      "caption": "最后一定看限制条件",
+      "figureKeyword": "risk-guardrail",
+      "narration": "第三个问题，一定看限制条件。它会告诉你，这个结论在哪些场景不能乱用。"
+    }
+  ]
+}
+```
+
+## Product Update
+
+```json
+{
+  "header": "写产品更新，别只罗列功能",
+  "seriesTitle": "产品表达法",
+  "seriesTagline": "让用户一眼看懂为什么升级",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["产品更新文案", "先回答这3件事"],
+      "narration": "写产品更新文案，不要只罗列功能，先回答这三件事。"
+    },
+    {
+      "kind": "body",
+      "caption": "这次解决了谁的痛点",
+      "figureKeyword": "customer-pain",
+      "narration": "第一，这次更新解决了谁的痛点。用户先关心自己，不关心你的技术细节。"
+    },
+    {
+      "kind": "body",
+      "caption": "变化要能一眼看见",
+      "figureKeyword": "before-after",
+      "narration": "第二，变化要能被一眼看见。截图、对比和一句话，比长说明更有效。"
+    },
+    {
+      "kind": "body",
+      "caption": "下一步动作必须明确",
+      "figureKeyword": "decision-fork",
+      "narration": "第三，下一步动作必须明确。让用户知道现在该点哪里，该试什么。"
+    }
+  ]
+}
+```
+
+## Meeting Closeout
+
+```json
+{
+  "header": "开完会以后，最怕没有动作",
+  "seriesTitle": "会议闭环术",
+  "seriesTagline": "把讨论变成责任和时间",
+  "cards": [
+    {
+      "kind": "title",
+      "title": ["一场有效会议", "结尾必须有3样东西"],
+      "narration": "一场有效会议，结尾必须留下三样东西。"
+    },
+    {
+      "kind": "body",
+      "caption": "谁负责，不要模糊",
+      "figureKeyword": "owner-deadline",
+      "narration": "第一，谁负责，不要模糊。没有负责人，就等于没有行动。"
+    },
+    {
+      "kind": "body",
+      "caption": "什么时候交付",
+      "figureKeyword": "timeline-review",
+      "narration": "第二，什么时候交付。没有时间点，任务就会一直停在讨论里。"
+    },
+    {
+      "kind": "body",
+      "caption": "风险提前摆出来",
+      "figureKeyword": "risk-guardrail",
+      "narration": "第三，风险提前摆出来。真正高效的团队，不怕问题，只怕问题被藏起来。"
+    }
+  ]
+}
+```