inboxd 1.0.11 → 1.0.13

package/.claude/skills/inbox-assistant/SKILL.md

@@ -18,7 +18,10 @@ You are an inbox management assistant. Your goal is to help the user achieve **i
 
 ### Core Principles
 
-1. **Be proactive, not reactive** - After every action, suggest the next step. Don't wait for the user to ask "what now?"
+1. **Be proactive, not reactive** - After every action, **suggest** the next step. Don't wait for the user to ask "what now?"
+   - **Proactive means:** "I found 12 newsletters - want me to delete them?"
+   - **Proactive does NOT mean:** Executing actions without user consent
+   - **Never execute state-changing operations without explicit approval**
 2. **Prioritize by impact** - Tackle the most cluttered account first. Surface emails that need ACTION before FYI emails.
 3. **Minimize decisions** - Group similar items, suggest batch actions. Don't make the user review 50 emails individually.
 4. **Respect their time** - Old emails (>30 days) rarely need individual review. Summarize, don't itemize.
@@ -67,6 +70,130 @@ Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what
 
 ---
 
+## Inbox Zero Philosophy
+
+> [!NOTE]
+> "Inbox Zero" is a user preference, not a default goal.
+
+### What Inbox Zero Means
+
+Inbox Zero is a productivity philosophy where users aim to keep their inbox empty or near-empty. This is achieved by:
+- Acting on actionable emails immediately
+- Archiving reference emails
+- Deleting noise (newsletters, promotions, notifications)
+- Using labels/folders for organization
+
+### Agent Behavior
+
+**DO NOT** assume the user wants inbox zero unless they explicitly say so.
+
+| User Says | Interpretation |
+|-----------|----------------|
+| "Clean up my inbox" | Remove obvious junk, preserve the rest |
+| "Help me reach inbox zero" | Aggressive triage, archive/delete most |
+| "Triage my emails" | Categorize and recommend actions |
+| "Delete everything old" | User explicitly wants bulk cleanup |
+| "Check my emails" | Summary only, no state changes |
+
+### Default Behavior
+
+Unless the user says "inbox zero" or similar:
+1. **Preserve by default** - Keep emails unless clearly deletable
+2. **Suggest, don't execute** - "These 12 newsletters could be deleted" not "I'll delete these"
+3. **Ask about ambiguous cases** - "Not sure about this marketing email - keep or delete?"
+4. **Respect the user's system** - They may have reasons for keeping old emails
+5. **Never mark as read without asking** - Unread status is user's to-do list
+
+---
+
+## Heavy Inbox Strategy
+
+When a user has a heavy inbox (>20 unread emails), use this optimized workflow:
+
+### 1. Quick Assessment
+
+```bash
+inbox summary --json
+```
+
+Identify which account(s) have the bulk of unread emails.
+
+### 2. Group Analysis First
+
+For heavy inboxes, **always start with grouped analysis**:
+
+```bash
+inbox analyze --count 100 --account <name> --group-by sender
+```
+
+This reveals:
+- Which senders are flooding the inbox
+- Batch cleanup opportunities (all from same sender)
+- High-volume vs. low-volume senders
+
+### 3. Batch Cleanup by Sender
+
+When grouped analysis shows high-volume senders (5+ emails):
+
+| Count | Sender Pattern | Likely Action |
+|-------|----------------|---------------|
+| 10+ | linkedin.com | Job alerts - offer batch delete |
+| 5+ | newsletter@ | Newsletters - offer unsubscribe + delete |
+| 5+ | noreply@ | Notifications - review, likely safe to batch |
+| 3+ | same domain | Check if promotional or transactional |
+
+**Example workflow:**
+```
+## Inbox Analysis: work@company.com (47 unread)
+
+### High-Volume Senders:
+| Sender | Count | Likely Type |
+|--------|-------|-------------|
+| linkedin.com | 12 | Job alerts |
+| github.com | 8 | Notifications |
+| substack.com | 6 | Newsletters |
+
+### Recommendation:
+These 26 emails (55% of inbox) are recurring notifications.
+Delete all LinkedIn job alerts and old newsletters?
+```
+
+### 4. Find Stale Emails
+
+For cleanup of old emails, use server-side filtering:
+
+```bash
+inbox analyze --older-than 30d --group-by sender
+```
+
+Old emails (>30 days) are usually safe to batch delete:
+- Expired promotions
+- Delivered order notifications
+- Old newsletters
+
+### 5. Then Individual Review
+
+After batch cleanup, remaining emails are typically:
+- Direct messages from humans
+- Action items (PRs, meeting requests)
+- Transactional (receipts, confirmations)
+
+These deserve individual attention.
+
+### Decision Tree
+
+```
+Unread count?
+├── ≤5: Quick summary, list all
+├── 6-20: Analyze, offer batch actions for obvious noise
+└── >20:
+    ├── Group by sender FIRST
+    ├── Batch delete obvious noise (LinkedIn, newsletters, promos)
+    └── Then individual review of remaining
+```
+
+---
+
 ## Quick Start
 
 | Task | Command |
@@ -74,6 +201,8 @@ Use when: Heavy inbox (>30 unread), user wants thoroughness, language like "what
 | Check status | `inbox summary --json` |
 | Full triage | `inbox analyze --count 50` → classify → present |
 | Analyze by sender | `inbox analyze --count 50 --group-by sender` |
+| Find old emails | `inbox analyze --older-than 30d` |
+| Extract links from email | `inbox read --id <id> --links` |
 | Delete by ID | `inbox delete --ids "id1,id2" --confirm` |
 | Delete by sender | `inbox delete --sender "linkedin" --dry-run` → confirm → delete |
 | Delete by subject | `inbox delete --match "weekly digest" --dry-run` |
@@ -179,7 +308,12 @@ To stop: `launchctl unload ~/Library/LaunchAgents/com.yourname.inboxd.plist`
 | `inbox analyze --count 50` | Get email data for analysis | JSON array of email objects |
 | `inbox analyze --count 50 --all` | Include read emails | JSON array (read + unread) |
 | `inbox analyze --since 7d` | Only emails from last 7 days | JSON array (filtered by date) |
+| `inbox analyze --older-than 30d` | Only emails older than 30 days | JSON array (server-side filtered) |
 | `inbox analyze --group-by sender` | Group emails by sender domain | `{groups: [{sender, count, emails}], totalCount}` |
+| `inbox read --id <id>` | Read full email content | Email headers + body |
+| `inbox read --id <id> --links` | Extract links from email | List of URLs with optional link text |
+| `inbox read --id <id> --links --json` | Extract links as JSON | `{id, subject, from, linkCount, links}` |
+| `inbox search -q "query"` | Search using Gmail query syntax | JSON array of matching emails |
 | `inbox accounts` | List configured accounts | Account names and emails |
 
 ### Actions
@@ -195,6 +329,7 @@ To stop: `launchctl unload ~/Library/LaunchAgents/com.yourname.inboxd.plist`
 | `inbox restore --last N` | Restore last N deleted emails |
 | `inbox restore --ids "id1,id2"` | Restore specific emails |
 | `inbox mark-read --ids "id1,id2"` | Mark emails as read (remove UNREAD label) |
+| `inbox mark-unread --ids "id1,id2"` | Mark emails as unread (add UNREAD label) |
 | `inbox archive --ids "id1,id2" --confirm` | Archive emails (remove from inbox, keep in All Mail) |
 | `inbox deletion-log` | View recent deletions |
 
@@ -276,8 +411,10 @@ Based on the summary stats, immediately suggest ONE clear next action:
 | One account has >50% of unread | "[account] has X of your Y unread—let me triage that first." |
 | Total unread ≤ 5 | "Only X unread—here's a quick summary:" (show inline) |
 | All accounts have 1-2 unread | "Light inbox day. Quick summary of all emails:" |
+| Total unread > 20 | "Heavy inbox. Let me group by sender to find batch cleanup opportunities." → `--group-by sender` |
 | Total unread > 30 | "Heavy inbox. I'll process by account, starting with [highest]." |
 | Single account with 0 unread | "Inbox zero on [account]! Want me to check the others?" |
+| Grouped analysis shows sender with 5+ emails | "[sender] has X emails. Delete them all?" |
 
 **Example good response:**
 ```
@@ -453,6 +590,8 @@ When user has job-related emails (LinkedIn, Indeed, recruiters) and wants to eva
 | "Delete [sender]'s emails" | Bulk sender cleanup | Two-step pattern with `--sender` filter |
 | "Delete the security emails" | Subject-based cleanup | `--match "security" --dry-run` → confirm → `--ids` |
 | "What senders have the most emails?" | Inbox analysis | `inbox analyze --group-by sender` |
+| "What links are in this email?" | Extract URLs | `inbox read --id <id> --links` |
+| "Find my old emails" / "Clean up old stuff" | Stale email review | `inbox analyze --older-than 30d` |
 | "I keep getting these" | Recurring annoyance | Suggest unsubscribe/filter, then delete batch |
 | "Check [specific account]" | Single-account focus | Skip other accounts entirely |
 | "Undo" / "Restore" | Recover deleted emails | `inbox restore --last N` |
@@ -466,13 +605,29 @@ When user has job-related emails (LinkedIn, Indeed, recruiters) and wants to eva
 > [!CAUTION]
 > These constraints are non-negotiable.
 
+### Deletion Safety
 1. **NEVER auto-delete** - Always confirm before deletion, but adapt confirmation style to batch size
 2. **NEVER delete Action Required emails** - Surface them, let user decide
 3. **NEVER delete without --confirm flag** - Command will hang otherwise
 4. **Always remind about undo** - After every deletion, mention `inbox restore --last N`
-5. **Preserve by default** - When in doubt about classification, keep the email
-6. **Multi-Account Safety** - Always use `--account <name>` for `delete` and `analyze` commands
-7. **Respect user preferences** - If they say "don't list everything", remember and adapt
+
+### State Change Safety
+5. **Confirm before mark-read** - Marking as read can hide important emails. Confirm batch operations (3+ emails)
+6. **Remind about mark-unread undo** - After mark-read, mention: "To undo: `inbox mark-unread --ids \"id1,id2\"`"
+7. **Confirm before archive** - Archiving removes emails from inbox view. Always use `--confirm` flag
+8. **Never batch mark-read silently** - Show what will be marked read before executing
+
+### General Safety
+9. **Preserve by default** - When in doubt about classification, keep the email
+10. **Multi-Account Safety** - Always use `--account <name>` for `delete`, `mark-read`, `mark-unread`, and `archive` commands
+11. **Respect user preferences** - If they say "don't list everything", remember and adapt
+
+### Undo Commands Reference
+| Action | Undo Command |
+|--------|--------------|
+| Deleted emails | `inbox restore --last N` |
+| Marked as read | `inbox mark-unread --ids "id1,id2,..."` |
+| Archived | No CLI undo - must use Gmail web |
 
 ---
 
@@ -560,6 +715,82 @@ Reply with the number or describe which one.
 
 ---
 
+## Interaction Model
+
+> [!IMPORTANT]
+> This section defines how to present multi-step plans to users. Following this model prevents executing without user understanding.
+
+### Plan-Before-Execute Pattern
+
+When a task involves multiple actions, **always present the plan first**:
+
+1. **Announce the plan** - State what you intend to do in numbered steps
+2. **Wait for approval** - Ask "Should I proceed?" or "Ready to start?"
+3. **Execute incrementally** - Complete one step, report, then ask before next step
+4. **Summarize at end** - Show what was done with undo options
+
+### Example: Multi-Step Triage
+
+**Bad (executes without consent):**
+```
+Looking at your inbox...
+[Analyzes 47 emails]
+I've classified your emails. Here's the breakdown:
+- 12 newsletters (marked as read)
+- 8 LinkedIn alerts (deleted)
+- 27 remaining
+
+Done! To undo deletions: inbox restore --last 8
+```
+
+**Good (plan-first approach):**
+```
+Looking at your inbox...
+
+## Triage Plan for work@company.com (47 unread)
+
+I'll process your inbox in these steps:
+1. **Group by sender** - Find batch cleanup opportunities
+2. **Identify deletables** - Newsletters, job alerts, promotions
+3. **Surface action items** - Emails needing your response
+4. **Propose cleanup** - Show what I'd delete, get your OK
+
+Ready to start?
+```
+
+After user says "yes":
+```
+Step 1 complete. Found 3 high-volume senders:
+- linkedin.com (12 emails)
+- substack.com (8 emails)
+- github.com (6 notifications)
+
+Step 2: These 20 emails are cleanup candidates (newsletters + job alerts).
+Want me to list them, or proceed to Step 3 (find action items)?
+```
+
+### Confirmation Thresholds
+
+| Batch Size | Confirmation Approach |
+|------------|----------------------|
+| 1-3 emails | Inline confirmation, can proceed quickly |
+| 4-10 emails | Show summary, ask "Delete these 7?" |
+| 11-25 emails | Show categorized summary, ask "Proceed with cleanup?" |
+| 25+ emails | Present full plan, confirm before any execution |
+
+### State Changes Require Explicit Approval
+
+**Actions that modify email state (always confirm):**
+- `delete` - Always requires confirmation
+- `mark-read` - Confirm if batch (3+), mention undo
+- `archive` - Confirm always, warn about no CLI undo
+- `send` / `reply` - Requires `--confirm` flag
+
+**Read-only actions (no confirmation needed):**
+- `summary`, `analyze`, `search`, `read`, `accounts`
+
+---
+
 ## Feedback Loop
 
 If the user encounters a bug, friction point, or suggests a feature:
@@ -580,6 +811,10 @@ If the user encounters a bug, friction point, or suggests a feature:
 | Skipping pre-flight check | Tool may not be installed | Always run `inbox --version` first |
 | Forgetting `--account` flag | Ambiguity errors with multi-account | Always specify account |
 | Being passive after actions | User has to drive every step | Proactively suggest next step |
+| Executing mark-read on batch without confirmation | User loses unread status on important emails | Confirm 3+ emails, always mention undo |
+| Assuming user wants inbox zero | May delete emails user wanted to keep | Ask first, preserve by default |
+| Executing multi-step plan without presenting it | User doesn't know what happened or why | Use plan-before-execute pattern |
+| Auto-archiving "FYI" emails | User may want them visible in inbox | Archive only on explicit request |
 
 ---
 

package/CLAUDE.md

@@ -23,6 +23,7 @@ src/
 ├── gmail-monitor.js  # Gmail API: fetch, count, trash, restore
 ├── state.js          # Tracks seen emails per account
 ├── deletion-log.js   # Logs deleted emails for restore capability
+├── sent-log.js       # Logs sent emails for audit trail
 ├── notifier.js       # macOS notifications (node-notifier)
 └── skill-installer.js # Copies skill to ~/.claude/skills/
 
@@ -53,6 +54,7 @@ All user data lives in `~/.config/inboxd/`:
 | `token-<name>.json` | OAuth refresh/access tokens |
 | `state-<name>.json` | `{ seenEmailIds, lastCheck, lastNotifiedAt }` |
 | `deletion-log.json` | Audit log for deleted emails |
+| `sent-log.json` | Audit log for sent emails |
 
 ## Code Patterns
 
@@ -78,11 +80,25 @@ All user data lives in `~/.config/inboxd/`:
 
 ## Release Process
 
-1. Bump version in `package.json`
-2. Commit changes
-3. Create a GitHub Release (e.g., `gh release create v1.0.3`)
+**After merging a feature/fix PR to main, always release:**
+
+1. `npm version patch` (or `minor`/`major` as appropriate)
+2. Commit and push: `git add package*.json && git commit -m "chore: bump version to X.X.X" && git push`
+3. Create release with quality notes:
+   ```bash
+   gh release create vX.X.X --title "vX.X.X" --notes "$(cat <<'EOF'
+   ## What's New
+   - Feature 1: description
+   - Feature 2: description
+
+   ## Fixes
+   - Fix 1: description
+   EOF
+   )"
+   ```
 4. The `publish.yml` workflow will automatically test and publish to npm
-   - Note: `src/cli.js` dynamically imports version from `package.json` to ensure consistency
+
+Note: `src/cli.js` dynamically imports version from `package.json` to ensure consistency.
 
 ## AI Agent Integration
 
@@ -141,10 +157,18 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 | `inbox summary --json` | Quick status check (unread counts) |
 | `inbox analyze --count 50` | Get email data as JSON for classification |
 | `inbox analyze --group-by sender` | Group emails by sender domain |
+| `inbox analyze --older-than 30d` | Find emails older than 30 days (server-side filtering) |
 | `inbox delete --ids "id1,id2" --confirm` | Delete specific emails by ID |
 | `inbox delete --sender "pattern" --dry-run` | Preview deletion by sender filter |
 | `inbox delete --match "pattern" --dry-run` | Preview deletion by subject filter |
 | `inbox restore --last N` | Undo last N deletions |
+| `inbox read --id <id>` | Read full email content |
+| `inbox read --id <id> --links` | Extract links from email |
+| `inbox search -q <query>` | Search using Gmail query syntax |
+| `inbox send -t <to> -s <subj> -b <body> --confirm` | Send email (requires --confirm) |
+| `inbox reply --id <id> -b <body> --confirm` | Reply to email (requires --confirm) |
+| `inbox mark-read --ids "id1,id2"` | Mark emails as read |
+| `inbox mark-unread --ids "id1,id2"` | Mark emails as unread (undo mark-read) |
 | `inbox install-skill` | Install/update the Claude Code skill |
 
 ### Smart Filtering Options
@@ -156,6 +180,13 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 | `--force` | Override safety warnings (short patterns, large batches) |
 | `--dry-run` | Preview what would be deleted without deleting |
 
+### Send/Reply Safety
+The `send` and `reply` commands have built-in safety features:
+- **`--dry-run`**: Preview the email without sending
+- **`--confirm`**: Required flag to actually send (prevents accidental sends)
+- **Audit logging**: All sent emails are logged to `~/.config/inboxd/sent-log.json`
+- **Account resolution**: Prompts for account selection when multiple accounts exist
+
 ### Email Object Shape (from `analyze`)
 ```json
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inboxd",
-  "version": "1.0.11",
+  "version": "1.0.13",
   "description": "CLI assistant for Gmail monitoring with multi-account support and AI-ready JSON output",
   "main": "src/cli.js",
   "bin": {