# MailDrop User Guide

## What This Is

MailDrop converts email into clean markdown files. No AI inside. No cloud. No API keys. Just a Python app that sits next to Outlook, strips out the corporate noise (signatures, disclaimers, "Sent from my iPhone"), and gives you a clean text file you can hand to any AI assistant.

It also generates structured communication files — Tunnels, Pulses, Forges, and Senates — that replace meetings with async, written, trackable processes.

## Setup

### Requirements

- Python 3.11+ (3.12 or 3.14 recommended)
- macOS or Windows

### Install

```bash
cd maildrop
python -m venv .venv

# macOS/Linux
.venv/bin/pip install -r requirements.txt

# Windows
.venv\Scripts\pip install -r requirements.txt
```

### Configure

Edit `maildrop.toml` to set your paths and name:

```toml
[paths]
inbox = "~/Documents/maildrop/inbox"
outbox = "~/Documents/maildrop/inbox/outbox"

[window]
width = 340
min_height = 580
always_on_top = true

[user]
name = "Your Name"
```

The `name` field pre-fills the Name input so you don't type it every launch.

### Run

```bash
# macOS/Linux
.venv/bin/python maildrop.py

# Windows
.venv\Scripts\python maildrop.py
```

### Pin the inbox to your Dock (macOS)

Drag `~/Documents/maildrop/inbox/` to the right side of your Dock. This gives you a one-drag workflow: Outlook email → Dock folder → MailDrop picks it up automatically.

---

## Converting Email

### The Problem

You get an email. It's HTML soup with nested reply chains, legal disclaimers, and "Sent from my iPhone." You want to give it to an AI to help you respond. If you paste the raw email, half the AI's context window is wasted on noise.

### The Fix

1. **Drag the email from Outlook to Finder** (to your Desktop, Downloads, or the inbox Dock folder). This creates a `.eml` file. Direct drag from Outlook to MailDrop won't work on most systems — Outlook doesn't hand off `.eml` data to non-native targets.

2. **MailDrop converts it.** If you dropped it in the inbox folder, it happens automatically. If you have the `.eml` somewhere else, drag it onto the MailDrop drop zone.

3. **The result:** The original `.eml` stays in `inbox/`. A clean `.md` file appears in `inbox/outbox/`. The preview pane shows you what the AI will see.

4. **Use it.** Hit "Copy Path" or "Copy Markdown" and hand it to your AI.

### What Gets Stripped

- Email signatures (`--` delimiter and everything below)
- Legal disclaimers ("This email is intended only for...")
- Device footers ("Sent from my iPhone", "Get Outlook for iOS")
- Excess blank lines
- HTML formatting → clean markdown

### What Gets Kept

- Subject line (as a `#` heading)
- From, To, CC, Date
- The actual message body, in clean markdown

---

## The Four Patterns

MailDrop can generate starter files for four communication patterns that replace meetings. Each file contains instructions that any AI assistant can read and follow — the AI doesn't need to know your system. The file teaches it.

### How to Initiate

1. Enter your **Name** (required, can't be "Anonymous" — we need attribution)
2. Enter a **Topic** or hit the dice button for a random one
3. Click **Tunnel**, **Pulse**, **Forge**, or **Senate**
4. A `.md` file appears in `inbox/outbox/` with a thread ID as the filename

### File Naming

Every pattern file is named:

```
TID_YYYYMMDD_RANDOM_PATTERN_your-topic.md
```

Example: `TID_20260413_847291_FORGE_migration-plan.md`

Split on `_` and you get five fields:
- `TID` — prefix, marks this as a tracked thread
- `20260413` — date
- `847291` — random 6 digits (uniqueness)
- `FORGE` — which pattern
- `migration-plan` — your human-readable topic

The same TID appears inside the file. This is the thread ID. All files in the same conversation share this ID. Any AI reading the files can reconstruct the full history by finding all files with the same TID.

---

### Tunnel — Replaces Email Chains

**What it is:** Structured communication where the content goes in a markdown file, not the email body. The email is just the envelope.

**When to use it:** Any time you'd normally write a long email — status updates, proposals, summaries, requests.

**How it works:**

1. Initiate a Tunnel in MailDrop
2. Fill in the template with your AI's help
3. Email the `.md` file as an attachment. Keep the email body to one line: "Attached: status update. Let me know if questions."
4. Put the thread ID in the subject line: `RE: Migration Status [TID_20260413_847291_TUNNEL_migration-status]`
5. When the recipient replies, they attach their own `.md` with the same thread ID
6. Any AI on either end reads all files with that TID and reconstructs the full conversation

**The recipient doesn't need MailDrop.** They don't even need AI. They can read the markdown with their eyes and reply however they want. The tunnel works at any speed, with or without AI at every node.

---

### Pulse — Replaces Standup Meetings

**What it is:** Five async questions answered daily in writing. AI synthesizes a morning brief.

**When to use it:** Daily team status. Replaces the 30-minute standup where seven people say "no blockers."

**The five questions:**

1. What did you ship or close?
2. What are you working on now?
3. What's blocked and what do you need?
4. Any risks or surprises?
5. Anything the team should know?

**How it works:**

1. Each team member gets a Pulse file (initiate one per person or share one template)
2. Fill in answers — takes five minutes
3. Collect all submissions, hand them to an AI: "Read all of these and produce a morning brief. Flag blockers, identify conflicts, surface risks."
4. Manager reads a one-page synthesis instead of sitting in a room

---

### Forge — Replaces Brainstorming Meetings

**What it is:** Blind parallel brainstorming. Everyone works independently. Nobody sees anyone else's submission until the deadline.

**When to use it:** You have a problem and need ideas. The first idea in a room anchors everyone else — the Forge removes the room.

**The mandatory field:** Every submission must include "Why This Might Fail." You can't propose an idea without attacking it yourself first. This kills groupthink.

**How it works:**

1. Initiator posts the problem and sets a deadline
2. Each participant gets a Forge file, fills it in independently with their AI's help
3. **No peeking.** Blind until deadline.
4. After deadline, collect all submissions and hand them to an AI: "Read all submissions. Cluster similar ideas, surface outliers, map conflicts, recommend a shortlist."
5. The AI produces a Forge Report. Discuss from there.

---

### Senate — Replaces Decision Meetings

**What it is:** Written debate rounds with named votes on the record. Dissent is preserved by policy.

**When to use it:** The Forge produced a shortlist but no clear winner. Time to decide.

**How it works:**

1. Initiator states the decision and lists options
2. Each participant fills in a Senate file: their position, their arguments, their concerns about other options
3. Rounds continue until 70% agreement
4. Final round: named, attributed votes. On the record.
5. If you voted no and explained why, that's preserved forever. If the decision blows up six months later, the record shows who saw it coming.

**Why named votes matter:** People commit differently when their name is on record. Anonymous polls produce different (worse) outcomes than attributed positions.

---

## Using MailDrop with Claude Code

This is the smoothest workflow. Claude Code can read files directly from your filesystem.

### Converting and responding to email

```
You: "Read /Users/me/Documents/maildrop/inbox/outbox/TID_20260413_847291_TUNNEL_migration-status.md
      and draft a response. Same format, same thread ID."

Claude: [reads the file, drafts a response in the same Tunnel format, writes it to disk]
```

That's it. Claude reads the clean markdown, understands the structure and the thread ID, and produces a response you can attach to an email.

### Running a Forge

```
You: "I need to run a Forge. The problem is: our data pipeline takes 6 hours
      and needs to be under 1 hour. Generate the problem statement."

Claude: [writes the Forge file to your outbox]

# After collecting submissions from your team:

You: "Read all the Forge submissions in /Users/me/Documents/maildrop/inbox/outbox/
      that have FORGE in the filename. Produce a Forge Report: cluster ideas,
      surface outliers, map conflicts, recommend a shortlist."

Claude: [reads all files, produces synthesis]
```

### Running a Senate

```
You: "The Forge narrowed it to three options. Initiate a Senate. Here are the options:
      1. Rewrite in Spark  2. Optimize existing SQL  3. Move to streaming"

Claude: [generates the Senate file with the three options]

# After collecting position statements:

You: "Read all Senate submissions for this thread. Track convergence.
      Have we hit 70%? If not, summarize the disagreements for the next round."

Claude: [analyzes positions, reports convergence or divergence]
```

### Daily Pulse

```
You: "Read all Pulse submissions in today's folder. Produce a morning brief.
      Flag blockers, identify conflicts across teams, surface risks."

Claude: [synthesizes all check-ins into a 1-page brief]
```

---

## Using MailDrop with Any Other AI

You don't need Claude. You don't need Claude Code. You don't even need a CLI. Any AI that can read text works — ChatGPT, Copilot, Gemini, your corporate AI portal, whatever IT lets you have.

The workflow is the clipboard.

### ChatGPT / Gemini / Corporate Portal (web)

1. MailDrop creates the `.md` file in your outbox
2. Hit **Copy Markdown** in MailDrop
3. Paste into the chat window
4. Type your instruction: "Draft a response to this email. Keep it professional, address the three questions, and use the same thread ID."
5. Copy the AI's response back
6. Paste into a new `.md` file (or just paste into Outlook if the recipient isn't using the system yet)

### Copilot in Microsoft 365

1. Open the `.md` file in your outbox with any text editor
2. Select all, copy
3. Open Copilot in Word, Teams, or the web sidebar
4. Paste and instruct
5. Copy result back

### The difference

With Claude Code, the AI reads and writes files directly. No copy-paste. With everything else, you're the clipboard bridge between the AI and the filesystem. Both work. One is smoother.

What you lose without Claude Code:
- Direct file access (you copy-paste instead)
- Multi-file reads (you paste one at a time, or concatenate)
- File writing (you copy the output and save it yourself)

What you keep:
- The clean markdown (the noise is still stripped)
- The thread ID (copy-paste preserves it)
- The meeting patterns (the AI instructions are in the file — any AI can read them)
- The structure (all four patterns work with any AI)

---

## Folder Structure

```
~/Documents/maildrop/
  inbox/                    ← drag emails here (from Outlook via Finder)
    outbox/                 ← converted .md files and pattern files land here
    some-email.eml          ← originals stay in inbox
```

The inbox Dock folder is your drop target. The outbox is where you find results. One Finder window, up and down.

---

## Tips

- **Name persists between sessions.** Set it once.
- **Topic clears on OK.** Each new initiation gets a fresh topic.
- **The dice button** generates a random two-word topic if you just need a quick placeholder.
- **You can have multiple threads open.** Each TID is unique. Files don't collide.
- **The AI instructions block** at the top of every pattern file is the key feature. A completely clueless AI reads that block and knows exactly what to do. You don't need to explain the system — the file explains itself.

---

## What This Is Not

- **Not an AI.** No LLM inside. No API calls. No cloud. Just file conversion and template generation.
- **Not a mail client.** It doesn't send or receive email. Outlook does that. MailDrop converts and structures.
- **Not a database.** Files are files. You organize them however you want. The TID in the filename is the only protocol.

---

*MailDrop was built by Bill Berger with Claude Code. The meeting patterns (Pulse, Forge, Senate, Hangout) are Bill's, designed from two decades of watching meetings fail. The AI wrote the code. The human knew why meetings are broken.*
