herdr-plugin-amq 0.1.8 → 0.1.9

package/README.md

@@ -3,305 +3,72 @@
 [![npm version](https://img.shields.io/npm/v/herdr-plugin-amq.svg)](https://www.npmjs.com/package/herdr-plugin-amq)
 [![CI](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml/badge.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/ci.yml)
 [![Security](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/security.yml/badge.svg)](https://github.com/cabra-lat/herdr-plugin-amq/actions/workflows/security.yml)
-[![Tests](https://img.shields.io/badge/tests-95%20passing-brightgreen.svg)](https://github.com/cabra-lat/herdr-plugin-amq)
-[![Coverage](https://img.shields.io/badge/coverage-80%25-brightgreen.svg)](https://github.com/cabra-lat/herdr-plugin-amq)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Proudly Vibe Coded - Plasma Mix](https://vibecoded.fyi/badges/flat/main/proudly-vibe-coded-plasma-mix.svg)](https://vibecoded.fyi/)
 
-> **The asynchronous nervous system for autonomous AI agent swarms in [Herdr](https://herdr.dev/).**  
-> Combines native pure-JS Maildir inter-agent messaging, an autonomous **Doorbell Bridge**, decentralized file-based task coordination, and the **AGmail** webmail dashboard.
+> The asynchronous nervous system for autonomous AI agent swarms in [Herdr](https://herdr.dev/).
 
----
+Herdr AMQ combines native pure-JS Maildir messaging, lifecycle-aware doorbells, a decentralized task bus, immutable CAS evidence, and the local-first **AGmail** dashboard.
 
-## The Origin & The Problem
+## Why it exists
 
-> *"If you follow AI news, you have probably seen endless hype around 'multi-agent swarms' talking to each other... That is cute for a 30-second screen recording. In a real codebase with actual physics, compiler errors, and Git history, it is a complete disaster."*  
-> — Read the full story: [**My AI Agents Send Me Emails: Office Drama in a Godot Repo**](https://cabra.pw/my-ai-agents-send-me-emails.html)
+LLM agents are turn-based: when an agent finishes a response or tool sequence, it goes idle. A persistent inbox is useful, but it needs a doorbell. Herdr AMQ watches agent panes, wakes only idle or done agents with unread mail or assigned backlog work, and leaves working panes alone.
 
-When coordinating swarms of AI coding agents across complex codebases, synchronous chat rooms and blocking `wait` loops fall apart:
-1. **Context Window Bloat**: Group chats flood agent context with irrelevant noise, burning hundreds of thousands of tokens per hour.
-2. **Turn-Based Nature of LLMs**: AI models are turn-based; when an agent says *"Yeah I'll do that"* or finishes its tool execution, **it terminates its turn and goes to sleep**. It cannot run a busy-wait loop.
-3. **Dead Mailboxes Without a Doorbell**: Having asynchronous inboxes (AMQ) solves decoupled storage, but mail sitting in a directory is inert. If an agent is asleep, incoming messages sit unread forever.
+The result is an asynchronous workflow:
 
-### The Missing Piece: The Doorbell Bridge
+1. A coordinator or human sends a message or creates a task.
+2. The bridge detects the unread item and checks the Herdr pane state.
+3. An idle agent receives a precise drain/claim prompt.
+4. The agent works in its isolated worktree and replies on the original thread.
+5. AGmail provides a human view of messages, activity, tasks, and evidence.
 
-This plugin bridges **AMQ** (the persistent storage) and **Herdr** (the terminal multiplexer and agent lifecycle supervisor).
+## Documentation map
 
-The **Bridge Daemon** continuously inspects agent inboxes. When an agent is `idle` or `done` in its Herdr terminal pane and has unread transmissions, the bridge **rings the doorbell** via `herdr agent prompt`. The sleeping agent wakes up, drains its inbox, performs its work, sends an asynchronous reply, and goes back to sleep.
+- [Architecture and live model reporting](docs/architecture.md)
+- [Installation and Herdr setup](docs/installation.md)
+- [CLI, fleet lifecycle, and templates](docs/cli-and-workflows.md)
+- [Security and testing](docs/security-and-testing.md)
+- [AGmail visual tour](docs/ui-screenshots.md)
 
-```mermaid
-flowchart TD
-    subgraph Storage ["Persistent Transport Layer"]
-        AMQ[".agent-mail/ (Maildir + RFC 5322)<br/>Decoupled Markdown Transmissions"]
-        BUS[".agent-mail/bus/ (Decentralized Task Cards)<br/>backlog/ → doing/ → blocked/ → done/"]
-        CAS[".agent-mail/blobs/ (CAS Blobstore)<br/>SHA-256 Render Strips & Proofs"]
-    end
-
-    subgraph Bridge ["The Autonomous Nervous System"]
-        DAEMON["Bridge Daemon (herdr-amq bridge-daemon)<br/>Watches mailboxes & checks Herdr agent states"]
-        DOORBELL{"Agent Status in Herdr?"}
-    end
-
-    subgraph Execution ["Herdr PTY / Terminal Swarm"]
-        H_BUSY["working → Leave alone (no spam)"]
-        H_BLOCKED["blocked → Alert coordinator / human"]
-        H_IDLE["idle / done → RING DOORBELL<br/>(herdr agent prompt)"]
-        AGENT["Awakened Agent<br/>1. herdr-amq drain --me <handle><br/>2. Executes task in isolated worktree<br/>3. herdr-amq send / reply --id ...<br/>4. Goes back to sleep"]
-    end
-
-    subgraph Oversight ["Human-in-the-Loop & Mission Control"]
-        AGMAIL["AGmail Webmail & Kanban Dashboard<br/>http://127.0.0.1:8505 (Strictly Local)"]
-    end
-
-    AMQ -->|New mail arrives| DAEMON
-    DAEMON --> DOORBELL
-    DOORBELL -->|working| H_BUSY
-    DOORBELL -->|blocked| H_BLOCKED
-    DOORBELL -->|idle/done| H_IDLE
-    H_IDLE --> AGENT
-    AGENT -->|Sends mail + CAS attachments| AMQ
-    AGENT -->|Claims / updates tasks| BUS
-    AGENT -->|Pins render artifacts| CAS
-    AMQ -.->|Monitored & inspected by| AGMAIL
-    BUS -.->|Rendered live in Kanban| AGMAIL
-```
-
----
-
-## Key Features
-
-### 1. The Autonomous Doorbell Bridge
-- **Lifecycle-Aware Wakeups**: Rings doorbells (`herdr agent prompt`) only when agents are `idle` or `done`, preventing command interleaving during active turns.
-- **Dual-Queue Wakeups (Mail & Tasks)**: Evaluates both unread Maildir messages and pending backlog tasks assigned to idle agents, prompting agents with specific drainage and claim actions.
-- **De-duplication**: Tracks delivered message and task IDs in persistent state (`bridge-state.json`) so agents are never doorbelled twice for the same event.
-- **Self-Healing Panes**: Automatically detects and renames desynced terminal titles back to their canonical agent handles (`herdr agent rename`).
-- **Blocked State Alerts**: When an agent with unread mail is blocked on external input, logs actionable alert directives for human intervention.
-
-### 2. Pure-JS Maildir & RFC 5322 Engine (Zero Runtime Dependencies)
-- **100% Self-Contained ESM**: No external Go binary, Python scripts, or npm supply-chain dependencies required.
-- **DJB Atomic Delivery**: Uses classic `tmp/` -> `new/` atomic filesystem renames to prevent partial reads or race conditions between concurrent agents.
-- **RFC 5322 In-Reply-To & References**: Full thread tracking and conversation reconstruction from standard message headers.
-
-### 3. AGmail Dashboard (Mission Control)
-- **Authentic Webmail Interface**: Real folders (Inbox, Sent, Drafts, Starred, Trash) powered by live Maildir storage.
-- **Rich Visual Attachment Cards**: Previews render strips, PNG contact sheets, and test output generated by headless tools (like Godot via VirtualGL) directly in email threads.
-- **Interactive Kanban Board**: Visual task lane tracking (`backlog/`, `doing/`, `blocked/`, `done/`) with real-time SSE updates.
-- **Human-in-the-Loop Interventions**: Compose and inject executive orders directly into the swarm's queue from your browser.
-- **Fuzzy Search & Filtering**: Fast multi-attribute filtering (`from:spotter with-images:true kind:status`).
-
-### 4. Git Worktree Isolation & Task Bus
-- **Multi-Lane Isolation**: Automatically provisions and manages dedicated Git worktrees (`.worktrees/<agent>`) so parallel agents never step on each other's unstaged files.
-- **Decentralized File-Based Task Cards**: Directory-based task bus (`.agent-mail/bus/`) immune to concurrent merge conflicts.
-
----
-
-## Requirements
-
-- **Node.js** >= 18
-- **[Herdr](https://herdr.dev/)** >= 0.7.0 *(Terminal workspace manager & agent lifecycle supervisor)*
-- **Zero npm runtime dependencies**
-
----
-
-## Installation & Linking
-
-Link the plugin into your local Herdr configuration:
+## Quick start
 
 ```bash
-# Clone or navigate to the repository
-cd herdr-plugin-amq
-
-# Link into Herdr
+npm ci --ignore-scripts
 herdr plugin link .
-```
-
-Verify that the plugin and its actions are active:
-
-```bash
-herdr plugin list
-herdr plugin action list --plugin cabra.amq
-```
-
----
-
-## Herdr Actions & Keybindings
-
-Add keybindings to `~/.config/herdr/config.toml` for instant access:
-
-```toml
-[[keys.command]]
-key = "prefix+m"
-type = "plugin_action"
-command = "cabra.amq.bridge-status"
-description = "Check AMQ mailbox status"
-
-[[keys.command]]
-key = "prefix+M"
-type = "plugin_action"
-command = "cabra.amq.doorbell-check"
-description = "Ring AMQ doorbells for idle agents"
-```
-
-### Available Plugin Actions
-
-```bash
-# Check queue status, active daemon, and unread mail per agent
-herdr plugin action invoke cabra.amq.bridge-status
-
-# Start background bridge daemon
-herdr plugin action invoke cabra.amq.bridge-start
-
-# Stop background bridge daemon
-herdr plugin action invoke cabra.amq.bridge-stop
-
-# Trigger an immediate one-shot doorbell check
-herdr plugin action invoke cabra.amq.doorbell-check
-
-# Launch the AGmail webmail dashboard
-herdr plugin action invoke cabra.amq.open-dashboard
-
-# Migrate legacy message attachments into immutable CAS blobs or pinned Git commits
-herdr plugin action invoke cabra.amq.migrate
-```
-
-### Herdr Terminal Panes
-
-Open modal terminal panes inside Herdr:
-
-```bash
-# Fast terminal inbox peek popup
-herdr plugin pane open --plugin cabra.amq --entrypoint inbox-popup
-
-# Dashboard server in dedicated pane
-herdr plugin pane open --plugin cabra.amq --entrypoint dashboard
-```
-
----
-
-## CLI Reference (`herdr-amq`)
-
-The plugin ships an executable CLI dispatcher (`bin/herdr-amq.mjs`) used by both agents and operators:
-
-```bash
-# Start AGmail webmail dashboard (default: http://127.0.0.1:8505)
+herdr-amq bootstrap --kind opencode
 herdr-amq dashboard
-
-# Start the continuous bridge daemon
-herdr-amq bridge-daemon
-
-# Messaging
-herdr-amq send --to spotter --subject "Check ADS alignment" --body @/tmp/prompt.txt
-herdr-amq reply --id 20260922-120000-001@swarm --body "Approved. Commit with explicit pathspec."
-herdr-amq drain --me coordinator
-
-# Decentralized Kanban Task Bus
-herdr-amq task list
-herdr-amq task drain --me range
-herdr-amq task next --me range
-herdr-amq task claim TSK-402 --me worker-alpha
-herdr-amq task done TSK-402 --proof "Proof of Sabotage: INV-29 passed with non-zero exit on mutation"
-herdr-amq task block TSK-402 --reason "Waiting on asset import lock"
-
-# Attachment Migration (historical CAS blob / Git pinning)
-herdr-amq migrate [--dry-run] [--verbose]
-
-# Fleet Discovery & Cold Start (unions .opencode, .agents, .pi, AGENTS.md)
-herdr-amq fleet status
-herdr-amq fleet prepopulate
-herdr-amq fleet up [--kind agy|opencode|pi] [--agents a,b,c] [--dry-run]
-
-# Instant One-Shot Swarm Cold-Start (prepopulate + launch + daemon + doorbell)
-herdr-amq bootstrap [--kind agy]
-
-# Print or install the agentic skill
-herdr-amq --skill
-herdr-amq --skill --install .opencode/skills/herdr-amq
 ```
 
----
+The dashboard is local-only at `http://127.0.0.1:8505`. The CLI and agent protocol are documented in the [workflow guide](docs/cli-and-workflows.md).
 
-## Onboarding & Swarm Cold Start
+## AGmail preview
 
-When onboarding a new repository or recovering after all Herdr panes were lost (e.g. machine reboot or closed panes):
+![AGmail agent activity sheet](docs/images/agmail-agent-activity.webp)
 
-### 1. Instant Automated Bootstrap
-Run a single command to discover external tool personas, provision isolated worktrees, and launch interactive agent sessions:
+The activity card reports live harness state and the current model when Herdr/OpenCode exposes it. Profile configuration remains a fallback, with the source exposed in the API.
 
-```bash
-herdr-amq bootstrap [--kind agy|opencode|pi]
-```
-
-Under the hood, this pipeline automatically:
-1. **Unifies Personas**: Scans `.opencode/agents/`, `.agents/`, `.pi/agents/`, `.claude/agents/`, rule declarations in `AGENTS.md` (e.g. `Handles: coordinator, ...`), and established `.worktrees/`.
-2. **Prepopulates Storage & Worktrees**: Generates clean Maildir queues (`.agent-mail/agents/<handle>/`) and dedicated Git worktrees (`.worktrees/<handle>`) on `agent/<handle>`.
-3. **Pre-authorizes Workspace Trust**: Injects worktree paths into `trustedWorkspaces` in `~/.gemini/antigravity-cli/settings.json` so `agy` bypasses interactive TUI trust confirmation dialogs.
-4. **Environment Sanitation**: Seeds child PTYs with robust PATH resolution (`~/.local/bin`, Nix profiles) so agent CLIs and local binaries are found unconditionally.
-5. **Supervised Lifecycle**: Launches Herdr terminal tabs with shell-boot backoff, starts the Doorbell Bridge daemon, and executes an initial doorbell pass.
-
-### 2. Context Resilience (Do agents lose context on cold start?)
-**No.** Context is completely decoupled from the terminal scrollback:
-* **Persistent Transmissions**: All messages, decisions, reviews, and CAS/Git attachments live as RFC 5322 markdown files in `.agent-mail/`.
-* **Decentralized Task Bus**: Tasks live in `.agent-mail/bus/{backlog,doing,blocked,done}/`.
-* **Code Branch Isolation**: Staged and uncommitted edits remain intact in `.worktrees/<handle>` on the agent's branch.
-* **Turn-Based Epistolary Execution**: When an agent wakes up, it drains its inbox (`herdr-amq mail drain --me <handle>`), reads its assigned task card, inspects `git status`, and resumes work without relying on monolithic LLM chat memory.
-
----
+![AGmail task dossier](docs/images/agmail-task-drawer.webp)
 
-## Agentic Skill Integration
-
-AI coding agents (Antigravity, Claude Code, OpenCode, Aider) can consume the skill definition directly to learn the protocol without human instruction:
-
-```bash
-# Output full YAML-frontmattered SKILL.md
-herdr-amq --skill
-
-# Auto-install directly into your workspace
-herdr-amq --skill --install .opencode/skills/herdr-amq/SKILL.md
-```
+The compact mobile task form keeps its owner warning and action row visible at narrow widths.
 
----
+![Compact AGmail New Task form](docs/images/agmail-mobile-new-task.webp)
 
-## Security & Threat Model (Strictly Local-Only)
-
-> [!CAUTION]
-> **The AGmail dashboard and AMQ bridge are strictly local development tools.**
-> Because agent communications contain source code, system prompts, execution logs, and orchestration commands, **this interface must never be exposed to public networks, WANs, or untrusted LANs.**
-
-By design, `herdr-plugin-amq` implements strict defense-in-depth protections verified by continuous red-team exploit tests:
-
-* **Exclusive Loopback Binding**: The HTTP server strictly binds to `127.0.0.1` IPv4 loopback (dropping non-local external TCP requests at the OS level).
-* **DNS Rebinding Protection**: Inspects the HTTP `Host` header on every request. Any foreign domain (e.g. `attacker.com` pointing to 127.0.0.1) receives immediate `403 Forbidden`.
-* **Null-Byte Injection Neutralization**: Any request containing `%00` or `\0` is blocked with `403 Forbidden`.
-* **Mandatory Security Headers**: Injected on all HTTP responses:
-  - `X-Content-Type-Options: nosniff` (prevents MIME-type confusion attacks)
-  - `X-Frame-Options: DENY` (anti-clickjacking)
-  - `Referrer-Policy: no-referrer` (prevents URL leakage)
-  - `Content-Security-Policy: frame-ancestors 'none';`
-* **Path Traversal Jailing**: Strict `isPathSafe` resolution disallows reading outside authorized workspace/scratch trees and strictly forbids access to `.ssh`, `.env`, `/etc/passwd`, credentials, or `.git/config`.
-
----
+## Requirements
 
-## Testing & Quality Assurance
+- Node.js >= 18
+- Herdr >= 0.7.0
+- Chrome/Chromium for browser journeys only
+- Zero npm runtime dependencies
 
-Our test suite adheres to high-rigor standards with zero external test runners:
+## Verification
 
 ```bash
-# Run 95 automated unit, integration, simulation & security tests
 npm test
-
-# Run red-team security penetration audit suite
-npm run test:security
-
-# Run tests with experimental coverage reporting (80%+ lines and functions)
-npm run test:coverage
-
-# Validate JavaScript module syntax across all files
+npm run test:e2e
 npm run check
+npm audit --audit-level=high
 ```
 
-Automated GitHub Actions CI validates compatibility across **Node 18.x, 20.x, and 22.x** on both **Ubuntu** and **macOS**, alongside a dedicated **Security Compliance & Red-Team Audit** workflow.
-
----
+The browser suite uses an isolated Maildir, board, and fake Herdr socket, so screenshots and tests never touch the live swarm.
 
 ## License
 

package/docs/architecture.md

@@ -0,0 +1,50 @@
+# Architecture
+
+Herdr AMQ is the coordination layer between turn-based coding agents and a human operator. It keeps transport, task state, and oversight separate so a sleeping agent can be woken without sharing a chat context.
+
+## Why the bridge exists
+
+Synchronous group chat does not fit autonomous coding sessions:
+
+1. Group messages consume context with irrelevant activity.
+2. An agent turn ends after a response or tool sequence; it cannot busy-wait for the next instruction.
+3. A Maildir inbox preserves messages, but an idle agent needs a lifecycle-aware wakeup.
+
+AMQ provides persistent Maildir messages, a file-based task bus, and immutable CAS attachments. The bridge watches Herdr panes and prompts only agents that are `idle` or `done`. Working panes are left alone; blocked panes raise an actionable alert.
+
+## Data flow
+
+```mermaid
+flowchart TD
+    AMQ[".agent-mail/ Maildir messages"] --> BRIDGE["Bridge daemon"]
+    BUS[".agent-mail/bus/ task cards"] --> BRIDGE
+    BRIDGE --> STATUS{"Herdr pane state"}
+    STATUS -->|working| IDLE["Leave pane alone"]
+    STATUS -->|blocked| ALERT["Alert coordinator"]
+    STATUS -->|idle or done| DOORBELL["herdr agent prompt"]
+    DOORBELL --> WAKE["Agent drains mail and tasks"]
+    WAKE --> AMQ
+    WAKE --> BUS
+    AMQ --> DASH["AGmail dashboard"]
+    BUS --> DASH
+    WAKE --> CAS[".agent-mail/blobs/ CAS evidence"]
+    CAS --> DASH
+```
+
+## Components
+
+| Component | Responsibility |
+|---|---|
+| `src/bridge.mjs` | Lifecycle-aware Maildir/task doorbells, deduplication, blocked alerts |
+| `src/herdr.mjs` | Herdr socket snapshot/events and live pane activity |
+| `src/runtime-models.mjs` | Best-effort live model lookup from harness metadata and OpenCode sessions |
+| `src/store.mjs` | Maildir parsing, profiles, attachments, and agent discovery |
+| `src/board.mjs` | Backlog, claimed, blocked, and done task cards |
+| `src/server.mjs` | Loopback API, SSE updates, and AGmail static assets |
+| `src/web/` | Responsive webmail, activity sheet, and Kanban UI |
+
+## Live model reporting
+
+The profile model is configuration metadata, not proof of the model currently selected by a running harness. When Herdr exposes model fields, AGmail uses them first. For OpenCode panes, the Herdr `agent_session.value` is resolved against the local OpenCode session database and rendered as `provider/model (variant)`. The API also returns `modelSource` so the UI and operators can distinguish live harness data from a profile fallback.
+
+The resolver is best-effort: unavailable Herdr/OpenCode data leaves the configured profile visible rather than inventing a model.

package/docs/cli-and-workflows.md

@@ -0,0 +1,72 @@
+# CLI and workflows
+
+`herdr-amq` is the executable dispatcher in `bin/herdr-amq.mjs`. It is usable from an agent shell, a Herdr pane, or a human operator session.
+
+## Core commands
+
+```bash
+herdr-amq dashboard
+herdr-amq bridge-daemon
+herdr-amq status
+
+herdr-amq send --to spotter --subject "Check ADS alignment" --body @/tmp/prompt.txt
+herdr-amq reply --id <message-id> --body "Reply on the original thread"
+herdr-amq drain --me coordinator --include-body
+
+herdr-amq task list
+herdr-amq task drain --me <handle>
+herdr-amq task next --me <handle>
+herdr-amq task claim <task-id> --me <handle>
+herdr-amq task done <task-id> --proof "Verification evidence"
+herdr-amq task block <task-id> --reason "Waiting on an external dependency"
+
+herdr-amq migrate [--dry-run] [--verbose]
+herdr-amq --skill
+herdr-amq --skill --install .opencode/skills/herdr-amq/SKILL.md
+```
+
+Mail messages use Maildir delivery and RFC 5322 threading headers. Attachments are stored through the CAS blobstore or pinned to a Git object when migrating historical files.
+
+## Fleet lifecycle
+
+```bash
+herdr-amq fleet status
+herdr-amq fleet prepopulate
+herdr-amq fleet up --kind opencode --agents coordinator,range,qa
+herdr-amq bootstrap --kind opencode
+```
+
+Bootstrap discovers supported persona directories and worktrees, provisions Maildirs, delivers first-registration welcomes, prepares isolated worktrees, starts the bridge daemon, and performs an initial doorbell pass.
+
+## Local prompt templates
+
+Optional files customize local policy:
+
+```text
+.agent-mail/templates/welcome.md
+.agent-mail/templates/doorbell.md
+```
+
+Templates support scalar substitutions only. The doorbell always appends the required drain/claim actions and conditional-reply guidance, so a template cannot disable delivery or make an unrequested reply.
+
+Supported doorbell variables:
+
+| Variable | Meaning |
+|---|---|
+| `agent.handle` | Recipient handle |
+| `mail.count` | Unread message count |
+| `mail.senders` | Sanitized sender list |
+| `board.backlog` | Assigned backlog count |
+| `board.blocked` | Assigned blocked count |
+| `board.doing` | Assigned in-progress count |
+| `board.done` | Assigned completed count |
+| `board.total` | Total board cards |
+
+## Agent skill
+
+```bash
+herdr-amq --skill
+herdr-amq --skill --install .opencode/skills/herdr-amq/SKILL.md
+```
+
+The skill teaches an agent to drain first, claim before editing, preserve threads on replies, and include proof when completing a card.

package/docs/installation.md

@@ -0,0 +1,70 @@
+# Installation and Herdr setup
+
+## Requirements
+
+- Node.js 18 or newer
+- Herdr 0.7.0 or newer
+- A repository with a `.agent-mail` queue, or run fleet bootstrap to create one
+- Chrome/Chromium only for the optional browser journeys
+
+The runtime has no npm production dependencies. `playwright-core` is a development-only dependency for the browser suite.
+
+## Link the plugin
+
+```bash
+git clone https://github.com/cabra-lat/herdr-plugin-amq.git herdr-plugin-amq
+cd herdr-plugin-amq
+herdr plugin link .
+herdr plugin list
+herdr plugin action list --plugin cabra.amq
+```
+
+The dashboard and queue root are discovered from the current workspace. The web server binds to `127.0.0.1` and refuses foreign `Host` headers.
+
+## Herdr actions
+
+```bash
+herdr plugin action invoke cabra.amq.bridge-status
+herdr plugin action invoke cabra.amq.bridge-start
+herdr plugin action invoke cabra.amq.bridge-stop
+herdr plugin action invoke cabra.amq.doorbell-check
+herdr plugin action invoke cabra.amq.open-dashboard
+herdr plugin action invoke cabra.amq.migrate
+```
+
+Example keybindings for `~/.config/herdr/config.toml`:
+
+```toml
+[[keys.command]]
+key = "prefix+m"
+type = "plugin_action"
+command = "cabra.amq.bridge-status"
+description = "Check AMQ mailbox status"
+
+[[keys.command]]
+key = "prefix+M"
+type = "plugin_action"
+command = "cabra.amq.doorbell-check"
+description = "Ring AMQ doorbells for idle agents"
+```
+
+## Panes
+
+```bash
+herdr plugin pane open --plugin cabra.amq --entrypoint inbox-popup
+herdr plugin pane open --plugin cabra.amq --entrypoint dashboard
+```
+
+The dashboard entrypoint is also available as `herdr-amq dashboard` and defaults to `http://127.0.0.1:8505`.
+
+## Browser verification
+
+The browser suite uses an isolated Maildir, board, and fake Herdr socket. It never reads or writes the live swarm.
+
+```bash
+npm ci --ignore-scripts
+CHROMIUM_BIN="$(command -v chromium)" npm run test:e2e
+E2E_ARTIFACT_DIR="$PWD/artifacts/e2e" CHROMIUM_BIN="$(command -v chromium)" npm run test:e2e
+```
+
+The suite covers desktop, 390×844 mobile, and 320×568 compact journeys, including the activity sheet, task drawer, sticky message header, pull-to-refresh guard, and New Task action visibility. Screenshots and `report.json` are written under `artifacts/e2e/`.

package/docs/security-and-testing.md

@@ -0,0 +1,33 @@
+# Security and testing
+
+## Threat model
+
+AGmail and the AMQ bridge are strictly local development tools. Agent communications can contain source code, prompts, logs, and execution commands, so the dashboard must not be exposed to a WAN or untrusted LAN.
+
+The server applies:
+
+- Loopback-only binding
+- DNS-rebinding protection through `Host` validation
+- Null-byte request rejection
+- `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, and CSP headers
+- Path-traversal and credential-path denial
+- Bounded, symlink-rejected local prompt templates
+- No-store headers for dashboard HTML, JavaScript, and CSS
+
+Do not place secrets in profiles, briefs, prompt templates, task descriptions, or screenshots.
+
+## Test layers
+
+```bash
+npm test
+npm run test:security
+npm run test:coverage
+npm run check
+npm run test:e2e
+```
+
+`npm test` runs the native unit, integration, simulation, registration-security, and red-team suites. `npm run test:e2e` uses a temporary queue and fake Herdr socket, then captures desktop/mobile journeys without touching live mailboxes.
+
+## Definition of done
+
+A change is ready when syntax, unit/integration tests, browser journeys, audit, and diff checks pass. Report skipped or unavailable gates explicitly; do not turn a missing signal into a pass.

package/docs/ui-screenshots.md

@@ -0,0 +1,21 @@
+# AGmail visual tour
+
+These captures come from the isolated browser fixture. They contain no live mailbox data and are checked by the desktop/mobile journey suite.
+
+## Agent activity
+
+The activity sheet combines the live Herdr state, assigned task, unread count, pane ID, and the model reported by the running harness. The model is sourced from Herdr/OpenCode session metadata when available, rather than blindly displaying the profile fallback.
+
+![AGmail agent activity sheet showing live task, pane, and harness model](images/agmail-agent-activity.webp)
+
+## Task dossier
+
+The task drawer keeps the stage controls, owner, linked AMQ thread, transmissions, and dispatch composer together while preserving the board context behind the drawer.
+
+![AGmail task dossier with linked transmissions and dispatch controls](images/agmail-task-drawer.webp)
+
+## Compact New Task flow
+
+At 320×568, the owner tip and sticky action row remain visible. The form warns before assigning a card to an owner with claimed or blocked work.
+
+![Compact mobile New Task form with visible Cancel and Create Task actions](images/agmail-mobile-new-task.webp)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "herdr-plugin-amq",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Herdr plugin for AMQ (Agent Message Queue) autonomous bridge, status monitoring, and AGmail dashboard",
   "type": "module",
   "main": "src/index.mjs",
@@ -11,6 +11,7 @@
     "bin/",
     "src/",
     "skills/",
+    "docs/",
     "herdr-plugin.toml",
     "README.md",
     "LICENSE"
@@ -19,9 +20,11 @@
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/*.test.mjs",
-    "test:coverage": "mkdir -p coverage && node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
-    "check": "node --check bin/herdr-amq.mjs src/*.mjs test/*.test.mjs",
+    "test": "HERDR_DISABLE_PROMPT=1 node --test test/*.test.mjs",
+    "test:coverage": "mkdir -p coverage && HERDR_DISABLE_PROMPT=1 node --test --experimental-test-coverage --test-reporter=spec --test-reporter=lcov --test-reporter-destination=stdout --test-reporter-destination=coverage/lcov.info test/*.test.mjs",
+    "test:e2e": "HERDR_DISABLE_PROMPT=1 node --test test/e2e/*.test.mjs",
+    "test:visual": "npm run test:e2e",
+    "check": "node --check bin/herdr-amq.mjs src/*.mjs src/web/app.js test/*.test.mjs test/e2e/*.mjs",
     "test:security": "node --test test/security.test.mjs",
     "coverage:summary": "node tools/coverage-summary.mjs",
     "status": "node bin/herdr-amq.mjs status",
@@ -46,5 +49,8 @@
     "agmail"
   ],
   "author": "cabra.lat",
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "playwright-core": "1.48.2"
+  }
 }