researcher

What this skill does

# Researcher

Create distinctive, memorable HTML one-pagers that avoid generic "AI slop" aesthetics.

## Setup Required

Before using this skill, configure your output directory:

```bash
# Add to your shell profile (~/.zshrc or ~/.bashrc)
export RESEARCHER_DIR="$HOME/research"

# Create the directory structure
mkdir -p "$RESEARCHER_DIR/html" "$RESEARCHER_DIR/md" "$RESEARCHER_DIR/pdf"
```

**Requirements:**
- macOS, Linux, or Windows with WSL
- Brave Browser or Google Chrome installed

## Instructions

When the user asks to research a topic and create a PDF:

1. **Research the topic** and gather key information
2. **Choose an aesthetic preset** based on content type (see Document Aesthetics below)
3. **Create an HTML file** in `$RESEARCHER_DIR/html/` with:
   - Filename: `{topic-slug}-YYYYMMDD.html` (lowercase, hyphens, date suffix)
   - Example: `python-web-frameworks-20251212.html`
   - Date is the creation date; keep original date if updating later
   - Compact, print-friendly design (max 1-2 pages)
   - Follow the design standards below

4. **Generate the PDF** by running:
   ```bash
   research-pdf-generate
   ```
   Or if the command isn't in PATH:
   ```bash
   $RESEARCHER_DIR/generate-pdfs.sh
   ```

5. **Verify** the PDF was created in `$RESEARCHER_DIR/pdf/`

## File Locations

All paths relative to `$RESEARCHER_DIR` (defaults to `~/research`):

| Purpose | Path |
|---------|------|
| HTML source files | `$RESEARCHER_DIR/html/` |
| Markdown source files | `$RESEARCHER_DIR/md/` |
| Generated PDFs | `$RESEARCHER_DIR/pdf/` |
| Conversion script | `$RESEARCHER_DIR/generate-pdfs.sh` |

---

## Output Modes

### HTML Mode (Default)
Full-featured output with curated CSS aesthetics. Best for:
- Visually distinctive documents
- Browser viewing with micro-interactions
- Print-quality PDFs

### Markdown Mode
Lightweight plaintext output. Best for:
- Version control (git-friendly)
- Easy editing
- Cross-platform compatibility
- Quick notes and drafts

When user requests Markdown output:
1. Create file in `$RESEARCHER_DIR/md/{topic-slug}-YYYYMMDD.md`
2. Use clean Markdown formatting (no HTML)
3. Include YAML frontmatter for metadata

**Markdown Template:**
```markdown
---
title: [Document Title]
date: YYYY-MM-DD
author: Researcher by @jontsai
tags: [tag1, tag2]
---

# [Document Title]

[Brief summary/abstract]

## Section 1

Content...

## Section 2

Content...

---

## References

1. [Source Name](url) — Description
2. [Source Name](url) — Description

---

*Generated by [Researcher](https://github.com/jontsai/claude-plugins) — Claude Code plugin by [@jontsai](https://github.com/jontsai)*
```

---

## Design Philosophy

**CRITICAL: Avoid generic AI aesthetics.** Every document should have distinctive character.

### What to AVOID (Generic AI Slop)
- System font stacks (`-apple-system, BlinkMacSystemFont, Roboto`)
- Flat white/gray backgrounds with no texture
- Purple gradients on white (overused AI default)
- Identical layouts across all document types
- No motion or interactivity in browser view

### What to EMBRACE
- **Intentional typography** - Fonts chosen for the content's personality
- **Texture and atmosphere** - Paper grain, subtle patterns, depth
- **Micro-interactions** - Hover states, transitions (for browser viewing)
- **Layout surprise** - Break the grid occasionally for emphasis
- **Cohesive theming** - CSS variables for consistency

---

## Document Aesthetics (Choose Based on Content Type)

### 1. TERMINAL - For Dev Tools, CLI, Technical Cheatsheets
Dark theme with hacker aesthetic. Think terminal green on dark.

```css
:root {
  --font-display: 'JetBrains Mono', 'Fira Code', monospace;
  --font-body: 'JetBrains Mono', 'Fira Code', monospace;
  --color-ink: #e6edf3;
  --color-ink-bright: #00ff88;
  --color-ink-dim: #7d8590;
  --color-paper: #0d1117;
  --color-paper-elevated: #161b22;
  --color-accent: #58a6ff;
  --color-accent-soft: rgba(88, 166, 255, 0.1);
  --color-border: #30363d;
  --color-muted: #484f58;
}
body {
  background: var(--color-paper);
  color: var(--color-ink);
  /* CRT scanline effect */
  background-image: repeating-linear-gradient(
    0deg,
    transparent,
    transparent 2px,
    rgba(0, 255, 136, 0.03) 2px,
    rgba(0, 255, 136, 0.03) 4px
  );
}
```

### 2. EDITORIAL - For Restaurant Guides, Reviews, Lifestyle
Warm, magazine-like. Serif headlines, refined spacing.

```css
:root {
  --font-display: 'Playfair Display', 'Crimson Pro', Georgia, serif;
  --font-body: 'Source Sans 3', 'Libre Franklin', sans-serif;
  --color-ink: #1a1a1a;
  --color-paper: #fefcf9;
  --color-accent: #c41e3a; /* Carmine red */
  --color-accent-soft: #fef0f2;
  --color-muted: #6b7280;
}
body {
  background: var(--color-paper);
  /* Subtle paper texture */
  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 200 200' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)' opacity='0.04'/%3E%3C/svg%3E");
}
h1 {
  font-family: var(--font-display);
  font-weight: 700;
  letter-spacing: -0.02em;
  border-bottom: 3px double var(--color-accent);
}
```

### 3. CORPORATE - For Business Analysis, Board Docs, Professional
Navy + gold accents. Refined, trustworthy, premium feel.

```css
:root {
  --font-display: 'Fraunces', 'Source Serif Pro', Georgia, serif;
  --font-body: 'Inter', 'Source Sans 3', sans-serif;
  --color-ink: #1e293b;
  --color-paper: #ffffff;
  --color-accent: #1e40af; /* Deep blue */
  --color-accent-gold: #b8860b;
  --color-accent-soft: #eff6ff;
  --color-muted: #64748b;
}
body {
  background: linear-gradient(180deg, #ffffff 0%, #f8fafc 100%);
}
h1 {
  color: var(--color-accent);
  border-bottom: 2px solid var(--color-accent-gold);
}
.section h2 {
  background: linear-gradient(135deg, var(--color-accent), #1e3a8a);
  color: white;
}
```

### 4. INDUSTRIAL - For Automotive, Hardware, Specs
Bold, utilitarian, data-forward. Wide headers, strong lines.

```css
:root {
  --font-display: 'Oswald', 'Bebas Neue', Impact, sans-serif;
  --font-body: 'Barlow', 'Roboto Condensed', sans-serif;
  --color-ink: #111827;
  --color-paper: #f3f4f6;
  --color-accent: #dc2626; /* Industrial red */
  --color-accent-alt: #fbbf24; /* Warning yellow */
  --color-stripe: #1f2937;
}
body {
  background: var(--color-paper);
  /* Subtle grid pattern */
  background-image:
    linear-gradient(rgba(0,0,0,0.03) 1px, transparent 1px),
    linear-gradient(90deg, rgba(0,0,0,0.03) 1px, transparent 1px);
  background-size: 20px 20px;
}
h1 {
  font-family: var(--font-display);
  text-transform: uppercase;
  letter-spacing: 0.1em;
  background: var(--color-stripe);
  color: white;
  padding: 12px 20px;
  margin: -20px -20px 20px -20px;
}
```

### 5. FRESH - For Health, Eco, Nature Topics
Organic feel, soft greens, breathing space.

```css
:root {
  --font-display: 'DM Serif Display', Georgia, serif;
  --font-body: 'DM Sans', 'Nunito', sans-serif;
  --color-ink: #1a3d2e;
  --color-paper: #f0fdf4;
  --color-accent: #16a34a;
  --color-accent-soft: #dcfce7;
  --color-earth: #78716c;
}
body {
  background: linear-gradient(135deg, #f0fdf4 0%, #ecfdf5 50%, #f0fdf9 100%);
}
.section {
  border-radius: 16px;
  border: 1px solid #bbf7d0;
}
```

---

## Required CSS Foundation

Every document MUST include this foundation:

```css
*, *::before, *::after {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

body {
  font-family: var(--font-body);
  font-size: 11px;
  line-height: 1.5;
  padding: 20px;
  max-width: 8.5in;
  margin: 0 auto;
  color: var(--color-ink);
  background: var(--color-paper);
}

/* Micro-interactions for browser viewing */
.section {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}
.section:hover {
  transform: translateY(-2px);
  box-shadow: 0 8px 30px rgba(0,0,0,0.08);
}

tr {
  transition: background 0.15s ease;
}
tr:hover {
  background: var(--color-accent-soft) !imp