inboxd 1.0.8 → 1.0.10

package/CLAUDE.md

@@ -23,7 +23,11 @@ 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
-└── notifier.js       # macOS notifications (node-notifier)
+├── notifier.js       # macOS notifications (node-notifier)
+└── skill-installer.js # Copies skill to ~/.claude/skills/
+
+scripts/
+└── postinstall.js    # npm postinstall hint about install-skill
 
 tests/                # Vitest tests with mocked Google APIs
 __mocks__/            # Manual mocks for googleapis, @google-cloud/local-auth
@@ -82,10 +86,48 @@ All user data lives in `~/.config/inboxd/`:
 
 ## AI Agent Integration
 
-This package includes a Claude Code skill for AI-powered inbox management.
+This package follows the **Agent-Ready CLI** pattern: a CLI designed for both humans and AI agents.
+
+### The Pattern
+
+Traditional CLIs are for humans. Agent-ready CLIs add:
+1. **Structured output** (`--json`, `analyze`) for agents to parse
+2. **Opinionated commands** with built-in safety (log before delete, undo)
+3. **Skills** that teach agents how to use the tool effectively
+
+### Skill Installation
+
+The skill can be installed globally for all Claude Code sessions:
+
+```bash
+inbox install-skill      # Install to ~/.claude/skills/
+inbox install-skill --uninstall  # Remove
+```
+
+The `inbox setup` wizard also offers to install the skill automatically.
+
+### Skill Location & Update Detection
+
+| Location | Purpose |
+|----------|---------|
+| `.claude/skills/inbox-assistant/SKILL.md` | Source (bundled with package) |
+| `~/.claude/skills/inbox-assistant/SKILL.md` | Installed (global for Claude Code) |
+
+The skill uses content-hash detection (no version field). Updates are detected automatically:
+- On `npm install`: Auto-updates if skill already installed
+- Manual: Run `inbox install-skill` to update
 
-### Skill Location
-`.claude/skills/inbox-assistant/SKILL.md`
+Safety features:
+- `source: inboxd` marker identifies ownership (won't overwrite user's own skills)
+- Creates `SKILL.md.backup` before replacing modified files
+- Use `--force` to override ownership check
+
+### Architecture
+
+```
+src/skill-installer.js    # Handles copying skill to ~/.claude/skills/
+scripts/postinstall.js    # npm postinstall hint about install-skill
+```
 
 ### What the Skill Provides
 - **Triage**: Classify emails (Important, Newsletters, Promotions, Notifications, Low-Priority)
@@ -98,8 +140,21 @@ This package includes a Claude Code skill for AI-powered inbox management.
 |---------|---------|
 | `inbox summary --json` | Quick status check (unread counts) |
 | `inbox analyze --count 50` | Get email data as JSON for classification |
-| `inbox delete --ids "id1,id2" --confirm` | Delete with confirmation flag |
+| `inbox analyze --group-by sender` | Group emails by sender domain |
+| `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 install-skill` | Install/update the Claude Code skill |
+
+### Smart Filtering Options
+| Option | Description |
+|--------|-------------|
+| `--sender <pattern>` | Case-insensitive substring match on From field |
+| `--match <pattern>` | Case-insensitive substring match on Subject field |
+| `--limit <N>` | Max emails for filter operations (default: 50) |
+| `--force` | Override safety warnings (short patterns, large batches) |
+| `--dry-run` | Preview what would be deleted without deleting |
 
 ### Email Object Shape (from `analyze`)
 ```json

package/README.md

@@ -80,10 +80,13 @@ inbox summary
 | `inbox check` | Check for new emails + send notifications |
 | `inbox check -q` | Silent check (for background use) |
 | `inbox delete --ids <ids>` | Move emails to trash |
+| `inbox delete --sender <pattern>` | Delete by sender (with confirmation) |
+| `inbox delete --match <pattern>` | Delete by subject (with confirmation) |
 | `inbox restore --last 1` | Restore last deleted email |
 | `inbox deletion-log` | View deletion history |
 | `inbox logout --all` | Remove all accounts |
 | `inbox install-service` | Install background monitoring (macOS) |
+| `inbox install-skill` | Install Claude Code skill for AI agents |
 
 ## Configuration
 
@@ -143,18 +146,40 @@ inbox analyze --count 20
 
 ## AI Agent Integration
 
-This package includes a Claude Code skill for AI-powered inbox management. The skill provides expert-level email triage, cleanup recommendations, and safe deletion workflows.
+This package is designed to be used by both humans and AI agents. While the CLI works great on its own, it really shines when paired with an AI coding assistant like Claude Code.
 
-### Using with Claude Code
+### The Pattern: Agent-Ready CLI Tools
 
-1. Copy the skill to your Claude Code skills directory:
-   ```bash
-   cp -r node_modules/inboxd/.claude/skills/inbox-assistant ~/.claude/skills/
-   ```
+Traditional CLI tools are designed for humans. But with AI agents becoming capable of using tools, we can make CLIs that work for both:
 
-2. Invoke with `/inbox-assistant` or just ask Claude to manage your inbox.
+1. **Structured output** (`--json`, `analyze`) for agents to parse
+2. **Opinionated commands** with built-in safety (logging before delete, undo capability)
+3. **Skills** that teach agents how to use the tool effectively
 
-### What the Skill Does
+This package includes a **skill** that can be installed globally, enabling any Claude Code session to manage your inbox intelligently.
+
+### Installing the Skill
+
+After installing inboxd, run:
+
+```bash
+inbox install-skill
+```
+
+This copies the inbox-assistant skill to `~/.claude/skills/`, making it available in all your Claude Code sessions.
+
+The setup wizard (`inbox setup`) also offers to install the skill automatically.
+
+### What the Skill Enables
+
+Once installed, you can ask Claude Code things like:
+
+- "Check my emails" → Summary + recommendations
+- "Clean up my inbox" → Identifies deletable emails, confirms before removing
+- "What's important?" → Surfaces action-required emails only
+- "Undo" → Restores recently deleted emails
+
+The skill provides:
 
 | Capability | Description |
 |------------|-------------|
@@ -163,6 +188,20 @@ This package includes a Claude Code skill for AI-powered inbox management. The s
 | **Restore** | Provides undo capability for accidental deletions |
 | **Safety** | Never auto-deletes, enforces batch limits, always shows before deleting |
 
+### Updating the Skill
+
+The skill auto-updates when you update inboxd (if already installed). You can also update manually:
+
+```bash
+npm update -g inboxd
+inbox install-skill
+```
+
+Safety features:
+- Won't overwrite skills not created by inboxd (uses `source: inboxd` marker)
+- Creates `SKILL.md.backup` before replacing if you've modified the skill
+- Use `inbox install-skill --force` to override ownership check
+
 ### CLI vs MCP
 
 Unlike an MCP server that exposes raw Gmail API primitives, `inboxd` provides **opinionated commands** with built-in safety:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "inboxd",
-  "version": "1.0.8",
+  "version": "1.0.10",
   "description": "CLI assistant for Gmail monitoring with multi-account support and AI-ready JSON output",
   "main": "src/cli.js",
   "bin": {
@@ -21,7 +21,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "lint": "eslint src tests",
-    "inbox": "node src/cli.js"
+    "inbox": "node src/cli.js",
+    "postinstall": "node scripts/postinstall.js || true"
   },
   "keywords": [
     "gmail",

package/scripts/postinstall.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script - shows helpful hints after npm install
+ * and auto-updates skill if already installed
+ */
+
+// Skip during CI or if quiet mode
+if (process.env.CI || process.env.npm_config_loglevel === 'silent') {
+  process.exit(0);
+}
+
+const { getSkillStatus, checkForUpdate, installSkill } = require('../src/skill-installer');
+
+/**
+ * Show the install hint message for new users
+ */
+function showInstallHint() {
+  const message = `
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│  inboxd installed successfully!                             │
+│                                                             │
+│  Quick start:                                               │
+│    inbox setup              # First-time configuration      │
+│                                                             │
+│  AI Agent Integration:                                      │
+│    inbox install-skill      # Enable Claude Code skill      │
+│                                                             │
+│  This lets AI agents manage your inbox with expert triage.  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+`;
+  console.log(message);
+}
+
+/**
+ * Handle skill auto-update logic
+ */
+function handleSkillUpdate() {
+  try {
+    const status = getSkillStatus();
+
+    if (!status.installed) {
+      // Not installed → show manual install hint
+      showInstallHint();
+      return;
+    }
+
+    if (!status.isOurs) {
+      // Someone else's skill with same name → don't touch, warn
+      console.log(`\n⚠️  ~/.claude/skills/inbox-assistant exists but isn't from inboxd`);
+      console.log(`   The existing skill has source: "${status.source || 'none'}"`);
+      console.log(`   Run 'inbox install-skill --force' to replace it\n`);
+      return;
+    }
+
+    // It's ours → check for updates
+    const update = checkForUpdate();
+
+    if (update.updateAvailable) {
+      const result = installSkill();
+
+      if (result.success) {
+        if (result.backedUp) {
+          console.log(`\n✓ inbox-assistant skill updated`);
+          console.log(`  Your previous version was saved to: SKILL.md.backup\n`);
+        } else {
+          console.log(`\n✓ inbox-assistant skill updated\n`);
+        }
+      } else if (result.reason === 'backup_failed') {
+        console.log(`\n⚠️  Could not backup existing skill - update skipped`);
+        console.log(`   Run 'inbox install-skill' manually to update\n`);
+      }
+    }
+    // Up-to-date → silent (no message)
+  } catch (err) {
+    // Fail silently - postinstall should not break npm install
+    // User can always run 'inbox install-skill' manually
+  }
+}
+
+// Run the update logic
+handleSkillUpdate();