# Guide — The Hitchhiker's Guide to Content Creation

> "A towel is about the most massively useful thing an interstellar hitchhiker can have."
> A good morning brief is a close second.

An automated content pipeline for Claude Code. Fetches signals from RSS feeds, Gmail newsletters, and Hacker News, then produces a narrative daily brief, multiple LinkedIn drafts, and blog outlines — written in your authentic voice, delivered to your phone.

## Security & Trust

Guide is not just prompt text — it ships executable helper scripts and workflows. When configured, it can read newsletter content from Gmail, fetch external URLs from those newsletters, and send notifications through iMessage or Slack.

Use it only in environments and accounts you trust, review the scripts before enabling them, and keep credentials such as Slack webhooks or Gmail auth outside the repository.

## Quick Start

1. **Install**:
   ```
   /plugin install guide@heart-of-gold-toolkit
   ```

2. **Set up** — the wizard walks you through sources, themes, and voice:
   ```
   /guide:setup
   ```

3. **Run**:
   ```
   /guide:pipeline
   ```

## Skills

### /guide:setup

Interactive configuration wizard. Asks what RSS feeds you read, whether you use Gmail newsletters, what topics matter to you, and how you write. Creates `content/config.yaml` and offers to run your first pipeline.

Run once to get started. Run again any time to add sources or change settings.

### /guide:pipeline

The daily content engine. Fetches ~100 signals, scores them against your themes, and produces:

- **A narrative brief** — opens with "The Story" (what's happening in the world right now, woven from 3-5 signals), followed by tiered reading list and content angles
- **3 LinkedIn drafts** — each from a different angle, different tone, different entry point
- **Blog outline** — weekly, when an angle deserves deeper treatment (emotional arc structure)
- **YouTube/long-form ideas** — topics worth ranting about on camera

Then commits everything to git, pushes to GitHub, and sends a rich mini-brief via iMessage with clickable links.

**Source weighting:** Newsletters (1.5x) > Gmail digests (1.2x) > HN (1.0x). Voice captures get 2x weight — your own thoughts are the highest-value input.

### /guide:capture

Daily thought capture. Morning intentions or evening reflections.

```
/guide:capture       # morning mode (auto-detected before noon)
/guide:capture pm    # evening mode
```

Works from the terminal or via **iMessage replies** when running with `--channels plugin:imessage@claude-plugins-official`. Get a nudge, reply with your thoughts, Claude saves the capture with detected themes and connections.

### /guide:write-post

Guided blog writing in seven phases:
1. Context gathering
2. Scaffolding
3. Guided dictation
4. Shaping
5. Iteration
6. Publish preparation
7. Audio narration

Can pick up blog outlines generated by the pipeline (`needs_write_post: true` in frontmatter).

### /guide:claude-code

Headless Claude Code handoff for second opinions, code review, targeted analysis, or follow-up on a bounded task.

Use it when you want another agent harness to invoke Claude Code non-interactively, capture the result, and summarize it back. The skill ships with a small wrapper script that standardizes `claude -p` / resume usage across installs.

### /guide:codex

Headless OpenAI Codex CLI handoff for code analysis, refactoring, or automated editing. Use when you want to invoke `codex exec` / `codex resume` non-interactively and bring the result back.

### /guide:gemini

Headless Google Gemini CLI handoff for code analysis, refactoring, or automated editing. Use when you want to invoke `gemini` / `gemini resume` non-interactively and bring the result back.

## How the Pipeline Works

```
Sources (RSS + Gmail + HN)
  ↓
Scout → fetch scripts (fetch-rss.py, fetch-gmail.sh, fetch-hn.sh)
  ↓
Analyze → score 1-5 against themes, dedup vs last 3 briefs, find 4-6 angles
  ↓
Create → narrative brief + 3 LinkedIn drafts + blog outline + YouTube ideas
  ↓
Edit → voice fidelity check (base 85, jargon -10, claims -5, threshold 75)
  ↓
Deliver → git commit + push + iMessage brief with GitHub links
```

## Configuration

Full schema in `defaults/config.yaml`. Key sections:

| Section | What it controls |
|---------|-----------------|
| `voice` | Voice profile path, tone keywords, 17-term jargon blocklist |
| `themes` | Personal + professional topics for signal scoring |
| `sources.rss` | RSS/Atom feeds with freshness windows |
| `sources.gmail` | Gmail label, max items (uses `gws` CLI) |
| `sources.hackernews` | Top stories limit |
| `sources.web_search` | Search keywords (optional) |
| `agents` | Model assignments per pipeline phase (scout: sonnet, creator: opus, etc.) |
| `cadence` | LinkedIn 3x/week, blog biweekly targets |
| `notifications` | iMessage recipient, Slack webhook |
| `output` | Directory paths for briefs, drafts, pipeline state, captures |

## Running on a Schedule

### Option A: launchd (one-shot, headless)

```bash
cp scripts/com.heart-of-gold.pipeline.plist ~/Library/LaunchAgents/
# Edit: WorkingDirectory, Hour, PATH
launchctl load ~/Library/LaunchAgents/com.heart-of-gold.pipeline.plist
```

Uses `claude -p "Run /guide:pipeline..." --model sonnet` in headless mode. Lock file prevents concurrent runs.

### Option B: Persistent session with iMessage

```bash
claude --channels plugin:imessage@claude-plugins-official
```

Set up in-session crons with `CronCreate` for the pipeline (e.g., 2 AM daily), morning capture nudge, and evening capture nudge. This enables two-way iMessage interaction — briefs arrive in your self-chat, you reply to give feedback or do captures.

## Scripts

| Script | Language | What it does |
|--------|----------|-------------|
| `fetch-rss.py` | Python | Parse RSS/Atom feeds, filter by freshness, strip HTML |
| `fetch-gmail.sh` | Bash | Fetch Gmail newsletters via `gws` CLI `+triage` helper |
| `fetch-hn.sh` | Bash | Fetch HN top stories via Firebase API, parallel item fetching |
| `notify.sh` | Bash | Send iMessage (osascript) or Slack (webhook) notifications |

## Dependencies

- Python 3.10+ with `feedparser` and `pyyaml`
- `jq`, `curl`, and `zip`
- Bun runtime for the share-server reference implementation and CLI handoff skills
- Optional: `gws` CLI (Gmail), `osascript` (iMessage), `bun` (iMessage plugin server), `tailscale` CLI (private viewer exposure)

## Tests

287 story-based tests + 10 security red-team tests:

```bash
pytest                                                    # standard suite
pytest --override-ini="python_files=test_*" \
       --override-ini="python_functions=test_*"           # include red-team
```