@research-copilot/plugin 1.1.17 → 1.1.18

package/dist/skills/paper-slide-deck/references/analysis-framework.md

@@ -0,0 +1,392 @@
+# Presentation Analysis Framework
+
+Deep content analysis for effective slide deck creation.
+
+## 1. Message Hierarchy
+
+Identify the core message structure before designing slides.
+
+### Core Message (One Sentence)
+- What is the single most important takeaway?
+- If the audience remembers only one thing, what should it be?
+- Can you state it in ≤15 words?
+
+### Supporting Points (3-5 Maximum)
+- What evidence supports the core message?
+- What sub-topics must be covered?
+- Prioritize by audience relevance, not source order
+
+### Call-to-Action
+- What should the audience DO after viewing?
+- Is it clear, specific, and achievable?
+- Where does it appear (slide position)?
+
+## 2. Audience Decision Matrix
+
+| Question | Analysis |
+|----------|----------|
+| Who is the primary audience? | [Role, expertise level, relationship to topic] |
+| What do they currently believe? | [Existing knowledge, assumptions, biases] |
+| What decision do we want them to make? | [Specific action or conclusion] |
+| What barriers exist? | [Objections, concerns, missing information] |
+| What evidence will convince them? | [Data types, credibility sources, emotional hooks] |
+
+### Audience Adaptation
+
+| Audience Type | Content Focus | Visual Treatment |
+|---------------|---------------|------------------|
+| Executives | Outcomes, ROI, strategic impact | High-level, clean, data highlights |
+| Technical | Architecture, implementation, specs | Detailed diagrams, code, schematics |
+| General | Benefits, stories, relatability | Visual metaphors, simple charts |
+| Investors | Market size, traction, team | Growth charts, milestones, comparisons |
+| Learners | Step-by-step, examples, practice | Progressive reveals, exercises |
+
+## 3. Visual Opportunity Map
+
+Identify which content benefits from visualization.
+
+### Content-to-Visual Mapping
+
+| Content Type | Visual Treatment | Example |
+|--------------|------------------|---------|
+| Comparisons | Side-by-side, before/after | Feature comparison table |
+| Processes | Flow diagrams, numbered steps | Workflow illustration |
+| Hierarchies | Org charts, pyramids, trees | Organizational structure |
+| Timelines | Horizontal/vertical timelines | Project milestones |
+| Statistics | Charts, highlighted numbers | Key metrics with context |
+| Concepts | Icons, metaphors, illustrations | Abstract idea visualization |
+| Relationships | Venn diagrams, networks | Ecosystem or dependencies |
+| Lists | Structured grids, icon rows | Feature bullets with icons |
+
+### Visual Priority
+
+Rate each piece of content:
+- **Must Visualize**: Complex data, key differentiators, memorable moments
+- **Should Visualize**: Supporting evidence, secondary points
+- **Text Only**: Simple statements, transitions, minor details
+
+## 4. Presentation Flow
+
+Structure for impact and retention.
+
+### Opening (First 2-3 Slides)
+
+| Element | Purpose |
+|---------|---------|
+| Hook | Capture attention (surprising stat, question, story) |
+| Context | Why this matters now |
+| Preview | What audience will learn/gain |
+
+### Middle (Content Slides)
+
+| Pattern | When to Use |
+|---------|-------------|
+| Problem → Solution | Introducing new products/ideas |
+| Situation → Complication → Resolution | Complex business cases |
+| What → Why → How | Educational content |
+| Past → Present → Future | Transformation stories |
+| Claim → Evidence → Implication | Data-driven arguments |
+
+### Closing (Final 2-3 Slides)
+
+| Element | Purpose |
+|---------|---------|
+| Synthesis | Tie back to core message |
+| Call-to-Action | Clear next steps |
+| Memorable Close | Resonant quote, image, or statement |
+
+### Transitions
+
+- Each slide should answer: "What comes next?"
+- Use narrative connectors between sections
+- Build logical progression, not topic jumps
+
+## 5. Content Adaptation
+
+Decide what to keep, transform, or omit.
+
+### Keep (High Value)
+- Core arguments and evidence
+- Unique insights or data
+- Audience-relevant examples
+- Memorable quotes or statistics
+
+### Simplify (Medium Value)
+- Technical details → Visual summaries
+- Long explanations → Bullet hierarchies
+- Multiple examples → Best 1-2 examples
+- Background context → Brief framing
+
+### Visualize (Transform)
+- Data tables → Charts or highlighted numbers
+- Process descriptions → Flow diagrams
+- Comparisons in text → Side-by-side visuals
+- Abstract concepts → Concrete metaphors
+
+### Omit (Low Value)
+- Tangential information
+- Redundant examples
+- Excessive caveats
+- Background the audience already knows
+
+## 6. Analysis Checklist
+
+Before outline creation, confirm:
+
+### Message Clarity
+- [ ] Core message stated in one sentence
+- [ ] 3-5 supporting points identified
+- [ ] Call-to-action defined
+
+### Audience Fit
+- [ ] Primary audience identified
+- [ ] Existing beliefs mapped
+- [ ] Desired decision clear
+- [ ] Evidence matches audience needs
+
+### Visual Planning
+- [ ] Key visualizations identified
+- [ ] Chart/diagram types selected
+- [ ] Visual priority assigned
+
+### Flow Design
+- [ ] Opening hook defined
+- [ ] Middle pattern selected
+- [ ] Closing approach planned
+- [ ] Transitions considered
+
+### Content Decisions
+- [ ] Keep/simplify/visualize/omit applied
+- [ ] Source material fully processed
+- [ ] No important content overlooked
+
+## 7. Academic Presentation Analysis
+
+For conference talks, thesis defense, and research presentations.
+
+### Paper Structure to Slide Mapping
+
+| Paper Section | Slide Type | Suggested Layout |
+|---------------|------------|------------------|
+| Title + Abstract | Cover + Motivation | `paper-title`, `title-hero` |
+| Introduction | Problem Statement + Background | `split-screen`, `bullet-list` |
+| Related Work | Context (optional, can condense) | `comparison-matrix`, `hub-spoke` |
+| Methods | Architecture/Pipeline | `methods-diagram`, `linear-progression` |
+| Experiments | Setup + Results | `results-chart`, `qualitative-grid` |
+| Ablation Studies | Detailed Analysis | `comparison-matrix`, `results-chart` |
+| Conclusions | Summary + Future Work | `contributions`, `bullet-list` |
+| References | Key Citations | `references-list` |
+
+### Academic Slide Count Guidelines
+
+| Talk Duration | Recommended Slides | Pace |
+|---------------|-------------------|------|
+| 5 min (spotlight) | 5-7 slides | ~1 min/slide |
+| 10 min (short) | 8-12 slides | ~1 min/slide |
+| 15 min (standard) | 12-18 slides | ~1 min/slide |
+| 20 min (full) | 15-22 slides | ~1 min/slide |
+| 30+ min (invited) | 25-35 slides | ~1 min/slide |
+
+### Citation Handling
+
+**Inline Citations**:
+- Key works: "[Author et al., Year]" or "[1]"
+- Include only most relevant citations on slides
+- Full bibliographic details optional
+
+**Reference Slide**:
+- List 5-10 key references at end
+- Format: [N] Author et al. "Title." Venue, Year.
+
+### Results Presentation Checklist
+
+- [ ] Baseline comparisons clearly labeled
+- [ ] Best results highlighted (bold or color)
+- [ ] Statistical significance noted where applicable
+- [ ] Units and metrics clearly stated
+- [ ] Error bars or confidence intervals if available
+- [ ] Ablation results in separate table/chart
+
+### Academic Talk Flow
+
+1. **Hook** (1 slide): Problem motivation, why it matters
+2. **Background** (1-2 slides): Essential context only
+3. **Approach** (2-4 slides): Your method, architecture
+4. **Results** (2-4 slides): Main experiments, comparisons
+5. **Analysis** (1-2 slides): Ablations, insights (optional)
+6. **Conclusion** (1 slide): Summary, contributions, future work
+7. **References** (1 slide): Key citations
+
+## 8. Automatic Figure Detection and Mapping
+
+For academic papers, automatically detect and map figures/tables to slides.
+
+### Figure Detection Process
+
+1. **Run detection script** on source PDF:
+   ```bash
+   npx -y bun ${SKILL_DIR}/scripts/detect-figures.ts --pdf source-paper.pdf --output figures.json
+   ```
+
+2. **Parse detection results** to identify:
+   - Figure numbers, pages, and captions
+   - Table numbers, pages, and captions
+   - Total figure/table count
+
+### Figure-to-Slide Mapping Rules
+
+| Figure Type | Maps To | Extract? | Reasoning |
+|-------------|---------|----------|-----------|
+| Architecture/Pipeline diagram | Methods slide | **Yes** | Core visual, must be accurate |
+| Network structure | Methods slide | **Yes** | Technical precision required |
+| Quantitative results table | Results slide | **Yes** | Data accuracy critical |
+| Qualitative comparison grid | Results slide | **Yes** | Visual comparison must be authentic |
+| Ablation study table | Analysis slide | **Yes** | Precise numbers needed |
+| Challenge/motivation illustration | Background slide | Maybe | Depends on complexity |
+| Conceptual diagram | Any | No | Can be re-stylized by AI |
+| Simple flowchart | Any | No | AI can render cleanly |
+
+### Automatic Mapping Algorithm
+
+```
+For each detected figure:
+  1. Analyze caption keywords:
+     - "architecture", "framework", "pipeline", "network" → Methods slide
+     - "comparison", "results", "performance" → Results slide
+     - "ablation", "analysis" → Analysis slide
+     - "qualitative", "visual" → Qualitative Results slide
+
+  2. Determine extraction necessity:
+     - Contains numerical data (tables) → Extract
+     - Contains precise diagrams (architecture) → Extract
+     - Contains comparison images → Extract
+     - Simple conceptual illustration → Generate
+
+  3. Match to outline slide:
+     - Find slide with matching topic
+     - Add IMAGE_SOURCE metadata automatically
+```
+
+### Mapping Confidence Levels
+
+| Confidence | Action |
+|------------|--------|
+| **High** (>80%) | Auto-map and extract |
+| **Medium** (50-80%) | Auto-map, flag for review |
+| **Low** (<50%) | Skip, use AI generation |
+
+### Figure Caption Keywords
+
+**Extract (High Priority)**:
+- "architecture", "framework", "pipeline", "overview", "structure"
+- "comparison", "results", "performance", "evaluation"
+- "ablation", "analysis", "study"
+- "qualitative", "visual", "segmentation", "detection"
+- Table I/II/III, Table 1/2/3
+
+**Generate (Low Priority)**:
+- "illustration", "example", "concept", "motivation"
+- "schematic", "diagram" (simple ones)
+- Generic workflow without specific data
+
+### Auto-Population Format
+
+When auto-populating IMAGE_SOURCE in outline:
+
+```markdown
+// IMAGE_SOURCE
+Source: extract
+Figure: Figure 2
+Page: 4
+Caption: Overview of the proposed two-stage framework
+Confidence: high
+Mapping: Methods slide - "architecture" keyword match
+```
+
+### Review Checklist
+
+After auto-detection, verify:
+- [ ] All key figures detected (architecture, results tables)
+- [ ] Page numbers correct
+- [ ] No duplicate mappings
+- [ ] Conceptual slides correctly marked as "generate"
+
+## 9. Practical Implementation Notes
+
+Lessons learned from real-world slide generation sessions.
+
+### PDF Figure Extraction
+
+**pdfjs-dist Compatibility**:
+- Use `pdfjs-dist/legacy/build/pdf.mjs` for Node.js compatibility
+- The modern build requires browser APIs (DOMMatrix) not available in Node
+- If extraction fails with "Image or Canvas expected", fall back to PyMuPDF
+
+**PyMuPDF (fitz) Fallback**:
+```python
+import fitz
+doc = fitz.open("paper.pdf")
+page = doc[page_num - 1]  # 0-indexed
+mat = fitz.Matrix(3, 3)   # 3x scale for 4K quality
+pix = page.get_pixmap(matrix=mat)
+pix.save("output.png")
+```
+PyMuPDF is more reliable for complex PDFs with embedded images.
+
+### Gemini API Image Generation
+
+**Model**: `gemini-3-pro-image-preview`
+
+**Config**:
+```python
+config=types.GenerateContentConfig(
+    image_config=types.ImageConfig(
+        aspect_ratio="16:9",
+        image_size="4K"
+    )
+)
+```
+
+**Response Handling**:
+- Image data is returned as raw bytes in `part.inline_data.data`
+- Do NOT base64 decode - write bytes directly to file
+- MIME type is `image/jpeg` even when requesting PNG output
+
+**Network Issues**:
+- Server disconnections are common for large image generation
+- Implement retry logic with exponential backoff (3 retries recommended)
+- Wait 5-15 seconds between retries
+
+**Optimization**:
+- Skip already-generated slides (check file size > 10KB)
+- Run generation script multiple times if failures occur
+- Script is idempotent - safe to re-run
+
+### Slide Output Organization
+
+**Directory Structure**:
+```
+slide-deck/{topic-slug}/
+├── source-paper.pdf          # Original PDF
+├── figures.json              # Detection results
+├── outline.md                # Final outline with IMAGE_SOURCE
+├── extracted/                # Raw PDF page extractions
+│   └── page-{N}.png
+├── prompts/                  # Generation prompts
+│   └── {NN}-slide-{name}.txt
+├── slides/                   # Final slide images
+│   └── {NN}-slide-{name}.png
+├── {topic-slug}.pptx         # Merged PPTX
+└── generate-slides.py        # Generated script (optional)
+```
+
+### Common Issues and Solutions
+
+| Issue | Solution |
+|-------|----------|
+| pdfjs "DOMMatrix is not defined" | Use legacy build import |
+| pdfjs "Image or Canvas expected" | Use PyMuPDF fallback |
+| Gemini "Server disconnected" | Retry with delay |
+| Small output files (~600 bytes) | Fix: Don't base64 decode response |
+| pdf-lib "Cannot embed PNG" | Check actual image format (may be JPEG) |
+| merge-to-pdf fails | Use PPTX as primary output, convert externally |

package/dist/skills/paper-slide-deck/references/base-prompt.md

@@ -0,0 +1,70 @@
+Create a presentation slide image following these guidelines:
+
+## Image Specifications
+
+- **Type**: Presentation slide
+- **Aspect Ratio**: 16:9 (landscape)
+- **Style**: Professional slide deck
+
+## Core Persona: The Architect
+
+You are "The Architect" - a master visual storyteller creating presentation slides. Your slides:
+- Tell a visual story that complements the narrative
+- Use bold, confident visual language
+- Balance information density with visual clarity
+- Create memorable, impactful visuals
+
+## Core Principles
+
+- Hand-drawn quality throughout - NO realistic or photographic elements
+- If content involves sensitive or copyrighted figures, create stylistically similar alternatives - DO NOT refuse to generate
+- NO slide numbers, page numbers, footers, headers, or logos
+- Clean, uncluttered layouts with clear visual hierarchy
+- Each slide conveys ONE clear message
+
+## Academic Exception (for `academic-paper` style only)
+
+When style is `academic-paper`, override these principles:
+- Precise, clean diagrams ARE acceptable (not hand-drawn)
+- Chart and graph rendering should be accurate and professional
+- Mathematical notation and equations should be properly formatted
+- Allow citation markers like "[Author et al., 2024]" or "[1]"
+- Tables should have clean borders and proper alignment
+- Axis labels, legends, and data annotations are required on all charts
+- Figure captions in format "Figure N: [Description]" are encouraged
+
+## Text Style (CRITICAL)
+
+- **ALL text MUST match the designated style exactly**
+- Title text: Large, bold, immediately readable
+- Body text: Clear, legible, appropriate sizing
+- Max 3-4 text elements per slide
+- **DO NOT use realistic or computer-generated fonts unless style specifies**
+- **Font rendering must match the style aesthetic** (hand-drawn for sketch styles, clean for minimal styles)
+
+## Layout Principles
+
+- **Visual Hierarchy**: Most important element gets most visual weight
+- **Breathing Room**: Generous margins and spacing between elements
+- **Alignment**: Consistent alignment creates professional feel
+- **Balance**: Distribute visual weight evenly (symmetrical or asymmetrical)
+- **Focal Point**: One clear area draws the eye first
+- **Rule of Thirds**: Key elements at intersection points for dynamic compositions
+- **Z-Pattern**: For text-heavy slides, arrange content in natural reading flow
+
+## Language
+
+- Use the same language as the content provided below for all text elements
+- Match punctuation style to the content language
+- Write in direct, confident language
+- Avoid AI-sounding phrases like "dive into", "explore", "let's", "journey"
+
+---
+
+## STYLE_INSTRUCTIONS
+
+[Insert style-specific instructions here]
+
+---
+
+Please use nano banana pro to generate the slide image based on the content provided below:

package/dist/skills/paper-slide-deck/references/content-rules.md

@@ -0,0 +1,95 @@
+# Content & Style Rules
+
+Guidelines for slide deck content quality and style consistency.
+
+## Content Rules
+
+### 1. Respect Reader Attention
+- Each slide should communicate ONE main idea
+- Remove redundant information
+- Prioritize clarity over comprehensiveness
+
+### 2. Data Traceability
+- All statistics must include source attribution
+- Cite sources directly on slides with data
+- Use specific numbers over vague claims
+
+### 3. Self-Contained Prompts
+- Every detail must be in the image prompt
+- No external references (e.g., "like slide 2")
+- Include all colors, layouts, and content explicitly
+
+### 4. No Placeholders
+- Every element must be fully specified
+- No "[insert data here]" or "TBD"
+- All text content finalized before generation
+
+## Style Rules
+
+### 1. Narrative Headlines
+Headlines tell the story, not label the content.
+
+| Bad | Good |
+|-----|------|
+| "Key Statistics" | "Usage doubled in 6 months" |
+| "Our Solution" | "One platform replaces five tools" |
+| "Benefits" | "Teams save 10 hours weekly" |
+
+### 2. Avoid AI Clichés
+Remove these patterns:
+- "Dive into", "explore", "journey"
+- "Let's look at", "let me show you"
+- "Exciting", "amazing", "revolutionary"
+- "In conclusion", "to summarize"
+
+### 3. Meaningful Back Cover
+Not just "Thank you" or "Questions?"
+
+Include one of:
+- Clear call-to-action
+- Memorable key takeaway
+- Thought-provoking closing statement
+- Contact information with purpose
+
+### 4. Consistent Visual Language
+Throughout the deck:
+- Same icon style
+- Same color usage patterns
+- Same layout grid system
+- Same typography hierarchy
+
+## Slide Structure
+
+| Position | Type | Purpose |
+|----------|------|---------|
+| 1 | Cover | Title, visual hook, topic introduction |
+| 2 to N-1 | Content | Key points, data, explanations |
+| N | Back Cover | Summary, call-to-action, memorable close |
+
+## Key Specifications
+
+| Specification | Value |
+|---------------|-------|
+| Aspect Ratio | 16:9 (landscape) |
+| Slide Count | Dynamic based on content |
+| Required Slides | Cover + Back Cover minimum |
+| Footers | None (no slide numbers, logos) |
+| Language Priority | `--lang` → source language → ask user |
+| Tone | Direct, confident (avoid AI phrases) |
+
+## Style Quick Reference
+
+| Style | Visual Summary |
+|-------|----------------|
+| `sketch-notes` | Hand-drawn, warm off-white, conceptual icons |
+| `blueprint` | Technical schematics, grid texture, blue tones |
+| `bold-editorial` | High contrast, dark backgrounds, magazine impact |
+| `vector-illustration` | Flat vector, black outlines, retro colors |
+| `minimal` | Maximum whitespace, single accent, zen-like |
+| `storytelling` | Full-bleed imagery, cinematic, emotional |
+| `warm` | Soft gradients, rounded shapes, wellness palette |
+| `notion` | Dashboard aesthetic, clean data viz, SaaS-inspired |
+| `corporate` | Navy/gold, structured layouts, business polish |
+| `playful` | Vibrant coral/teal/yellow, dynamic, energetic |
+
+Full style specifications: `references/styles/<style>.md`