Review and update README documentation

CLAUDE.md

@@ -54,9 +54,9 @@ Once Go source files are added:
 
 ## Testing in CI Environment
 
-To run tests in a container matching CI (Go 1.21, Linux):
+To run tests in a container matching CI (Go 1.25, Linux):
 ```bash
-docker run --rm -v $(pwd):/app -w /app golang:1.21 go test -v -race ./...
+docker run --rm -v $(pwd):/app -w /app golang:1.25 go test -v -race ./...
 ```
 
 This helps catch issues that only manifest in the CI environment (e.g., running as root, different Go version).

README.md

@@ -22,7 +22,7 @@ A Go CLI tool for inter-agent communication within tmux sessions. Agents running
 
 ## Requirements
 
-- Go 1.23 or later
+- Go 1.25 or later
 - tmux (must be running inside a tmux session)
 - Linux or macOS
 
@@ -222,7 +222,8 @@ agentmail mailman [--daemon]
 - `--daemon` - Run in background (daemonize)
 
 **Behavior:**
-- Monitors all mailboxes every 10 seconds
+- Uses file watching (fsnotify) for instant notification on mailbox changes
+- Includes 60-second safety timer that runs alongside watching
 - Sends notifications to agents with `ready` status that have unread mail
 - Notifications sent via tmux: `tmux send-keys -t <window> "Check your agentmail"`
 - Stores PID in `.agentmail/mailman.pid`
@@ -239,6 +240,7 @@ agentmail mailman --daemon
 
 **Exit codes:**
 - `0` - Daemon started/stopped successfully
+- `1` - Error (failed to start, PID file error, etc.)
 - `2` - Daemon already running
 
 ### onboard
@@ -417,8 +419,9 @@ The plugin configures hooks that automatically:
 | Event | Action | Status |
 |-------|--------|--------|
 | **SessionStart** | Sets status to ready, runs onboarding | `ready` |
-| **SessionEnd** | Sets status to offline | `offline` |
+| **UserPromptSubmit** | Sets status to work (agent is busy) | `work` |
 | **Stop** (end of turn) | Sets status to ready, checks for messages | `ready` |
+| **SessionEnd** | Sets status to offline | `offline` |
 
 ### Plugin Commands
 
@@ -531,11 +534,13 @@ The mailman daemon provides proactive notifications for agents:
 ┌─────────────────────────────────────────────────────────────┐
 │                     Mailman Daemon                          │
 │                                                             │
-│  1. Read recipient states from .agentmail/recipients.jsonl │
-│  2. For each "ready" agent:                                 │
-│     - Check if unread messages exist                        │
-│     - If yes and not already notified: send notification    │
-│  3. Sleep 10 seconds, repeat                                │
+│  1. Watch .agentmail/ for file changes (fsnotify)          │
+│  2. On change (debounced 500ms) or 60s fallback timer:     │
+│     - Read recipient states from recipients.jsonl          │
+│     - For each "ready" agent with unread messages:         │
+│       - If not already notified: send notification         │
+│  3. Also notifies stateless agents (no recipient state)    │
+│     every 60 seconds if they have unread messages          │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -585,10 +590,10 @@ go vet ./...
 
 ### Testing in CI Environment
 
-To match the CI environment (Go 1.23, Linux):
+To match the CI environment (Go 1.25, Linux):
 
 ```bash
-docker run --rm -v $(pwd):/app -w /app golang:1.23 go test -v -race ./...
+docker run --rm -v $(pwd):/app -w /app golang:1.25 go test -v -race ./...
 ```
 
 ## Project Structure

claude-plugin/commands/status.md

@@ -13,6 +13,6 @@ If argument is missing, ask the user which status to set:
 - `work` - Busy working (notifications suppressed)
 - `offline` - Offline (notifications suppressed)
 
-Run `agentmail status <status>` to update. Status is stored in `.git/mail-recipients.jsonl` and used by the mailman daemon.
+Run `agentmail status <status>` to update. Status is stored in `.agentmail/recipients.jsonl` and used by the mailman daemon.
 
 Note: The plugin automatically manages status via hooks (SessionStart→ready, SessionEnd→offline, Stop→ready).

claude-plugin/skills/agentmail/SKILL.md

@@ -12,13 +12,13 @@ AgentMail enables communication between AI agents running in different tmux wind
 
 ## Overview
 
-AgentMail is a CLI tool for inter-agent communication within tmux sessions. Messages are stored in `.git/mail/` as JSONL files, providing persistent, file-locked message queues for each agent.
+AgentMail is a CLI tool for inter-agent communication within tmux sessions. Messages are stored in `.agentmail/mailboxes/` as JSONL files, providing persistent, file-locked message queues for each agent.
 
 ## Prerequisites
 
 - Must be running inside a tmux session
 - AgentMail CLI must be installed and available in PATH
-- Must be in a git repository (messages stored in `.git/mail/`)
+- Messages stored in `.agentmail/` directory
 
 ## Core Commands
 
@@ -88,10 +88,9 @@ The plugin automatically manages your status:
 ## Message Format
 
 Messages include:
-- **ID**: Unique 6-character hex identifier
+- **ID**: Unique 8-character base62 identifier (a-z, A-Z, 0-9)
 - **From**: Sender's tmux window name
 - **To**: Recipient's tmux window name
-- **Timestamp**: ISO 8601 format
 - **Content**: Message body
 
 ## Best Practices

cmd/agentmail/main.go

@@ -151,7 +151,7 @@ Valid statuses:
   work     Agent is busy working (resets notification flag)
   offline  Agent is offline (resets notification flag)
 
-The status is stored in .git/mail-recipients.jsonl and used by the
+The status is stored in .agentmail/recipients.jsonl and used by the
 mailman daemon for notification decisions.
 
 When transitioning to 'work' or 'offline', the notified flag is reset
@@ -291,7 +291,7 @@ Examples:
 	rootHelp := `agentmail - Inter-agent communication for tmux sessions
 
 Agents running in different tmux windows can send and receive messages
-through a simple file-based mail system stored in .git/mail/.
+through a simple file-based mail system stored in .agentmail/.
 
 Commands:
   send        Send a message to a tmux window