docs: Expand pigeon (pmail) details in README and AGENTS

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -7,7 +7,8 @@ This is **claude-mods** - a collection of custom extensions for Claude Code:
 - **3 commands** for session management (/sync, /save) and experimental features (/canvas)
 - **67 skills** for CLI tools, patterns, workflows, and development tasks
 - **5 output styles** for response personality (Vesper, Spartan, Mentor, Executive, Pair)
-- **4 hooks** for pre-commit linting, post-edit formatting, dangerous command warnings, and inter-session mail
+- **4 hooks** for pre-commit linting, post-edit formatting, dangerous command warnings, and pmail notifications
+- **Pigeon** inter-session messaging (`pigeon send/read/reply`) - SQLite-backed pmail at `~/.claude/pmail.db`
 
 ## Installation
 
@@ -32,7 +33,7 @@ cd claude-mods && ./scripts/install.sh  # or .\scripts\install.ps1 on Windows
 | `commands/` | Slash command definitions |
 | `skills/` | Skill definitions with SKILL.md |
 | `output-styles/` | Response personalities (vesper, spartan, mentor, executive, pair) |
-| `hooks/` | Working hook scripts (lint, format, safety) |
+| `hooks/` | Working hook scripts (lint, format, safety, pmail) |
 | `rules/` | Claude Code rules (5 files: cli-tools, thinking, commit-style, naming-conventions, skill-agent-updates) |
 | `tools/` | Modern CLI toolkit documentation |
 | `tests/` | Validation scripts + justfile |
@@ -55,6 +56,7 @@ On "INIT:" message at session start:
 | `docs/WORKFLOWS.md` | 10 workflow patterns from Anthropic best practices |
 | `skills/tool-discovery/` | Find the right library for any task |
 | `hooks/README.md` | Pre/post execution hook examples |
+| `skills/pigeon/` | Inter-session pmail - send, read, reply, broadcast, search across projects |
 
 ## Quick Reference
 
@@ -68,6 +70,8 @@ On "INIT:" message at session start:
 
 **Session Cache:** v3.1 schema stores full task objects, session ID (for `--resume`), PR linkage (for `--from-pr`), and writes a summary to native MEMORY.md. Backwards compatible with v3.0.
 
+**Pigeon (pmail):** `pigeon send <project> "subject" "body"` | `pigeon read` | `pigeon reply <id> "body"` | `pigeon status` | `pigeon broadcast "subject" "body"`. Attach files with `--attach <path>`. Disable per-project: `touch .claude/pigeon.disable`. DB at `~/.claude/pmail.db`, scripts at `~/.claude/pigeon/`.
+
 ## Performance
 
 **MCP Tool Search:** When using multiple MCP servers, enable tool search to save context:

README.md

@@ -26,7 +26,7 @@ From Python async patterns to Rust ownership models, from AWS Fargate deployment
 - 🎨 **`genart-ops` skill** - Comprehensive generative art skill (1,843 lines) covering three.js scene scaffolding, p5.js sketch structure, SVG generation, GLSL shaders (noise, SDF, ray marching, IQ palettes), procedural algorithms (flow fields, Poisson disk, L-systems, WFC, Voronoi), and OKLAB/OKLCH colour theory
 - 📐 **Agent Skills spec compliance** - All 67 skills migrated to the [Agent Skills specification](https://agentskills.io/specification). Non-standard frontmatter fields moved into `metadata:` block, `license: MIT` and `metadata.author: claude-mods` on every skill. Verified 67/67 pass.
 - 📚 **Docs updated** - `SKILL-SUBAGENT-REFERENCE.md` rewritten with spec as standard, `naming-conventions.md` updated with spec-compliant frontmatter examples, `AGENT-SKILLS-COMPLIANCE-BRIEF.md` added to docs/
-- 📬 **`pigeon` skill** - Inter-session pmail between Claude Code sessions across projects. SQLite-backed messaging at `~/.claude/pmail.db` with hook-based notification. Integrated into `/sync` for session-start mail check.
+- 📬 **`pigeon` skill** - Inter-session pmail between Claude Code sessions across projects. SQLite-backed at `~/.claude/pmail.db` with git-rooted project identity (survives renames/moves/clones), threading, file attachments, broadcast, search, and signal-file-driven hook notifications. Integrated into `/sync` for session-start mail check. Per-project disable via `.claude/pigeon.disable`. Renamed from `agentmail` to avoid collision with [AgentMail](https://www.agentmail.to) (YC S25).
 
 **v2.3.0** (March 2026)
 - 🎯 **Orchestrator-dispatch pattern** - Three skills upgraded from static reference dumps to active orchestrators that classify intent, dispatch to agents, and manage safety tiers:
@@ -257,7 +257,7 @@ See [skill-creator](skills/skill-creator/) for the complete guide.
 | [python-env](skills/python-env/) | Fast Python environment management with uv |
 | [task-runner](skills/task-runner/) | Run project commands with just |
 | [screenshot](skills/screenshot/) | Find and display recent screenshots from common screenshot directories |
-| [pigeon](skills/pigeon/) | Inter-session pmail - SQLite-backed messaging between Claude Code sessions across projects |
+| [pigeon](skills/pigeon/) | Inter-session pmail - send/receive messages between Claude Code sessions across projects. SQLite-backed (`~/.claude/pmail.db`), git-rooted project identity, threading, attachments, broadcast, search. Hook-driven notifications. Per-project disable. |
 
 #### Development Skills
 | Skill | Description |
@@ -283,7 +283,7 @@ See [skill-creator](skills/skill-creator/) for the complete guide.
 | [pre-commit-lint.sh](hooks/pre-commit-lint.sh) | PreToolUse | Auto-lint staged files before commit (JS/TS, Python, Go, Rust, PHP) |
 | [post-edit-format.sh](hooks/post-edit-format.sh) | PostToolUse | Auto-format files after Write/Edit (Prettier, Ruff, gofmt, rustfmt) |
 | [dangerous-cmd-warn.sh](hooks/dangerous-cmd-warn.sh) | PreToolUse | Block destructive commands (force push, rm -rf, DROP TABLE) |
-| [check-mail.sh](hooks/check-mail.sh) | PreToolUse | Check for unread inter-session mail (10s cooldown, silent when empty) |
+| [check-mail.sh](hooks/check-mail.sh) | PreToolUse | Check for unread pmail via signal file (no cooldown, zero-cost when empty) |
 
 ### Output Styles