inboxd 1.0.8 → 1.0.9

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,43 @@ 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
+```
 
-### Skill Location
-`.claude/skills/inbox-assistant/SKILL.md`
+The `inbox setup` wizard also offers to install the skill automatically.
+
+### Skill Location & Versioning
+
+| 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 has a `version` field in its front matter. When updating:
+1. Bump version in `SKILL.md`
+2. Users run `inbox install-skill` to get the update
+
+### 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)
@@ -100,6 +137,7 @@ This package includes a Claude Code skill for AI-powered inbox management.
 | `inbox analyze --count 50` | Get email data as JSON for classification |
 | `inbox delete --ids "id1,id2" --confirm` | Delete with confirmation flag |
 | `inbox restore --last N` | Undo last N deletions |
+| `inbox install-skill` | Install/update the Claude Code skill |
 
 ### Email Object Shape (from `analyze`)
 ```json

package/README.md

@@ -84,6 +84,7 @@ inbox summary
 | `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 +144,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 +186,15 @@ 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
+
+When you update inboxd, run `inbox install-skill` again to get the latest skill version:
+
+```bash
+npm update -g inboxd
+inbox install-skill
+```
+
 ### 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.9",
   "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,79 @@
+#!/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 (previous saved to SKILL.md.backup)\n`);
+        } else {
+          console.log(`\n✓ inbox-assistant skill updated\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();