Close AXI admission gaps (principles 2-7, 9, 10); v0.3.0

[tangentus]

Why

The axi.md admission review of hey-axi@0.2.0 (pinned to 2af99c1, kunchenguid/axi#226) admitted it only as an exception. It found AXI principles 2-7, 9 and 10 partly unmet. This PR fixes each gap and releases the result as 0.3.0.

These rules stay as they were:

• Nothing is sent without --allow-send. compose and reply still become drafts, and forward, draft send and bulk-reply send are still refused.
• Tests only ever use a fake hey.
• HEY's next-command hints (breadcrumbs) are kept.

What changed, by principle

• 2 Minimal schemas: every default list schema has at most 4 fields, and the heuristic for unknown lists is capped at 4. Results that hold several lists get a minimal schema for each list.
• 3 Truncation: the home view keeps the --full hint. Long plain-text output is cut with a size and a --full hint, and --full returns it whole.
• 4 Aggregates: every list has a count. Lists without HEY's envelope, lists of plain values and results with several lists are counted too. HEY's total_count/next_page are read from meta or from next to the list (box listings). hey-axi only says "total" when HEY does; otherwise the count reads "N shown; no more pages reported".
• 5 Empty states: lists without HEY's envelope get explicit empty states. --quiet keeps the count, the empty state and hey-axi's hints. No data prints "no data returned".
• 6 Errors and exit codes:
  • Missing flag values, wrong value types, switches given a value (--draft=false), unknown letters in stacked shorthands (-vZ), and missing or extra positional arguments all exit 2 before HEY runs.
  • Unknown commands are rejected from the manifest alone (no runtime hey commands), with "did you mean" suggestions.
  • Exit codes are now 0/1/2, and every error has a kind.
  • HEY's error envelopes and plain-text errors are reduced to one clean line. Stack traces, panics and ANSI codes are dropped, and debug keys are removed from meta.
  • Raw output is held until HEY succeeds, so a failed run prints only the structured error.
  • Idempotent no-ops: state-setting commands answer ok: true, noop: true (exit 0) only when HEY's failure matches that command's own end-state pattern. Deletes of missing items are no-ops too. Reads, sends and generic conflicts stay errors.
  • Nothing can prompt:
    • tui, mcp, the setup wizard and browser login are refused unless the new --interactive opt-in is given.
    • Captured runs get closed stdin, HEY_NONINTERACTIVE=1 and EDITOR/VISUAL=false.
    • Content that would open an editor must be passed up front; --message - reads it from stdin.
• 7 Ambient context:
  • hey-axi setup scope writes .hey-axi.json, so the home view is directory-scoped (box, label or search, plus account).
  • setup hooks also installs session-end hooks for Claude Code, Codex and OpenCode. These record command names and numeric ids only, tagged with the agent session id when available, and the next home view shows a one-line last_session.
  • The skill examples use npx -y hey-axi.
• 9 Contextual disclosure: --account/--base-url are carried into object and string breadcrumbs, notices and error fix-it lines. The home view says how to see the rest of a truncated list.
• 10 Help:
  • Every one of the 154 runnable commands' --help lists its arguments, every flag with its type and default, every global flag with its default, and 2-3 examples.
  • The manifest now keeps every flag default and type.
  • The home view's bin is an absolute path, with ~ for the home directory.

Also changed:

• set-aside, set-aside group and skill are now runnable.
• Added CHANGELOG.md; updated README and AGENTS.md.
• Regenerated the skill reference and benchmarks: about 89.7% fewer tokens than hey --json.

Tests

• npm test: 141/141 pass. All tests use the fake hey, and the new test/admission.test.js covers each item above.
• npm run skill:check: up to date.
• The benchmark doc matches a fresh run.

Not merged and not published. The npm release (0.3.0) and the axi.md re-pin wait for owner approval.

Independent re-review status

I ran the same codex-based admission review the axi pipeline uses against each branch head. The latest pass (at b21f95a) returned inconclusive; the pass before it (at c5dd79d) returned exception. Every original gap is now resolved or narrowed. The remaining findings are listed below.

Design choices to confirm:

• The home view is account-wide unless .hey-axi.json is set.
• --interactive stays as an explicit opt-in for person-only commands.
• HEY's breadcrumbs are always kept.

Wrapper edge cases still open:

• No-op matching is still wording-based. For example, label add can match "already in" for a different label, and a batch seen can be acknowledged when only one id was already seen.
• The first line of HEY's own error text is kept (cleaned, not rewritten).
• Primitive arrays nested inside a container get no count.
• --page is appended rather than replaced.
• Scope values aren't shell-quoted in suggestions.
• The setup commands' help doesn't state the defaults of their switches.

Upstream axi-sdk-js: the start hook doesn't quote paths, and its PATH lookup can pick a shadowed executable.