@diottodev/runic 1.0.0 → 1.1.0

package/research/notebooklm/skills/notebooklm/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: notebooklm
+description: "Browser automation skill for controlling Google's NotebookLM. Handles reading and querying notebooks, adding sources (URLs, text, files, YouTube links, synthesized content), generating Studio outputs (Audio Overview, infographics, slide decks, study guides, briefing docs, mind maps, timelines, FAQs), and creating new notebooks. Triggers on any phrase involving NotebookLM — 'open NotebookLM', 'check my [name] notebook', 'pull info from NotebookLM', 'ask my notebook about X', 'add [source] to NotebookLM', 'create an infographic in NotebookLM', 'use NotebookLM Studio', 'generate a slide deck from my notebook', or any variation where the goal involves NotebookLM. Requires browser automation environment — fails gracefully when unavailable."
+license: MIT
+metadata:
+  source_spec: "megaprompts/03-notebooklm-megaprompt.md"
+  build_pattern: "Path B (direct conversion)"
+  shape: "browser-automation (distinct from research-pack convention)"
+  version: 1.0.0
+---
+
+# NotebookLM — Browser Automation
+
+> **Requires:** A browser automation environment (Claude Code CLI with computer-use, Claude Chrome Extension, or equivalent). **Skill will gracefully fail in non-automation contexts with a clear "not supported" message.**
+
+> **Critical:** This skill is the only browser-automation skill in the v2 collection. It does NOT follow the research-pack Agent Integrity Rules convention. Different constraints apply (UI dynamics, async generation, login walls).
+
+## Step 0: Browser Context Setup (Mandatory)
+
+Before any other action, verify browser automation is available:
+
+1. Check whether browser-control tools are loaded in the harness (screenshot, click, find-element, navigate)
+2. If unavailable → **halt with clear message:** "This skill requires browser automation. Currently in {context}. Cannot proceed. Use Claude Code CLI with computer-use, Claude Chrome Extension, or equivalent."
+3. If available → take initial screenshot, navigate to https://notebooklm.google.com
+4. **Detect login wall via screenshot.** If login screen detected: halt with "Please log in to NotebookLM in the browser, then re-invoke this skill." **Never attempt to handle login automatically.**
+
+## Phase 0: Grill-Me Intake (Action-Routing)
+
+Up to 4 forcing questions, one at a time, dependency-ordered. Most invocations stop at Q3.
+
+### Q1 (root) — Action
+
+> **What do you want me to do? Pick one:**
+>
+> 1. **Read / extract** — ask a question of an existing notebook
+> 2. **Add a source** — push content (URL, text, file, Google Doc, or synthesized content) into a notebook
+> 3. **Generate a Studio output** — Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Infographic, Slides, or Mind Map
+> 4. **Create a new notebook** — initialize with title + initial sources
+>
+> *Why I'm asking:* Each action takes a different path through the UI and requires different parameters. Naming the action upfront prevents wasted screenshots and lets me ask only the follow-up questions that apply.
+
+**Forcing choice.** If the user says "open NotebookLM" without specifying an action, **refuse to start** and re-ask Q1.
+
+### Q2 (depends on Q1) — Notebook identity
+
+> **Which notebook?** *(asked for actions 1, 2, 3 — not for "create new")*
+>
+> *Why I'm asking:* If you give me a name, I'll search the homepage; if you give me a URL, I'll navigate directly. Names that are ambiguous will get a disambiguation prompt with screenshots.
+
+For action 4 (create new): replace with "What's the title for the new notebook?"
+
+### Q3 (depends on Q1) — Action-specific parameter
+
+**Action 1 (read/extract):**
+> "What's the question to ask the notebook? Use natural phrasing — the notebook's chat handles it best."
+
+**Action 2 (add source):**
+> "What source type? Pick one:
+> 1. URL / website / YouTube link
+> 2. Copied text (paste here or point at content)
+> 3. File upload (provide absolute path)
+> 4. Google Doc (link)
+> 5. Synthesized content (I'll pre-process and add as 'Copied text')
+>
+> *Why I'm asking:* Each source type goes through a different sub-flow in the Add Source dialog. Picking upfront saves a step."
+
+**Action 3 (Studio output):**
+> "Which Studio output? Audio Overview / Study Guide / Briefing Doc / Timeline / FAQ / Table of Contents / Infographic / Slides / Mind Map. And: any custom-prompt direction? **Default prompts produce mediocre output — I always open the customization menu and write a detailed prompt.** Tell me the angle or audience.
+>
+> *Why I'm asking:* The output type sets the UI button to find. The custom prompt is mandatory for quality."
+
+**Action 4 (create new):**
+> "Initial sources? Provide URLs, file paths, or 'I'll add later'."
+
+### Q4 (depends on Q1 = action 3) — Studio custom prompt detail
+
+> **Tell me the angle, audience, and length for the Studio output. Examples:**
+>
+> - **Audio Overview:** "Two-host conversation for a non-technical executive, 8–10 min, focus on business implications not technical depth"
+> - **Infographic:** "Decision-tree style, action-oriented, 6 panels max, monochrome navy"
+> - **Study Guide:** "Undergrad-level, definitions + 3 practice questions per concept"
+>
+> *Why I'm asking:* This becomes the custom prompt. **Default Studio prompts produce mediocre output — specific direction produces sharp output.**
+
+**Asked only for Studio output generation (Q1=3). Skip otherwise.**
+
+**Stop condition:** After Q4 (or earlier with dependency skips), commit and start the action sequence.
+
+See [`references/studio_output_custom_prompts.md`](references/studio_output_custom_prompts.md) for the canon.
+
+## Notebook Discovery
+
+For actions 1-3 (require existing notebook):
+
+1. Navigate to homepage → screenshot
+2. If user provided **URL** → navigate directly
+3. If user provided **name**:
+   - Use semantic find() to locate notebook card by visible title text
+   - If multiple matches → screenshot homepage, list options, ask user to specify
+   - If no match → ask user to provide URL or confirm spelling
+
+For action 4 (create new):
+1. Locate "New notebook" button on homepage
+2. Click → set title from Q2
+3. Add initial sources per Q3
+
+## Action 1: Read / Extract
+
+1. Open the notebook (notebook discovery above)
+2. Locate chat input (semantic find or screenshot coordinates)
+3. Type the question (use the user's natural phrasing from Q3)
+4. Submit (Enter or send button)
+5. **Wait 3–5 seconds**
+6. Screenshot the response area
+7. Extract and present in **clean format** (not raw chat dump)
+
+## Action 2: Add Sources
+
+Sub-flows per source type:
+
+| Type | UI flow |
+|---|---|
+| URL / Website / YouTube | Add Source → Link → paste URL |
+| Copied Text | Add Source → Copied text → paste content |
+| File Upload | Use file-upload tool with absolute path + input ref (never click native file picker) |
+| Google Doc | Add Source → Google Docs → Drive picker |
+| Synthesized content | Pre-process content elsewhere, then add as Copied text |
+
+**After every add:** wait for ingestion spinner, screenshot to confirm success.
+
+**Synthesized content pattern (powerful):** instead of asking NotebookLM to ingest a raw URL with potentially noisy content, pre-process the content (extract main article, strip nav/ads/comments), then add as "Copied text". Produces dramatically better summarization.
+
+## Action 3: Studio Outputs
+
+**All 9 output types supported:** Audio Overview, Study Guide, Briefing Doc, Timeline, FAQ, Table of Contents, Infographic, Slides, Mind Map.
+
+**Mandatory workflow:**
+
+1. Locate Studio panel (right side; may need toggle)
+2. Find the specific output button for the requested type
+3. **Open customization menu** (chevron/arrow next to button) — **NOT the main button**
+4. **Write detailed custom prompt** (from Q4)
+5. Confirm and submit
+6. **Do NOT wait for completion** — confirm generation started, notify user, return
+
+### Custom prompt examples (4 output types)
+
+**Audio Overview:**
+> "Two-host conversation between a researcher and an experienced practitioner. Audience: non-technical executive making a budget decision. Length: 8-10 minutes. Focus on business implications, not technical depth. Include one concrete example per major point. Acknowledge counter-arguments briefly."
+
+**Infographic:**
+> "Decision-tree style. Action-oriented (each panel ends with a decision or action). 6 panels max. Monochrome navy + amber highlight. Each panel has: title (4-6 words), 1-2 sentence body, decision/action line. No filler panels."
+
+**Study Guide:**
+> "Undergraduate-level (define every technical term). Structure: 6 concepts × 4 elements each (definition / why it matters / one worked example / 3 practice questions). Practice questions Bloom-higher-order (apply/analyze), not recall."
+
+**Slides (slide deck):**
+> "12 slides max. 1-2 sentences per slide body. Presenter notes per slide with: one concrete example + one likely audience objection + how to address it. No bullet points in slide bodies — prose only. End with one-slide call-to-action."
+
+See [`references/studio_output_custom_prompts.md`](references/studio_output_custom_prompts.md) for more.
+
+## Action 4: Create New Notebook
+
+1. Navigate to homepage
+2. Click "New notebook"
+3. Set title from Q2
+4. Add initial sources from Q3 (use Action 2 sub-flows per source type)
+5. **Wait for auto-summary generation** (this one IS synchronous — usually completes in <30 sec)
+6. Screenshot final state
+
+## Critical Async Behavior
+
+> **Async output rule:** For Studio generations (especially **Audio Overview** — 5-10 min), DO NOT wait for completion. The user's session will time out.
+>
+> Workflow: Click Generate → confirm generation has started via screenshot → tell the user "Generation in progress — NotebookLM will notify you when ready" → **end the task.**
+
+This is the **fire-and-notify** pattern. Different from add-source and auto-summary (which are fast enough to wait).
+
+Use `scripts/async_action_classifier.py` to determine wait-or-notify per action:
+
+| Action | Wait? |
+|---|---|
+| Add Source (URL/text/file) | Yes — wait for ingestion spinner (~5-30s) |
+| Read/Extract (chat) | Yes — wait 3-5s for response |
+| Studio: Audio Overview | **No** — fire and notify (5-10 min) |
+| Studio: Infographic / Slides / Mind Map | **No** — fire and notify (2-5 min) |
+| Studio: Study Guide / Briefing Doc / FAQ | Yes — wait ~30-60s |
+| Create New Notebook | Yes — wait for auto-summary (<30s) |
+
+See [`references/async_action_discipline.md`](references/async_action_discipline.md) for the canon.
+
+## Screenshot-First Discipline
+
+NotebookLM is a **dynamic SPA** where UI varies by:
+- Account tier (free vs Plus vs Enterprise)
+- Feature rollout (some Studio types not yet available to all users)
+- Recent UI changes (Google iterates the product frequently)
+
+**Every UI action must be preceded by a screenshot.** Reasons:
+
+1. Verify the UI matches expectations before acting
+2. Catch login walls early
+3. Detect unexpected layout changes
+4. Audit trail for debugging
+
+Use `screenshot()` (or equivalent in your browser-automation tool) before every meaningful UI interaction.
+
+See [`references/browser_automation_canon.md`](references/browser_automation_canon.md) for the discipline.
+
+## find()-Before-Click
+
+Use **semantic element finders** before pixel coordinates wherever possible:
+
+- ✅ `find(text="Audio Overview")` → returns element regardless of position
+- ❌ `click(x=420, y=380)` → breaks when UI rearranges
+
+Semantic finders survive minor UI changes. Pixel coordinates do not.
+
+Only fall back to coordinates when:
+- Semantic find() returns nothing
+- Element has no stable text/aria-label/data-attribute
+- Visual position is the only reliable signal
+
+## Saving Outputs to Workspace
+
+For Read/Extract actions producing useful information:
+
+1. Extract chat response cleanly (strip UI chrome)
+2. Format readably (paragraphs, lists, code blocks as appropriate)
+3. If user requested → save to file (`${WORKSPACE}/notebooklm/<notebook-slug>-<action>-<date>.md`)
+4. Otherwise → return in chat as final summary
+
+For Studio outputs:
+1. NotebookLM hosts the output (Audio Overview is in-app, Infographic downloadable, etc.)
+2. Report the location (URL or in-app navigation path) to user
+3. Don't try to download/save Studio outputs to local workspace — that's NotebookLM's job
+
+## Reporting Back Format
+
+After completing any action:
+
+1. Take final screenshot if visually relevant
+2. Give **clean summary** (not raw chat dump):
+   - Notebook used (name)
+   - Action taken (specific)
+   - Result (1-2 sentences)
+   - For generated outputs: what was created + where it is + when ready
+3. For fire-and-notify actions: explicit "NotebookLM will notify you when ready"
+
+## Error Handling
+
+| Failure | Behavior |
+|---|---|
+| Browser automation unavailable | Fail fast with "this skill requires browser automation" message (Step 0 halt) |
+| Login wall detected | Stop. Tell user to log in. Don't attempt auto-login. |
+| Multiple notebooks match name | Screenshot homepage, list options, ask user to specify |
+| Source ingestion spinner stuck > 60s | Note timeout, ask user if they want to retry |
+| Studio button not found in panel | Scroll down or look for "Discover more"; if still missing, note feature may not be enabled for this account |
+| Chat response doesn't appear in 10s | Screenshot, check for error state, retry once |
+| Page layout changed unexpectedly | Screenshot, describe what's visible, ask user for guidance |
+
+## Tooling
+
+| Script | Role |
+|---|---|
+| `scripts/action_router.py` | Q1-Q4 answers → action plan + UI flow + required parameters |
+| `scripts/custom_prompt_template_generator.py` | Studio output type + audience + length → starter custom prompt |
+| `scripts/async_action_classifier.py` | Action name → wait-or-notify pattern (fire-and-notify for slow generations) |
+
+## References
+
+- [`references/browser_automation_canon.md`](references/browser_automation_canon.md) — screenshot-first + find-before-click + tool-agnostic patterns (7+ sources)
+- [`references/studio_output_custom_prompts.md`](references/studio_output_custom_prompts.md) — why defaults are mediocre + per-output-type templates (7+ sources)
+- [`references/async_action_discipline.md`](references/async_action_discipline.md) — fire-and-notify pattern for slow UI ops (7+ sources)
+
+## Anti-Patterns To Reject
+
+- Tool-specific tool names without abstraction (e.g., hardcoding "Claude Chrome Extension")
+- Synchronous waiting on Studio generations (especially Audio Overview)
+- Skipping screenshots between actions
+- Using pixel coordinates when semantic find() is available
+- Attempting to handle login flows automatically
+- Generating Studio outputs without opening customization menu
+- Using default Studio prompts (always write custom)
+
+---
+
+**Version:** 1.0.0
+**Source spec:** [`megaprompts/03-notebooklm-megaprompt.md`](../../../../megaprompts/03-notebooklm-megaprompt.md)
+**Build pattern:** Path B (direct conversion). Browser-automation shape — distinct from research-pack convention.

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

@@ -0,0 +1,206 @@
+# Async Action Discipline — Fire-and-Notify for Slow UI Operations
+
+This reference answers exactly one decision: **for each NotebookLM action, does the skill wait synchronously OR fire and notify the user?**
+
+## The Core Trade-Off
+
+Browser-automation sessions have practical time limits:
+
+- **Claude Code CLI sessions:** typically time out after ~10 minutes of inactivity
+- **Chrome Extension sessions:** depend on the user keeping the tab open
+- **API contexts:** strict timeout (60s-5min depending on tier)
+
+NotebookLM's Studio operations vary in completion time:
+
+- **Audio Overview:** 5-10 minutes (model generation + audio synthesis)
+- **Infographic / Slides / Mind Map:** 2-5 minutes (complex visual generation)
+- **Study Guide / Briefing Doc / FAQ:** 30-60 seconds (text generation)
+- **Add Source ingestion:** 5-30 seconds (parsing + indexing)
+- **Auto-summary on new notebook:** 10-30 seconds
+
+The mis-match between session timeout and operation time means **synchronous waiting on slow ops is a failure mode**. The skill must fire-and-notify for slow operations instead.
+
+## The Fire-and-Notify Pattern
+
+When triggering a slow operation:
+
+1. Locate the trigger button (via find())
+2. Click it
+3. **Verify generation started** via screenshot (look for spinner / "Generating" indicator)
+4. **Tell the user**: "Generation in progress — NotebookLM will notify you when ready. NotebookLM sends in-app and email notifications when complete."
+5. **End the task** — return control to the user
+
+Key: **don't loop waiting for completion**. The browser-automation session will time out before NotebookLM finishes.
+
+The user already knows how NotebookLM works — they'll see the notification when the Audio Overview is ready. The skill's job is to confirm the generation **started**, not to babysit it to completion.
+
+## Per-Action Timing Catalog
+
+| Action | Type | Timing | Wait or Notify? |
+|---|---|---|---|
+| Chat send (Read/Extract) | Q&A | 3-10s | **Wait** (short) |
+| Add Source: URL | Ingestion | 5-15s | **Wait** |
+| Add Source: Text | Ingestion | 5-15s | **Wait** |
+| Add Source: File upload | Ingestion | 10-30s | **Wait** (with 60s timeout) |
+| Add Source: Google Doc | Ingestion | 10-30s | **Wait** (with 60s timeout) |
+| Create New Notebook | Init + summary | 15-30s | **Wait** |
+| Studio: Study Guide | Generation | 30-60s | **Wait** (with 90s timeout) |
+| Studio: Briefing Doc | Generation | 30-60s | **Wait** (with 90s timeout) |
+| Studio: FAQ | Generation | 30-60s | **Wait** (with 90s timeout) |
+| Studio: Table of Contents | Generation | 20-40s | **Wait** |
+| Studio: Timeline | Generation | 30-60s | **Wait** (with 90s timeout) |
+| **Studio: Audio Overview** | Audio gen | **5-10 min** | **NOTIFY** (fire-and-notify) |
+| **Studio: Infographic** | Visual gen | **2-5 min** | **NOTIFY** |
+| **Studio: Slides** | Visual gen | **2-5 min** | **NOTIFY** |
+| **Studio: Mind Map** | Visual gen | **2-5 min** | **NOTIFY** |
+
+The dividing line: **>2 minutes → fire-and-notify**. Anything shorter, wait synchronously with appropriate timeout.
+
+## Wait-Discipline Details
+
+For "wait" actions, the discipline:
+
+1. After clicking the trigger, **start a wait loop** with timeout
+2. Poll for completion signal:
+   - Spinner disappearing
+   - "Done" / "Ready" indicator
+   - Result content appearing
+3. Take screenshot at intervals (every 10-15s) for audit
+4. If timeout exceeded → screenshot, note timeout, ask user how to proceed
+
+Example for chat (Read/Extract):
+
+```
+1. Submit question
+2. Take screenshot at T+3s
+3. If response present → extract, return
+4. If still generating → take screenshot at T+8s
+5. If response present → extract, return
+6. If still not present → take screenshot at T+15s, note delay
+7. If T+30s and still no response → note error, retry once
+8. If second attempt fails → report failure with screenshot
+```
+
+## Notify-Discipline Details
+
+For "notify" (fire-and-notify) actions:
+
+1. Click Generate (in the customization menu, after custom prompt is set)
+2. Take screenshot **within 5s** to verify generation started
+3. Confirm via visible signal:
+   - Spinner appearing
+   - Status text changing to "Generating..."
+   - Generate button disabled or replaced with "Cancel"
+4. **Tell the user**:
+   > "Generation triggered for {output_type}. NotebookLM takes ~{N} minutes for this. NOT waiting in this session — NotebookLM will notify you in-app and via email when ready. Returning control to you."
+5. **End the task**. Don't loop.
+
+## What Goes Wrong With Synchronous Waiting
+
+### Failure 1: Session timeout
+
+Skill clicks "Generate Audio Overview" at T+0. Browser-automation session times out at T+10min. Skill never confirms generation completed. User gets confused error message.
+
+### Failure 2: Wasted compute
+
+Skill loops `screenshot()` every 5s waiting for completion. 10 minutes × 12 screenshots/min = 120 wasted screenshots. Compute cost adds up.
+
+### Failure 3: Hides errors
+
+While waiting, if NotebookLM shows a transient error and recovers, the skill's wait loop might not catch it. Better: confirm started, hand off to NotebookLM's own error handling.
+
+### Failure 4: Blocks user
+
+User wanted to do something else while Audio Overview generated. Synchronous wait blocks the session.
+
+## What Goes Wrong With Premature Notify
+
+The opposite failure: applying fire-and-notify to a fast action.
+
+### Anti-example: Read/Extract chat send
+
+If the skill clicks send + immediately notifies "Response is being generated", the user has to come back later to retrieve it. But chat responses complete in 3-10s. Waiting is correct.
+
+### Anti-example: Add Source URL
+
+URL ingestion is 5-15s. The skill should wait for the ingestion spinner to clear, then confirm success. Premature notify means user doesn't know if the source was added successfully.
+
+The 2-minute dividing line is empirically the right boundary. Below it, wait. Above it, notify.
+
+## Tooling
+
+`scripts/async_action_classifier.py` returns the wait-or-notify verdict per action:
+
+```bash
+python async_action_classifier.py --action audio_overview
+# Returns: FIRE_AND_NOTIFY (estimated 5-10 min)
+
+python async_action_classifier.py --action add_source_url
+# Returns: WAIT (estimated 5-15s, timeout 60s)
+```
+
+Use this before triggering any Studio or Add-Source action so the skill applies the right pattern.
+
+## Edge Cases
+
+### Generation visibly fails immediately
+
+If the Generate click results in an error toast within 5s → catch it, report, don't notify "in progress."
+
+### Generation queued behind another generation
+
+NotebookLM serializes Studio generations per notebook. If user requests Audio Overview while previous one is generating → either:
+- Wait for previous to clear (only if previous is ~30s from completion based on visible progress)
+- Notify: "Previous generation in progress; new one will queue"
+
+### User cancels mid-generation
+
+If user types "stop" while skill is in wait loop → stop polling, screenshot final state, report what was triggered.
+
+## Anti-Patterns
+
+### Synchronous wait on Audio Overview
+
+The classic failure. 5-10 min wait exceeds session timeout.
+
+### Fire-and-notify on chat send
+
+Premature notify on fast action. User can't tell if it worked.
+
+### No completion signal verification
+
+Just clicking Generate and notifying without confirming generation started. If the click missed (semantic find on wrong element), the user thinks generation started when it didn't.
+
+### Loop screenshot every 1s during wait
+
+Wastes compute. 10-15s intervals are fine for waits.
+
+### Ignore visible error toasts
+
+If error appears, react. Don't proceed with "in progress" message if generation clearly didn't start.
+
+## Operational Checklist (Per Action)
+
+- [ ] Classify action via `async_action_classifier.py` (wait vs notify)
+- [ ] If wait: set appropriate timeout (longer for file upload than chat)
+- [ ] If notify: verify generation started via screenshot within 5s
+- [ ] Tell user explicitly when fire-and-notify ("NotebookLM will notify you when ready")
+- [ ] End task after notify — don't loop
+- [ ] On wait timeout: screenshot + ask user how to proceed
+- [ ] On visible error: report immediately
+
+## Citations (7 sources)
+
+1. **Anthropic API documentation — session timeout behavior.** Source for the 60s-5min API timeout ranges that motivate fire-and-notify for slow ops. https://docs.anthropic.com/
+
+2. **Google NotebookLM Studio documentation + community findings (2024-2026).** Source for the per-output-type timing estimates (Audio Overview 5-10 min, Infographic 2-5 min, etc.). Empirical from user reports.
+
+3. **Erlang / OTP "let it crash" philosophy (Joe Armstrong).** Source for the broader async pattern: don't wait for slow operations synchronously. Hand off + let the supervising system handle completion notifications.
+
+4. **AWS Step Functions documentation.** Source for the fire-and-notify pattern in distributed systems. Step Functions explicitly distinguishes "Wait" tasks from "Callback" (fire-and-notify) tasks based on duration.
+
+5. **Twelve-Factor App — Factor IX (Disposability).** Source for the "fast startup, graceful shutdown" discipline. Skills should be disposable — return control quickly rather than holding sessions open.
+
+6. **Node.js event loop documentation.** Source for the async-event-loop discipline. Synchronous blocking on slow ops harms throughput; async handoff preserves it.
+
+7. **Playwright + Selenium wait-strategy documentation.** Source for the polling-with-timeout pattern for "wait" actions. Both frameworks document the discipline of bounded waits with explicit timeouts.