ai-courier 0.3.2__tar.gz

ai_courier-0.3.2/.claude/settings.local.json

@@ -0,0 +1,20 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add *)",
+      "Bash(git commit -m ' *)",
+      "Bash(git checkout *)",
+      "Bash(COURIER_LIVE_TESTS=1 pytest tests/e2e/ -v --collect-only)",
+      "Bash(ruff check *)",
+      "Bash(.venv/bin/python -m pytest --version)",
+      "Bash(.venv/bin/python -c \"import pytest; print\\(pytest.__version__\\)\")",
+      "Bash(/opt/homebrew/bin/python3 -c \"import pytest; print\\(pytest.__version__, pytest.__file__\\)\")",
+      "Bash(.venv/bin/python -m pip install -e \".[dev]\")",
+      "Bash(.venv/bin/ruff check *)",
+      "Bash(COURIER_LIVE_TESTS=1 .venv/bin/python -m pytest tests/e2e/ -v --collect-only)",
+      "Bash(.venv/bin/python -m pytest tests/ --collect-only)",
+      "Bash(git commit -m 'test: add opt-in E2E harness with session fixtures *)",
+      "Bash(COURIER_LIVE_TESTS=1 .venv/bin/pytest tests/e2e/ -v --collect-only)"
+    ]
+  }
+}

ai_courier-0.3.2/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+*.db
+config.json
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

ai_courier-0.3.2/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to Courier are documented here. Format loosely based on
+[Keep a Changelog](https://keepachangelog.com/); versioning follows SemVer.
+
+## [0.3.2] — 2026-04-17
+
+### Changed
+- **PyPI package renamed from `courier-mcp` to `ai-courier`** ahead of first
+  public PyPI release. Avoids collision with the unrelated `@trycourier/courier-mcp`
+  (Courier Inc.'s notification-API MCP server on npm) and positions the name
+  for cross-provider ambition — future Gmail / Exchange / Apple bindings
+  stay inside the same package rather than being stuck with a Fastmail-
+  flavored name.
+- Install changes from `pip install courier-mcp` → `pip install ai-courier`.
+- Everything else unchanged: repo stays `iamdadzilla/courier`, CLI verb
+  stays `courier`, MCP server command stays `courier-mcp`, project and
+  brand stay "Courier". Only the PyPI distribution name moves.
+
+## [0.3.1] — 2026-04-17
+
+### Added
+- **`courier test-cleanup`** — sweep stray `[courier-e2e*]` test artifacts
+  from all mailboxes to Trash. Idempotent; filters out already-trashed
+  matches. Addresses the fixture-teardown orphan problem surfaced after
+  the first live Fastmail-MCP-free sweep.
+
+## [0.3.0] — 2026-04-17
+
+### Added
+- **Folder filing** — `email_mailboxes` lists folders/labels with paths;
+  `email_move(ids, to)` moves to a mailbox by ID, name, or path
+  (`"Clients/Guardian"`); `email_label(ids, labels, add)` adds/removes
+  mailbox memberships without touching other memberships.
+- **Threaded reply** — `email_reply(email_id, body, send, include_quote)`
+  composes a proper reply (In-Reply-To, References, `Re:` prefix,
+  Reply-To-or-From To: resolution); creates a draft by default.
+- **E2E test suite** — `tests/e2e/`, opt-in via `COURIER_LIVE_TESTS=1`,
+  self-cleaning via a `Courier/Tests` mailbox and `Courier Tests`
+  calendar. New `courier test-setup` CLI command creates the sandbox.
+- CLI verbs: `courier mailboxes`, `courier move`, `courier label`,
+  `courier reply`, `courier test-setup`.
+- `Email.message_id` and `Email.reply_to_addrs` — extracted from JMAP.
+
+### Fixed
+- `_normalize_utcdate` silently passed non-UTC offsets through, so
+  `datetime.now(tz=UTC).isoformat()` output returned empty search
+  results with no error. Now validates via `datetime.fromisoformat`
+  and rejects non-UTC offsets with `ValueError`.
+- `create_draft` sent `inReplyTo` as a string, but RFC 8621 §4.1.3.1
+  types it as `String[]`. Fastmail rejected threaded draft creates.
+  Now wrapped in a list; parsing normalizes list-or-string-or-None
+  back to the existing `Email.in_reply_to: str | None` contract.
+- `pyproject.toml` now sets `asyncio_default_test_loop_scope = "session"`
+  so function-scoped tests share the session-scoped fixtures' event loop.
+
+### Changed
+- `__version__` corrected to `0.3.0` (was stale at `0.1.0` through v0.2).
+
+### Migration
+Agents using Courier can now retire Fastmail MCP entirely — all
+previous filing and threaded-reply operations now have Courier
+equivalents. See `docs/superpowers/specs/2026-04-17-courier-v0.3-design.md`
+for the full mapping.
+
+## [0.2.0] — 2026-04-16
+
+### Added
+- **Attachment support**
+  - `Attachment` dataclass + `Email.attachments` list, populated from
+    JMAP `bodyStructure` walk.
+  - `JMAPClient.download_blob()` and `upload_blob()` using the session's
+    `downloadUrl` / `uploadUrl` templates (RFC 8620 §6.2).
+  - `create_draft()` / `send_email()` accept attachments — `send_email`
+    takes `attachment_paths` and handles upload.
+  - MCP tools `email_attachments` (list) and `email_attachment_save`
+    (download to local path). `email_send` gains optional `attachment_paths`.
+  - CLI `courier attachments <email_id>` and `courier download <email_id> <dest>`.
+  - `courier read` now shows attachment list in the header.
+
+- **Calendar invite MIME detection**
+  - `Email.has_calendar_invite` populated by walking `bodyStructure` for
+    `text/calendar` parts.
+  - New triage guard `requires_calendar_invite`.
+  - Default rule `calendar-invite-mime` (actionable, confidence 0.95).
+
+- **Calendar event deduplication** across calendars via `(uid, recurrence_id)`.
+
+- **All-day event support** in `create_event` + `calendar_create` MCP tool.
+  All-day events emit `VALUE=DATE` per RFC 5545 §3.6.1.
+
+### Changed
+- `free_busy` gains `working_hours` and `working_days` parameters; gaps are
+  split at day boundaries and trimmed to the working window when set.
+- `courier free` defaults to Mon–Fri 09:00–17:00 local; flags `--all-hours`,
+  `--start-hour`, `--end-hour` added.
+- `courier free` CLI shows end date when a slot crosses midnight (previously
+  displayed only the end time, which hid the date and looked wrong).
+
+### Fixed
+- `free_busy` previously reported multi-day 24/7 gaps (e.g. a 77-hour
+  Friday-evening-through-Monday-morning slot) when there were no meetings
+  over a weekend. These are now properly constrained and split by day.
+
+## [0.1.0] — 2026-04-13
+
+- Initial release. JMAP email client, CalDAV calendar client, rule-based
+  triage, MCP server, CLI. Fastmail-only.

ai_courier-0.3.2/CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+Courier is an AI-native email & calendar client — an MCP server (and companion CLI) that talks directly to **JMAP** (email) and **CalDAV** (calendar) as a first-class peer client, not as a wrapper around a human-facing app. It is Fastmail-only today, but `AccountConfig.provider` is intended to be extensible.
+
+Two entry points, both defined as `[project.scripts]` in `pyproject.toml`:
+
+- `courier` — CLI (`src/courier/cli.py:main`)
+- `courier-mcp` — MCP server over stdio (`src/courier/server.py:main`)
+
+## Commands
+
+```bash
+# Install for development (editable + dev extras)
+pip install -e ".[dev]"
+
+# Run all tests
+pytest
+
+# Run a single test file / test
+pytest tests/test_triage_rules.py
+pytest tests/test_triage_rules.py::test_noreply_sender
+
+# Lint
+ruff check .
+
+# Run CLI against the configured Fastmail account
+courier setup           # first-time account config (prompts for JMAP token + CalDAV app password)
+courier inbox           # triaged inbox
+courier new             # delta since last check (watermark-based)
+courier status
+
+# Run MCP server (stdio)
+courier-mcp
+```
+
+`pyproject.toml` sets `asyncio_mode = "auto"` for pytest-asyncio, so `async def test_*` functions run without an explicit marker. Ruff is configured for `py311`, line length 100, rules `E,F,I,W`.
+
+## Architecture
+
+The codebase is a flat package under `src/courier/`. The dependency graph runs one direction: `cli.py` / `server.py` → `triage.py` → `triage_rules.py` → `jmap.py`, with `cal.py`, `state.py`, and `config.py` as leaves. There is no circular coupling.
+
+### Layers
+
+1. **Protocol clients** (`jmap.py`, `cal.py`)
+   - `JMAPClient` implements just enough of RFC 8620/8621 to be a complete email client: session discovery, Email/get, Email/query, Email/set, Mailbox/get, blob download/upload.
+   - `Email` (in `jmap.py`) and `Event` (in `cal.py`) are **context-window-optimized** dataclasses — flat, agent-shaped representations with a `summary()`/`summary_dict()` method for token-efficient serialization. They are **not** MIME trees or VObject graphs.
+   - `CalDAVClient` bypasses python-caldav's broken Fastmail principal discovery by doing a raw PROPFIND on the calendar-home-set URL. If you touch CalDAV setup, preserve this — it's intentional.
+   - `free_busy` respects working hours and splits multi-day gaps at day boundaries; the default for the CLI is Mon–Fri 09:00–17:00 local (see CHANGELOG 0.2.0).
+
+2. **Persistence** (`state.py`)
+   - `StateStore` is a thin SQLite wrapper. Four tables: `watermarks`, `triage`, `contact_signals`, `session_state`. Every table has `account_id` as part of the primary key — **the schema is multi-account from day one**, even though today only one Fastmail account is configured. Preserve this pattern when adding columns or tables.
+   - `contact_signals` tracks per-address send/receive counts and is what `requires_known_contact` / `requires_unknown_contact` triage guards read.
+
+3. **Triage** (`triage.py`, `triage_rules.py`, `default_rules.yaml`)
+   - `triage.py` is a **backward-compatible facade**: it re-exports `URGENT`/`NEEDS_REPLY`/`ACTIONABLE`/`FYI`/`BULK` constants and wraps `triage_rules.classify_email` / `classify_batch` with a lazy default ruleset. Don't regress this — existing callers (including tests) depend on the old signature.
+   - `triage_rules.py` loads YAML rules from `src/courier/default_rules.yaml` (shipped) and merges `~/.config/courier/triage-rules.yaml` (user). Rules are evaluated top-to-bottom; first match wins; no match → `fyi`.
+   - User-override merge semantics (important): `sender_overrides` are **additive**, but if the user defines `rules`, those **replace** the defaults entirely. This is documented at the top of `default_rules.yaml`.
+   - The default ruleset is lazy-loaded once per process and **never invalidated** — rule file changes require a restart.
+
+4. **Config** (`config.py`)
+   - JSON config at `~/.config/courier/config.json`. `AccountConfig` holds **two** credentials per account: a JMAP API token (`api_token`) for email and a CalDAV app password (`app_password`) for calendar — Fastmail issues these separately.
+   - `db_path` defaults to `~/.config/courier/courier.db`.
+
+5. **Surfaces** (`cli.py`, `server.py`)
+   - `server.py` defines the MCP tool surface (see README's tool table) and uses module-level singletons (`_config`, `_jmap`, `_caldav`, `_state`) lazily initialized on first use. The MCP tool names are the public API — renaming them is a breaking change for anyone who has added Courier to their Claude/agent config.
+   - `server._ensure_list()` exists because some MCP runtimes (e.g. Cowork) serialize arrays as JSON strings. Keep the coercion when adding new batch tools.
+   - The MCP layer passes the Fastmail account's local timezone (`account.timezone`, default `America/Chicago`) into `Event.summary_dict(local_tz=...)` so calendar output is rendered in local time.
+
+### A few load-bearing conventions
+
+- `Email.summary(max_body=...)` is the token-budget knob. `email_read` uses 10 000 chars; `email_thread` uses 2 000 per message; list endpoints use the 500 default. Respect this when adding new read endpoints.
+- `email_new` is watermark-driven: it reads `watermarks` for the inbox, filters, then writes the newest seen `date`+`id` back. Don't short-circuit this — the whole "what's new since last session" UX depends on it.
+- All-day events use `VALUE=DATE` (RFC 5545 §3.6.1). `server.calendar_create` sniffs `"T" not in raw_start` to decide all-day vs. timed; `cal.create_event(all_day=True)` is the underlying flag. Don't route bare-date strings through `datetime.fromisoformat`.
+- `Email.has_calendar_invite` is populated by walking JMAP `bodyStructure` for `text/calendar` parts and is consumed by the `requires_calendar_invite` triage guard and the `calendar-invite-mime` default rule.
+
+## Testing notes
+
+- Tests are pure unit tests against the dataclasses and state layer — nothing hits the network. `tests/conftest.py` provides an `account` fixture and a `make_email(**overrides)` factory; prefer these over constructing `Email` objects inline.
+- `test_triage_rules.py` is the largest suite and exercises the YAML loader, guards, and override semantics. When changing `default_rules.yaml` or adding rule guards, extend that file.
+- There is no end-to-end JMAP/CalDAV test — connection behaviour is exercised manually via `courier status` / `courier setup`.
+- `tests/e2e/` is the opt-in live integration suite, gated by `COURIER_LIVE_TESTS=1`. It uses a sandbox mailbox `Courier/Tests` and calendar `Courier Tests`, both created by `courier test-setup`. Every write test self-cleans via a `self_sent_email` fixture that sends a timestamped test message to the configured account, yields it, and trashes both copies on teardown. Do not add live tests outside `tests/e2e/`.
+- `asyncio_default_test_loop_scope = "session"` is set in `pyproject.toml` so function-scoped tests share the same event loop as session-scoped fixtures (required for reusing the `live_jmap` httpx client). Don't change this without checking every async fixture.
+
+## Scope discipline
+
+- Don't introduce a provider abstraction for a second provider that doesn't exist yet. `AccountConfig.provider` is a string and `cal.py` already branches on `"fastmail"` for URL auto-build — that's the pattern to extend.
+- Don't add fallback strategies (HTML-to-text scraping, IMAP fallback, etc.) on your own initiative. Fail fast and loud; the surrounding user instructions in `~/.claude/CLAUDE.md` explicitly prohibit silent fallbacks.

ai_courier-0.3.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jim Perry / Harness Intelligence
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ai_courier-0.3.2/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: ai-courier
+Version: 0.3.2
+Summary: AI-native email & calendar client over JMAP and CalDAV
+Author-email: Jim Perry <jim@hi-team.net>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,caldav,calendar,email,jmap,mcp
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.11
+Requires-Dist: caldav>=1.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: vobject>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Courier
+
+**AI-native email & calendar client over JMAP and CalDAV.**
+
+Your AI agent deserves its own email client — not an adapter wrapping a human one.
+
+## The Problem
+
+Every AI agent framework connects to email and calendar by wrapping human-facing apps. MCP servers adapt web UIs. Osascript automates native mail clients. Browser tools click through webmail. Each introduces friction because the agent is fighting an interface designed for someone else.
+
+Courier takes a different approach: connect directly to the open protocols (JMAP for email, CalDAV for calendar) as a first-class client — a peer alongside your human apps, not a wrapper around them.
+
+## What Makes It Different
+
+- **Context-window-optimized output** — emails are structured for AI consumption, not HTML rendering
+- **Session state & watermarks** — "what's new?" is a first-class operation that persists between sessions
+- **Triage classification** — emails arrive pre-sorted: urgent, needs_reply, actionable, fyi, bulk
+- **Batch-first operations** — archive 15 emails in one call, not 15 separate requests
+- **Sane timezone handling** — CalDAV with proper TZID normalization and recurrence expansion
+- **Composable** — higher-order operations like "find all emails from this person and summarize the thread"
+
+## Quick Start
+
+```bash
+pip install ai-courier
+
+# Configure your Fastmail account
+courier setup
+
+# Check your inbox (triaged by priority)
+courier inbox
+
+# What's new since last check?
+courier new
+
+# Today's calendar
+courier today
+
+# Find free time
+courier free
+```
+
+## As an MCP Server
+
+Add to your Claude configuration:
+
+```json
+{
+  "mcpServers": {
+    "courier": {
+      "command": "courier-mcp"
+    }
+  }
+}
+```
+
+Available tools:
+
+| Tool | Description |
+|------|-------------|
+| `email_inbox` | Triaged inbox (urgent → bulk) |
+| `email_new` | New emails since last check (watermark-based) |
+| `email_search` | Flexible email search |
+| `email_read` | Read full email by ID |
+| `email_thread` | Get full thread |
+| `email_archive` | Archive emails (batch) |
+| `email_trash` | Trash emails (batch) |
+| `email_mark_read` | Mark read (batch) |
+| `email_draft` | Create draft |
+| `email_send` | Send email |
+| `email_mailboxes` | List folders/labels with IDs, paths, roles |
+| `email_move` | Move emails to a folder (by ID, name, or path) |
+| `email_label` | Add/remove labels without touching other memberships |
+| `email_reply` | Threaded reply (In-Reply-To + References); draft or send |
+| `calendar_today` | Today's events |
+| `calendar_week` | This week's events |
+| `calendar_events` | Events in date range |
+| `calendar_free` | Find free time slots |
+| `calendar_create` | Create event |
+| `courier_status` | Connection & watermark status |
+
+## Customizing Triage Rules
+
+Triage rules are defined in YAML. The defaults ship with Courier (see `src/courier/default_rules.yaml`). To customize, create `~/.config/courier/triage-rules.yaml`:
+
+```yaml
+# Force specific senders to a classification (checked first, confidence 1.0)
+sender_overrides:
+  "ceo@mycompany.com": { classification: urgent, reason: "VIP sender" }
+  "deals@spammy.com": { classification: bulk, reason: "always bulk" }
+
+# Custom rules — if you define any, they REPLACE the defaults entirely.
+# Omit this section to keep defaults and only add sender overrides.
+rules:
+  - name: my-custom-rule
+    classification: urgent
+    confidence: 0.9
+    reason: "keyword: '{match}'"
+    subject_pattern: "\\b(fire|outage|p0)\\b"
+```
+
+Each rule supports regex match conditions (`from_pattern`, `subject_pattern`, `body_pattern`, `domain_pattern`) and guard conditions (`requires_known_contact`, `requires_unknown_contact`, `max_size`, `requires_thread`, `requires_flagged`). Rules are evaluated top-to-bottom; first match wins.
+
+See `src/courier/default_rules.yaml` for the full schema documentation and all default rules.
+
+## Architecture
+
+```
+AI Agent (Claude, GPT, etc.)
+    │
+    ▼
+Courier MCP Server ← the novel layer
+    ├── Email (JMAP)     ├── Calendar (CalDAV)
+    │   ├── Watermarks   │   ├── TZID normalization
+    │   ├── Triage       │   ├── Recurrence expansion
+    │   └── Batch ops    │   └── Free/busy
+    └────────────────────┘
+    │
+    ▼
+SQLite (state, watermarks, contact signals)
+    │
+    ▼
+JMAP API ──── CalDAV API
+(Fastmail)    (Fastmail)
+```
+
+Courier talks to the same backend your human apps do. It's a parallel client, not a wrapper.
+
+## Requirements
+
+- Python 3.11+
+- A Fastmail account with an API token ([get one here](https://www.fastmail.com/settings/security/tokens))
+- Scopes needed: Mail, Calendars (Contacts optional)
+
+## Development
+
+```bash
+git clone https://github.com/iamdadzilla/courier.git
+cd courier
+pip install -e ".[dev]"
+pytest
+```
+
+## Why "Courier"?
+
+A courier delivers messages directly. No intermediary, no adapter, no wrapper. Just the message.
+
+## License
+
+MIT

ai_courier-0.3.2/README.md

@@ -0,0 +1,150 @@
+# Courier
+
+**AI-native email & calendar client over JMAP and CalDAV.**
+
+Your AI agent deserves its own email client — not an adapter wrapping a human one.
+
+## The Problem
+
+Every AI agent framework connects to email and calendar by wrapping human-facing apps. MCP servers adapt web UIs. Osascript automates native mail clients. Browser tools click through webmail. Each introduces friction because the agent is fighting an interface designed for someone else.
+
+Courier takes a different approach: connect directly to the open protocols (JMAP for email, CalDAV for calendar) as a first-class client — a peer alongside your human apps, not a wrapper around them.
+
+## What Makes It Different
+
+- **Context-window-optimized output** — emails are structured for AI consumption, not HTML rendering
+- **Session state & watermarks** — "what's new?" is a first-class operation that persists between sessions
+- **Triage classification** — emails arrive pre-sorted: urgent, needs_reply, actionable, fyi, bulk
+- **Batch-first operations** — archive 15 emails in one call, not 15 separate requests
+- **Sane timezone handling** — CalDAV with proper TZID normalization and recurrence expansion
+- **Composable** — higher-order operations like "find all emails from this person and summarize the thread"
+
+## Quick Start
+
+```bash
+pip install ai-courier
+
+# Configure your Fastmail account
+courier setup
+
+# Check your inbox (triaged by priority)
+courier inbox
+
+# What's new since last check?
+courier new
+
+# Today's calendar
+courier today
+
+# Find free time
+courier free
+```
+
+## As an MCP Server
+
+Add to your Claude configuration:
+
+```json
+{
+  "mcpServers": {
+    "courier": {
+      "command": "courier-mcp"
+    }
+  }
+}
+```
+
+Available tools:
+
+| Tool | Description |
+|------|-------------|
+| `email_inbox` | Triaged inbox (urgent → bulk) |
+| `email_new` | New emails since last check (watermark-based) |
+| `email_search` | Flexible email search |
+| `email_read` | Read full email by ID |
+| `email_thread` | Get full thread |
+| `email_archive` | Archive emails (batch) |
+| `email_trash` | Trash emails (batch) |
+| `email_mark_read` | Mark read (batch) |
+| `email_draft` | Create draft |
+| `email_send` | Send email |
+| `email_mailboxes` | List folders/labels with IDs, paths, roles |
+| `email_move` | Move emails to a folder (by ID, name, or path) |
+| `email_label` | Add/remove labels without touching other memberships |
+| `email_reply` | Threaded reply (In-Reply-To + References); draft or send |
+| `calendar_today` | Today's events |
+| `calendar_week` | This week's events |
+| `calendar_events` | Events in date range |
+| `calendar_free` | Find free time slots |
+| `calendar_create` | Create event |
+| `courier_status` | Connection & watermark status |
+
+## Customizing Triage Rules
+
+Triage rules are defined in YAML. The defaults ship with Courier (see `src/courier/default_rules.yaml`). To customize, create `~/.config/courier/triage-rules.yaml`:
+
+```yaml
+# Force specific senders to a classification (checked first, confidence 1.0)
+sender_overrides:
+  "ceo@mycompany.com": { classification: urgent, reason: "VIP sender" }
+  "deals@spammy.com": { classification: bulk, reason: "always bulk" }
+
+# Custom rules — if you define any, they REPLACE the defaults entirely.
+# Omit this section to keep defaults and only add sender overrides.
+rules:
+  - name: my-custom-rule
+    classification: urgent
+    confidence: 0.9
+    reason: "keyword: '{match}'"
+    subject_pattern: "\\b(fire|outage|p0)\\b"
+```
+
+Each rule supports regex match conditions (`from_pattern`, `subject_pattern`, `body_pattern`, `domain_pattern`) and guard conditions (`requires_known_contact`, `requires_unknown_contact`, `max_size`, `requires_thread`, `requires_flagged`). Rules are evaluated top-to-bottom; first match wins.
+
+See `src/courier/default_rules.yaml` for the full schema documentation and all default rules.
+
+## Architecture
+
+```
+AI Agent (Claude, GPT, etc.)
+    │
+    ▼
+Courier MCP Server ← the novel layer
+    ├── Email (JMAP)     ├── Calendar (CalDAV)
+    │   ├── Watermarks   │   ├── TZID normalization
+    │   ├── Triage       │   ├── Recurrence expansion
+    │   └── Batch ops    │   └── Free/busy
+    └────────────────────┘
+    │
+    ▼
+SQLite (state, watermarks, contact signals)
+    │
+    ▼
+JMAP API ──── CalDAV API
+(Fastmail)    (Fastmail)
+```
+
+Courier talks to the same backend your human apps do. It's a parallel client, not a wrapper.
+
+## Requirements
+
+- Python 3.11+
+- A Fastmail account with an API token ([get one here](https://www.fastmail.com/settings/security/tokens))
+- Scopes needed: Mail, Calendars (Contacts optional)
+
+## Development
+
+```bash
+git clone https://github.com/iamdadzilla/courier.git
+cd courier
+pip install -e ".[dev]"
+pytest
+```
+
+## Why "Courier"?
+
+A courier delivers messages directly. No intermediary, no adapter, no wrapper. Just the message.
+
+## License
+
+MIT

ai_courier-0.3.2/docs/superpowers/plans/2026-04-17-courier-v0.3-pr-body.md

@@ -0,0 +1,27 @@
+## Summary
+
+Ships Courier v0.3: **retires Fastmail MCP from the sweep entirely.**
+
+- **Four new MCP tools** — `email_mailboxes` (discover folders/labels with paths), `email_move` (file by ID/name/path), `email_label` (non-destructive multi-tagging), `email_reply` (threaded In-Reply-To + References + `Re:` prefix, draft or send)
+- **Opt-in E2E suite** — `tests/e2e/` gated by `COURIER_LIVE_TESTS=1`, 19 live tests against real Fastmail, self-cleaning via `Courier/Tests` sandbox (created by new `courier test-setup` command)
+- **Three v0.2 bugs caught and fixed along the way** — asyncio test-loop scope mismatch, `_normalize_utcdate` silent acceptance of non-UTC offsets, `create_draft` sending `inReplyTo` as a string instead of `String[]` per RFC 8621 §4.1.3.1
+
+All three "stale?" vault notes definitively confirmed stale: attachment send, attachment download, and all-day events (`VALUE=DATE` per RFC 5545 §3.6.1) all work end-to-end. Hi-Team skill library and system docs scrubbed of Fastmail MCP references.
+
+23 commits, +1480/-30 across 20 files. Spec: [`docs/superpowers/specs/2026-04-17-courier-v0.3-design.md`](docs/superpowers/specs/2026-04-17-courier-v0.3-design.md). Plan: [`docs/superpowers/plans/2026-04-17-courier-v0.3.md`](docs/superpowers/plans/2026-04-17-courier-v0.3.md).
+
+## Test plan
+
+- [ ] `pytest tests/ --ignore=tests/e2e -v` — 241 passed
+- [ ] `COURIER_LIVE_TESTS=1 pytest tests/e2e/ -v` — 19 passed (rerun once on fixture-poll-ceiling flake if it hits)
+- [ ] `ruff check .` — 51 errors (flat baseline; zero new introduced by v0.3)
+- [ ] `courier --help` shows new subcommands: `test-setup`, `mailboxes`, `move`, `label`, `reply`
+- [ ] `python -c "import courier; print(courier.__version__)"` → `0.3.0`
+- [ ] **Acceptance:** disconnect Fastmail MCP in `~/.claude/settings.json`, run one full morning sweep — completes cleanly with Courier only
+- [ ] Richard onboards per `Knowledge/System/richard-setup-guide.md` Part 5 with his own Fastmail creds and runs a live sweep
+
+## Post-merge
+
+- Tag `v0.3.0` and publish to PyPI
+- Vault skill library already updated on the `main` vault (Sync.com-synced, not git-tracked)
+- Update `Knowledge/Tech/Courier/courier-sweep-log.md` after the first Fastmail-MCP-free sweep confirms acceptance