hey-axi 0.2.0 → 0.3.1

package/README.md

@@ -1,8 +1,10 @@
 # hey-axi
 
+[![skills.sh](https://skills.sh/b/TangentialSolutions/hey-axi)](https://skills.sh/TangentialSolutions/hey-axi)
+
 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** (144 commands, plus the `login`/`logout` aliases and the `box <id>`-style shortcuts) by routing from HEY's own `hey commands --json` catalog.
+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.
 
 ## Install
 
@@ -24,7 +26,7 @@ hey-axi uses `$HEY_BIN` if it's set, and otherwise finds `hey` on `PATH`. launch
 ## Usage
 
 ```bash
-hey-axi                                    # home view: who/what, the Imbox (10 threads), next commands
+hey-axi                                    # home view: scope, last session, Imbox count + 10 threads, next commands
 hey-axi box view imbox                     # TOON: summary, a few columns per thread, notice, help
 hey-axi box imbox                          # HEY's shortcut forms work too
 hey-axi --account 2 search --from a@b.com  # global flags anywhere
@@ -32,7 +34,9 @@ hey-axi thread read 123                    # bodies cut at 1000 chars with "(tru
 hey-axi thread read 123 --full             # HEY's complete, untouched result
 hey-axi box view imbox --fields id,subject,creator.email_address   # choose columns (--fields all = every field)
 hey-axi thread read 123 --json             # the same shaped output as compact JSON
-hey-axi box view imbox --quiet             # data only, no envelope
+hey-axi box view imbox --quiet             # drop HEY's summary/notice/breadcrumbs; keep data, count and hints
+hey-axi reply 123 --message - < note.txt   # message body from stdin (saved as a draft)
+hey-axi setup scope --label Acme           # per-directory home view (.hey-axi.json)
 hey-axi --version                          # bare hey-axi version (fast path); `hey-axi version` adds HEY's
 hey-axi box view imbox --ids-only          # raw HEY output (also --count/--markdown/--html/--styled/--jq)
 hey-axi set-aside group view 4 --limit 5   # three-word commands
@@ -41,12 +45,15 @@ hey-axi move --help                        # usage, flags, examples, notes (no H
 
 ### Output shaping
 
-- **Home view.** `hey-axi` with no arguments prints `bin`, `description`, the Imbox summary and its 10 newest threads, and `help` lines with next commands. If HEY is missing, signed out or failing, it prints `status` with the fix and still exits 0.
-- **Minimal fields.** List commands show a few columns. The defaults per command are in `src/shape.js` and in each command's `--help`. `--fields a,b,c` picks columns, using default aliases (`from`, `subject`, `at`) or dotted paths (`creator.email_address`, `messages.0.summary`); `--fields all` keeps everything. An unknown field exits 2 and lists what's available.
+- **Home view.** `hey-axi` with no arguments prints `bin`, `description`, the `scope`, a one-line `last_session` summary (when session capture is on), a `count` of threads, the 10 newest threads, and `help` lines with next commands (including how to see the rest). If HEY is missing, signed out or failing, it prints `status` with the fix and still exits 0.
+- **Directory scope.** `hey-axi setup scope --label Acme` (or `--box`, `--search`, `--account`, `--limit`) writes `.hey-axi.json` in the current directory. The home view in that directory (or any subdirectory) then shows that label, box or search instead of the Imbox, and carries `--account` into every suggested command. `--status` shows it, `--remove` deletes it, and re-running with the same values is a no-op.
+- **Minimal fields.** List commands show at most 4 columns (usually an id, the thread id, sender and subject). The defaults per command are in `src/shape.js` and in each command's `--help`. `--fields a,b,c` picks columns, using default aliases (`from`, `subject`, `at`) or dotted paths (`creator.email_address`, `messages.0.summary`); `--fields all` keeps everything. An unknown field exits 2 and lists what's available.
 - **Truncation.** Strings longer than 1000 characters (120 in list cells) are cut and marked `… (truncated, N chars total)`, and a `help` line suggests `--full`.
-- **Aggregates and empty states.** `count: N of T total` when HEY reports a total; ``empty: 0 results for `…` `` when a list is empty.
-- **Help lines.** HEY's breadcrumbs become ``help: Run `hey-axi …` to …``, and HEY's hints are rewritten to name `hey-axi`.
-- **Fail loud.** Unknown flags and missing required flags (`move` without `--to`) exit 2 before HEY runs, listing the valid flags.
+- **Aggregates and empty states.** Every list gets a `count`: `N of T total` when HEY reports a total (in `meta` or next to the list), `N total` when HEY says the list is complete, `N shown; more available` with a `help` line naming `--all`/`--page`/`--limit` when HEY says there's more, and `N shown; no more pages reported` when HEY says neither. Lists of plain values and results holding several lists (`2 todos, 1 habits`) are counted too. An empty list prints ``empty: 0 results for `…` ``, and a command with no data prints `result: no data returned`. Non-JSON success output is wrapped as `ok: true` + `output`.
+- **Help lines.** A list always ends with a next step: HEY's own, or (when HEY gives none) the matching `view`/`show` command. HEY's breadcrumbs (next-command hints) become ``help: Run `hey-axi …` to …``, HEY's hints are rewritten to name `hey-axi`, and `--account`/`--base-url` are carried into them.
+- **Fail loud.** Unknown commands (with "did you mean"), unknown flags, flags with a missing or wrongly typed value (`--limit abc`), missing or extra arguments (`thread read` without an id), and missing required flags (`move` without `--to`) all exit 2 before HEY runs, with the valid usage.
+- **Idempotent mutations.** For state-setting commands (`seen`, `todo complete`, `label add`, `move`, `screener approve`, `timetrack stop`, name-based `create`s, …), when HEY's failure says that command's own end state already holds ("already seen", "already completed", "already exists", …), and for deletes whose target is already gone, hey-axi prints `ok: true`, `noop: true` and exits 0. The patterns are per command (`END_STATES` in `src/policy.js`); a generic conflict, any read, any send or reply, a `move` whose failure names a different box than `--to`, "already exists" on a create, and a delete whose not-found names something other than the target stay errors.
+- **Complete per-command help.** `hey-axi <command> --help` lists arguments, every flag with its type and default, global flags, and 2-3 examples, with no HEY call.
 - `--full` turns all of this off, and `--json` prints the same shaped result as compact JSON.
 
 ### How each kind of command runs
@@ -54,9 +61,10 @@ hey-axi move --help                        # usage, flags, examples, notes (no H
 | Kind | Commands | Behavior |
 |---|---|---|
 | JSON (default) | almost everything | `hey … --json` → TOON (or compact JSON with `--json`) |
-| Raw output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq`; `shell-completion generate`; `timetrack export` without `--output` | HEY's output is printed as-is |
-| Stream | `watch` | NDJSON relayed line by line as events arrive; Ctrl-C/SIGTERM forwarded to HEY |
-| Interactive | `tui`, `auth login`/`login`, `setup …`, `mcp`, `upgrade` | HEY gets the terminal (inherited stdio). `tui` refuses to start without a TTY |
+| Raw output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq`; `shell-completion generate`; `timetrack export` without `--output` | HEY's output is printed as-is once HEY succeeds; on failure only a structured error is printed |
+| Stream | `watch` | Each event printed as it arrives, as a TOON block followed by a blank line (`--json`: HEY's NDJSON, one line per event); Ctrl-C/SIGTERM forwarded to HEY |
+| Needs a person | `tui`, `mcp`, the `setup` wizard, `auth login`/`login` without `--token`/`--cookie` | Refused (exit 2) unless `--interactive` is passed, terminal or not, with the alternative (e.g. pass `--token`, or ask the user to run `hey-axi auth login --interactive` in their terminal). With `--interactive`, HEY gets the terminal (for `mcp`, its stdio, so an MCP client can register `hey-axi mcp --interactive`); the others also need a real terminal |
+| Captured | other `setup …` commands, `upgrade`, `auth login --token …` | Run with stdin closed, `HEY_NONINTERACTIVE=1` and `EDITOR`/`VISUAL=false`, so nothing can wait for input; output is shaped like any other command |
 
 ### Safety rails
 
@@ -65,20 +73,28 @@ hey-axi move --help                        # usage, flags, examples, notes (no H
   - `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.
 - **Credentials stay out of agent context.** `auth token` needs `--allow-secret` or `HEY_AXI_ALLOW_SECRETS=1`.
-- hey-axi's own flags (`--allow-send`, `--allow-secret`, `--fields`, `--full`) are never forwarded to HEY.
+- **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.
 
 ### Errors and exit codes
 
-Errors are printed as structured TOON: `ok: false`, `error`, and, when HEY gave them, `code`, `hint`, `meta`, plus a `help` next step (when HEY gave no hint) and `exit_code`. hey-axi passes HEY's exit code through: 1 usage, 2 not found, 3 auth, 4 forbidden, 5 rate limit, 6 network, 7 API, 8 ambiguous (`hey help exit-codes`). hey-axi's own refusals (unknown/incomplete command, unknown flag or field, missing required flag, blocked send, missing TTY) exit **2**. If `hey` can't be found, hey-axi exits **127**.
+Errors are printed as structured TOON on stdout: `ok: false`, `error`, a `kind`, and, when HEY gave them, `code`, `hint` and `meta`, plus a `help` next step. HEY's error text is translated too: only its first meaningful line is kept, stack traces, panics and terminal escapes are dropped, and debug keys (`stack`, `trace`, …) are removed from `meta`. On success HEY's stderr notices (warnings, `next_page: …`) go to stderr without that noise.
+
+| 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 |
 
 ## Agent integrations: session hook or skill
 
 There are two ways to give an agent hey-axi. You only need one:
 
-1. **Session hook (recommended where supported):** `hey-axi setup hooks` registers the home view as session-start context for **Claude Code** (`~/.claude/settings.json`), **Codex** (`~/.codex/hooks.json`, and it turns on `[features].hooks` in `~/.codex/config.toml`) and **OpenCode** (a managed plugin in `~/.config/opencode/plugins/`). Every new session then starts with your Imbox summary and the next commands, and no tool call is needed.
+1. **Session hooks (recommended where supported):** `hey-axi setup hooks` registers the home view as session-start context, and a session-end hook (`hey-axi hook session-end`), for **Claude Code** (`~/.claude/settings.json`), **Codex** (`~/.codex/hooks.json`, and it turns on `[features].hooks` in `~/.codex/config.toml`) and **OpenCode** (a managed plugin in `~/.config/opencode/plugins/`). Every new session then starts with your Imbox summary and the next commands, and no tool call is needed.
    - `--project` writes to the current directory's `.claude/`, `.codex/` and `.opencode/` instead.
    - `--status` reports what's installed, and `--remove` removes only hey-axi's entries.
    - Re-running is a no-op, or repairs the path if hey-axi moved. It uses [axi-sdk-js](https://www.npmjs.com/package/axi-sdk-js)'s installer.
+   - The session-end hook records a one-line summary (at most 300 characters) of what the session did (drafts saved, messages sent, other changes; command names and numeric ids only, never message content) under `$XDG_STATE_HOME/hey-axi` (or `$HEY_AXI_STATE_DIR`), and the next home view shows it as `last_session`. Nothing is recorded unless `setup hooks` turned it on, and `setup hooks --remove` turns it off. Entries are tagged with the agent session (`CLAUDE_CODE_SESSION_ID` in Claude Code, `CODEX_THREAD_ID` in Codex, or `HEY_AXI_SESSION_ID`) so concurrent sessions in one directory stay apart. OpenCode has no exact session-end event, so its plugin records on `session.idle`/`session.deleted`.
    - Note that the hook puts Imbox senders and subjects into every session's context.
 2. **Agent skill (broader support, loads on demand):** see below.
 
@@ -110,7 +126,7 @@ See [docs/listing.md](docs/listing.md) for how hey-axi gets listed on skills.sh
 npm run refresh-manifest     # runs only `hey version` and `hey commands`
 ```
 
-If the snapshot doesn't know a command, hey-axi asks the installed `hey commands --json` at runtime before reporting `unknown command`. So newer HEY releases work even before the snapshot is refreshed. 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. A weekly GitHub Action (`manifest-drift`) fails when the snapshot falls behind the latest HEY release.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hey-axi",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Agent-ergonomic AXI wrapper for Basecamp's HEY CLI: TOON output, send-to-draft safety, and a shareable agent skill",
   "keywords": [
     "axi",

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+, 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) signed in to a HEY account, and network access to app.hey.com.
 metadata:
   author: TangentialSolutions
   repository: https://github.com/TangentialSolutions/hey-axi
@@ -10,116 +10,119 @@ metadata:
 
 # hey-axi: HEY email for agents
 
-`hey-axi` runs Basecamp's HEY CLI (`hey`) and prints compact TOON. Lists show a few columns, long text is cut (the total size is shown), and suggestions name `hey-axi` commands. Every `hey` command works: `hey-axi <same args as hey>`.
+`hey-axi` runs Basecamp's HEY CLI (`hey`) and prints compact TOON. Lists show at most four columns and a count, long text is cut (the total size is shown), and suggestions name `hey-axi` commands. Every `hey` command works: `npx -y hey-axi <same args as hey>`.
+
+Examples below use `npx -y hey-axi`, which works without installing anything. If `hey-axi` is installed globally (`npm i -g hey-axi`), drop the `npx -y`.
 
 ## 1. Start here
 
-Run `hey-axi` with no arguments. It shows the Imbox and what to do next. If HEY is missing or signed out, it prints a `status` line and the fix instead.
+Run `npx -y hey-axi` with no arguments. It shows the mail for this directory's scope (the Imbox unless a `.hey-axi.json` says otherwise), a `count`, what the last session here did, and what to do next. If HEY is missing or signed out, it prints a `status` line and the fix instead.
 
 <!-- generated:home:start -->
 <!-- Generated by scripts/gen-skill.js from src/guide.js, the same text the home view prints. Do not edit by hand. -->
 What hey-axi is: HEY email, calendars and todos for agents: compact TOON over Basecamp's HEY CLI; outgoing mail is saved as a draft unless --allow-send
 
 Next steps the home view suggests:
-- Run `hey-axi thread read <topic_id>` to read a thread
-- Run `hey-axi box view imbox --limit 50` for more (also feed, papertrail, aside, later)
-- Run `hey-axi search "<query>"` to search mail
-- Run `hey-axi screener list` for senders waiting to be screened
-- Run `hey-axi reply <topic_id> --message "..."` to draft a reply (not sent without --allow-send)
-- Run `hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full
+- Run `npx -y hey-axi thread read <topic_id>` to read a thread
+- Run `npx -y hey-axi box view imbox --limit 50` for more (also feed, papertrail, aside, later)
+- Run `npx -y hey-axi search "<query>"` to search mail
+- Run `npx -y hey-axi screener list` for senders waiting to be screened
+- Run `npx -y hey-axi reply <topic_id> --message "..."` to draft a reply (not sent without --allow-send)
+- Run `npx -y hey-axi --help` for all commands; lists take --fields a,b / --fields all, long text --full
 <!-- generated:home:end -->
 
 Problems:
-- `hey-axi: command not found`: run it as `npx -y hey-axi …`, or install it (see "Install" below).
-- `status: HEY CLI not found` / exit **127**: install `hey`, or set `HEY_BIN=/path/to/hey` (cron/launchd jobs usually need `HEY_BIN=$HOME/.local/bin/hey`).
-- `status: not signed in` / exit **3**: ask the **user** to run `hey auth login` in their own terminal. It opens a browser. Don't try to sign in for them, and never print tokens (`auth token` is blocked unless `--allow-secret` is passed).
-- `hey-axi doctor` finds other login and config problems. `hey-axi version` shows both versions.
+- `status: HEY CLI not found` (`kind: hey_missing`): install `hey`, or set `HEY_BIN=/path/to/hey` (cron/launchd jobs usually need `HEY_BIN=$HOME/.local/bin/hey`).
+- `status: not signed in` (`kind: auth`): ask the **user** to run `npx -y hey-axi auth login --interactive` in their own terminal. It opens a browser, so without `--interactive` it is refused (exit 2); `tui`, `mcp` and the `setup` wizard work the same way. Never pass `--interactive` yourself. Don't try to sign in for them, and never print tokens (`auth token` is blocked unless `--allow-secret` is passed).
+- `npx -y hey-axi doctor` finds other login and config problems. `npx -y hey-axi version` shows both versions.
 
 ## 2. Read and triage
 
 ```bash
-hey-axi box list                          # boxes and their ids
-hey-axi box view imbox --limit 25         # rows in a box (imbox, feed, papertrail, aside, later, …)
-hey-axi thread read <topic_id>            # the thread (long bodies cut; --full for all)
-hey-axi search "invoice" --from a@b.com --date last_30_days
-hey-axi screener list                     # senders waiting to be screened
-hey-axi set-aside view   |   hey-axi bubble list   |   hey-axi draft list
+npx -y hey-axi box list                          # boxes and their ids
+npx -y hey-axi box view imbox --limit 25         # rows in a box (imbox, feed, papertrail, aside, later, …)
+npx -y hey-axi thread read <topic_id>            # the thread (long bodies cut; --full for all)
+npx -y hey-axi search "invoice" --from a@b.com --date last_30_days
+npx -y hey-axi screener list                     # senders waiting to be screened
+npx -y hey-axi set-aside view   |   npx -y hey-axi bubble list   |   npx -y hey-axi draft list
 ```
 
 **Which id to use.** Each `box view` row has an `id` (the box item) and a `topic_id` (the thread):
 - `topic_id` goes to `thread read`, `reply` and `forward`.
 - `id` goes to `seen`, `unseen`, `move`, `label`, `bubble`, `trash`, `spam` and `ignore`.
-- A row with kind `bundle` has no `topic_id`. Open it with `hey-axi bundle view <id>`.
+- A row with kind `bundle` has no `topic_id`. Open it with `npx -y hey-axi bundle view <id>`.
 - Screener commands take the clearance `id` from `screener list`. These aren't contact ids.
 
 ```bash
-hey-axi seen <id>...           hey-axi unseen <id>...
-hey-axi move <id>... --to feed          # imbox | feed | aside | later | papertrail
-hey-axi label add <id>... --to "Receipts"
-hey-axi bubble up <id>... --tomorrow    # or --now | --on <date> | --weekend | --next-week
-hey-axi screener approve <clearance-id> hey-axi screener deny <clearance-id>
-hey-axi trash <id>...          hey-axi spam <id>...      hey-axi ignore <id>...
+npx -y hey-axi seen <id>...           npx -y hey-axi unseen <id>...
+npx -y hey-axi move <id>... --to feed          # imbox | feed | aside | later | papertrail
+npx -y hey-axi label add <id>... --to "Receipts"
+npx -y hey-axi bubble up <id>... --tomorrow    # exactly one of --now | --on <date> | --tomorrow | --weekend | --next-week
+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.
 
-Output includes HEY's `next`/breadcrumb hints. Follow them for paging (`--page N`, `--all`) and follow-up commands instead of guessing. `hey <command> --help` explains a command in depth.
+Mutations are idempotent: when the desired state already holds (already seen, already deleted), the answer is `noop: true` with exit 0, not an error.
+
+Output includes HEY's breadcrumb hints as `help` lines (with your `--account` carried over), plus `Run … --all for all N` when a list was cut. Follow them instead of guessing.
 
 ## 3. Writing mail: drafts by default
 
 - `compose` and `reply` are **saved as drafts** automatically. The output starts with `sent: false`, `saved_as: draft` and an `axi_notice`. Tell the user that a draft is waiting in HEY. Don't claim it was sent.
   ```bash
-  hey-axi reply <topic_id> --message "Thanks, Thursday works."
-  hey-axi compose --to a@b.com --subject "Hi" --message "…"
-  hey-axi draft list   |   hey-axi draft show <draft-id>
+  npx -y hey-axi reply <topic_id> --message "Thanks, Thursday works."
+  npx -y hey-axi compose --to a@b.com --subject "Hi" --message "…"
+  cat reply.md | npx -y hey-axi reply <topic_id> --message -
+  npx -y hey-axi draft list   |   npx -y hey-axi draft show <draft-id>
   ```
+- 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.
 
-## 4. Output: fields, truncation, modes
+## 4. Output: fields, truncation, counts, modes
 
-- **Lists show a few columns** (for example `box view`: `id, topic_id, from, subject, seen, at`). Pick others with `--fields id,subject,creator.email_address`; aliases and dotted paths both work. `--fields all` keeps every field. An unknown field fails with exit 2 and lists the ones available. `hey-axi <command> --help` shows the defaults.
+- **Lists show at most four columns** (for example `box view`: `id, topic_id, from, subject`). Pick others with `--fields id,subject,seen,at,creator.email_address`; aliases and dotted paths both work. `--fields all` keeps every field. An unknown field fails with exit 2 and lists the ones available. `npx -y hey-axi <command> --help` shows the defaults.
 - **Long text is cut** at 1000 characters in detail views (thread bodies, drafts) and 120 in list cells, marked `… (truncated, N chars total)`. The output then includes a `Run … --full` help line. Use `--full` only when you need the whole text.
-- Lists say `empty: 0 results for …` when nothing matched, and `count: N of T total` when HEY knows the total. Follow `notice`/`help` for paging (`--page`, `--all`).
+- **Every list has a `count`**: `N of T total`, `N total` (HEY said the list is complete), `N shown; more available` (then a help line says how to get the rest), or `N shown; no more pages reported` (HEY gave no total and no further page). Empty lists say `empty: 0 results for …`.
 
 | Want | Use |
 |---|---|
-| Default: summary, data, help lines, as TOON | (nothing) |
+| Default: summary, count, data, help lines, as TOON | (nothing) |
 | The same as compact JSON | `--json` |
-| Data only | `--quiet` |
+| Less: data, count, empty state and hints only | `--quiet` |
 | HEY's complete, untouched result | `--full` (combine with `--json` for raw JSON) |
 | Raw HEY output | `--ids-only`, `--count`, `--markdown`, `--html`, `--styled`, `--jq '<expr>'` |
-| Help for one command: usage, flags, examples, notes (no network) | `hey-axi <command> --help` |
+| Help for one command: usage, arguments, flags with defaults, examples, notes (no network) | `npx -y hey-axi <command> --help` |
 
-Unknown flags are rejected before anything runs (exit 2, with the valid flags listed), and so are missing required flags such as `move --to`. Global flags like `--account <id|all>` can go anywhere.
+Everything is checked before HEY runs (exit 2, with the fix inline): unknown commands (with "did you mean"), unknown flags (the valid ones are listed), flags without a value, values of the wrong type (`--limit abc`), missing or extra arguments (quote multi-word text), missing required flags such as `move --to`. Global flags like `--account <id|all>` can go anywhere.
 
 ## 5. Watching for changes
 
-`hey-axi watch` streams HEY's NDJSON one line at a time until it's interrupted. Use bounded forms in agent sessions:
+`npx -y hey-axi watch` streams each event as it arrives (a TOON block per event, separated by blank lines; add `--json` for HEY's NDJSON, one line per event) until it's interrupted. Use bounded forms in agent sessions:
 
 ```bash
-hey-axi watch --box imbox --events new --exit-on-first --timeout 10m
+npx -y hey-axi watch --box imbox --events new --exit-on-first --timeout 10m
 ```
 
 Lines also include `ready`, `disconnected` and `resync`. On `resync`, re-read that box.
 
 ## 6. Errors and exit codes
 
-Errors are TOON on stdout: `ok: false`, `error`, plus `code`/`hint`/`meta` when HEY provided them, a `help` line with the next step, and `exit_code`. Exit codes: 0 ok · 1 usage · 2 not found, or a hey-axi refusal (unknown flag or field, blocked send) · 3 auth · 4 forbidden · 5 rate limit · 6 network · 7 API · 8 ambiguous · 127 `hey` missing. 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`, `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.
 
 ## Install
 
 ```bash
 # HEY CLI (macOS/Linux)
 curl -fsSL https://hey.com/install-cli | bash        # or: brew install --cask basecamp/tap/hey
-hey auth login                                      # the user runs this once, interactively
+npx -y hey-axi auth login --interactive            # the user runs this once, in their own terminal
 
-# hey-axi
+# hey-axi (optional: every example here also works as npx -y hey-axi …)
 npm i -g hey-axi                                    # puts `hey-axi` on PATH
 ```
 
-No global install? Prefix any command with `npx -y`, e.g. `npx -y hey-axi box view imbox`. It's slower on the first run, so install it if you'll run many commands.
-
-Optional: `hey-axi setup hooks` (user-invoked) shows the home view at the start of every Claude Code, Codex and OpenCode session. `--project` limits it to one directory, and `--remove` undoes it.
+Session hook (the alternative to this skill; you only need one): `npx -y hey-axi setup hooks` (user-invoked) shows the home view at the start of every Claude Code, Codex and OpenCode session and records what each session did for the next one. `--project` limits it to one directory, and `--remove` undoes it. `npx -y hey-axi setup scope --label <name>` focuses a directory's home view on one label, box or search.
 
 More commands (calendar, todos, habits, journal, time tracking, contacts, collections), with their default fields: [references/commands.md](references/commands.md).

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

@@ -2,9 +2,9 @@
 
 <!-- Generated by scripts/gen-skill.js from src/manifest.json (hey 1.7.0). Do not edit by hand. -->
 
-Every command from HEY CLI 1.7.0 (151 runnable paths, including the `login`/`logout` aliases and shortcut forms such as `box <name>`). Run each as `hey-axi <command> [args] [flags]`.
-`hey-axi <command> --help` shows usage, flag descriptions, 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>`. Anything else unknown is rejected (exit 2).
+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).
+`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).
 
 | Command | What it does | Flags | hey-axi behavior |
 |---|---|---|---|
@@ -13,33 +13,33 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `account use` | Set the default linked mail account |  |  |
 | `attachment list` | List a thread's attachments | `--allow-partial` | fields: id, filename, content_type, byte_size |
 | `attachment save` | Save an attachment to disk | `--force` `--output <v>` |  |
-| `auth login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | interactive (user runs it) |
+| `auth login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` |  |
 | `auth logout` | Clear stored credentials |  |  |
 | `auth refresh` | Force token refresh |  |  |
 | `auth status` | Show authentication status |  |  |
 | `auth token` | Print access token to stdout | `--stored` | refused unless `--allow-secret` |
-| `box` | List HEY boxes and their email threads | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `box` | List HEY boxes and their email threads | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `box list` | List your HEY boxes | `--all` `--limit <v>` | fields: id, kind, name |
-| `box view` | List email threads in a box | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
-| `bubble list` | List bubbled-up and scheduled email threads | `--all` `--limit <v>` | fields: id, topic_id, from, subject, seen, at, bubbles_up |
+| `box view` | List email threads in a box | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
+| `bubble list` | List bubbled-up and scheduled email threads | `--all` `--limit <v>` | fields: id, topic_id, subject, bubbles_up |
 | `bubble pop` | Cancel bubble-ups |  |  |
 | `bubble up` | Bubble email threads up | `--next-week` `--now` `--on <v>` `--tomorrow` `--weekend` |  |
 | `bulk-reply preview` | Preview threads and recipients without sending |  |  |
 | `bulk-reply send` | Send one reply to multiple threads | `--attach <v>` `--message <v>` `--message-html <v>` | refused unless `--allow-send` |
 | `bulk-reply undo` | Recall a delayed bulk reply |  |  |
-| `bundle` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
-| `bundle view` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `bundle` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
+| `bundle view` | List the unseen threads a bundle groups | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `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 |
-| `collection` | List and manage email collections | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, 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>` |  |
 | `collection list` | List your email collections | `--all` `--limit <v>` | fields: id, name |
 | `collection remove` | Remove email threads from a collection | `--from <v>` |  |
 | `collection update` | Update a collection | `--name <v>` `--summary <v>` |  |
-| `collection view` | List email threads in a collection | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `collection view` | List email threads in a collection | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `commands` | List all available commands |  |  |
 | `compose` | Write and send a new email | `--attach <v>` `--bcc <v>` `--cc <v>` `--draft` `--from <v>` `--message <v>` `--message-html <v>` `--no-name-tag` `--subject <v>` `--thread-id <v>` `--to <v>` | saved as a draft unless `--allow-send` |
 | `config set` | Set a configuration value in the global config |  |  |
@@ -56,7 +56,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `contact note show` | Read a private contact note |  |  |
 | `contact show` | View a contact |  |  |
 | `contact show-again` | Show a hidden contact again |  |  |
-| `contact threads` | List every thread with a contact | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
+| `contact threads` | List every thread with a contact | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `contact unbundle` | List a contact's mail separately |  |  |
 | `contact update` | Edit a contact | `--alias <v>` `--email <v>` `--name <v>` |  |
 | `doctor` | Find login and configuration problems |  |  |
@@ -66,11 +66,11 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `draft send` | Deliver a draft |  | refused unless `--allow-send` |
 | `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, calendar |
+| `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 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, calendar |
-| `event week` | List the events of one week, as HEY draws it | `--all` `--limit <v>` | fields: id, title, starts_at, ends_at, calendar |
+| `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 |
 | `forward` | Forward the latest message in a thread | `--bcc <v>` `--cc <v>` `--message <v>` `--message-html <v>` `--to <v>` | refused unless `--allow-send` |
 | `habit complete` | Mark a habit as complete for a date | `--date <v>` |  |
 | `habit create` | Create a habit | `--color <v>` `--days <v>` `--icon <v>` `--name <v>` |  |
@@ -79,47 +79,50 @@ 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, seen, at |
+| `label` | List and manage email labels | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
 | `label add` | Add a label to email threads | `--to <v>` |  |
 | `label create` | Create a label and add it to email threads |  |  |
 | `label list` | List your email labels | `--all` `--limit <v>` | fields: id, name |
 | `label remove` | Remove labels from email threads | `--from <v>` |  |
-| `label view` | List email threads with a label | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
-| `login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` | interactive (user runs it) |
+| `label view` | List email threads with a label | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
+| `login` | Authenticate with the HEY server | `--cookie <v>` `--no-browser` `--token <v>` |  |
 | `logout` | Clear stored credentials |  |  |
-| `mcp` | Serve HEY to MCP clients over stdio | `--domains <v>` `--read-only` | interactive (user runs it) |
+| `mcp` | Serve HEY to MCP clients over stdio | `--domains <v>` `--read-only` |  |
 | `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 deny` | Turn a sender away | `--spam` |  |
-| `screener history` | List the senders already screened | `--all` `--page <v>` | fields: id, status, name, email_address, decided |
-| `screener list` | List the senders waiting to be screened | `--all` `--page <v>` | fields: id, name, email_address, subject, topic_id |
-| `search` | Search email threads and messages | `--all` `--any <v>` `--attachment <v>` `--date <v>` `--exact <v>` `--from <v>` `--in <v>` `--label <v>` `--none <v>` `--page <v>` `--required <v>` `--subject <v>` `--to <v>` | fields: id, topic_id, subject, from, at |
+| `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 |
+| `search` | Search email threads and messages | `--all` `--any <v>` `--attachment <v>` `--date <v>` `--exact <v>` `--from <v>` `--in <v>` `--label <v>` `--none <v>` `--page <v>` `--required <v>` `--subject <v>` `--to <v>` | fields: topic_id, subject, from, at |
 | `search filters` | List available search refinement values |  |  |
 | `seen` | Mark email threads as seen |  |  |
+| `set-aside` | List and group email threads in Set Aside |  |  |
+| `set-aside group` | List and manage groups in Set Aside |  |  |
 | `set-aside group add` | Add email threads to a Set Aside group | `--to <v>` |  |
 | `set-aside group create` | Gather email threads into a new Set Aside group |  |  |
 | `set-aside group delete` | Break up a Set Aside group |  |  |
 | `set-aside group list` | List the groups in Set Aside |  | fields: id, thread_count |
 | `set-aside group remove` | Take email threads out of their Set Aside group |  |  |
-| `set-aside group view` | List email threads in a Set Aside group | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
-| `set-aside view` | List email threads in Set Aside | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject, seen, at |
-| `setup` | Set up HEY for first use | `--silent-success` `--skip-agents` `--skip-omarchy` | interactive (user runs it) |
-| `setup agents` | Install or remove HEY coding-agent integrations | `--remove` | interactive (user runs it) |
-| `setup claude` | Connect Claude Code to HEY |  | interactive (user runs it) |
-| `setup codex` | Connect Codex to HEY |  | interactive (user runs it) |
-| `setup omarchy` | Install hey into the Omarchy desktop | `--no-notify` `--notify` `--remove` | interactive (user runs it) |
+| `set-aside group view` | List email threads in a Set Aside group | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
+| `set-aside view` | List email threads in Set Aside | `--all` `--limit <v>` `--page <v>` | fields: id, topic_id, from, subject |
+| `setup` | Set up HEY for first use | `--silent-success` `--skip-agents` `--skip-omarchy` |  |
+| `setup agents` | Install or remove HEY coding-agent integrations | `--remove` |  |
+| `setup claude` | Connect Claude Code to HEY |  |  |
+| `setup codex` | Connect Codex to HEY |  |  |
+| `setup omarchy` | Install hey into the Omarchy desktop | `--no-notify` `--notify` `--remove` |  |
 | `share` | Get a sharing link for an email thread |  |  |
 | `shell-completion generate` | Print a completion script to stdout |  | raw output |
 | `shell-completion install` | Install shell completions where your shell will find them | `--force` |  |
+| `skill` | Manage the embedded agent skill |  |  |
 | `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 |  |  |
@@ -132,7 +135,7 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `timetrack delete` | Delete a time track |  |  |
 | `timetrack edit` | Edit a completed time track | `--category <v>` `--end <v>` `--notes <v>` `--start <v>` |  |
 | `timetrack export` | Export completed time tracks as CSV | `--force` `--output <v>` | raw CSV unless `--output <file>` |
-| `timetrack list` | List completed time tracks | `--all` `--category <v>` `--limit <v>` | fields: id, starts_at, ends_at, category, notes |
+| `timetrack list` | List completed time tracks | `--all` `--category <v>` `--limit <v>` | fields: id, starts_at, ends_at, category |
 | `timetrack start` | Start time tracking |  |  |
 | `timetrack stop` | Stop time tracking | `--category <v>` |  |
 | `todo add` | Create a new todo | `--date <v>` `--title <v>` |  |
@@ -141,12 +144,12 @@ Flags every command accepts: `--account <id|all>`, `--json`, `--quiet`, `--field
 | `todo list` | List todos | `--all` `--calendar <v>` `--ends-on <v>` `--limit <v>` `--starts-on <v>` | fields: id, title, starts_at, completed_at |
 | `todo uncomplete` | Mark a todo as incomplete |  |  |
 | `trash` | Move email threads to Trash |  |  |
-| `tui` | Launch the interactive terminal UI | `--instance <v>` `--remote` `--screener` `--topic <v>` `--topic-title <v>` | interactive, needs a TTY (user runs it) |
+| `tui` | Launch the interactive terminal UI | `--instance <v>` `--remote` `--screener` `--topic <v>` `--topic-title <v>` |  |
 | `unseen` | Mark email threads as unseen |  |  |
 | `unshare` | Turn off an email thread's sharing link |  |  |
-| `upgrade` | Upgrade hey to the latest release |  | interactive (user runs it) |
+| `upgrade` | Upgrade hey to the latest release |  |  |
 | `version` | Show the installed hey version |  |  |
-| `watch` | Follow email threads and calendars as they change | `--box <v>` `--events <v>` `--exit-on-first` `--run-async <v>` `--run-sync <v>` `--since <v>` `--timeout <v>` | streams NDJSON |
+| `watch` | Follow email threads and calendars as they change | `--box <v>` `--events <v>` `--exit-on-first` `--run-async <v>` `--run-sync <v>` `--since <v>` `--timeout <v>` | streams events (TOON; --json for NDJSON) |
 | `workflow` | List and manage email workflows |  |  |
 | `workflow add` | Add email threads to a workflow stage | `--stage <v>` `--to <v>` |  |
 | `workflow create` | Create an email workflow |  |  |