@diottodev/runic 1.0.0 → 1.1.0

package/research/notebooklm/skills/notebooklm/references/browser_automation_canon.md

@@ -0,0 +1,192 @@
+# Browser Automation Canon — Screenshot-First + find()-Before-Click
+
+This reference answers exactly one decision: **what discipline does the notebooklm skill follow when controlling NotebookLM's UI, and why?**
+
+## The Core Frame
+
+NotebookLM is a **dynamic single-page application** where the UI varies significantly by:
+
+- Account tier (free / Plus / Enterprise)
+- Feature rollout (Studio types not yet GA for all users)
+- Time (Google iterates the product frequently — buttons move, labels change, layouts shift)
+- A/B experiments (different users see different UIs)
+
+Hard-coded coordinates break instantly when these change. Semantic discipline survives.
+
+## The Two Disciplines
+
+### 1. Screenshot-First
+
+**Every meaningful UI action must be preceded by a screenshot.**
+
+Reasons:
+
+1. **Verify UI matches expectations** before acting (account-tier differences, A/B variants)
+2. **Catch login walls early** before attempting actions on a not-logged-in page
+3. **Detect unexpected layout changes** (Google ships UI changes weekly)
+4. **Audit trail** for debugging when actions fail
+
+The performance cost is negligible (screenshots are fast). The safety benefit is large.
+
+### 2. find()-Before-Click
+
+**Use semantic element finders before pixel coordinates.**
+
+Pattern preference:
+
+| Pattern | Survives | Use when |
+|---|---|---|
+| `find(text="Audio Overview")` | UI rearrangements | Element has stable visible text |
+| `find(aria_label="Generate")` | A11y-labeled elements | Element has stable aria-label |
+| `find(data_test="studio-btn")` | Internal test IDs | Element has stable data-* attribute (rare in NotebookLM) |
+| `find(role="button", name="Send")` | Accessibility tree | Element role + accessible name stable |
+| `click(x=420, y=380)` | Nothing | **Last resort only** — UI must visually align exactly |
+
+### Why coordinates break
+
+Google rolled out a UI redesign in Q2 2025 that moved the Studio panel from right-side to a collapsible drawer. Skills using pixel coordinates broke overnight. Skills using `find(text="Studio")` adapted automatically.
+
+## The Tool-Agnostic Vocabulary
+
+NotebookLM skill uses generic terms — NOT hardcoded to a specific tool:
+
+| Skill says | Tool-specific implementation examples |
+|---|---|
+| "browser automation tool" | Claude computer-use, Claude Chrome Extension, Playwright, Puppeteer |
+| "screenshot tool" | `screenshot()`, `page.screenshot()`, `browser.captureScreenshot()` |
+| "find tool" | `find_element()`, `page.locator()`, `$$(selector)` |
+| "click tool" | `click()`, `page.click()`, `element.click()` |
+| "navigate tool" | `navigate()`, `page.goto()`, `browser.open()` |
+| "file-upload tool" | Tool-specific file-upload mechanism (not native file picker) |
+
+Why: the skill should work across browser-automation environments. Tool-specific code locks the skill to one harness.
+
+## Critical Discipline: Never Click Native File Pickers
+
+When uploading a file to NotebookLM:
+
+❌ **Do NOT click the "Choose File" button** — this opens a native OS file picker that browser automation cannot control.
+
+✅ **Use the file-upload tool** — your browser-automation environment provides a way to attach files programmatically. Example patterns:
+
+- Playwright: `page.set_input_files(input_ref, file_path)`
+- Computer-use: `upload_file(file_input_locator, absolute_path)`
+- Puppeteer: `page.$eval(input_selector, (el, path) => el.files = ...)`
+
+The file-upload tool bypasses the native picker entirely.
+
+## Login Wall Discipline
+
+NotebookLM requires Google authentication. Login walls can appear:
+
+- Initial visit (not logged in)
+- Session timeout (logged in but stale)
+- Account switch (multiple Google accounts)
+- 2FA challenge (security verification)
+
+**Hard rule: never attempt to handle login automatically.**
+
+Why:
+- Credentials are sensitive
+- 2FA requires human interaction
+- Account state varies (logged in to wrong account, etc.)
+- Browser-automation handling login creates security audit nightmares
+
+Detection pattern:
+
+```
+1. Take screenshot
+2. Check for login signals: "Sign in to Google", login URL, password field visible
+3. If detected → halt with clear message: "Please log in to NotebookLM in your browser, then re-invoke this skill."
+4. Do not type credentials, do not click login buttons
+```
+
+## Async Wait Discipline (See Also: async_action_discipline.md)
+
+Different actions have different timing:
+
+- **Fast (< 5s)**: chat send, basic clicks — wait synchronously
+- **Medium (5-60s)**: source ingestion, auto-summary, Study Guide / Briefing Doc — wait with timeout
+- **Slow (1-10 min)**: Audio Overview, Infographic, Slides — **fire-and-notify, don't wait**
+
+Mis-applying the timing causes:
+- Session timeout (user waits 10 min for Audio Overview to complete)
+- False failure reports (skill thinks it failed because it timed out waiting)
+- Wasted compute
+
+## Screenshot Audit Pattern
+
+For debugging + transparency, the skill should produce a screenshot trail per session:
+
+```
+~/notebooklm_sessions/<date>-<action>/
+  001-step0-environment-check.png
+  002-homepage-loaded.png
+  003-notebook-found.png
+  004-chat-input-located.png
+  005-question-submitted.png
+  006-response-received.png
+```
+
+Per-screenshot rationale:
+- Step 0 baseline (proves environment was checked)
+- Each UI interaction documented
+- Final state captured
+
+This is the audit-log equivalent for browser-automation skills.
+
+## Anti-Patterns
+
+### "Just click where it usually is"
+
+Pixel coordinates. Breaks on any UI change. Most common failure mode.
+
+### "Skip screenshots to save time"
+
+The cost of skipping is unrecoverable: when something goes wrong, no audit trail exists. Always screenshot.
+
+### "Try to handle login programmatically"
+
+Security risk + brittle. Always halt and ask user to log in manually.
+
+### "Wait for Audio Overview synchronously"
+
+5-10 minute generations exceed session timeout. Fire-and-notify pattern.
+
+### "Use the main Studio button"
+
+Default Studio prompts produce mediocre output. Always open the customization menu (chevron next to main button) and write a custom prompt.
+
+### "Hardcode 'Claude Chrome Extension'"
+
+Tool-specific. Use "browser automation tool" or equivalent generic term.
+
+### "Click 'Choose File' for uploads"
+
+Opens native file picker, breaks automation. Use the file-upload tool.
+
+## Operational Checklist (Per UI Action)
+
+- [ ] Screenshot taken before action
+- [ ] Semantic find() attempted before pixel coordinates
+- [ ] Login wall check after navigation
+- [ ] Tool-agnostic vocabulary in skill body
+- [ ] File uploads use file-upload tool, not file picker
+- [ ] Async timing classified correctly (wait vs fire-and-notify)
+- [ ] Screenshot trail saved for audit
+
+## Citations (7 sources)
+
+1. **Anthropic Computer Use documentation (Claude 3.5 Sonnet + later).** Source for the screenshot-first + semantic-find discipline in Claude's official browser automation tool. The patterns in this reference are the production patterns Anthropic recommends.
+
+2. **Playwright documentation — playwright.dev.** Source for the semantic locator patterns (`page.locator()`, role-based selectors, accessibility tree). Playwright's locator model is the modern standard.
+
+3. **Selenium documentation + best practices guides.** Source for the historical context: Selenium pioneered semantic finders 15+ years before Playwright; the patterns are well-established.
+
+4. **W3C Web Driver protocol.** Source for the standardized element-locator strategies (id, name, class, link text, partial link text, tag name, css, xpath). The protocol formalized what to find by.
+
+5. **Microsoft Power Automate Desktop UI automation guidance.** Source for the "image-based selectors are last resort" guidance. Microsoft's enterprise RPA tooling formalized the same discipline.
+
+6. **Google A11y / ARIA patterns — w3.org/WAI/ARIA/.** Source for the role + accessible-name selector strategy. ARIA labels are the most stable selector when present.
+
+7. **Anthropic's "Tool Use" + browser automation cookbook (docs.anthropic.com).** Source for the tool-agnostic vocabulary discipline. Anthropic explicitly recommends generic "screenshot tool" / "click tool" language to keep skills portable across harnesses.

package/research/notebooklm/skills/notebooklm/references/studio_output_custom_prompts.md

@@ -0,0 +1,217 @@
+# Studio Output Custom Prompts — Why Defaults Are Mediocre
+
+This reference answers exactly one decision: **why does the notebooklm skill always open the Studio customization menu and write a detailed custom prompt, and what does a good custom prompt look like per output type?**
+
+## The Core Claim
+
+NotebookLM's Studio generates 9 output types from your notebook's sources:
+
+- Audio Overview (podcast-style)
+- Study Guide
+- Briefing Doc
+- Timeline
+- FAQ
+- Table of Contents
+- Infographic
+- Slides (slide deck)
+- Mind Map
+
+**The default prompts produce mediocre output.** They are written to work across all possible source materials → they are generic by design. Generic prompts produce generic output.
+
+The mediocre-output failure mode:
+- **Audio Overview default:** generic two-host summary, 12-15 min, undifferentiated voice
+- **Infographic default:** title-and-bullet panels, no decision logic, generic palette
+- **Study Guide default:** definition list + bland questions, no audience calibration
+
+**Sharp custom prompts produce dramatically better output.** The customization menu (chevron next to the main Studio button) opens a text field where you describe: angle / audience / length / style / specific structure.
+
+## When to Use Custom Prompts
+
+**Always.** This is non-negotiable in the notebooklm skill.
+
+The mandatory workflow for Action 3 (Studio output):
+
+1. Locate the specific output button (find by text — e.g., `find(text="Audio Overview")`)
+2. **Open the customization menu** — the chevron/dropdown arrow next to the main button (NOT the main button itself)
+3. **Write a detailed custom prompt** in the text field
+4. Submit Generate
+
+Skipping step 2-3 (clicking the main button directly) uses the default prompt. The skill refuses to do this.
+
+## Custom Prompt Anatomy
+
+A good custom prompt specifies:
+
+| Element | Why |
+|---|---|
+| **Audience** | Drives jargon level + assumed background |
+| **Angle** | What perspective / lens to apply (e.g., business vs technical) |
+| **Length** | Prevents bloat or thinness |
+| **Structure** | Specific layout (panels, slides, sections) |
+| **Style** | Tone, voice, formality |
+| **Examples / counter-examples** | Concrete anchors |
+
+A weak prompt has 1-2 of these. A strong prompt has 4-5.
+
+## Per-Output-Type Custom Prompt Templates
+
+### Audio Overview
+
+**Default fails because:** generic two-host conversational tone, undefined audience, often 12-15 min (too long), surface-level coverage.
+
+**Good custom prompt:**
+
+> "Two-host conversation between a researcher and an experienced practitioner. Audience: [non-technical executive | technical lead | undergraduate student | general public]. Length: 8-10 minutes. Focus on [business implications | technical mechanism | historical evolution | practical applications]. Include one concrete example per major point. Acknowledge counter-arguments briefly. End with one specific takeaway, not a generic summary."
+
+**Pattern:**
+- Two-host setup (specify roles, not just "two hosts")
+- Audience explicit
+- Length tight
+- Focus angle picked
+- Concrete-example requirement
+- Counter-argument requirement
+- Specific closing instruction
+
+### Infographic
+
+**Default fails because:** generic title-and-bullets, no decision logic, oversize panel count, neutral palette.
+
+**Good custom prompt:**
+
+> "Decision-tree style. Action-oriented (each panel ends with a decision or action the viewer takes). 6 panels max. Monochrome navy with amber highlight on the action line. Each panel has: title (4-6 words), 1-2 sentence body explaining the situation, decision/action line in amber. No filler panels. Last panel: 'next step' with specific URL/contact/resource."
+
+**Pattern:**
+- Style (decision-tree vs storytelling vs comparison vs process)
+- Action-orientation
+- Panel count cap (6 is the sweet spot; 8+ becomes unreadable)
+- Color palette
+- Per-panel structure
+- Closing call-to-action
+
+### Study Guide
+
+**Default fails because:** definition list + bland recall questions, no audience calibration, no Bloom higher-order discipline.
+
+**Good custom prompt:**
+
+> "[Undergraduate | Graduate | Professional] level — define every technical term if undergrad, assume fluency if grad. Structure: [N] concepts, each with 4 elements: (1) one-paragraph definition, (2) why this matters in practice (concrete example), (3) one worked problem, (4) 3 practice questions Bloom-higher-order (apply / analyze / evaluate; NO recall questions). Discussion questions tied to a specific learning outcome listed at the start of each section."
+
+**Pattern:**
+- Audience explicit (drives jargon + question complexity)
+- Concept count specific
+- Per-concept structure rigid
+- Bloom-level discipline
+- Learning-outcome anchoring
+
+### Slides (Slide Deck)
+
+**Default fails because:** dense slides, bullet-heavy, no presenter notes, generic structure.
+
+**Good custom prompt:**
+
+> "12 slides max. 1-2 sentences per slide body — NO bullet points in slide bodies (prose only). Per slide: include presenter notes with (a) one concrete example, (b) one likely audience objection, (c) how to address it. Title slide + 10 content slides + closing call-to-action slide. Closing slide: specific next step (not 'thank you')."
+
+**Pattern:**
+- Slide count cap (12 max for executive audience)
+- Body density rule (1-2 sentences, no bullets)
+- Presenter notes mandatory + structured
+- Title + content + close structure
+- Closing call-to-action (not generic 'thank you')
+
+### Briefing Doc
+
+**Default fails because:** generic memo structure, no key-decisions section, undifferentiated length.
+
+**Good custom prompt:**
+
+> "Audience: [executive / board / investor / partner]. Length: [1 page / 2 pages / 5 pages]. Structure: (1) BLUF (bottom line up front, 2 sentences max), (2) Key findings (3-5 numbered), (3) Decisions needed from this audience (numbered, with options + recommendation), (4) Open questions (3 max), (5) Suggested next step (1 specific action). Tone: [neutral analytical / persuasive / cautionary]."
+
+### Timeline
+
+**Default fails because:** chronological dump with no significance annotation.
+
+**Good custom prompt:**
+
+> "Milestone-focused (not event-dump). [N] milestones max. Per milestone: date, milestone (one phrase), significance (one sentence — why this changed the field). Order: reverse-chronological [or chronological if historical narrative]. Group into 3-4 eras with era-level summary at each boundary. Exclude minor events that don't shift the trajectory."
+
+### FAQ
+
+**Default fails because:** generic Q&A pairs, no audience-calibrated answer depth.
+
+**Good custom prompt:**
+
+> "Audience: [internal team / customer / external stakeholder]. 8-12 questions. Each answer: 2-3 sentences max. Question phrasing: how the audience would actually ask it (not how the topic owner would write it). Group into 3 categories. Include 2-3 'difficult question' entries (objections / concerns) — handle them directly, not evasively."
+
+### Mind Map
+
+**Default fails because:** generic radial spread with no priority hierarchy.
+
+**Good custom prompt:**
+
+> "Central concept: [name]. 3-5 primary branches (the major dimensions). Each branch: 2-4 sub-branches. Max depth: 3 levels (central → branch → sub-branch). Use noun phrases for branches (not full sentences). Mark 2-3 sub-branches as 'critical' (the highest-leverage points). Skip details that don't connect back to a critical sub-branch."
+
+### Table of Contents
+
+**Default fails because:** literal section dump, no annotation.
+
+**Good custom prompt:**
+
+> "Structure: section number + section title + 1-sentence summary of what the section covers. Length: 8-15 sections. Group into 2-3 parts with part-level summary at each boundary. Mark 2-3 sections as 'start here' for newcomers."
+
+## Anti-Patterns
+
+### Click the main Studio button (default prompt)
+
+The most common skill failure. Always open customization menu.
+
+### Generic custom prompt
+
+> "Make a good infographic about my notebook."
+
+This is a default prompt with extra words. Specify audience / angle / length / structure / style.
+
+### Over-detailed custom prompt
+
+> "Use exactly the color #1A3A5C for headers, then #E8F0F8 for table headers, with Arial 12pt body, then..."
+
+NotebookLM's Studio engine doesn't honor pixel-precise design specs. Stay at the level of "monochrome navy with amber highlight," not exact hex codes.
+
+### Custom prompt for the wrong output type
+
+> Asked for Audio Overview, wrote a custom prompt about visual design.
+
+Match prompt content to output type. Audio prompt → audio direction; visual prompt → visual direction.
+
+### Custom prompt that contradicts source material
+
+> "Generate an infographic showing my notebook's positive findings about X" — when the notebook has mixed findings.
+
+Studio outputs source-grounded content. Custom prompts shape **how** content is presented, not what content exists. Force-skew via custom prompt produces inaccurate output.
+
+## Operational Checklist (Per Studio Output Generation)
+
+- [ ] Q4 (custom prompt direction) collected from user
+- [ ] Studio panel located via find() (not pixel coordinates)
+- [ ] Specific output button located (not the panel header)
+- [ ] **Customization menu opened** (chevron, NOT main button)
+- [ ] Custom prompt written: audience + angle + length + structure + style
+- [ ] Custom prompt run through `scripts/custom_prompt_template_generator.py` for starter if needed
+- [ ] Generate button clicked
+- [ ] Confirmation screenshot taken
+- [ ] User notified: "Generation in progress — NotebookLM will notify you when ready" (for slow ops)
+
+## Citations (7 sources)
+
+1. **Google NotebookLM documentation + product blog posts (2024-2026).** Source for the Studio output catalog and the customization menu existence. Google has progressively added customization since Audio Overview launched.
+
+2. **Anthropic's prompt engineering guide — docs.anthropic.com.** Source for the audience-angle-length-structure-style anatomy of effective prompts. The pattern transfers from Claude prompting to NotebookLM Studio prompting.
+
+3. **Refactoring UI — Adam Wathan & Steve Schoger (2018).** Source for visual-output design discipline (panel-count caps, palette restraint, action-orientation). The Infographic and Slides templates apply this discipline.
+
+4. **Carmine Gallo, *Talk Like TED* (2014).** Source for the slide-deck structure (12-max, 1-2 sentences per slide, presenter notes with examples + objections). Gallo's analysis of top TED talks formalizes the discipline.
+
+5. **Patrick Lencioni, *The Five Dysfunctions of a Team* (2002).** Source for the BLUF (bottom line up front) discipline used in Briefing Doc template. Executive briefings front-load the decision.
+
+6. **Bloom's revised taxonomy — Anderson & Krathwohl (2001).** Source for the Study Guide's Bloom-higher-order discipline (apply / analyze / evaluate / create). Connects to research-pack's discussion question canon.
+
+7. **Edward Tufte, *Visual Display of Quantitative Information* (1983, 2001 2nd ed.).** Source for the data-ink ratio discipline applied to Infographic + Timeline templates. Tufte's "small multiples" and "milestone discipline" inform the per-panel and per-milestone structures.

package/research/notebooklm/skills/notebooklm/scripts/action_router.py

@@ -0,0 +1,272 @@
+#!/usr/bin/env python3
+"""action_router.py — Q1-Q4 answers → action plan + UI flow + required parameters.
+
+Stdlib-only. Routes notebooklm intake answers to one of 4 action flows:
+
+  1. read_extract — chat-based extraction
+  2. add_source   — push content via Add Source dialog (5 sub-types)
+  3. studio       — generate Studio output (9 types) with mandatory custom prompt
+  4. create_new   — new notebook with title + initial sources
+
+Returns the action plan: required parameters, UI flow steps, mandatory checks.
+
+NO LLM CALLS. Pure rule-based routing.
+
+Usage:
+    python action_router.py --action read_extract --notebook "Q3 prep" --question "what are recent trends?"
+    python action_router.py --action add_source --notebook "Q3 prep" --source-type url --source-value "https://..."
+    python action_router.py --action studio --notebook "Q3 prep" --studio-type audio_overview --custom-prompt "..."
+    python action_router.py --action create_new --title "New project" --initial-sources "url1,url2"
+    python action_router.py --sample
+"""
+
+import argparse
+import json
+import sys
+from typing import Any, Dict, List, Optional
+
+
+VALID_ACTIONS = ["read_extract", "add_source", "studio", "create_new"]
+VALID_SOURCE_TYPES = ["url", "text", "file", "google_doc", "synthesized"]
+VALID_STUDIO_TYPES = [
+    "audio_overview", "study_guide", "briefing_doc", "timeline", "faq",
+    "table_of_contents", "infographic", "slides", "mind_map",
+]
+
+
+ACTION_FLOWS = {
+    "read_extract": {
+        "required_params": ["notebook", "question"],
+        "ui_flow": [
+            "Step 0: Browser environment check",
+            "Navigate to homepage → screenshot",
+            "Login wall check (halt if detected)",
+            "Notebook discovery (find by name or navigate URL)",
+            "Open notebook → screenshot",
+            "Locate chat input via find()",
+            "Type question (user's natural phrasing)",
+            "Submit (Enter or send button)",
+            "Wait 3-5s (synchronous; chat is fast)",
+            "Screenshot response area",
+            "Extract response in clean format (not raw chat dump)",
+            "Report to user",
+        ],
+        "timing": "WAIT (3-10s)",
+        "screenshots_required": 4,
+    },
+    "add_source": {
+        "required_params": ["notebook", "source_type", "source_value"],
+        "ui_flow_by_source_type": {
+            "url": [
+                "Open notebook → screenshot",
+                "Click 'Add Source' → screenshot",
+                "Click 'Link' option",
+                "Paste URL",
+                "Submit → wait for ingestion spinner",
+                "Screenshot to confirm success",
+            ],
+            "text": [
+                "Open notebook → screenshot",
+                "Click 'Add Source' → screenshot",
+                "Click 'Copied text' option",
+                "Paste content",
+                "Submit → wait for ingestion spinner",
+                "Screenshot to confirm success",
+            ],
+            "file": [
+                "Open notebook → screenshot",
+                "Click 'Add Source' → screenshot",
+                "Click 'Upload file' option",
+                "Use file-upload tool with absolute path (NOT native file picker)",
+                "Wait for upload + ingestion",
+                "Screenshot to confirm success",
+            ],
+            "google_doc": [
+                "Open notebook → screenshot",
+                "Click 'Add Source' → screenshot",
+                "Click 'Google Docs' option",
+                "Use Drive picker",
+                "Confirm doc selection",
+                "Wait for ingestion",
+                "Screenshot to confirm success",
+            ],
+            "synthesized": [
+                "Pre-process content externally (extract main content, strip nav/ads)",
+                "Open notebook → screenshot",
+                "Click 'Add Source' → screenshot",
+                "Click 'Copied text' option",
+                "Paste synthesized content",
+                "Submit → wait for ingestion",
+                "Screenshot to confirm success",
+            ],
+        },
+        "timing": "WAIT (5-30s with 60s timeout)",
+        "screenshots_required": 3,
+    },
+    "studio": {
+        "required_params": ["notebook", "studio_type", "custom_prompt"],
+        "ui_flow": [
+            "Step 0: Browser environment check",
+            "Navigate to notebook → screenshot",
+            "Locate Studio panel (right side; may need toggle) → screenshot",
+            "Find specific output button via find(text=studio_type)",
+            "**Open customization menu** (chevron NEXT to button; NOT main button)",
+            "**Write detailed custom prompt** in customization field",
+            "Submit Generate",
+            "**Verify generation started** via screenshot within 5s",
+            "**Fire-and-notify if slow** (Audio Overview, Infographic, Slides, Mind Map = 2-10 min)",
+            "Tell user: 'Generation in progress — NotebookLM will notify you when ready'",
+            "End task (don't wait for completion on slow ops)",
+        ],
+        "timing_by_studio_type": {
+            "audio_overview": "FIRE_AND_NOTIFY (5-10 min)",
+            "study_guide": "WAIT (30-60s, timeout 90s)",
+            "briefing_doc": "WAIT (30-60s, timeout 90s)",
+            "timeline": "WAIT (30-60s, timeout 90s)",
+            "faq": "WAIT (30-60s, timeout 90s)",
+            "table_of_contents": "WAIT (20-40s, timeout 60s)",
+            "infographic": "FIRE_AND_NOTIFY (2-5 min)",
+            "slides": "FIRE_AND_NOTIFY (2-5 min)",
+            "mind_map": "FIRE_AND_NOTIFY (2-5 min)",
+        },
+        "screenshots_required": 5,
+        "critical_rule": "ALWAYS open customization menu (chevron) — NEVER click main Studio button (uses default mediocre prompt)",
+    },
+    "create_new": {
+        "required_params": ["title"],
+        "optional_params": ["initial_sources"],
+        "ui_flow": [
+            "Step 0: Browser environment check",
+            "Navigate to homepage → screenshot",
+            "Click 'New notebook' button (find via text)",
+            "Set title from --title argument",
+            "If initial_sources provided: add each via Action 2 sub-flow (per source type)",
+            "Wait for auto-summary generation (typically <30s)",
+            "Screenshot final state",
+            "Report new notebook URL to user",
+        ],
+        "timing": "WAIT (15-30s for init + auto-summary)",
+        "screenshots_required": 3,
+    },
+}
+
+
+def route(action: str, **params) -> Dict[str, Any]:
+    if action not in VALID_ACTIONS:
+        raise ValueError(f"Invalid action '{action}'. Pick from: {VALID_ACTIONS}")
+
+    flow_template = ACTION_FLOWS[action].copy()
+    flow_template["action"] = action
+    flow_template["parameters"] = params
+
+    # Validate required params
+    required = flow_template.get("required_params", [])
+    missing = [p for p in required if not params.get(p)]
+    if missing:
+        flow_template["validation_errors"] = [f"Missing required parameter: {p}" for p in missing]
+
+    # Per-action customization
+    if action == "add_source":
+        source_type = params.get("source_type")
+        if source_type and source_type not in VALID_SOURCE_TYPES:
+            flow_template["validation_errors"] = flow_template.get("validation_errors", []) + [
+                f"Invalid source_type '{source_type}'. Pick from: {VALID_SOURCE_TYPES}"
+            ]
+        elif source_type:
+            flow_template["ui_flow"] = flow_template["ui_flow_by_source_type"][source_type]
+            del flow_template["ui_flow_by_source_type"]
+
+    if action == "studio":
+        studio_type = params.get("studio_type")
+        if studio_type and studio_type not in VALID_STUDIO_TYPES:
+            flow_template["validation_errors"] = flow_template.get("validation_errors", []) + [
+                f"Invalid studio_type '{studio_type}'. Pick from: {VALID_STUDIO_TYPES}"
+            ]
+        elif studio_type:
+            flow_template["timing"] = flow_template["timing_by_studio_type"][studio_type]
+        # Custom prompt is mandatory for studio
+        if not params.get("custom_prompt") or len(params.get("custom_prompt", "")) < 30:
+            flow_template["validation_errors"] = flow_template.get("validation_errors", []) + [
+                "Studio output requires DETAILED custom_prompt (min 30 chars). Default prompts produce mediocre output."
+            ]
+
+    return flow_template
+
+
+def render_human(result: Dict[str, Any]) -> str:
+    out: List[str] = []
+    out.append(f"Action: {result['action']}")
+    out.append("")
+    out.append("Parameters:")
+    for k, v in result.get("parameters", {}).items():
+        if v:
+            display = v if len(str(v)) < 80 else str(v)[:77] + "..."
+            out.append(f"  {k}: {display}")
+    out.append("")
+
+    if result.get("validation_errors"):
+        out.append("⚠️  Validation errors:")
+        for err in result["validation_errors"]:
+            out.append(f"  - {err}")
+        out.append("")
+
+    out.append(f"Timing: {result.get('timing', 'N/A')}")
+    out.append(f"Screenshots required: {result.get('screenshots_required', 'N/A')}")
+    if result.get("critical_rule"):
+        out.append(f"⚠️  Critical rule: {result['critical_rule']}")
+    out.append("")
+    out.append("UI flow:")
+    flow = result.get("ui_flow", [])
+    for i, step in enumerate(flow, 1):
+        out.append(f"  {i}. {step}")
+    return "\n".join(out)
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--action", choices=VALID_ACTIONS)
+    parser.add_argument("--notebook")
+    parser.add_argument("--question")
+    parser.add_argument("--source-type", choices=VALID_SOURCE_TYPES)
+    parser.add_argument("--source-value")
+    parser.add_argument("--studio-type", choices=VALID_STUDIO_TYPES)
+    parser.add_argument("--custom-prompt")
+    parser.add_argument("--title")
+    parser.add_argument("--initial-sources")
+    parser.add_argument("--sample", action="store_true")
+    parser.add_argument("--output", choices=["human", "json"], default="human")
+    args = parser.parse_args(argv)
+
+    if args.sample:
+        result = route(
+            "studio",
+            notebook="Q3 launch prep",
+            studio_type="audio_overview",
+            custom_prompt="Two-host conversation for non-technical executive, 8-10 min, focus on business implications not technical depth",
+        )
+    elif args.action:
+        params: Dict[str, Any] = {}
+        if args.notebook: params["notebook"] = args.notebook
+        if args.question: params["question"] = args.question
+        if args.source_type: params["source_type"] = args.source_type
+        if args.source_value: params["source_value"] = args.source_value
+        if args.studio_type: params["studio_type"] = args.studio_type
+        if args.custom_prompt: params["custom_prompt"] = args.custom_prompt
+        if args.title: params["title"] = args.title
+        if args.initial_sources: params["initial_sources"] = args.initial_sources
+        try:
+            result = route(args.action, **params)
+        except ValueError as e:
+            print(f"error: {e}", file=sys.stderr); return 2
+    else:
+        parser.print_help(); return 0
+
+    if args.output == "json":
+        print(json.dumps(result, indent=2))
+    else:
+        print(render_human(result))
+    return 0 if not result.get("validation_errors") else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))