hey-axi 0.3.0 → 0.3.2

package/README.md

@@ -1,8 +1,10 @@
 # hey-axi
 
+[![skills.sh](https://skills.sh/b/TangentialSolutions/hey-axi)](https://skills.sh/TangentialSolutions/hey-axi) [![npm](https://img.shields.io/npm/v/hey-axi.svg)](https://www.npmjs.com/package/hey-axi) [![test](https://github.com/TangentialSolutions/hey-axi/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/TangentialSolutions/hey-axi/actions/workflows/test.yml)
+
 An agent-friendly wrapper for [HEY CLI](https://github.com/basecamp/hey-cli) (`hey`), Basecamp's command line for HEY email, calendars, todos, habits, time tracking and journals.
 
-hey-axi runs `hey`, asks for its JSON response envelope, and prints it as [TOON](https://github.com/toon-format/toon). It follows the [AXI](https://axi.md) principles: a live home view, minimal default fields, truncated long text, definitive empty states, and unknown flags rejected up front. On our synthetic benchmark that's **~89% fewer tokens than `hey --json`** ([docs/benchmarks.md](docs/benchmarks.md)). It also adds a few safety rails. It covers **every command in HEY CLI v1.7.0** (154 runnable command paths, including the `login`/`logout` aliases, plus the `box <id>`-style shortcuts) by routing from a snapshot of HEY's own `hey commands --json` catalog. See [CHANGELOG.md](CHANGELOG.md) for what changed in each release.
+hey-axi runs `hey`, asks for its JSON response envelope, and prints it as [TOON](https://github.com/toon-format/toon). It follows the [AXI](https://axi.md) principles: a live home view, minimal default fields, truncated long text, definitive empty states, and unknown flags rejected up front. On our synthetic benchmark that's **~89% fewer tokens than `hey --json`** ([docs/benchmarks.md](docs/benchmarks.md)). It also adds a few safety rails. It covers **every command in HEY CLI v1.7.0 plus the commands on HEY's unreleased `main` branch as of 2026-10-06** (commit [`9dfe00f`](https://github.com/basecamp/hey-cli/commit/9dfe00fb6594a4da5272b8ed0692f494229f14d2)): 155 runnable command paths, including the `login`/`logout` aliases, plus the `box <id>`-style shortcuts. It routes from a snapshot of HEY's own `hey commands --json` catalog. The main-only additions (`contact deliver`, `event delete --occurrence/--apply-to`) need a HEY built from main, or the next HEY release; with HEY v1.7.0 they fail with `kind: hey_outdated`. See [CHANGELOG.md](CHANGELOG.md) for what changed in each release.
 
 ## Install
 
@@ -70,9 +72,13 @@ hey-axi move --help                        # usage, flags, examples, notes (no H
   - `compose` and `reply` are **saved as drafts**. hey-axi adds `--draft`, and the output starts with `sent: false`, `saved_as: draft` and an `axi_notice` (also printed to stderr).
   - `forward`, `draft send` and `bulk-reply send` have no draft mode in HEY, so they're refused (exit 2) with the safe alternative (`reply … --to`, `draft show`, `bulk-reply preview`).
   - If you pass `--draft` or `--dry-run` yourself, hey-axi adds and marks nothing.
+  - With `--allow-send`, a send HEY confirms is marked `sent: true` (and names the delivered message's `id`/`topic_id` when HEY reports them, as HEY main does). If HEY holds it for Undo Send (`delayed: true`), a `held` line says it hasn't gone out yet and the thread won't show it until it does.
+  - If HEY refuses to send and keeps the message as a draft (HEY main's `not_delivered`, usually the sending limit), the result is an error with `kind: not_delivered`, `sent: false` and the draft id, and says not to repeat the send. HEY v1.7.0 reports such a send as sent, so it can't be detected there.
+  - Recipients HEY would silently drop (no domain or top-level domain, like `bob` or `bob@example`) are refused (exit 2, `sent: false`) before HEY runs, for `compose`, `reply`, `forward` and `draft edit`. HEY main's own "not a valid email address" refusal is reported the same way.
 - **Credentials stay out of agent context.** `auth token` needs `--allow-secret` or `HEY_AXI_ALLOW_SECRETS=1`.
+- **Destructive commands need an opt-in.** `screener clear` (HEY main) moves everything waiting in the Screener to Trash, for every sender, and HEY asks for no confirmation. hey-axi refuses it (exit 2, HEY isn't run, nothing changes) unless you pass `--allow-destructive` or set `HEY_AXI_ALLOW_DESTRUCTIVE=1`. The refusal says what it would do and suggests `screener list` and per-sender `screener deny` first.
 - **Content-first.** `compose`, `reply`, `draft edit`, `journal write`, `contact note set` and `bulk-reply send` must be given their content (`--message`, `--message -` for stdin, or a positional) and are refused (exit 2) otherwise, so HEY never opens an editor.
-- hey-axi's own flags (`--allow-send`, `--allow-secret`, `--interactive`, `--fields`, `--full`) are never forwarded to HEY. Switches take no value: `--draft=false` or `--allow-send=false` is refused (exit 2) rather than guessed at.
+- hey-axi's own flags (`--allow-send`, `--allow-secret`, `--allow-destructive`, `--interactive`, `--fields`, `--full`) are never forwarded to HEY. Switches take no value: `--draft=false` or `--allow-send=false` is refused (exit 2) rather than guessed at.
 
 ### Errors and exit codes
 
@@ -81,8 +87,8 @@ Errors are printed as structured TOON on stdout: `ok: false`, `error`, a `kind`,
 | Exit | Meaning |
 |---|---|
 | 0 | success (including no-op mutations and empty results) |
-| 1 | the command failed; `kind` says why: `not_found`, `auth`, `forbidden`, `rate_limited`, `network`, `api_error`, `ambiguous`, `hey_missing`, `command_error` |
-| 2 | usage error (`kind: usage`): unknown command/flag/field, bad flag value, missing or extra arguments, missing required flag or content, a switch given a value (`--draft=false`), blocked send, a person-only command without `--interactive`, or a usage error reported by HEY |
+| 1 | the command failed; `kind` says why: `not_found`, `auth`, `forbidden`, `rate_limited`, `network`, `api_error`, `ambiguous`, `hey_missing`, `hey_outdated` (the installed HEY is older than the command needs), `not_delivered` (HEY kept a send as a draft), `command_error` |
+| 2 | usage error (`kind: usage`): unknown command/flag/field, bad flag value, missing or extra arguments, missing required flag or content, a switch given a value (`--draft=false`), blocked send, a destructive command without `--allow-destructive`, a person-only command without `--interactive`, or a usage error reported by HEY |
 
 ## Agent integrations: session hook or skill
 
@@ -118,13 +124,16 @@ See [docs/listing.md](docs/listing.md) for how hey-axi gets listed on skills.sh
 
 ## Keeping up with HEY releases
 
-`src/manifest.json` is a snapshot of `hey commands --json`. To regenerate it from whichever `hey` you have installed:
+`src/manifest.json` is a snapshot of `hey commands --json` plus usage parsed from `hey <command> --help`. The current snapshot was built from HEY's unreleased `main` branch (commit `9dfe00f`, 2026-10-06), so its `hey_version` reads `1.7.0+main.9dfe00f`. To regenerate it:
 
 ```bash
-npm run refresh-manifest     # runs only `hey version` and `hey commands`
+npm run refresh-manifest     # from whichever `hey` you have installed (runs only `hey version`, `hey commands`, `hey <command> --help`)
+npm run manifest:main        # clone basecamp/hey-cli main, build it (needs Go and git), and rewrite the manifest from it
+npm run check-drift          # same build, but only compare: exits 1 with a readable diff when commands or flags differ
+node scripts/check-drift.js --ref v1.8.0 --write   # a tagged release instead of main
 ```
 
-hey-axi routes only from the snapshot, so an unknown command is rejected immediately (exit 2, with suggestions) without running HEY. New HEY commands become available after a refresh and a hey-axi release. A weekly GitHub Action (`manifest-drift`) fails when the snapshot falls behind the latest HEY release.
+hey-axi routes only from the snapshot, so an unknown command is rejected immediately (exit 2, with suggestions) without running HEY. New HEY commands become available after a refresh and a hey-axi release. The `upstream drift` GitHub Action builds HEY from basecamp/hey-cli `main` daily (and on changes to the manifest or scripts) and fails when its commands or flags differ from the snapshot; help-text-only changes are listed in the job summary without failing. It also warns when HEY publishes a release newer than the one the snapshot builds on.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hey-axi",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Agent-ergonomic AXI wrapper for Basecamp's HEY CLI: TOON output, send-to-draft safety, and a shareable agent skill",
   "keywords": [
     "axi",
@@ -41,6 +41,8 @@
   "scripts": {
     "test": "node --test test/*.test.js",
     "refresh-manifest": "node scripts/refresh-manifest.js",
+    "check-drift": "node scripts/check-drift.js",
+    "manifest:main": "node scripts/check-drift.js --write",
     "bench:tokens": "node bench/tokens.mjs",
     "bench:capture": "node bench/capture.mjs",
     "bench:fixtures": "node bench/generate-api-fixtures.mjs",
@@ -49,7 +51,7 @@
   },
   "dependencies": {
     "@toon-format/toon": "^4.1.1",
-    "axi-sdk-js": "^0.1.12"
+    "axi-sdk-js": "^0.1.13"
   },
   "engines": {
     "node": ">=20"

package/skills/hey-axi/SKILL.md

@@ -2,7 +2,7 @@
 name: hey-axi
 description: Read, triage and draft HEY email (and HEY calendars, todos, habits, journal, time tracking) from the shell through hey-axi, a token-efficient TOON wrapper around Basecamp's HEY CLI that saves outgoing mail as drafts unless sending is explicitly allowed. Use when the user asks you to check, search, read, summarize, sort, label, screen, archive or reply to their HEY (hey.com) email, watch for new mail, or manage HEY todos, events, habits, journal entries or time tracks.
 license: MIT
-compatibility: Requires Node.js 20+ (commands run as `npx -y hey-axi`), the HEY CLI (`hey`, v1.7.0 or newer) signed in to a HEY account, and network access to app.hey.com.
+compatibility: Requires Node.js 20+ (commands run as `npx -y hey-axi`), the HEY CLI (`hey`, v1.7.0 or newer; `contact deliver` and `event delete --occurrence` need a HEY built from basecamp/hey-cli main until HEY's next release) signed in to a HEY account, and network access to app.hey.com.
 metadata:
   author: TangentialSolutions
   repository: https://github.com/TangentialSolutions/hey-axi
@@ -62,7 +62,11 @@ npx -y hey-axi screener approve <clearance-id>
 npx -y hey-axi trash <id>...          npx -y hey-axi spam <id>...      npx -y hey-axi ignore <id>...
 ```
 
-`trash`, `spam`, `ignore`, `screener deny --spam` and `screener clear` (which clears the whole queue) run without any confirmation. Confirm with the user before you run them in bulk.
+`trash`, `spam`, `ignore` and `screener deny --spam` run without any confirmation. Confirm with the user before you run them in bulk.
+
+`screener clear` moves **everything** waiting in the Screener to Trash, for every sender, so hey-axi refuses it (exit 2, nothing changes) unless `--allow-destructive` is passed. Prefer `screener deny <clearance-id>` per sender. Only add `--allow-destructive` after the user has explicitly confirmed clearing the whole Screener.
+
+`npx -y hey-axi contact deliver <contact-id> --to imbox|feed|papertrail|screened-out` chooses where a contact's future mail arrives (a contact id from `contact list`). `npx -y hey-axi event delete <series-id> --occurrence <occurrence_id> --apply-to current|future` deletes one day (or that day onward) of a repeating event; the occurrence_id comes from `event day`/`event week`.
 
 Mutations are idempotent: when the desired state already holds (already seen, already deleted), the answer is `noop: true` with exit 0, not an error.
 
@@ -80,6 +84,9 @@ Output includes HEY's breadcrumb hints as `help` lines (with your `--account` ca
 - The message is required (`--message`, `--message-html`, `--attach`, or `--message -` to read stdin): HEY never opens an editor under hey-axi. The same goes for `journal write --content`, `contact note set --note` and `draft edit` (pass the fields to change).
 - `forward`, `draft send` and `bulk-reply send` are **refused** (exit 2) because HEY has no draft mode for them. The error names the safe alternative.
 - To actually send, the user must explicitly ask you to, and you add `--allow-send` (or they set `HEY_AXI_ALLOW_SEND=1`). Don't add it on your own initiative.
+- A real send answers `sent: true`; newer HEY versions also name the message (`id`) and its thread (`topic_id`). `held:` means Undo Send is holding it back: it is sent, but `thread read` won't show it (or a thread it starts) until HEY releases it.
+- `kind: not_delivered` (`sent: false`) means HEY refused the send (usually the account's sending limit) and kept it as draft `draft_id`. **Don't repeat the send**, which only makes another draft; tell the user, and send the draft later with `draft send <draft_id> --allow-send` when they ask.
+- A recipient without a full address (`bob`, `bob@localhost`) is refused before HEY runs (exit 2, `sent: false`): fix or remove it.
 
 ## 4. Output: fields, truncation, counts, modes
 
@@ -110,7 +117,7 @@ Lines also include `ready`, `disconnected` and `resync`. On `resync`, re-read th
 
 ## 6. Errors and exit codes
 
-Errors are TOON on stdout: `ok: false`, `error`, `kind` (`usage`, `not_found`, `auth`, `forbidden`, `rate_limited`, `network`, `api_error`, `ambiguous`, `hey_missing`, `command_error`), HEY's `code`/`hint`/`meta` when it gave them, and a `help` line with the next step. Exit codes: **0** success (including no-ops) · **1** error · **2** usage error or refusal (unknown command/flag/field, bad argument, blocked send, needs the user). Read `hint`/`help` before you retry.
+Errors are TOON on stdout: `ok: false`, `error`, `kind` (`usage`, `not_found`, `auth`, `forbidden`, `rate_limited`, `network`, `api_error`, `ambiguous`, `not_delivered`, `hey_missing`, `hey_outdated`, `command_error`), HEY's `code`/`hint`/`meta` when it gave them, and a `help` line with the next step. Exit codes: **0** success (including no-ops) · **1** error · **2** usage error or refusal (unknown command/flag/field, bad argument, blocked send, `screener clear` without `--allow-destructive`, needs the user). Read `hint`/`help` before you retry. `hey_outdated` means the installed `hey` is older than hey-axi's command catalog (`npx -y hey-axi version` shows it).
 
 ## Install
 

package/skills/hey-axi/references/commands.md

@@ -1,8 +1,8 @@
 # hey-axi command reference
 
-<!-- Generated by scripts/gen-skill.js from src/manifest.json (hey 1.7.0). Do not edit by hand. -->
+<!-- Generated by scripts/gen-skill.js from src/manifest.json (hey 1.7.0+main.9dfe00f). Do not edit by hand. -->
 
-Every command from HEY CLI 1.7.0 (154 runnable paths, including the `login`/`logout` aliases and shortcut forms such as `box <name>`). Run each as `npx -y hey-axi <command> [args] [flags]` (just `hey-axi …` when it is installed globally).
+Every command from HEY CLI v1.7.0 plus the commands on HEY main as of 2026-10-06 (commit 9dfe00f, unreleased): 155 runnable paths, including the `login`/`logout` aliases and shortcut forms such as `box <name>`. Run each as `npx -y hey-axi <command> [args] [flags]` (just `hey-axi …` when it is installed globally).
 `npx -y hey-axi <command> --help` shows usage, arguments, every flag with its default, 2-3 examples and notes, offline.
 Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--fields <a,b|all>`, `--full`, `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq <expr>`. Unknown commands, flags and arguments, flags without a value and values of the wrong type are rejected before HEY runs (exit 2).
 
@@ -32,7 +32,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `calendar list` | List calendars |  | fields: id, name, kind, owned |
 | `clip create` | Save text from an email entry | `--content <v>` |  |
 | `clip delete` | Delete a saved clip |  |  |
-| `clip list` | List the newest page of passages clipped from email |  | fields: id, content, topic_id, at |
+| `clip list` | List the newest page of passages clipped from email |  | fields: id, topic_id, at |
 | `collection` | List and manage email collections | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `collection add` | Add email threads to a collection | `--to <v>` |  |
 | `collection create` | Create a collection | `--summary <v>` |  |
@@ -49,6 +49,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `config untrust-local` | Remove trust for this repository's local HEY settings |  |  |
 | `contact add` | Add a contact | `--account-user-id <v>` `--alias <v>` `--email <v>` `--name <v>` |  |
 | `contact bundle` | Bundle a contact's mail |  |  |
+| `contact deliver` | Choose where a contact's email arrives | `--to <v>` |  |
 | `contact hide` | Hide a contact |  |  |
 | `contact list` | List contacts | `--all` `--page <v>` | fields: id, name, email_address |
 | `contact note delete` | Delete a private contact note |  |  |
@@ -67,7 +68,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `draft show` | Read a draft back |  |  |
 | `event add` | Create an event | `--all-day` `--calendar <v>` `--circle` `--countdown <v>` `--countdown-unit <v>` `--end-time <v>` `--ends-on <v>` `--invite <v>` `--link <v>` `--location <v>` `--notes <v>` `--remind <v>` `--repeat <v>` `--repeat-times <v>` `--repeat-until <v>` `--start-time <v>` `--starts-on <v>` `--time-zone <v>` `--title <v>` |  |
 | `event day` | List the events of one day, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at |
-| `event delete` | Delete an event |  |  |
+| `event delete` | Delete an event | `--apply-to <v>` `--occurrence <v>` |  |
 | `event edit` | Change an event | `--all-day` `--allow-plain-notes` `--apply-to <v>` `--calendar <v>` `--circle` `--countdown <v>` `--countdown-unit <v>` `--end-time <v>` `--ends-on <v>` `--invite <v>` `--link <v>` `--location <v>` `--notes <v>` `--occurrence <v>` `--remind <v>` `--repeat <v>` `--repeat-times <v>` `--repeat-until <v>` `--start-time <v>` `--starts-on <v>` `--time-zone <v>` `--title <v>` |  |
 | `event list` | List calendar events | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, ends_at |
 | `event week` | List the events of one week, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at |
@@ -79,7 +80,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `habit list` | List habits | `--all` `--date <v>` `--limit <v>` | fields: id, title, days |
 | `habit uncomplete` | Remove a habit completion for a date | `--date <v>` |  |
 | `ignore` | Ignore email threads |  |  |
-| `journal list` | List journal entries | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, starts_at, content |
+| `journal list` | List journal entries | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, date |
 | `journal read` | Read a journal entry (default: today) |  |  |
 | `journal write` | Write or edit a journal entry (default: today) | `--content <v>` `--content-html <v>` |  |
 | `label` | List and manage email labels | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
@@ -94,7 +95,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `move` | Move email threads to another box | `--to <v>` |  |
 | `reply` | Reply to a thread | `--attach <v>` `--bcc <v>` `--cc <v>` `--draft` `--dry-run` `--message <v>` `--message-html <v>` `--replace-recipients` `--to <v>` | saved as a draft unless `--allow-send` |
 | `screener approve` | Let a sender through | `--box <v>` `--seen` |  |
-| `screener clear` | Empty the Screener without deciding |  |  |
+| `screener clear` | Trash everything waiting in the Screener |  | refused unless `--allow-destructive` |
 | `screener deny` | Turn a sender away | `--spam` |  |
 | `screener history` | List the senders already screened | `--all` `--page <v>` | fields: id, status, email_address, decided |
 | `screener list` | List the senders waiting to be screened | `--all` `--page <v>` | fields: id, email_address, subject, topic_id |
@@ -122,7 +123,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `skill install` | Install the hey skill globally for your coding agents |  |  |
 | `snippet create` | Create a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` |  |
 | `snippet delete` | Delete a reusable email snippet |  |  |
-| `snippet list` | List reusable email snippets |  | fields: id, name, content |
+| `snippet list` | List reusable email snippets |  | fields: id, name |
 | `snippet update` | Update a reusable email snippet | `--content <v>` `--content-html <v>` `--name <v>` |  |
 | `spam` | Mark email threads as spam |  |  |
 | `stop-ignoring` | Stop ignoring email threads |  |  |

package/src/args.js

@@ -8,7 +8,7 @@ export const GLOBAL_BOOLEAN_FLAGS = ["json", "quiet", "ids-only", "count", "mark
 export const GLOBAL_SHORTHANDS = ["-v", "-h"];
 
 // hey-axi's own flags. Never forwarded to HEY.
-export const AXI_BOOLEAN_FLAGS = ["allow-send", "allow-secret", "full", "interactive"];
+export const AXI_BOOLEAN_FLAGS = ["allow-send", "allow-secret", "allow-destructive", "full", "interactive"];
 export const AXI_VALUE_FLAGS = ["fields"];
 
 // Output selectors that make HEY print something other than a JSON envelope. When any is
@@ -149,6 +149,23 @@ function typeError(name, type, value) {
   return null;
 }
 
+// Rules HEY enforces itself but its catalog doesn't mark (no "(required)" in the flag's
+// description, no list of values), so hey-axi can fail loud before HEY runs:
+//   required: flags the command can't run without
+//   choices:  the only values a flag takes
+//   together: flags that are only meaningful with each other
+export const FLAG_RULES = {
+  "contact deliver": { required: ["--to"], choices: { "--to": ["imbox", "feed", "papertrail", "screened-out"] } },
+  "event delete": { choices: { "--apply-to": ["current", "future"] }, together: [["--occurrence", "--apply-to"]] },
+  "event edit": { choices: { "--apply-to": ["current", "future"] }, together: [["--occurrence", "--apply-to"]] },
+};
+
+// Every required flag of a command: marked "(required)" by HEY, or listed in FLAG_RULES.
+export function requiredFlags(node) {
+  const marked = (node.flags || []).filter((flag) => /\(required\)$/.test(flag.desc || "")).map((flag) => `--${flag.name}`);
+  return [...new Set([...marked, ...(FLAG_RULES[node.path]?.required || [])])];
+}
+
 // AXI: reject unknown flags, flags without their value, values of the wrong type and
 // missing required flags before HEY is ever called.
 // Returns null, or { unknown } / { missingValue } / { badValue } / { missing }.
@@ -174,9 +191,21 @@ export function validateFlags(node, flags, { values = [], missingValues = [] } =
     const problem = typeError(name, types.get(name), value);
     if (problem) return { badValue: problem };
   }
-  const missing = (node.flags || [])
-    .filter((flag) => /\(required\)$/.test(flag.desc || ""))
-    .filter((flag) => !flags.has(`--${flag.name}`) && !(flag.shorthand && flags.has(`-${flag.shorthand}`)))
-    .map((flag) => `--${flag.name}`);
-  return missing.length ? { missing } : null;
+  const rules = FLAG_RULES[node.path] || {};
+  for (const [name, value] of values) {
+    const choices = rules.choices?.[name];
+    if (choices && !choices.includes(value)) return { badValue: `${name} takes one of ${choices.join(", ")}, got "${value}"` };
+  }
+  const shorthandOf = (name) => (node.flags || []).find((flag) => `--${flag.name}` === name)?.shorthand;
+  const given = (name) => flags.has(name) || (shorthandOf(name) && flags.has(`-${shorthandOf(name)}`));
+  const missing = requiredFlags(node).filter((name) => !given(name));
+  if (missing.length) return { missing };
+  for (const group of rules.together || []) {
+    const present = group.filter(given);
+    if (present.length && present.length < group.length) {
+      const absent = group.filter((name) => !given(name));
+      return { badValue: `${present.join(" and ")} needs ${absent.join(" and ")} for \`${node.path}\` (pass ${group.join(" and ")} together)` };
+    }
+  }
+  return null;
 }

package/src/cli.js

@@ -9,10 +9,11 @@ import { spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { createInterface } from "node:readline";
 import { encode } from "@toon-format/toon";
-import { closestNames, loadBundledManifest, resolveCommand } from "./router.js";
-import { STDIN_VALUE_FLAGS, checkPolicy, contentProblem, noopFor, runMode, sendCommands, sendStaging, userOnlyPaths } from "./policy.js";
+import { closestNames, coverageLabel, loadBundledManifest, resolveCommand } from "./router.js";
+import { STDIN_VALUE_FLAGS, checkPolicy, contentProblem, destructiveCommands, noopFor, runMode, sendCommands, sendStaging, userOnlyPaths } from "./policy.js";
 import { translateFailure, cleanLine, warningLines } from "./errors.js";
-import { RAW_OUTPUT_FLAGS, flagLabel, flagValue, hasAny, nodeValueFlags, scanArgs, stripAxiFlags, validateFlags, valueFlagSet } from "./args.js";
+import { FLAG_RULES, RAW_OUTPUT_FLAGS, flagLabel, flagValue, hasAny, nodeValueFlags, scanArgs, stripAxiFlags, validateFlags, valueFlagSet } from "./args.js";
+import { markSent, recipientProblem } from "./send.js";
 import { argumentHelp, checkArity, oneOfHelp } from "./arity.js";
 import { FieldError, LIST_FIELDS, DETAIL_FIELDS, carrySelectors, withSelectors, shapeEnvelope } from "./shape.js";
 import { homeView } from "./home.js";
@@ -29,7 +30,7 @@ const HEY = process.env.HEY_BIN || "hey";
 const QUIET_ENV = { HEY_NONINTERACTIVE: "1", EDITOR: "false", VISUAL: "false" };
 const heyEnv = () => ({ ...process.env, ...QUIET_ENV });
 
-const ALWAYS_ALLOWED = "--help, --json, --quiet, --fields, --full, --account, --ids-only, --count, --markdown, --html, --styled, --jq, --stats, --verbose, --base-url, --allow-send, --allow-secret, --interactive";
+const ALWAYS_ALLOWED = "--help, --json, --quiet, --fields, --full, --account, --ids-only, --count, --markdown, --html, --styled, --jq, --stats, --verbose, --base-url, --allow-send, --allow-secret, --allow-destructive, --interactive";
 
 const GLOBAL_HELP = [
   "--account <id|all>  linked account (default: HEY's default account)",
@@ -44,6 +45,7 @@ const GLOBAL_HELP = [
 const OWN_FLAG_HELP = [
   [(path) => sendCommands().includes(path), "--allow-send  really send (default false: saved as a draft, or refused when there is no draft mode)"],
   [(path) => path === "auth token", "--allow-secret  print the token (default false: refused)"],
+  [(path) => destructiveCommands().includes(path), "--allow-destructive  really run it (default false: refused, nothing is changed)"],
   [(path) => userOnlyPaths().includes(path), "--interactive  hand HEY the terminal; for a person at a terminal (default false: refused)"],
 ];
 
@@ -53,7 +55,7 @@ function usage(manifest) {
     "",
     "Run `hey-axi` with no arguments for a live home view (mail for this directory's scope + next commands).",
     "",
-    `commands (from hey ${manifest.hey_version}; run \`hey-axi <command> --help\` for details):`,
+    `commands (from HEY CLI ${coverageLabel(manifest)}; run \`hey-axi <command> --help\` for details):`,
   ];
   for (const node of manifest.commands) {
     const subs = node.subcommands?.length ? ` ${node.subcommands.map((child) => child.name).join("|")}` : "";
@@ -85,6 +87,8 @@ function usage(manifest) {
     "  Nothing is sent without --allow-send (or HEY_AXI_ALLOW_SEND=1): compose and reply are saved",
     "  as drafts (hey-axi adds --draft and says so); forward, draft send and bulk-reply send are refused.",
     "  auth token needs --allow-secret / HEY_AXI_ALLOW_SECRETS=1.",
+    "  screener clear (trashes everything waiting in the Screener) needs --allow-destructive /",
+    "  HEY_AXI_ALLOW_DESTRUCTIVE=1; without it, it is refused and nothing is changed.",
   );
   return lines.join("\n");
 }
@@ -103,11 +107,16 @@ export function commandHelp(node) {
     for (const child of node.subcommands) lines.push(`  ${child.path} — ${child.short}`);
   }
   if (node.flags?.length) {
+    const rules = FLAG_RULES[node.path] || {};
     lines.push("", "flags:");
     for (const flag of node.flags) {
-      const extra = [flag.desc, `(${flagDefault(flag)})`].filter(Boolean).join(" ");
+      const name = `--${flag.name}`;
+      const required = rules.required?.includes(name) && !/\(required\)$/.test(flag.desc || "") ? "(required)" : "";
+      const choices = rules.choices?.[name] ? `one of: ${rules.choices[name].join(", ")}` : "";
+      const extra = [flag.desc, required, choices, `(${flagDefault(flag)})`].filter(Boolean).join(" ");
       lines.push(`  ${flagLabel(flag)}  ${extra}`);
     }
+    for (const group of rules.together || []) lines.push(`  ${group.join(" and ")} go together: pass both or neither`);
   }
   lines.push("", "global flags (allowed on every command):", ...GLOBAL_HELP.map((line) => `  ${line}`));
   const own = OWN_FLAG_HELP.filter(([applies]) => applies(node.path)).map(([, line]) => `  ${line}`);
@@ -412,6 +421,10 @@ if (refusal) fail({ ok: false, ...refusal }, 2);
 const missingContent = contentProblem(node, flags, positionals);
 if (missingContent) fail({ ok: false, kind: "usage", ...missingContent }, 2);
 
+// A recipient HEY would drop (no domain): refused here, so no HEY version can lose it.
+const badRecipient = recipientProblem(path, scan.values);
+if (badRecipient) fail({ ok: false, kind: "usage", ...badRecipient }, 2);
+
 let heyArgs = stripAxiFlags(args);
 // `--message -` (and --note -, --content -): read the content from stdin.
 const fromStdin = scan.values.filter(([name, value]) => STDIN_VALUE_FLAGS.includes(name) && value === "-").map(([name]) => name);
@@ -461,20 +474,29 @@ function markStaged(parsed) {
   return { ...marker, data: parsed };
 }
 
-function reportFailure(result) {
-  const { failure, exitCode, warnings } = translateFailure(result, { path });
+// A real delivery: a send command, not staged as a draft, not --draft or --dry-run.
+const delivering = sendCommands().includes(path) && !staging && !flags.has("--draft") && !flags.has("--dry-run");
+
+async function reportFailure(result) {
+  const { failure, exitCode, warnings } = translateFailure(result, { path, usage: usageLines, example: examplesFor(node)[0], coverage: coverageLabel(manifest) });
   // The fix-it commands keep the invocation's --account/--base-url.
   for (const key of ["hint", "help"]) {
     if (Array.isArray(failure[key])) failure[key] = failure[key].map((line) => carrySelectors(line, carry));
     else if (failure[key]) failure[key] = carrySelectors(failure[key], carry);
   }
   for (const line of warnings) process.stderr.write(`${line}\n`);
-  const noop = exitCode !== 0 && noopFor(path, failure, positionals, { to: flagValue(args, "to"), from: flagValue(args, "from") });
+  const noop = exitCode !== 0 && noopFor(path, failure, positionals, { to: flagValue(args, "to"), from: flagValue(args, "from"), occurrence: flagValue(args, "occurrence") });
   if (noop) {
     if (json) process.stdout.write(`${JSON.stringify(noop)}\n`);
     else output(noop);
     process.exit(0);
   }
+  if (failure.kind === "not_delivered") {
+    // HEY kept the message as a draft: remember it as one, so the next home view says so.
+    const { recordActivity } = await import("./activity.js");
+    const { findScope } = await import("./scope.js");
+    recordActivity({ path, positionals: failure.draft_id ? [failure.draft_id] : [], staged: true, scopeDir: scopeDirFor(process.cwd(), findScope) });
+  }
   if (json) process.stdout.write(`${JSON.stringify(failure)}\n`);
   else output(failure);
   process.exit(exitCode);
@@ -484,7 +506,7 @@ const mode = runMode(path, flags);
 if (mode === "interactive") {
   // Only reached with the explicit --interactive opt-in (and a terminal, except for mcp).
   const result = await runHeyInteractive(heyArgs);
-  if (result.error) reportFailure(result);
+  if (result.error) await reportFailure(result);
   process.exit(result.status === 0 ? 0 : 1);
 }
 if (raw || mode !== "json") {
@@ -493,7 +515,7 @@ if (raw || mode !== "json") {
   // A watch stopped by a signal ended the way the agent asked: not an error.
   if (mode === "stream" && (result.signal || result.status === 130 || result.status === 143)) process.exit(0);
   // HEY's stdout here is data, not an error message: it never goes into the failure.
-  if (result.error || result.status !== 0) reportFailure({ ...result, stdout: "" });
+  if (result.error || result.status !== 0) await reportFailure({ ...result, stdout: "" });
   writeWarnings(result.stderr);
   if (mode !== "stream" && result.stdout?.length) process.stdout.write(result.stdout);
   process.exit(0);
@@ -522,7 +544,7 @@ if (path === "version") {
 }
 
 const result = await runHey(command, ["--json"]);
-if (result.status !== 0) reportFailure(result);
+if (result.status !== 0) await reportFailure(result);
 writeWarnings(result.stderr);
 
 let parsed;
@@ -551,6 +573,8 @@ try {
   }, 2);
 }
 shaped = markStaged(shaped);
+// A delivered message: say so, and when Undo Send holds it, that the thread won't show it yet.
+if (delivering && !full && !plainText) shaped = markSent(shaped);
 
 // A list whose HEY result carried no next steps still gets one (AXI principle 9): the
 // matching view/show command when there is one, else how to see every field.
@@ -568,14 +592,14 @@ if (!full && !quiet && !plainText && shaped && typeof shaped === "object" && sha
       ? `Run \`${withSelectors(`hey-axi ${sibling.path} --help`, carry)}\` to see how to add one`
       : sibling
       ? `Run \`${withSelectors(`hey-axi ${sibling.path} <id>`, carry)}\` to see one in full`
-      : shaped.empty ? `Run \`hey-axi ${path} --help\` to check the filters` : `Run \`${commandLine} --fields all\` to see every field`;
+      : shaped.empty ? `Run \`${withSelectors(`hey-axi ${path} --help`, carry)}\` to check the filters` : `Run \`${commandLine} --fields all\` to see every field`;
     shaped.help = [next, ...help];
   }
 }
 
 const { recordActivity } = await import("./activity.js");
 const { findScope } = await import("./scope.js");
-recordActivity({ path, positionals, staged: Boolean(staging), sent: sendCommands().includes(path) && !staging && !flags.has("--draft") && !flags.has("--dry-run"), scopeDir: scopeDirFor(process.cwd(), findScope) });
+recordActivity({ path, positionals, staged: Boolean(staging), sent: delivering, scopeDir: scopeDirFor(process.cwd(), findScope) });
 
 if (json) process.stdout.write(`${JSON.stringify(shaped)}\n`);
 else output(shaped);

package/src/errors.js

@@ -8,10 +8,12 @@
 // A `help` line always says what to do next.
 
 import { heyToAxi } from "./text.js";
+import { HEY_BAD_ADDRESS, notDelivered, recipientRefusal } from "./send.js";
 
 // HEY's exit codes (`hey help exit-codes`) → a kind, a message and the next step.
 const KINDS = {
-  1: { kind: "command_error", message: "the command failed", help: "Run `hey-axi <command> --help` to check the arguments" },
+  // No fixed help: the fix for an unrecognized failure is built from the command (fixFor).
+  1: { kind: "command_error", message: "the command failed" },
   2: { kind: "not_found", message: "not found", help: "Check the id; list commands such as `hey-axi box view imbox` show valid ids (threads use topic_id)" },
   3: { kind: "auth", message: "not signed in to HEY", help: "Run `hey-axi auth login --token <token>` if you have a token; otherwise ask the user to run `hey-axi auth login --interactive` in their terminal. Check with `hey-axi auth status`" },
   4: { kind: "forbidden", message: "this account can't do that", help: "Check `hey-axi account list` and --account" },
@@ -24,6 +26,22 @@ const KINDS = {
 
 const USAGE_CODES = new Set(["usage", "invalid_argument", "invalid_flag", "validation"]);
 
+const DOCTOR = "Run `hey-axi doctor` to check HEY's sign-in, configuration and connection";
+
+// The specific next step for a failure that matched no known kind, or a usage error: the
+// command's own USAGE line and an example inline (no "see --help" round trip), then the
+// one command that diagnoses HEY itself.
+//   context: { path, usage: ["usage: hey-axi thread read <thread-id>"], example }
+function fixFor(context = {}, { usageError = false } = {}) {
+  const { path, usage = [], example } = context;
+  if (!path) return [DOCTOR];
+  const lines = usage.length ? [...usage] : [];
+  if (example) lines.push(`example: ${example}`);
+  if (!lines.length) lines.push(`Run \`hey-axi ${path} --help\` for its arguments and flags`);
+  if (!usageError) lines.push("Run `hey-axi doctor` if the arguments are right (it checks HEY's sign-in, configuration and connection)");
+  return lines;
+}
+
 // AXI exit code for a failed HEY run.
 export function axiExitCode(status, code) {
   if (status === 0) return 0;
@@ -38,11 +56,25 @@ const NOISE = /^(warning:|panic:|fatal error:|\[signal |runtime error|\s+at |gor
 // Programming-language errors from inside HEY or its libraries say nothing an agent can
 // act on: they are dropped, and the failure's own message (by kind) stands alone.
 const INTERNAL = /^(Uncaught )?(TypeError|ReferenceError|SyntaxError|RangeError|InternalError|AssertionError|panic|fatal|runtime error|invalid memory address|nil pointer|unexpected end of JSON|json: |SIGSEGV)\b/i;
+// Any other "<Something>Error:" / "<Something>Exception:" line, a Ruby/Python-style
+// class path (Foo::Bar, foo.bar.BazError) or a traceback is a dependency's own error
+// (SqliteError, PG::ConnectionBad, sqlalchemy.exc.OperationalError): dropped the same way.
+const DEPENDENCY = /^(Uncaught\s+)?([\w$]+(\.[\w$]+|::[\w$]+)*(Error|Exception|Fault)\b|[A-Z]\w*(::[A-Z]\w*)+\b|Traceback\b|Caused by\b|node:internal\b)/;
+// Names of HTTP/database libraries; a short value that is just one of these says nothing.
+const LIBRARY = /\b(undici|axios|node-fetch|got|superagent|sqlite3?|better-sqlite3|sequel|activerecord|faraday|net\/http|go-http-client|libcurl|openssl|electron|node(\.js)?|v8)\b/i;
+// The ones that are never ordinary words: a line or meta value that still names one,
+// even mid-sentence ("request via superagent failed"), is dependency detail and is dropped.
+const LIBRARY_NAME = /(^|[^\w-])(undici|axios|node-fetch|superagent|better-sqlite3|sqlite3|activerecord|faraday|net\/http|go-http-client|libcurl|node\.js|nodejs)(?![\w-])/i;
+// HEY's error codes are snake_case words (usage, not_found, not_delivered ...); anything
+// else in `code` (SqliteError, ECONNRESET) is a dependency's and is left out.
+const HEY_CODE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
 // Low-level network codes become plain words.
 const NETWORK = [
   [/\bECONNRESET\b/, "the connection was reset"], [/\bECONNREFUSED\b/, "the connection was refused"],
   [/\bETIMEDOUT\b|\bi\/o timeout\b|context deadline exceeded/i, "the request timed out"], [/\bENOTFOUND\b|no such host/i, "the server name could not be resolved"],
   [/\bEAI_AGAIN\b/, "DNS lookup failed"], [/\bcertificate\b|\bx509\b|\bTLS\b/i, "a TLS/certificate problem"],
+  // Local database codes (HEY's cache) become plain words too.
+  [/\bSQLITE_(BUSY|LOCKED)\b|database is locked/i, "the local database is busy; retry in a moment"], [/\bSQLITE_[A-Z]+\b/, "a local database error"],
 ];
 
 export function cleanLine(text) {
@@ -51,10 +83,14 @@ export function cleanLine(text) {
   let line = lines[0].trim().replace(/^(error|Error|ERROR):\s*/, "");
   const network = NETWORK.find(([pattern]) => pattern.test(line));
   if (network) return network[1];
-  if (INTERNAL.test(line)) return "";
+  if (INTERNAL.test(line) || DEPENDENCY.test(line)) return "";
   // Library prefixes ("axios:", "fetch failed:", "Get \"https://…\":") and raw URLs add nothing.
-  line = line.replace(/^(axios|undici|fetch failed|request failed|(get|post|put|patch|delete) "[^"]*"):?\s*/i, "").replace(/\bhttps?:\/\/\S+/g, "the HEY server").trim();
-  if (!line) return "";
+  line = line.replace(/^((axios|undici|node-fetch|got|superagent|faraday|sqlite3?|better-sqlite3)(\s*error)?|fetch failed|request failed|(get|post|put|patch|delete) "[^"]*"):?\s*/i, "")
+    .replace(/\bhttps?:\/\/\S+/g, "the HEY server")
+    // File paths and source locations (/usr/lib/…/x.js:12:3, C:\\…) are internal detail.
+    .replace(/(^|\s)(\/|~\/|[A-Za-z]:\\)[^\s:]+(:\d+)*/g, "$1a local file").replace(/\s{2,}/g, " ").trim();
+  // A line that is still a dependency error after its prefix came off is dropped too.
+  if (!line || INTERNAL.test(line) || DEPENDENCY.test(line) || LIBRARY_NAME.test(line) || /^[\w./-]+$/.test(line) && LIBRARY.test(line)) return "";
   return heyToAxi(line.length > 200 ? `${line.slice(0, 200)}…` : line);
 }
 
@@ -72,7 +108,12 @@ const DEBUG_KEYS = /stack|trace|backtrace|panic|goroutine|debug|caller|frames?$/
 // HEY's error meta without debugging detail: stack-like keys are dropped and
 // multi-line strings are cut to their one meaningful line.
 export function cleanMeta(value, depth = 0) {
-  if (typeof value === "string") return /[\r\n\u001b]/.test(value) || value.length > 200 ? cleanLine(value) : value;
+  if (typeof value === "string") {
+    if (/[\r\n\u001b]/.test(value) || value.length > 200) return cleanLine(value);
+    // Short values are kept as they are, unless they are a dependency's error or name.
+    const bare = value.trim().replace(/^(error|Error|ERROR):\s*/, "");
+    return INTERNAL.test(bare) || DEPENDENCY.test(bare) || LIBRARY_NAME.test(bare) || (/^[\w./@ -]{1,40}$/.test(bare) && LIBRARY.test(bare) && !/\s\w+\s\w+/.test(bare)) ? undefined : value;
+  }
   if (!value || typeof value !== "object" || depth > 3) return depth > 3 ? undefined : value;
   if (Array.isArray(value)) return value.slice(0, 20).map((item) => cleanMeta(item, depth + 1)).filter((item) => item !== undefined && item !== "");
   const out = {};
@@ -107,31 +148,59 @@ function findEnvelope(text) {
 }
 
 // Returns { failure, exitCode, warnings }: the object to print, hey-axi's exit code,
-// and diagnostic lines for stderr.
-export function translateFailure(result, { path } = {}) {
-  const raw = KINDS[result.status] || KINDS[1];
-  const info = path ? { ...raw, help: raw.help.replace("<command>", path) } : raw;
+// and diagnostic lines for stderr. `context` ({ path, usage, example }) names the command
+// so the fix-it lines can be specific.
+export function translateFailure(result, context = {}) {
+  const { path } = context;
+  const info = KINDS[result.status] || KINDS[1];
+  const help = (kind = info) => kind.help || fixFor(context);
   if (result.error) {
-    return { failure: { ok: false, error: result.error, kind: info.kind, help: info.help }, exitCode: 1, warnings: [] };
+    return { failure: { ok: false, error: result.error, kind: info.kind, help: help() }, exitCode: 1, warnings: [] };
   }
   for (const text of [result.stderr, result.stdout]) {
     const found = findEnvelope(text);
     if (!found) continue;
     const { envelope } = found;
+    // A send HEY refused and kept as a draft: say it wasn't sent, and never "retry".
+    if (envelope.code === "not_delivered") return { failure: notDelivered(envelope), exitCode: 1, warnings: warnings(found.prefix) };
     // Even HEY's own envelope is translated: one clean line, no stack frames or escapes.
     const failure = { ok: false, error: cleanLine(String(envelope.error)) || info.message, kind: info.kind };
-    if (envelope.code !== undefined && envelope.code !== "" && envelope.code !== "unknown") failure.code = String(envelope.code);
+    const code = envelope.code === undefined || envelope.code === null ? "" : String(envelope.code);
+    if (code && code !== "unknown" && HEY_CODE.test(code) && !LIBRARY.test(code)) failure.code = code;
     const meta = envelope.meta === undefined || envelope.meta === "" ? undefined : cleanMeta(envelope.meta);
     if (meta !== undefined) failure.meta = meta;
-    const usage = USAGE_CODES.has(envelope.code) || /^usage: /i.test(String(envelope.error));
+    const usage = USAGE_CODES.has(code) || /^usage: /i.test(String(envelope.error));
     if (usage) failure.kind = "usage";
+    // hey-axi checked the command and flags against its catalog before HEY ran, so HEY
+    // not knowing one means the installed HEY is older than that catalog (for example
+    // v1.7.0 and `contact deliver`, which is only on HEY's main branch so far).
+    const unknown = usage && path && failure.error.match(/^unknown (flag|shorthand flag|command)[:\s]+["']?([^"'\s]+)["']?/i);
+    if (unknown) {
+      const what = /command/i.test(unknown[1]) ? `the command \`${path}\`` : `${unknown[2]} for \`${path}\``;
+      return {
+        failure: {
+          ok: false,
+          kind: "hey_outdated",
+          error: `the installed HEY CLI doesn't have ${what}${context.coverage ? `; hey-axi's catalog is HEY CLI ${context.coverage}` : ""}`,
+          help: ["Run `hey-axi version` to see which HEY is installed", "Upgrade HEY with `hey-axi upgrade`; commands not in a HEY release yet need a HEY built from basecamp/hey-cli main"],
+        },
+        exitCode: 1,
+        warnings: warnings(found.prefix),
+      };
+    }
+    // HEY refused a recipient it would otherwise drop: name it and the fix.
+    const badAddress = usage && failure.error.match(HEY_BAD_ADDRESS);
+    if (badAddress) {
+      const refusal = recipientRefusal(path, badAddress[1]);
+      return { failure: { ...failure, sent: false, reason: refusal.reason, hint: refusal.hint, help: `Fix or remove that address, then run the command again` }, exitCode: 2, warnings: warnings(found.prefix) };
+    }
     const hint = envelope.hint ? cleanLine(String(envelope.hint)) : "";
     if (hint && !/^Run 'hey(-axi)? --help'/.test(hint)) failure.hint = hint;
-    failure.help = usage ? `Run \`hey-axi ${path || "<command>"} --help\` for its arguments and flags` : info.help;
-    return { failure, exitCode: usage ? 2 : axiExitCode(result.status, envelope.code), warnings: warnings(found.prefix) };
+    failure.help = usage ? fixFor(context, { usageError: true }) : help();
+    return { failure, exitCode: usage ? 2 : axiExitCode(result.status, code), warnings: warnings(found.prefix) };
   }
   const detail = cleanLine(result.stderr) || cleanLine(result.stdout);
-  const failure = { ok: false, error: detail ? `${info.message}: ${detail}` : info.message, kind: info.kind, help: info.help };
+  const failure = { ok: false, error: detail ? `${info.message}: ${detail}` : info.message, kind: info.kind, help: help() };
   return { failure, exitCode: axiExitCode(result.status), warnings: [...warnings(result.stderr), ...warnings(result.stdout)] };
 }