---
agent_doc_session: c80f3e69-053d-4606-bc0f-ca11e7bb2950
tmux_session: '1'
---

# Corky Functional Specification

> Language-independent specification for the corky email sync and collaboration tool.
> This document captures the exact behavior a port must reproduce.

## 1. Overview

Corky syncs email threads from IMAP providers into a flat directory of Markdown files,
supports AI-assisted drafting, manages mailbox sharing via git submodules or plain directories,
and pushes routing intelligence to Cloudflare.

## 2. Data Directory

### 2.1 Layout

```
{data_dir}/
  conversations/        # One .md file per thread
  drafts/               # Outgoing email drafts
  contacts/             # Per-contact context
    {name}/
      AGENTS.md
      CLAUDE.md -> AGENTS.md
  mailboxes/            # Named mailboxes (plain dirs or git submodules)
    {name}/
      conversations/
      drafts/
      contacts/
      AGENTS.md
      CLAUDE.md -> AGENTS.md
      README.md
      voice.md
      .gitignore
  social/               # Social media drafts (YAML frontmatter + body)
    {YYYYMMDD-HHMMSS-platform}.md
  profiles.toml         # Social media profile registry
  manifest.toml         # Thread index (generated by sync)
  .sync-state.json      # IMAP + contact sync state
```

### 2.2 Resolution Order

The data directory is resolved at runtime in this order:
1. `mail/` directory in current working directory (developer workflow)
2. `CORKY_DATA` environment variable
3. App config mailbox (see §2.4)
4. `~/Documents/mail` (hardcoded fallback)

### 2.3 Config Directory

Config always lives inside the data directory (`mail/`).

Config files: `.corky.toml`, `voice.md`, `credentials.json`

### 2.4 App Config

Location: `{platformdirs.user_config_dir("corky")}/config.toml`
- Linux: `~/.config/corky/config.toml`
- macOS: `~/Library/Application Support/corky/config.toml`
- Windows: `%APPDATA%/corky/config.toml`

Stores named mailboxes (data directory references) and a default. Used in resolution step 3.

Mailbox resolution (when no explicit name given):
1. `default_mailbox` set → use that mailbox
2. Exactly one mailbox → use it implicitly
3. Multiple mailboxes, no default → error with list
4. No mailboxes → return None (fall through to step 4)

### 2.5 Directory Naming Convention

| Directory | Purpose | Name rationale |
|---|---|---|
| `mail/` | Corky data root | Short, familiar, Unix precedent (`maildir`, `/var/mail`). Avoids `mailbox/mailboxes/` stutter. |
| `mailboxes/` | Collaborator namespace | Namespace boundary — prevents collisions between mailbox names and system dirs (`social/`, `contacts/`). |
| `social/` | Social media drafts | Channel-specific content at data root level. |
| `contacts/` | Contact registry | Shared across all mailboxes. |

**Why "mailbox" internally, "mail" as directory:**
- "Mailbox" is the correct abstraction — per-entity message collection (actor model, Hewitt 1973)
- `mail/` is shorthand for the data root; it doesn't need to carry the full semantic weight
- `mailbox/` was considered but creates `mailbox/mailboxes/` path stutter
- `comms/` rejected — militaristic tone clashes with "corky"
- `correspondence/` rejected — too long (15 chars)
- Flatten approaches rejected — namespace collisions between mailbox names and system dirs

**The `mailboxes/` subdir is load-bearing architecture**, not cosmetic. It prevents a collaborator named "social" or "contacts" from colliding with system directories. Do not flatten without solving the namespace problem first.

## 3. File Formats

### 3.1 Conversation Markdown

```markdown
# {Subject}

**Labels**: {label1}, {label2}
**Accounts**: {account1}, {account2}
**Thread ID**: {thread_key}
**Last updated**: {RFC 2822 date}
**Tracking**: {domain1}, {domain2}   ← only present when tracking pixels detected

---

## {Sender Name} <{email}> — {RFC 2822 date}

**Message-ID**: {message-id}
**To**: {recipient1}, {recipient2}
**CC**: {cc1}

{Body text}

---

## {Reply sender} — {date}

{Body text}
```

Per-message `**Message-ID**:`, `**To**:`, and `**CC**:` lines are emitted after the message header when non-empty. Old files without these lines parse correctly (fields default to empty). `**Message-ID**:` is extracted during Gmail sync and stored per message for use in reply threading (`in_reply_to` in drafts).

Metadata regex: `^\*\*(.+?)\*\*:\s*(.+)$` (multiline)
Message header regex: `^## (.+?) — (.+)$` (multiline, em dash U+2014)

### 3.2 Draft Markdown

Drafts use YAML frontmatter with the subject as a Markdown heading in the body:

```markdown
---
to: alice@example.com
cc: bob@example.com
status: draft
author: Brian
account: personal
from: brian@example.com
in_reply_to: "<msg-id>"
thread_id: "<gmail-thread-id>"
scheduled_at: null
attachments:
  - /tmp/screenshot.png
  - ~/Documents/report.pdf
---

# Subject Line

Body text here.
```

Optional fields: `attachments` (list of file paths), `thread_id` (Gmail thread ID for threading replies)
Required fields: `# Subject` heading (in body), `to`, `---` delimiters
Recommended fields: `status`, `author`

Status values: `draft` → `review` → `approved` → `scheduled` → `sent`

**Threading via `thread_id`:** When present, the value is included as `threadId` in Gmail API send/draft requests. This ensures the reply is placed in the correct Gmail thread, complementing `in_reply_to` which sets the RFC 2822 `In-Reply-To` header.
Valid send statuses (for draft push --send): `review`, `approved`, `scheduled`

**Legacy format:** The `**Key**: value` format is still supported for backward compatibility:

```markdown
# {Subject}

**To**: {recipient}
**CC**: {optional}
**Status**: draft
**Author**: {name}
**Account**: {optional — account name from .corky.toml}
**From**: {optional — email address, used to resolve account}
**In-Reply-To**: {optional — message ID}

---

{Draft body}
```

`corky draft migrate [--dry-run]` converts legacy drafts to YAML frontmatter format.

### 3.3 .corky.toml

```toml
[owner]
github_user = "username"
name = "Display Name"

[accounts.{name}]
provider = "gmail"          # gmail | protonmail-bridge | imap
user = "you@gmail.com"
password = ""               # Inline password (not recommended)
password_cmd = ""           # Shell command to retrieve password
labels = ["correspondence"]
imap_host = ""              # Auto-filled by provider preset
imap_port = 993
imap_starttls = false
smtp_host = ""
smtp_port = 465
drafts_folder = "Drafts"
sync_days = 3650            # How far back to sync
default = false             # Mark one account as default

[contacts.{name}]
emails = ["addr@example.com"]
shared_with = ["mailbox-name"]  # Explicitly share with mailboxes (even without conversation match)
aliases = ["Display Name"]      # Match sender names that don't slugify to the directory name

[routing]
for-alex = ["mailboxes/alex"]
shared = ["mailboxes/alice", "mailboxes/bob"]
"work:for-lucas" = ["mailboxes/lucas"]   # account-scoped route

[mailboxes.alex]
auto_send = false

[watch]
poll_interval = 300         # Seconds between polls
notify = false              # Desktop notifications

[gmail]
client_id = ""              # OAuth2 client ID for Gmail API
client_id_cmd = ""          # Shell command (e.g. "pass corky/gmail/client_id")
client_secret = ""          # OAuth2 client secret
client_secret_cmd = ""      # Shell command (e.g. "pass corky/gmail/client_secret")

[[gmail.filters]]
label = "for-lucas"         # Gmail label to apply (resolved to ID via API)
match = ["from"]            # Match fields: "from", "to" (default: ["from"])
addresses = ["alice@example.com", "bob@example.com"]
forward_to = ""             # Optional forwarding address
star = false                # Add STARRED label
never_spam = false          # Remove SPAM label
always_important = false    # Add IMPORTANT label

[linkedin]
client_id = ""              # Inline client ID
client_id_cmd = ""          # Shell command (e.g. "pass corky/linkedin/client_id")
client_secret = ""          # Inline client secret
client_secret_cmd = ""      # Shell command (e.g. "pass corky/linkedin/client_secret")
```

Secret resolution order (shared `util::resolve_secret`):
1. Inline field value
2. `_cmd` field (shell command, capture stdout, strip trailing whitespace)
3. Error if both empty (LinkedIn credentials fall back to env vars before error — see §12.5)

Label scoping syntax: `account:label` (e.g. `"proton-dev:INBOX"`) binds a label to a specific account.

### 3.4 .sync-state.json

```json
{
  "accounts": {
    "{account_name}": {
      "labels": {
        "{label_name}": {
          "uidvalidity": 12345,
          "last_uid": 67890
        }
      }
    }
  },
  "contacts": {
    "{contact_name}": {
      "mailboxes": {
        "{mailbox_name}": "fnv1a_hash_hex"
      }
    }
  }
}
```

### 3.5 manifest.toml

```toml
[threads.{slug}]
subject = "Thread Subject"
thread_id = "thread key"
labels = ["label1", "label2"]
accounts = ["account1"]
last_updated = "RFC 2822 date"
contacts = ["contact-name"]
```

Generated after each sync by scanning conversation files and matching sender emails against `[contacts]` in `.corky.toml`.

### 3.6 config.toml (App Config)

```toml
default_mailbox = "personal"

[mailboxes.personal]
path = "~/Documents/mail"

[mailboxes.work]
path = "~/work/mail"
```

Top-level fields:
- `default_mailbox`: name of the default mailbox (set automatically to the first mailbox added)

Mailbox fields:
- `path`: absolute or `~`-relative path to a mail data directory

## 4. Algorithms

### 4.1 Thread Slug Generation

```
fn slugify(text: &str) -> String:
    text = text.to_lowercase()
    text = regex_replace(r"[^a-z0-9]+", "-", text)
    text = text.trim_matches('-')
    text = text[..min(60, text.len())]
    if text.is_empty(): return "untitled"
    return text
```

Slug collisions: If `{slug}.md` exists, try `{slug}-2.md`, `{slug}-3.md`, etc.

### 4.2 Thread Key Derivation

```
fn thread_key_from_subject(subject: &str) -> String:
    regex_replace(r"^(re|fwd?):\s*", "", subject.to_lowercase().trim())
```

Strips one layer of `Re:` or `Fwd:` prefix (case-insensitive), then lowercases.

### 4.3 Message Deduplication

Messages are deduplicated by `(from, date)` tuple. If both match an existing message in the thread, the message is skipped but labels/accounts metadata is still updated.

### 4.4 Multi-Source Accumulation

When the same thread is fetched from multiple labels or accounts:
- Labels are appended (no duplicates)
- Accounts are appended (no duplicates)
- Messages are merged and deduplicated
- Messages are sorted by parsed date

### 4.5 Label Routing

Labels in the `[routing]` section of `.corky.toml` route to configured mailbox directories.
Fan-out: one label can route to multiple mailboxes (array of paths).
Plain labels (no routing entry) route to `{data_dir}/conversations/`.
Routing values are paths like `mailboxes/{name}`, resolved relative to data_dir, with `/conversations/` appended.

Account:label syntax (`"proton-dev:INBOX"`):
- Only matches when syncing the named account
- The IMAP folder used is the part after the colon
- Supported in both account `labels` arrays and `[routing]` keys (e.g. `"work:for-lucas" = ["mailboxes/lucas"]` routes only when syncing the `work` account)

### 4.6 Manifest Generation

After sync, scan all `.md` files in `conversations/`:
1. Parse each file back into a Thread object
2. For each message, extract emails from `from`, `to`, and `cc` fields (`<email>` regex)
3. Match against `[contacts]` email→name mapping in `.corky.toml`
4. Write `manifest.toml` with thread metadata and matched contacts

A contact appears in the manifest if they sent, received, or were CC'd on any message in the thread.

## 5. Commands

### 5.1 init

```
corky init --user EMAIL [PATH] [--provider PROVIDER]
             [--password-cmd CMD] [--labels LABEL,...] [--github-user USER]
             [--name NAME] [--mailbox-name NAME] [--sync] [--force]
```

- `PATH`: project directory (default: `.` — current directory)
- Creates `{path}/mail/{conversations,drafts,contacts}/` with `.gitkeep` files
- Generates `.corky.toml` at `{path}/mail/`
- Installs `voice.md` at `{path}/mail/` if not present
- If inside a git repo: adds `mail` to `.gitignore`
- Installs agent skills to `.claude/skills/{corky,email,linkedin}/`
- Registers the project dir as a named mailbox in app config
- `--force`: overwrite existing config; without it, exit 1 if `.corky.toml` exists
- `--sync`: set `CORKY_DATA` env, run sync
- `--provider`: `gmail` (default), `protonmail-bridge`, `imap`
- `--labels`: default `correspondence` (comma-separated)
- `--mailbox-name`: mailbox name to register (default: `"default"`)

### 5.1.1 skill install

```
corky skill install
```

- Installs 3 agent skills into `.claude/skills/` in the current directory:
  - `corky/SKILL.md` — general corky commands
  - `email/SKILL.md` + 4 runbooks (`draft-reply`, `email-send`, `enrich-contact`, `review-inbox`)
  - `linkedin/SKILL.md` + 1 runbook (`linkedin-post`)
- Skips files that already exist (never overwrites)
- Works from any directory (mailbox repos ship the skills automatically via `mb add`/`mb reset`)

### 5.2 sync

```
corky sync                   # incremental IMAP sync (default)
corky sync full              # full IMAP resync (ignore saved state)
corky sync account NAME      # sync one account
corky sync refetch THREAD_ID # re-fetch a single thread by Gmail thread ID
corky sync routes            # apply routing to existing conversations
corky sync mailbox [NAME]    # push/pull shared mailboxes
```

Bare `corky sync` runs incremental IMAP sync for all configured accounts.
Subcommands:
- `full`: ignore saved state, re-fetch all messages within `sync_days`
- `account NAME`: sync only the named account
- `refetch THREAD_ID`: re-fetch a single Gmail thread by ID, bypassing sync state (see §6.8)
- `routes`: apply `[routing]` rules to existing `conversations/*.md` files,
  copying matching threads into mailbox `conversations/` directories
- `mailbox [NAME]`: git push/pull shared mailbox repos (alias for `mailbox sync`)

Exit code: 0 on success.

### 5.3 sync-auth

```
corky sync-auth
```

Gmail OAuth setup. Requires `credentials.json` from Google Cloud Console.
Runs a local server on port 3000 for the OAuth callback.
Outputs the refresh token for `.env`.

### 5.4 list-folders

```
corky list-folders [ACCOUNT]
```

Without argument: lists available account names.
With argument: connects to IMAP and lists all folders with flags.

### 5.5 draft push

```
corky draft push FILE [--send]
corky mailbox draft push FILE [--send]
```

Alias: `corky push-draft` (hidden, backwards-compatible).

Default: creates a draft via IMAP APPEND to the drafts folder.
`--send`: sends via SMTP. Requires Status to be `review` or `approved`.
After sending, updates Status field in the file to `sent`.

**Attachments:** When `attachments` is present in YAML frontmatter, the email is sent as
`multipart/mixed` with the text body and binary attachment parts. Content-type is auto-detected
via `mime_guess` (falls back to `application/octet-stream`). File existence is validated at
send time, not draft creation time.

Account resolution for sending:
1. `**Account**` field → match by name in `.corky.toml`
2. `**From**` field → match by email address
3. Fall back to default account

### 5.6 add-label

```
corky add-label LABEL --account NAME
```

Text-level TOML edit to add a label to an account's `labels` array.
Preserves comments and formatting. Returns false if label already present.

### 5.7 contact-add (hidden alias)

```
corky contact-add NAME --email EMAIL [--email EMAIL2]
```

Hidden backward-compatible alias for `contact add`. The `--label` and `--account` flags are accepted but ignored.

### 5.8 watch

```
corky watch [--interval N]
```

IMAP polling daemon. Syncs all accounts, then pushes to shared mailboxes.
Desktop notifications on new messages if `notify = true` in `.corky.toml`.
Clean shutdown on SIGTERM/SIGINT.

### 5.9 audit-docs

```
corky audit-docs
```

Checks instruction files (AGENTS.md, README.md, SKILL.md) against codebase:
- Referenced paths exist on disk
- `uv run` scripts are registered
- Type conventions (msgspec, not dataclasses)
- Combined line budget (1000 lines max)
- Staleness (docs older than source)

### 5.10 help

```
corky help [FILTER]
corky --help
```

Shows command reference. Optional filter matches command names.

### 5.11 mailbox add

```
corky mailbox add NAME --label LABEL [--name NAME] [--github] [--pat] [--public] [--account ACCT] [--org ORG]
```

Alias: `corky mb add`

Without `--github`: creates a plain directory at `mailboxes/{name}/` with conversations/drafts/contacts subdirectories and template files (AGENTS.md, README.md, voice.md, .gitignore).
With `--github`: creates a private GitHub repo (`{org}/to-{name}`), initializes with template files, adds as git submodule at `mailboxes/{name}/`. Updates `.corky.toml`.

`--github`: use a git submodule instead of a plain directory
`--pat`: PAT-based access (prints instructions instead of GitHub collaborator invite)
`--public`: public repo visibility
`--org`: override GitHub org (default: owner's github_user)

### 5.12 mailbox sync

```
corky mailbox sync [NAME]
```

Alias: `corky mb sync`

For each mailbox (or one named): git pull --rebase (if remote configured), copy voice.md if newer, sync GitHub Actions workflow, bidirectional topic sync (§7.7), stage+commit+push local changes, update submodule ref in parent. Skips git ops for plain (non-submodule) directories. Local-only mailboxes (no git remote) skip pull silently. On pull failure with a remote, logs the actual error message instead of a generic warning.

### 5.13 mailbox status

```
corky mailbox status
```

Alias: `corky mb status`

Shows incoming/outgoing commit counts for each mailbox submodule.

### 5.14 mailbox remove

```
corky mailbox remove NAME [--delete-repo]
```

Alias: `corky mb remove`

For plain directories: `rm -rf mailboxes/{name}/`.
For submodules: `git submodule deinit -f`, `git rm`, clean up `.git/modules/{path}`.
Removes from `.corky.toml`.
`--delete-repo`: interactively confirms, then deletes GitHub repo via `gh`.

### 5.15 mailbox rename

```
corky mailbox rename OLD NEW [--rename-repo]
```

Alias: `corky mb rename`

Moves `mailboxes/{old}` to `mailboxes/{new}`. Uses `git mv` for submodules, `mv` for plain dirs.
Updates `.corky.toml`.
`--rename-repo`: also rename the GitHub repo via `gh repo rename`.

### 5.16 mailbox reset

```
corky mailbox reset [NAME] [--no-sync]
```

Alias: `corky mb reset`

Pull latest, regenerate all template files (AGENTS.md, README.md, CLAUDE.md symlink, .gitignore, voice.md, notify.yml) at `mailboxes/{name}/`, commit, push.
`--no-sync`: regenerate files without pull/push.

### 5.17 unanswered

```
corky unanswered [SCOPE] [--from NAME]
corky mailbox unanswered [SCOPE] [--from NAME]
```

Alias: `corky find-unanswered` (hidden, backwards-compatible).

Scans conversations for threads where the last message sender doesn't match `--from`.

Scope argument:
- Omitted → scan root `conversations/` + all `mailboxes/*/conversations/`
- `.` → root `conversations/` only
- `NAME` → `mailboxes/{name}/conversations/` only

`--from` resolution: CLI flag > `[owner] name` in `.corky.toml` > error.

Output is grouped by scope when scanning multiple directories.

Sender regex: `^## (.+?) —` (multiline, em dash)

### 5.18 draft validate

```
corky draft validate [FILE|SCOPE...]
corky mailbox draft validate [FILE|SCOPE...]
```

Alias: `corky validate-draft` (hidden, backwards-compatible).

Validates draft files. Checks: subject heading, required fields (To), recommended fields (Status, Author), valid status value, `---` separator, non-empty body.

Scope argument (when no files given):
- Omitted → scan root `drafts/` + all `mailboxes/*/drafts/`
- `.` → root `drafts/` only
- `NAME` → `mailboxes/{name}/drafts/` only

Exit code: 0 if all valid, 1 if any errors.

### 5.19 mailbox list

```
corky mailbox list
```

Lists all registered mailboxes with paths. Marks the default mailbox. If no mailboxes configured, prints setup instructions.

### 5.20 Global `--mailbox` Flag

```
corky --mailbox NAME <subcommand> [args...]
```

Available on all commands. Resolves the named mailbox via app config and sets `CORKY_DATA` before dispatching to the subcommand.

### 5.21 draft new

```
corky draft new SUBJECT --to EMAIL [--cc EMAIL] [--account NAME] [--from EMAIL]
                [--in-reply-to MSG-ID] [--mailbox NAME] [--attach FILE ...]
corky mailbox draft new SUBJECT --to EMAIL [...]
```

Scaffolds a new draft file with pre-filled metadata.

Output: creates `drafts/YYYY-MM-DD-{slug}.md` and prints the path.

- `--mailbox NAME`: create in `mailboxes/{name}/drafts/` instead of root `drafts/`
- `--cc`: CC recipient
- `--account`: sending account name from `.corky.toml`
- `--from`: sending email address
- `--in-reply-to`: message ID for threading
- `--attach`: file path to attach (repeatable)
- Author resolved from `[owner] name` in `.corky.toml`
- Slug collisions handled with `-2`, `-3` suffix (same as sync)

### 5.22 contact add

```
corky contact add NAME --email EMAIL [--email EMAIL2]
corky contact add --from SLUG [NAME]
```

Creates `{data_dir}/contacts/{name}/` with `AGENTS.md` template and `CLAUDE.md` symlink.
Updates `.corky.toml` with the contact's email addresses.

Manual mode (`--email`): requires `NAME` positional. Creates contact with default AGENTS.md.

From-conversation mode (`--from`):
1. Find `conversations/{slug}.md` or `mailboxes/*/conversations/{slug}.md`
2. Parse thread, extract non-owner participants from `from`, `to`, `cc` fields
3. Filter owner emails via `accounts.*.user` in `.corky.toml`
4. Single participant: auto-derive name from display name (slugified)
5. Multiple participants: require positional `NAME` to select one
6. Generate enriched AGENTS.md with pre-filled Topics, Formality, Tone, and Research sections

`--from` and `--email` conflict (clap `conflicts_with`).

### 5.23 contact info

```
corky contact info NAME
```

Aggregates and displays contact information:
1. Contact config from `.corky.toml` (emails)
2. `contacts/{name}/AGENTS.md` content
3. Matching threads from `manifest.toml` (root) and `mailboxes/*/manifest.toml`
4. Summary: thread count, last activity date

Threads are matched where the `contacts` array in manifest contains `NAME`.

### 5.24 contact sync

```
corky contact sync
```

Syncs `contacts/{name}/CLAUDE.md` between root contacts/ and each mailbox contacts/ directory.

**Eligibility (root → mailbox):** A contact syncs to a mailbox if either:
- **Conversation match:** a sender in `mailboxes/{mb}/conversations/*.md` slugifies to the contact name (or an alias)
- **Explicit sharing:** `[contacts.{name}].shared_with` includes the mailbox name

**Mailbox → root:** Always allowed (no eligibility check).

**Resolution:** 3-way merge via content hashes stored in `.sync-state.json`:
1. If only one side changed since last sync → take that side
2. If both changed → conflict: fall back to newest-wins by mtime + warning
3. First sync (no base hash) → mtime wins

Only `CLAUDE.md` is synced; `CLAUDE.local.md` and other files are skipped.

### 5.25 contact push

```
corky contact push [PLATFORM] [--name NAME...]
```

Push local contacts to external platforms. Currently supports Google Contacts via the People API.

**Platforms:** `google` (default when no platform specified)

**Behavior:**
- Reads contacts from `.corky.toml` `[contacts.*]` and `mail/contacts/{name}/AGENTS.md`
- Maps local fields → Google Person: name, emails, organization, title, phone, LinkedIn URL
- Creates new contacts or updates existing ones (tracked by `resourceName` in `.people-sync-state.json`)
- Falls back to create if an update target returns 404 (deleted on Google side)

**Field extraction from AGENTS.md:**
- `**Role:**` → title + organization (splits on " at ")
- `**Organization:**` / `**Company:**` / `**Org:**` → organization
- `**Title:**` → title
- `**Phone:**` → phone number
- `**LinkedIn:**` → URL

**OAuth:** Reuses Gmail client credentials (`[gmail]` in `.corky.toml`), requests `https://www.googleapis.com/auth/contacts` scope. Tokens stored as `people:default`.

### 5.26 contact delete

```
corky contact delete <RESOURCE_NAME>...
```

Deletes one or more contacts from Google Contacts by resource name. Accepts full resource names (`people/c123456`) or short form (`c123456`). Uses the People API `deleteContact` endpoint with the same OAuth credentials as `contact push`.

### 5.27 filter auth

```
corky filter auth [--account NAME]
```

Gmail OAuth2 authorization for filter management. Opens a browser for the authorization code flow, starts a local callback server on `127.0.0.1:8484`, and stores the token in the shared token store (keyed as `gmail:{account}` or `gmail:default`).

Required scopes: `gmail.settings.basic` (read/write filters), `gmail.labels` (list labels for name-to-ID resolution).

**Credential resolution order:**
1. `[gmail]` in `.corky.toml` (`client_id`/`client_id_cmd`, `client_secret`/`client_secret_cmd`)
2. `--client-id` / `--client-secret` CLI flags
3. Env vars (`CORKY_GMAIL_CLIENT_ID`, `CORKY_GMAIL_CLIENT_SECRET`)
4. Built-in default credentials (public desktop-app OAuth, injected at compile time)

### 5.26 filter build

```
corky filter build [--input FILE] [--output FILE]
```

Generates `mailFilters.xml` (Gmail importable format) from filter definitions.

Without `--input`: reads `[[gmail.filters]]` from `.corky.toml`, writes `mailFilters.xml` to the data directory.
With `--input`: reads a standalone TOML file, writes `mailFilters.xml` next to it (or to `--output`).

### 5.27 filter pull

```
corky filter pull [--account NAME]
```

Fetches and displays all current Gmail filters via the Gmail Settings API (read-only). Shows criteria (from, to, subject, query) and actions (add/remove labels, forward) for each filter.

Requires a valid token from `corky filter auth`.

### 5.28 filter push

```
corky filter push [--account NAME] [--dry-run]
```

Pushes `[[gmail.filters]]` from `.corky.toml` to Gmail via the Settings API, replacing all existing filters.

Flow:
1. Load `[[gmail.filters]]` entries from `.corky.toml` (error if none defined)
2. Authenticate via stored token (auto-refreshes if expired)
3. Fetch Gmail label name-to-ID mapping (needed to resolve user label names to API IDs)
4. Convert each config filter to Gmail API format (addresses joined with `OR`, match fields default to `from`)
5. Fetch all existing Gmail filters
6. Delete all existing filters, then create new ones from config

With `--dry-run`: shows existing filters, what would be deleted, and what would be created — no changes made.

**Label resolution:** System labels (INBOX, STARRED, IMPORTANT, SENT, DRAFT, SPAM, TRASH, UNREAD, CATEGORY_*) resolve by name. User labels resolve via case-insensitive lookup against the fetched label map.

**Required OAuth scopes:** `gmail.settings.basic` + `gmail.labels`. If the token was issued before `gmail.labels` was added to the scope list, re-authenticate with `corky filter auth`.

### 5.29 filter check

```
corky filter check [--account NAME]
```

Read-only drift detection: compares `[[gmail.filters]]` in `.corky.toml` against live Gmail filters without making changes.

Flow:
1. Load local filters from `.corky.toml`, convert to API format
2. Fetch remote filters from Gmail (2 API calls: filters + labels)
3. Normalize both to comparable criteria signatures (from/to/query)
4. Report: filters in `.corky.toml` but not on Gmail, filters on Gmail but not in `.corky.toml`

**Watch integration:** `corky watch` runs this check hourly (same cadence as auto-upgrade). On drift, prints a warning suggesting `corky filter push`. Auth or config errors are silently ignored in watch mode.

### 5.30 transcribe

```
corky transcribe FILE [--model NAME] [--language CODE]
                      [--output FILE] [--speakers NAME,...]
                      [--diarize] [--no-confidence-retranscribe]
```

Transcribe an audio file to timestamped text using whisper-rs. Included by default (CPU). Use `transcribe-cuda` for GPU acceleration.

**Supported formats:** WAV, MP3, FLAC, OGG, M4A, AAC (via symphonia), AMR and others (via ffmpeg fallback).

**Audio pipeline:** All formats are decoded to 16kHz mono f32 PCM. Multi-channel audio is averaged to mono. Resampling uses sinc interpolation via rubato.

**Model resolution:**
1. `--model` flag (e.g. `--model tiny.en`)
2. `[transcription] model` in `.corky.toml`
3. Default: `large-v3-turbo`

Models auto-download from HuggingFace to `~/.cache/corky/models/` (or custom path from `[transcription] model_path`).

**Output modes:**

1. **Plain** (no flags): `[HH:MM:SS.mmm --> HH:MM:SS.mmm] text`
2. **Speaker labels** (`--speakers "Ron,Brian"`): YAML frontmatter + bold speaker names with timestamps. Uses whisper's tdrz speaker turn detection.
3. **Diarization** (`--diarize`): Uses pyannote-rs (ONNX Runtime) for speaker segmentation and embedding-based clustering. More accurate than tdrz for mono phone recordings where both speakers share the same audio channel.

**Diarization pipeline** (enabled by default):

1. Run whisper transcription → timestamped text segments
2. Convert f32 audio to i16 for pyannote-rs
3. Run segmentation model (`segmentation-3.0.onnx`) → speech segments with timestamps
4. Extract speaker embeddings per segment (`wespeaker_en_voxceleb_CAM++.onnx`)
5. Cluster embeddings via cosine similarity (threshold: 0.5) → speaker IDs
6. Merge: for each whisper segment, find the diarized speaker with most temporal overlap
7. Label output with speaker names

**Interactive speaker labeling** (when `--diarize` without `--speakers`):

The diarization pipeline detects speakers as numeric IDs. When no `--speakers` names are provided, corky shows representative text excerpts for each detected speaker and prompts interactively:

```
Speaker 1 excerpts:
  1. "Manufacturing China is up and running..."
  2. "the traditional model of payment processing..."
  3. "crypto is just superior in so many ways"
Who is Speaker 1? (name or enter to skip): Ron Berkes

Speaker 2 excerpts:
  1. "I want to plan for the future of people accepting..."
  2. "let's catch up soon"
Who is Speaker 2? (name or enter to skip): Brian Takita
```

When `--speakers` is provided with `--diarize`, names are mapped to speaker IDs in order of first appearance (no interactive prompt).

**Confidence-based re-transcription:**

After the initial transcription pass, segments with average confidence below the threshold are re-transcribed using a smaller audio window centered on the low-confidence block. This improves accuracy for noisy or overlapping speech sections.

- Threshold: configurable via `[transcription] confidence_threshold` in `.corky.toml` (default: `0.4`)
- Opt out: `--no-confidence-retranscribe` flag
- Window: extracts a tighter audio slice around the low-confidence segment and re-runs whisper on just that portion
- Result: replaces the original low-confidence segments only if the re-transcription produces higher confidence

**ONNX models:** Auto-downloaded from pyannote-rs GitHub releases to `~/.cache/corky/models/`. No gated HuggingFace access required.

**Output format** (with speakers or diarize):

```markdown
---
date: 2026-02-27
type: phone-call
participants:
  - Brian Takita
  - Ron Berkes
duration: "3:16"
---

**Ron Berkes** [00:00:00.000 → 00:00:05.780]
Good. That post went viral. Oh, yeah.

**Brian Takita** [00:00:05.780 → 00:00:07.360]
Yeah.
```

**Feature flags:**
- `transcribe` — whisper-rs transcription + tdrz speaker turns (enabled by default)
- `transcribe-cuda` — NVIDIA CUDA GPU-accelerated transcription (Linux)
- `transcribe-metal` — Apple Metal GPU-accelerated transcription (macOS)
- `diarize` — pyannote-rs speaker diarization (implies `transcribe`)

**GPU auto-detection:**

Both install methods auto-detect GPU availability and attempt GPU-accelerated builds:

- **`make install`** (from source): On macOS, builds with `--features transcribe-metal`. On Linux, runs `nvidia-smi` — if found, attempts `cargo install --features transcribe-cuda`. On failure (missing CUDA toolkit, incompatible driver), falls back to CPU-only install silently.
- **`make release-gpu`** (build only): Same auto-detection as `make install` but runs `cargo build --release` instead of `cargo install`.
- **`install.sh`** (prebuilt binary): Checks for `nvidia-smi` (Linux) or macOS platform. Downloads the appropriate GPU binary variant (`-cuda` or `-metal`). Falls back to standard binary if GPU variant isn't available.

No user action needed — GPU support is enabled automatically when hardware is available. If the GPU build fails, the install continues with CPU-only transcription.

**Audio decode pipeline:** Video formats (mov, mkv, webm, avi, ts, mts) go directly to ffmpeg. Audio formats supported by symphonia are tried first; on failure, ffmpeg is used as a fallback.

**Edge cases:**

| # | Edge Case | Expected Behavior |
|---|---|---|
| T1 | File not found | Exit with error message |
| T2 | Unknown model name | Exit with list of known models |
| T3 | No ffmpeg installed | Error with install instructions per OS |
| T4 | `--diarize` without feature | N/A — diarize is a default feature |
| T5 | No speakers detected | Output with "Unknown" speaker labels |
| T6 | Single speaker detected | All segments labeled as that speaker |
| T7 | Interactive prompt, user skips | Label as "Speaker N" |
| T8 | Very short segments | May fail embedding extraction; labeled "Unknown" |

## 6. Sync Algorithm

### 6.1 State

Per-account, per-label state: `(uidvalidity: u32, last_uid: u32)`

### 6.2 Incremental Sync

For each account, for each label:
1. `SELECT` the IMAP folder
2. Check `UIDVALIDITY` — if changed from stored value, do full sync
3. If incremental: `SEARCH UID {last_uid+1}:*`, filter out `<= last_uid`
4. If full: `SEARCH SINCE {today - sync_days}`
5. For each UID: `FETCH RFC822`, parse email, merge to thread file
6. Update `(uidvalidity, last_uid)` in state

### 6.3 Message Parsing

From RFC822:
- Subject: `email.header.decode_header()` (handles encoded words)
- From: `email.header.decode_header()`
- To: `email.header.decode_header()` (comma-separated recipients)
- CC: `email.header.decode_header()` (comma-separated recipients)
- Date: raw header string
- Body: walk multipart preferring `text/html` (converted to markdown via `htmd`) without `Content-Disposition`, falling back to `text/plain`, or get payload for non-multipart. Post-conversion cleanup strips `@media` CSS blocks, tracking pixel images, and inline `style` attributes.
- Tracking: tracking pixel domains detected during body cleanup are accumulated on the thread's `**Tracking**` metadata line.
- Thread key: `thread_key_from_subject(subject)`

### 6.4 Merge

For each message:
1. Find existing thread file by scanning `**Thread ID**` metadata in all `.md` files
2. If found, parse back into Thread object
3. Check dedup: `(from, date)` tuple
4. If new: append message, sort by date, update `last_date`
5. Accumulate labels and accounts
6. Write markdown, set file mtime to last message date

### 6.5 Orphan Cleanup

On `--full` sync: track all files written/updated. After sync, delete any `.md` files in `conversations/` not in the touched set.

### 6.6 State Persistence

State is saved only after all accounts complete successfully. If sync crashes mid-way, state is not saved — next run re-fetches.

### 6.7 Contact Sync

**State:** Per-contact, per-mailbox FNV-1a content hash in `.sync-state.json` under `contacts.{name}.mailboxes.{mb}`.

**Slugification:** Sender names from `## {Name} — {Date}` headers are slugified: strip " via ..." suffix, strip `<email>` brackets, lowercase, replace non-alphanumeric with hyphens, collapse runs, trim.

**Eligibility:** `build_eligible_set()` scans conversation headers + checks `shared_with` + resolves aliases per mailbox.

**3-way merge:** For each contact-mailbox pair where both files exist:
1. Hash root and mailbox content
2. If hashes match → already in sync, record hash
3. Compare each hash against stored base:
   - Root matches base → root unchanged, take mailbox
   - Mailbox matches base → mailbox unchanged, take root
   - Neither matches → conflict, mtime tiebreak + warning
   - No base → first sync, mtime tiebreak
4. Write winning content, preserve mtime, update stored hash

**Ineligible contacts (both exist):** Same 3-way logic but only allows mailbox → root direction.

### 6.8 Gmail API Sync

Alternative sync provider using the Gmail REST API instead of IMAP. Selected by `provider = "gmail-api"` in account config.

**Config (`.corky.toml`):**
```toml
[[accounts]]
name = "personal"
provider = "gmail-api"
user = "you@gmail.com"
labels = ["INBOX", "SENT"]
sync_days = 30
```

**Authentication:** OAuth2 via `gmail_auth::get_access_token_for_user()` with `GMAIL_SYNC_SCOPE`. Passes `user` as `login_hint` to pre-select the correct Google account. Credential resolution follows §5.25 (config → CLI → env → built-in defaults).

**State:** Per-account, per-label `GmailLabelState { last_history_id: Option<u64> }` in `.sync-state.json`.

**Incremental sync (historyId):**
1. If `last_history_id` exists and not `--full`: call `GET /history?startHistoryId={id}&historyTypes=messageAdded&labelId={label}` with pagination
2. On success: extract new message IDs, update `last_history_id` to highest seen
3. On failure (e.g., historyId expired): log warning, clear `last_history_id`, fall back to full sync

**Full sync:**
1. `GET /messages?labelIds={label}&q=after:{sync_days ago}` with pagination
2. For each message ID: `GET /messages/{id}?format=full`
3. Parse MIME payload preferring `text/html` body (converted to markdown via `htmd`), falling back to `text/plain`. Extract headers (From, To, Cc, Date, Subject). For parts where Gmail returns `attachmentId` instead of inline `data` (common with `multipart/related` messages), fetches body via `GET /messages/{id}/attachments/{attachmentId}`
4. Thread ID from Gmail preserved as dedup key
5. Label IDs resolved to human-readable names via `GET /labels`
6. Multi-label messages written to each label's mailbox + extra routes

**Account verification:** Before syncing, validates the OAuth token belongs to the configured `user` email address. Catches account mismatch early.

**404 resilience:** Individual messages that return HTTP 404 (deleted between listing and fetch) are logged and skipped. The sync continues with remaining messages rather than aborting the entire account.

**Shutdown handling:** Checks `AtomicBool` shutdown signal per-message and every 5 pages of listing. Returns early with partial results if interrupted.

**Single-thread refetch (`sync refetch THREAD_ID`):**
Re-fetches all messages in a single Gmail thread, bypassing `historyId` state. Useful when a message was synced but body extraction failed (e.g., `attachmentId` or base64 padding issues fixed in a later release).

1. Scans `conversations/` for a file matching the `**Thread ID**` metadata
2. Extracts account name and labels from the existing file
3. Deletes the old file to allow fresh content merge
4. Calls `GET /threads/{threadId}?format=full` — returns all messages in one API call
5. Re-merges each message via `merge_message_to_file()` (creates fresh file)
6. Also refreshes routed copies in mailbox directories
7. If no existing file found, tries all `gmail-api` accounts

No sync state is modified — `last_history_id` is untouched.

**Merge and orphan cleanup:** Same as IMAP (§6.4, §6.5) — messages merge into thread files, full sync deletes untouched files.

### 6.9 Doctor

`corky doctor [PROVIDER]` — health check that validates environment, configuration, and account connectivity.

**Always checks:**
- `.corky.toml` exists and parses successfully
- Mail directory exists

**Per-provider checks (all run when no PROVIDER given):**

| Provider | Checks |
|----------|--------|
| `gmail-api` | OAuth credentials resolution, sync token existence/validity/expiration, refresh token capability, user email match |
| `gmail`, `imap`, `protonmail-bridge` | Password config (inline or command), IMAP host and port |
| Gmail filters | Filter auth token status (`gmail:default` key), validity/expiration |
| `linkedin` | OAuth credentials (config/env), per-profile: handle, URN, token validity, auto-refresh |
| `youtube` | OAuth credentials (config/env), per-profile: handle, channel ID, token validity, auto-refresh |

**Output:** Line-by-line text. `✓` for pass, `✗` for failure. 2-space indentation for details. Sections separated by blank lines.

**Exit code:** 0 if all checks pass, 1 if any fail.

## 7. Mailbox Lifecycle

### 7.1 Add

Without `--github` (plain directory):
1. Create `mailboxes/{name}/` with conversations/drafts/contacts subdirectories
2. Write template files (AGENTS.md, CLAUDE.md symlink, README.md, voice.md, .gitignore, `.claude/skills/{corky,email,linkedin}/`)
3. Update `.corky.toml`

With `--github` (submodule):
1. Create GitHub repo (`gh repo create`)
2. Add collaborator (`gh api repos/.../collaborators/...`) or print PAT instructions
3. Clone to temp dir, write template files, commit, push
4. Add as git submodule at `mailboxes/{name}/`
5. Update `.corky.toml`

### 7.2 Sync

1. `git pull --rebase` in submodule (skipped for plain directories and local-only repos with no remote)
2. Copy `voice.md` if root copy is newer
3. Sync workflow template if newer
4. **Bidirectional topic sync** (see §7.7)
5. Stage, commit, push local changes (skipped for plain directories)
6. Update submodule ref in parent (`git add {submodule_path}`) (skipped for plain directories)

### 7.3 Status

For each mailbox submodule:
1. `git fetch`
2. `git rev-list --count HEAD..@{u}` (incoming)
3. `git rev-list --count @{u}..HEAD` (outgoing)

### 7.4 Remove

For plain directories: `rm -rf mailboxes/{name}/`.
For submodules:
1. `git submodule deinit -f`
2. `git rm -f`
3. Clean up `.git/modules/{path}`

Then:
4. Remove from `.corky.toml`
5. Optionally delete GitHub repo (interactive confirmation)

### 7.5 Rename

1. Move `mailboxes/{old}` to `mailboxes/{new}` (`git mv` for submodules, `mv` for plain dirs)
2. Optionally `gh repo rename`
3. Update `.corky.toml` entry

### 7.6 Reset

1. `git pull --rebase` (submodules with remote only)
2. Regenerate: AGENTS.md, CLAUDE.md (symlink), README.md, .gitignore, voice.md, `.claude/skills/{corky,email,linkedin}/` at `mailboxes/{name}/`
3. Stage, commit, push (submodules only)
4. Update submodule ref in parent (submodules only)

### 7.7 Topic Sync

Topics are bidirectionally synced between root and mailbox during `corky mailbox sync`.

**Configuration:** Topics opt in via the `mailboxes` field in `.corky.toml`:

```toml
[topics.brian-takita]
keywords = ["corky", "agent-doc"]
mailboxes = ["lucas"]
description = "Personal brand and tooling identity"
```

**Directory mapping:**
- Root: `topics/{name}/` (e.g., `topics/brian-takita/README.md`)
- Mailbox: `mailboxes/{mailbox}/topics/{name}/` (e.g., `mailboxes/lucas/topics/brian-takita/README.md`)

**Algorithm:**

1. Load topics from `.corky.toml`, filter by `mailboxes` containing the current mailbox name
2. For each matching topic, collect all files from both root and mailbox topic directories
3. For each file in the union:
   - **Forward (root → mailbox):** Copy if root file is newer or mailbox file is missing
   - **Reverse (mailbox → root):** Copy if mailbox file is newer or root file is missing
4. Newer file wins (mtime comparison). Missing files are always copied.

**Edge cases:**

| # | Case | Behavior |
|---|---|---|
| TS1 | No topics list this mailbox | No-op |
| TS2 | Root topic dir exists, mailbox doesn't | Forward copy creates mailbox topic dir |
| TS3 | Mailbox topic dir exists, root doesn't | Reverse copy creates root topic dir |
| TS4 | Both exist, root newer | Forward copy (root wins) |
| TS5 | Both exist, mailbox newer | Reverse copy (mailbox wins) |
| TS6 | New file on one side only | Copied to other side |
| TS7 | Different files on each side | Both copied (union of files) |
| TS8 | Subdirectories in topic | Recursively synced |

## 8. Draft Lifecycle

### 8.1 Create

Manual: create file in `{data_dir}/drafts/` or `{data_dir}/mailboxes/{name}/drafts/`.
Filename convention: `YYYY-MM-DD-{slug}.md`.

### 8.2 Validate

`corky draft validate` checks format. See section 5.18.

### 8.3 Push / Send

`corky draft push FILE`: IMAP APPEND to drafts folder (or Gmail API `drafts.create` for `gmail-api` accounts).
`corky draft push FILE --send`: SMTP send (or Gmail API `messages.send` for `gmail-api` accounts), update Status to `sent`.

Account resolution: Account field → From field → default account.

**Provider dispatch:** For accounts with `provider = "gmail-api"`, draft push and send use the Gmail REST API instead of IMAP/SMTP. OAuth token obtained via `get_send_access_token()` with scope `gmail.send`, stored under key `gmail:<account>:send` (separate from sync token). No password required for gmail-api accounts.

## 9. Watch Daemon

### 9.1 Poll Loop

```
while not shutdown:
    for each account:
        sync_account(full=false)
    save_state()
    count_new = compare uid snapshots before/after
    if count_new > 0:
        sync_mailboxes()
        notify(count_new)
    schedule_run()          # publish any due scheduled items (email + social)
    wait(interval) or shutdown
```

### 9.2 Signals

SIGTERM, SIGINT → clean shutdown (finish current poll, then exit). Both IMAP and Gmail API sync paths check the shutdown signal and return early when interrupted.

### 9.3 Notifications

- macOS: `osascript -e 'display notification ...'`
- Linux: `notify-send`
- Silently degrades if tool not installed.

### 9.4 Config

`[watch]` section in `.corky.toml`:
- `poll_interval`: seconds (default 300)
- `notify`: bool (default false)

CLI `--interval` overrides config.

## 10. Provider Presets

| Field | `gmail` | `protonmail-bridge` | `imap` (generic) |
|---|---|---|---|
| imap_host | imap.gmail.com | 127.0.0.1 | (required) |
| imap_port | 993 | 1143 | 993 |
| imap_starttls | false | true | false |
| smtp_host | smtp.gmail.com | 127.0.0.1 | (required) |
| smtp_port | 465 | 1025 | 465 |
| drafts_folder | [Gmail]/Drafts | Drafts | Drafts |

Preset values are defaults — any field explicitly set on the account wins.

## 11. Account Resolution

### 11.1 Secret Resolution

Shared pattern (`util::resolve_secret`) used by both account passwords and social OAuth credentials:

1. Inline value (non-empty string)
2. `_cmd` field (shell command via `sh -c`, capture stdout, strip trailing whitespace)
3. Error with context message if both are empty

**Account passwords:** `password` > `password_cmd` > error
**Social credentials:** `client_id` > `client_id_cmd` > env var fallback (see §12.5)

### 11.2 Sending Account

For `draft push`:
1. `**Account**` metadata field → lookup by name in `.corky.toml`
2. `**From**` metadata field → lookup by email address (case-insensitive)
3. Default account (first with `default = true`, or first in file)
4. Credential bubbling (see §11.3)

### 11.3 Credential Bubbling

When a draft lives inside a `mailboxes/` subtree, the child mailbox may not have its own IMAP/SMTP credentials. Corky resolves credentials bottom-up:

1. Check the leaf mailbox's `.corky.toml` for matching account credentials
2. Walk parent directories upward, checking each `.corky.toml` for an account whose `user` matches the `**From**` address
3. First match wins
4. If no credentials found at any level, bail with error

This enables child mailboxes to draft replies that the parent's account sends.

## 12. Social Media Posting

Corky supports publishing social media posts through a unified multi-platform architecture.

### 12.1 Supported Platforms

| Platform | Status | API |
|---|---|---|
| LinkedIn | Implemented | REST (OAuth2 authorization code) |
| YouTube | Implemented | Data API v3 (OAuth2 authorization code) |
| Bluesky | Planned | AT Protocol |
| Mastodon | Planned | ActivityPub |
| Twitter | Planned | OAuth2 |

### 12.2 Profile Registry (profiles.toml)

Lives at `{data_dir}/profiles.toml`. Maps human profile names to platform handles and URNs.

```toml
[btakita]
[btakita.linkedin]
handle = "brian-takita"
urn = "urn:li:person:abc123"

[btakita.twitter]
handle = "btakita"
```

**Validation checks:**
1. No duplicate handles within the same platform
2. No duplicate URNs within the same platform
3. No cross-profile URN reuse (same URN across different profiles)
4. Every profile should have at least one platform entry (warning)
5. Cross-platform coherence info (same profile, multiple platforms)

### 12.3 Social Drafts

Social drafts live in `{data_dir}/social/` as Markdown files with YAML frontmatter.

**Filename convention:** `YYYYMMDD-HHMMSS-{platform}.md`

**Frontmatter fields:**

| Field | Required | Default | Description |
|---|---|---|---|
| `platform` | yes | — | linkedin, bluesky, mastodon, twitter |
| `author` | yes | — | Profile name in profiles.toml |
| `visibility` | no | `public` | public, connections (platform-specific) |
| `status` | no | `draft` | draft → ready → published |
| `tags` | no | `[]` | Freeform tags |
| `scheduled_at` | no | — | Future publish time (not yet implemented) |
| `published_at` | no | — | Set on publish |
| `post_id` | no | — | Set on publish (platform post ID) |
| `post_url` | no | — | Set on publish (permalink) |
| `images` | no | `[]` | List of image paths (relative to draft file) |

**Images:** The `images` field accepts a list of file paths relative to the draft file location. On publish, each image is uploaded to the platform and attached to the post. LinkedIn supports up to 20 images per post (1 image = single image post, 2+ = carousel).

**Status transitions:** `draft` → `ready` → `published` (one-way).

### 12.4 Token Store

OAuth tokens stored at `{app_config_dir}/tokens.json` keyed by platform URN.

- File permissions: 0600 (owner read/write only)
- Tokens have a 5-minute grace window: tokens expiring within 5 minutes are treated as expired
- Token fields: access_token, refresh_token (optional), expires_at, scopes, platform

### 12.5 OAuth Flow

Authorization code flow (LinkedIn):

1. Build auth URL with client_id, redirect_uri, state, scopes
2. Open browser (`open` crate)
3. Start local HTTP server on `127.0.0.1:8484` (`tiny_http`)
4. Wait for callback (120s timeout)
5. Verify state parameter (CSRF protection)
6. Exchange code for token via POST
7. Fetch user URN via `/v2/userinfo`
8. Store token in tokens.json

Client credentials resolution order per field:
1. Inline value in `.corky.toml` (e.g. `client_id = "..."`)
2. Shell command via `_cmd` suffix (e.g. `client_id_cmd = "pass corky/linkedin/client_id"`)
3. Environment variable (`CORKY_LINKEDIN_CLIENT_ID` / `CORKY_LINKEDIN_CLIENT_SECRET`)

### 12.6 Publish Flow

1. Parse draft file (YAML frontmatter + body)
2. Verify status is `ready` (not `draft` or `published`)
3. Resolve author → URN via profiles.toml
4. Lookup valid token for URN in token store
5. Upload images (if any): resolve paths relative to draft file, call platform image upload API
6. Call platform API (LinkedIn: POST /rest/posts) with image URNs
7. Update draft frontmatter: status=published, post_id, post_url, published_at

**LinkedIn image upload flow:**
1. `POST /rest/images?action=initializeUpload` with `owner: urn:li:person:{id}` → returns upload URL + image URN
2. `PUT` binary image data to the upload URL
3. Include image URN(s) in post payload: single image → `content.media.id`, 2+ images → `content.multiImage.images[]`

**LinkedIn limits:** 3000 character post body, 20 images max, visibility: PUBLIC or CONNECTIONS.

### 12.7 CLI Commands

```
corky linkedin auth [--profile NAME]              # OAuth flow, stores token
corky linkedin draft [BODY] [--author X] [--visibility public] [--tags X,Y]
corky linkedin publish <file>                     # Publish ready draft
corky linkedin check                              # Validate profiles.toml
corky linkedin list [--status X]                  # List LinkedIn drafts
corky linkedin rename-author <old> <new>          # Rename across drafts + profiles
corky linkedin edit <file> [--body TEXT]           # Update published post text
corky linkedin comment <file> <body>             # Comment on a published post
```

### 12.8 Edge Case Table

| # | Edge Case | Expected Behavior |
|---|---|---|
| **Profile Validation** | | |
| P1 | Duplicate handle within same platform | Error: handle already mapped to different URN |
| P2 | Duplicate URN within same platform | Error: URN used by multiple profiles |
| P3 | Same URN across different profiles | Error: cross-profile URN conflict |
| P4 | Profile with no platform entries | Warning: profile has no platform entries |
| P5 | Cross-platform coherence (same profile, multiple platforms) | Info: verify same person |
| P6 | Empty profiles.toml | OK: empty map, no errors |
| P7 | Malformed TOML | Error with parse location |
| P8 | Missing profiles.toml | Error with guidance to run `corky linkedin check` |
| P9 | Collaborator merge introduces duplicate URN | Validation surfaces conflict |
| **Draft Parsing** | | |
| D1 | Valid draft with all fields | Parsed correctly |
| D2 | Missing required field (platform) | Error: missing field |
| D3 | Missing required field (author) | Error: missing field |
| D4 | Unknown platform | Error with list of supported platforms |
| D5 | Invalid status value | Error with valid statuses |
| D6 | No YAML frontmatter delimiters | Error: missing `---` |
| D7 | Empty body after frontmatter | Warning: empty post body |
| D8 | Render/parse round-trip | Identical meta |
| D9 | Malformed YAML | Error with parse details |
| **Token Store** | | |
| T1 | Missing tokens.json | Returns empty store |
| T2 | Save/load round-trip | All fields preserved |
| T3 | Get valid token | Returns Some |
| T4 | Get expired token | Returns None |
| T5 | Token in grace window (<5 min) | Returns None |
| T6 | Multiple tokens for different URNs | Correct per-URN lookup |
| T7 | Upsert overwrites existing | New replaces old |
| T8 | File permissions 0600 on save | Verified via metadata |
| T9 | Malformed tokens.json | Error with parse details |
| **Auth Flow** | | |
| A1 | Correct auth URL generation | Contains client_id, redirect_uri, scopes, state |
| A2 | Valid callback parse | Extracts code + state |
| A3 | Callback missing code | Error message |
| A4 | State mismatch (CSRF) | Error message |
| A5 | Callback with error param | Error: user denied |
| **Publish Flow** | | |
| PB1 | Draft not in "ready" status | Error: wrong status |
| PB2 | Already published | Error: already published |
| PB3 | Author not in profiles.toml | Error with available profiles |
| PB4 | Author has no entry for draft's platform | Error: no platform entry |
| PB5 | No token for resolved URN | Error with `corky linkedin auth` guidance |
| PB6 | Expired token | Error with re-auth guidance |
| PB7 | Successful publish | Updates post_id, post_url, published_at, status |
| PB8 | Network error during API call | Error propagated with context |
| PB9 | API error response (403, etc.) | Error with HTTP status + body |
| PB10 | Body exceeds 3000 char limit | Error with char count |
| **Image Upload** | | |
| IM1 | No images in draft | Text-only post (no content field) |
| IM2 | Image file not found | Error with resolved path |
| IM3 | Too many images (> 20) | Error with count and limit |
| IM4 | Draft round-trip with images | Images preserved in YAML |
| IM5 | Image path resolution | Resolved relative to draft file directory |
| IM6 | Empty images list | Same as no images (omitted from YAML) |

## 13. Scheduling

Unified scheduling for social media posts and email drafts. A single `schedule` module scans both draft systems and dispatches to their existing publish paths.

### 13.1 Architecture

`corky/src/schedule.rs` — single-file module, no traits or shared abstractions.

**Types:**
- `ScheduledKind` — enum: `Social`, `Email`
- `ScheduledItem` — `{ path, kind, scheduled_at, label }`
- `ProcessResult` — `{ path, kind, success, message }`

**Flow:**
1. Scan `social/` for `.md` files where `status: ready` and `scheduled_at <= now + grace`
2. Scan `drafts/` and `mailboxes/*/drafts/` for `.md` files where `**Status**: scheduled` and `**Scheduled-At** <= now + grace`
3. Sort by `scheduled_at` ascending (earliest first)
4. Dispatch: `Social` → `social::publish::publish(path)`, `Email` → `draft::run(path, send=true)`
5. Report results per-item

**Grace window:** 30 seconds. Items scheduled up to 30s in the future are still considered due (handles cron drift / clock skew).

### 13.2 Email Draft Scheduling

Added `**Status**: scheduled` as a valid send status alongside `review` and `approved`.

Email draft format:
```markdown
**Status**: scheduled
**Scheduled-At**: 2026-02-25T09:00:00Z
```

Status flow: `draft` → `scheduled` → `sent`

The `Scheduled-At` field uses RFC 3339 / ISO 8601 format with timezone (UTC recommended).

### 13.3 Social Draft Scheduling

Social drafts already have `scheduled_at: Option<DateTime<Utc>>` in YAML frontmatter (§12.3). The scheduler checks for `status: ready` combined with `scheduled_at` in the past.

Status flow: `draft` → `ready` (with `scheduled_at` set) → `published`

### 13.4 CLI Commands

```
corky schedule run              # Process all due scheduled items
corky schedule run --dry-run    # Show what would be published without doing it
corky schedule list             # List all pending scheduled items with times
```

`corky watch` includes scheduled publishing in its poll loop — no separate cron entry needed.
Run `corky watch` and it handles both IMAP sync and scheduled publishing.
`corky schedule run` remains available for one-shot use.

**Standalone cron** (alternative to `corky watch`):
```
*/5 * * * * corky schedule run
```

### 13.5 Edge Case Table

| # | Edge Case | Expected Behavior |
|---|---|---|
| S1 | No scheduled items | Exit 0, no output |
| S2 | Social item due | Publish via `social::publish`, print summary |
| S3 | Email item due | Send via `draft::run(send=true)`, print summary |
| S4 | Item in future | Skipped |
| S5 | `scheduled_at` missing on ready/scheduled item | Skipped (not a scheduled item) |
| S6 | Multiple items due | Process all, sorted by time, per-item results |
| S7 | Email with wrong status (not "scheduled") | Skipped |
| S8 | Social with wrong status (not "ready") | Skipped |
| S9 | Non-.md files in scan directories | Ignored |
| S10 | Item within 30s grace window | Treated as due |
| S11 | Publish fails (network) | Error logged, item stays scheduled, exit 1 |
| S12 | `--dry-run` flag | Print what would happen, don't publish |

## 14. Document Building

### 14.1 Overview

`corky doc` manages document building and Google Docs/Sheets integration. Subcommands:

| Command | Description |
|---------|-------------|
| `corky doc build <FILE>` | Convert markdown to PDF or DOCX |
| `corky doc upload <FILE> [--share] [--account EMAIL]` | Upload a file to Google Drive |
| `corky doc read <DOC> [-o FILE] [--account EMAIL]` | Read a Google Doc as markdown |
| `corky doc write <DOC> <FILE> [--account EMAIL]` | Update a Google Doc from markdown |
| `corky doc sheet <SHEET> [--range R] [--format table\|csv] [-o FILE] [--account EMAIL]` | Read a Google Sheet range |

The `--account EMAIL` flag selects which Google account's OAuth token to use. When omitted, the default account is used. This enables multi-account workflows where different documents belong to different Google accounts.

### 14.2 CLI Interface (build)

```
corky doc build <FILE>                      # PDF (default)
corky doc build --format docx <FILE>        # DOCX
corky doc build --template <NAME> <FILE>    # Named CSS template
corky doc build -o <OUTPUT> <FILE>          # Custom output path
```

### 14.2.1 Google Drive Upload

```
corky doc upload <FILE> [--share] [--account EMAIL]
```

Uploads a local file to Google Drive. The MIME type is inferred from the file extension. When `--share` is set, the uploaded file is shared (link-based access). Prints the web link on success.

### 14.2.2 Google Docs Read

```
corky doc read <DOC_URL_OR_ID> [-o FILE] [--account EMAIL]
```

Exports a Google Doc as markdown (via HTML export). Output goes to stdout by default or to `-o FILE`.

### 14.2.3 Google Docs Write

```
corky doc write <DOC_URL_OR_ID> <FILE> [--account EMAIL]
```

Replaces the content of a Google Doc with the contents of a local markdown file.

### 14.2.4 Google Sheets Read

```
corky doc sheet <SHEET_URL_OR_ID> [--range RANGE] [--format table|csv] [-o FILE] [--account EMAIL]
```

Reads a Google Sheets range and outputs as a markdown table (default) or CSV. `--range` specifies the cell range (e.g. `A1:D10`, `Sheet1!A1:C5`). Without `--range`, reads all data from the first sheet.

### 14.3 Format Pipelines

| Format | Pipeline | Tools Required |
|--------|----------|----------------|
| PDF | Markdown → pandoc → HTML → weasyprint → PDF | pandoc, weasyprint |
| DOCX | Markdown → pandoc → DOCX | pandoc |

### 14.4 Template Resolution

1. `--template <NAME>` CLI argument (highest priority)
2. `template:` field in YAML frontmatter
3. Default: `"proposal"`

Template CSS loaded from `{data_dir}/templates/{template_name}.css`. If the file does not exist, the document is rendered without custom styles.

### 14.5 Tool Checking

Before conversion, `check_tool()` verifies that required tools (`pandoc`, `weasyprint`) are on PATH. If missing, an error message provides install links.

### 14.6 Edge Cases

| ID | Scenario | Behavior |
|----|----------|----------|
| D1 | Input file missing | Error: "Input file not found" |
| D2 | Unsupported format | Error: "Use 'pdf' or 'docx'" |
| D3 | pandoc not installed | Error with install URL |
| D4 | weasyprint not installed (PDF only) | Error with install URL |
| D5 | CSS template file missing | Render without custom styles |
| D6 | No output path specified | Same directory as input, with format extension |
| D7 | No frontmatter | Default template "proposal" |
| D8 | pandoc fails | Temp HTML cleaned up, error reported |
| D9 | weasyprint fails | Temp HTML cleaned up, error reported |

## 15. Google Calendar

### 15.1 Overview

Manage Google Calendar events via the Calendar API v3. Reuses Gmail OAuth credentials from `[gmail]` in `.corky.toml` with the `https://www.googleapis.com/auth/calendar` scope. Tokens stored under `calendar:*` keys in the shared token store.

### 15.2 CLI Commands

| Command | Description |
|---------|-------------|
| `corky cal auth [--account NAME]` | OAuth2 browser flow for Calendar scope |
| `corky cal list [--limit N] [--query Q] [--account NAME]` | List upcoming events (default 10) |
| `corky cal create SUMMARY START END [--description D] [--location L] [--account NAME]` | Create a calendar event |
| `corky cal delete QUERY [--all] [--dry-run] [--account NAME]` | Delete events matching query |
| `corky cal check START END [--account NAME]` | Check availability in a time range |

### 15.3 Auth

`corky cal auth` runs the OAuth2 browser flow to obtain a Calendar-scoped token. Reuses the same `client_id` / `client_secret` from `[gmail]` config. If a valid Gmail token already exists, the Calendar scope is added to the existing authorization. The `--account` flag selects which Gmail account to authorize (defaults to the first configured account).

### 15.4 List

`corky cal list` fetches upcoming events from the primary calendar.

- `--limit N` — maximum number of events to return (default: 10)
- `--query Q` — free-text search filter passed to the Calendar API
- `--account NAME` — select Gmail account

Output: one line per event with date/time, summary, and location (if set).

### 15.5 Create

`corky cal create SUMMARY START END` creates a new event on the primary calendar.

**Positional arguments:**
- `SUMMARY` — event title
- `START` — start time as RFC 3339 datetime (`2026-03-10T09:00:00-07:00`) or `YYYY-MM-DD` for all-day events
- `END` — end time as RFC 3339 datetime or `YYYY-MM-DD` for all-day events

**Options:**
- `--description D` — event description / notes
- `--location L` — event location
- `--account NAME` — select Gmail account

When both `START` and `END` are `YYYY-MM-DD` (date-only), the event is created as an all-day event using `date` fields instead of `dateTime`. Mixed date/datetime args are rejected with an error. On success: prints event ID and link to Google Calendar.

### 15.6 Delete

`corky cal delete QUERY` searches for events matching `QUERY` and deletes them.

- Without `--all`: deletes individual event instances (up to 25 matching)
- With `--all`: deduplicates by `recurring_event_id` and deletes the series root event, removing all past and future instances
- `--dry-run`: shows matching events without deleting
- `--account NAME`: select Gmail account

### 15.7 Check

`corky cal check START END` queries the Calendar API to show availability in a time range.

**Positional arguments:**
- `START` — range start as RFC 3339 datetime
- `END` — range end as RFC 3339 datetime

**Options:**
- `--account NAME` — select Gmail account

Fetches up to 50 events in the range via `singleEvents=true` (expands recurring). Reports each busy period with event name and duration. Prints summary: total busy time, free time, and total range. Exits with status 0 regardless of busyness.

### 15.8 Edge Cases

| ID | Scenario | Behavior |
|----|----------|----------|
| C1 | Calendar API not enabled | 403 with activation URL |
| C2 | Token expired | Auto-refresh via refresh token |
| C3 | No events match query | "No events matching '...'" |
| C4 | Recurring series delete | Deletes series root, not instances |
| C5 | Event already deleted | 404/410 silently ignored |
| C6 | Mixed date/datetime in create | Error: "start and end must both be dates or both be datetimes" |
| C7 | End before start | Error: "end must be after start" |
| C8 | Check with no events | "Fully available" message |
| C9 | Create with past start time | Allowed (API permits past events) |

## 16. SMS Import

### 16.1 Overview

Import SMS messages from SMS Backup & Restore XML format into conversation markdown files.

### 16.2 CLI Interface

```
corky sync sms-import PATH [--label LABEL] [--account ACCOUNT]
```

- `PATH`: Path to SMS backup XML file
- `--label`: Label for imported conversations (default: "sms")
- `--account`: Account name (default: "sms")

## § 16b Config-driven Imports

### 16b.1 Overview

The `[[imports]]` config section defines import sources in `.corky.toml`.
`corky sync imports` reads all entries and dispatches to the matching handler
(`sms_import`, `telegram_import`, `slack_import`).

### 16b.2 Configuration

```toml
[[imports]]
type = "sms"                    # sms | telegram | slack
path = "~/Downloads/sms-backup.xml"
label = "sms"                   # default: same as type
account = "personal"            # default: same as type
```

- `type` (required): Handler to invoke.
- `path` (required): Source file or directory. Tilde (`~`) is expanded.
- `label` (optional): Conversation label. Defaults to the import type.
- `account` (optional): Account name for metadata. Defaults to the import type.

### 16b.3 CLI Interface

```
corky sync imports
```

Reads `[[imports]]` from `.corky.toml` and runs each entry in order.
Missing paths emit a warning and are skipped. Unknown types cause an error.

### 16b.4 Dispatch

| type | handler |
|------|---------|
| `sms` | `sync::sms_import::run()` |
| `telegram` | `sync::telegram_import::run()` |
| `slack` | `sync::slack_import::run()` |

## § 17 YouTube

### 17.1 Overview

YouTube integration supports video upload and caption management via the YouTube Data API v3.

### 17.2 Configuration

```toml
[youtube]
client_id_cmd = "pass corky/youtube/client_id"
client_secret_cmd = "pass corky/youtube/client_secret"
```

### 17.3 OAuth Flow

Authorization code flow (Google OAuth2):
1. `corky youtube auth` opens browser → Google consent screen (scopes: `youtube.upload`, `youtube.force-ssl`)
2. User authorizes, callback writes refresh token to token store
3. Subsequent commands use refresh token → access token auto-refresh

### 17.4 Draft Format

YouTube drafts extend the social draft format with additional fields:

```yaml
platform: youtube
author: btakita
visibility: unlisted
title: "Video Title"
video: /path/to/video.mp4
captions: /path/to/captions.srt
tags:
  - tag1
  - tag2
```

### 17.5 Upload Flow

1. Read draft file, resolve video path
2. Initialize resumable upload (POST to upload URI with metadata)
3. Stream video in 8MB chunks (PUT to upload URL)
4. On completion, extract video ID from response
5. If captions file specified, upload SRT via captions API
6. Update draft with `post_id` and `post_url`

### 17.6 CLI Commands

```
corky youtube auth                                  # Google OAuth2 flow
corky youtube check                                 # Validate YouTube profiles
corky youtube comment <file> "text"                 # Post a comment on a published video
corky youtube draft [BODY] [--author X] [--video PATH] [--captions PATH] [--title TEXT]
corky youtube edit <file>                           # Update published video metadata
corky youtube list [--status X]                     # List YouTube drafts
corky youtube playlist add <PLAYLIST_ID> <VIDEO_ID> [--position N]
corky youtube playlist create <TITLE> [--description TEXT] [--visibility V]
corky youtube playlist list                         # List your playlists
corky youtube playlist remove <PLAYLIST_ID> <VIDEO_ID>
corky youtube publish <file>                        # Upload video + captions
```

### 17.7 Playlist Management

Playlist operations use the YouTube Data API v3 playlists and playlistItems endpoints. The existing `youtube.force-ssl` OAuth scope covers all playlist operations — no additional authorization is needed.

- **create** — `playlists.insert` with snippet (title, description) and status (privacy)
- **add** — `playlistItems.insert` with snippet (playlistId, resourceId, optional position)
- **list** — `playlists.list` with `mine=true`, returns ID, title, privacy, item count
- **remove** — looks up the playlistItem ID via `playlistItems.list` (filter by playlistId + videoId), then `playlistItems.delete`

### 17.8 Constraints

- Maximum video file size: handled by resumable upload (no practical limit)
- Chunk size: 8MB (configurable internally)
- Captions: SRT format only
- Visibility: public, unlisted, or private
- Category ID defaults to 28 (Science & Technology)

## 18. Self-Hosted Deployment

Corky is fully self-hosted — it runs entirely on the user's machine with no external services beyond the provider APIs (Gmail, LinkedIn, YouTube).

### 18.1 Credential Modes

1. **Built-in defaults** (zero config) — corky ships with public OAuth client credentials compiled in. Suitable for most users.
2. **Self-hosted GCP project** — users create their own GCP project for full control over OAuth tokens, audit logs, and credential rotation. See `docs/guide/self-hosted-gmail.md`.

### 18.2 Privacy Model

- No data collection, storage, or transmission to third parties
- Email content stays on the local machine
- OAuth tokens stored locally (`~/.config/corky/`)
- No analytics, telemetry, or tracking
- Gmail API scopes: `gmail.readonly`, `gmail.send`, `gmail.settings.basic`, optionally `youtube.readonly`
- Does NOT request: delete, contacts, calendar, or YouTube modification permissions
- Users can revoke access anytime via Google security settings
- Full privacy policy: `docs/reference/privacy-policy.md`

