inboxd 1.0.12 → 1.1.0

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,42 @@ 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:
@@ -242,22 +281,22 @@ This will guide you through:
 
 ### Optional: Automatic Background Monitoring
 
-Users can enable automatic inbox checking with macOS notifications:
+Users can enable automatic inbox checking with notifications:
 
 ```bash
 inbox install-service              # Check every 5 minutes
 inbox install-service --interval 10  # Check every 10 minutes
+inbox install-service --uninstall    # Remove service
 ```
 
 This installs and starts a background service that:
 - Checks for new emails automatically
-- Sends macOS notifications when new emails arrive
+- Sends desktop notifications when new emails arrive
 - Starts on login
 
-To stop: `launchctl unload ~/Library/LaunchAgents/com.yourname.inboxd.plist`
+**macOS:** Uses launchd. To stop: `launchctl unload ~/Library/LaunchAgents/com.danielparedes.inboxd.plist`
 
-> [!NOTE]
-> This is macOS-only. Linux users can set up a cron job instead.
+**Linux:** Uses systemd. To stop: `systemctl --user stop inboxd.timer`
 
 ## Command Reference
 
@@ -290,8 +329,18 @@ 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 unarchive --last N` | Undo last N archived emails |
+| `inbox unarchive --ids "id1,id2"` | Unarchive specific emails |
+| `inbox stats` | Show email activity dashboard (deletions, sent counts) |
+| `inbox stats --days 7 --json` | Get stats as JSON for custom period |
+| `inbox cleanup-suggest` | Get smart cleanup suggestions based on deletion patterns |
 | `inbox deletion-log` | View recent deletions |
+| `inbox deletion-log --json` | Get deletion log as JSON |
+| `inbox accounts --json` | List accounts as JSON |
+| `inbox delete --dry-run --json` | Preview deletion as structured JSON |
+| `inbox restore --json` | Get restore results as JSON |
 
 ### Smart Filtering Options
 
@@ -550,6 +599,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` |
+| "Show my email stats" | Activity summary | `inbox stats` |
+| "What should I clean up?" | Pattern analysis | `inbox cleanup-suggest` |
 | "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 |
@@ -565,13 +616,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 | `inbox unarchive --last N` |
 
 ---
 
@@ -659,6 +726,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:
@@ -679,6 +822,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

@@ -11,7 +11,7 @@ inbox setup                 # First-time setup wizard
 inbox auth -a <name>        # Add account
 inbox summary               # Check all inboxes
 inbox check -q              # Background check
-inbox install-service       # Install launchd service (macOS only)
+inbox install-service       # Install background service (macOS/Linux)
 ```
 
 ## Architecture
@@ -20,9 +20,10 @@ inbox install-service       # Install launchd service (macOS only)
 src/
 ├── cli.js            # Entry point, command definitions (commander)
 ├── gmail-auth.js     # OAuth2 flow, token storage, multi-account management
-├── gmail-monitor.js  # Gmail API: fetch, count, trash, restore
+├── gmail-monitor.js  # Gmail API: fetch, count, trash, restore, archive
 ├── state.js          # Tracks seen emails per account
 ├── deletion-log.js   # Logs deleted emails for restore capability
+├── archive-log.js    # Logs archived emails for unarchive capability
 ├── sent-log.js       # Logs sent emails for audit trail
 ├── notifier.js       # macOS notifications (node-notifier)
 └── skill-installer.js # Copies skill to ~/.claude/skills/
@@ -54,6 +55,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 |
+| `archive-log.json` | Audit log for archived emails |
 | `sent-log.json` | Audit log for sent emails |
 
 ## Code Patterns
@@ -70,7 +72,10 @@ All user data lives in `~/.config/inboxd/`:
 - `inbox check` marks emails as seen after notifying
 - `inbox delete` logs to `deletion-log.json` before trashing
 - `inbox restore` moves from Trash to Inbox, removes log entry
-- `install-service` creates and automatically enables launchd service (macOS only, warns on other platforms)
+- `inbox archive` logs to `archive-log.json` before archiving
+- `inbox unarchive` moves archived emails back to Inbox, removes log entry
+- `inbox send/reply` prompts for interactive confirmation (or use `--confirm` to skip)
+- `install-service` creates and enables launchd (macOS) or systemd (Linux) service
 
 ## OAuth Notes
 
@@ -80,11 +85,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
 
@@ -153,7 +172,18 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 | `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 archive --ids "id1,id2" --confirm` | Archive emails (remove from inbox) |
+| `inbox unarchive --last N` | Undo last N archives |
+| `inbox stats` | Show email activity dashboard (deletions, sent) |
+| `inbox stats --json` | Get stats as JSON |
+| `inbox cleanup-suggest` | Get smart cleanup suggestions based on patterns |
+| `inbox accounts --json` | List accounts as JSON |
+| `inbox deletion-log --json` | Get deletion log as JSON |
+| `inbox delete --dry-run --json` | Preview deletion as JSON |
 | `inbox install-skill` | Install/update the Claude Code skill |
+| `inbox install-service --uninstall` | Remove background service |
 
 ### Smart Filtering Options
 | Option | Description |
@@ -166,8 +196,9 @@ scripts/postinstall.js    # npm postinstall hint about install-skill
 
 ### Send/Reply Safety
 The `send` and `reply` commands have built-in safety features:
+- **Interactive confirmation**: Prompts "Send this email? (y/N)" when no flags provided
 - **`--dry-run`**: Preview the email without sending
-- **`--confirm`**: Required flag to actually send (prevents accidental sends)
+- **`--confirm`**: Skip the interactive prompt (for automation/scripts)
 - **Audit logging**: All sent emails are logged to `~/.config/inboxd/sent-log.json`
 - **Account resolution**: Prompts for account selection when multiple accounts exist
 

package/package.json

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

package/src/archive-log.js

@@ -0,0 +1,104 @@
+const fs = require('fs');
+const path = require('path');
+const { TOKEN_DIR } = require('./gmail-auth');
+const { atomicWriteJsonSync } = require('./utils');
+
+const LOG_DIR = TOKEN_DIR;
+const LOG_FILE = path.join(LOG_DIR, 'archive-log.json');
+
+/**
+ * Ensures the log directory exists
+ */
+function ensureLogDir() {
+  if (!fs.existsSync(LOG_DIR)) {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * Reads the current archive log
+ * @returns {Array} Array of archive entries
+ */
+function readArchiveLog() {
+  ensureLogDir();
+  if (!fs.existsSync(LOG_FILE)) {
+    return [];
+  }
+  try {
+    const content = fs.readFileSync(LOG_FILE, 'utf8');
+    return JSON.parse(content);
+  } catch (_err) {
+    return [];
+  }
+}
+
+/**
+ * Logs archived emails to the archive log
+ * @param {Array} emails - Array of email objects with id, threadId, account, from, subject, snippet
+ */
+function logArchives(emails) {
+  ensureLogDir();
+  const log = readArchiveLog();
+  const timestamp = new Date().toISOString();
+
+  for (const email of emails) {
+    log.push({
+      archivedAt: timestamp,
+      account: email.account,
+      id: email.id,
+      threadId: email.threadId,
+      from: email.from,
+      subject: email.subject,
+      snippet: email.snippet,
+    });
+  }
+
+  atomicWriteJsonSync(LOG_FILE, log);
+}
+
+/**
+ * Gets recent archives from the log
+ * @param {number} days - Number of days to look back (default: 30)
+ * @returns {Array} Array of archive entries within the time range
+ */
+function getRecentArchives(days = 30) {
+  const log = readArchiveLog();
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - days);
+
+  return log.filter((entry) => {
+    const archivedAt = new Date(entry.archivedAt);
+    return archivedAt >= cutoff;
+  });
+}
+
+/**
+ * Gets the path to the log file (for display purposes)
+ * @returns {string} The log file path
+ */
+function getArchiveLogPath() {
+  return LOG_FILE;
+}
+
+/**
+ * Removes entries from the archive log (e.g., after unarchiving)
+ * @param {Array<string>} ids - Array of message IDs to remove
+ */
+function removeArchiveLogEntries(ids) {
+  ensureLogDir();
+  const log = readArchiveLog();
+
+  const newLog = log.filter(entry => !ids.includes(entry.id));
+
+  if (log.length !== newLog.length) {
+    atomicWriteJsonSync(LOG_FILE, newLog);
+  }
+}
+
+module.exports = {
+  logArchives,
+  getRecentArchives,
+  getArchiveLogPath,
+  readArchiveLog,
+  removeArchiveLogEntries,
+};