feat(agent-platform-design): add AXI as the third interface class (A3.2)

[ductiletoaster]

Task A3.2 — PixelOven Agent Stack Program Plan v3.5, Phase 1. Acceptance: "Crew PR merged."

agent-platform-design's interface-boundary framework had two classes, MCP and CLI — and no place for a tool that is agent-facing but must stay on one machine. That gap is load-bearing for the program: pulse's observation tools (calendar, slack, email) carry personal workplace OAuth credentials, and the framework as written offered them only "MCP tool first" — i.e. put a mailbox behind a shared gateway key. This adds the third class and makes the rule explicit.

The three classes

Class	Primary caller	Authorization	Where it runs
MCP	An LLM mid-task, across every consumer	Federated — the gateway is the authorization boundary; tools are VK-scoped and shared	Anywhere the gateway reaches
AXI	An agent, on the machine it is already running on	None of its own — inherits that machine's credentials and the invoking user's identity	Local: workstation, worker sandbox
CLI	Humans, scripts, CI	Whatever the shell already holds	Terminals, pipelines, runbooks

Authorization picks the class, not capability. Shared and centrally revocable → MCP. Personal to one machine or human, must never leave it → AXI. Human/script/CI caller → CLI. AXI's missing auth story is the reason to reach for it with workplace credentials, not a hole to plug — the blast radius stays the machine that already holds the credential.

What the section now carries

• The three-class table plus what an AXI actually is (the upstream 10-principle standard: token-efficient output, definitive empty states, structured errors and exit codes, no interactive prompts, next-step suggestions).

• The failure mode of choosing wrong, per class — MCP for a personal credential (one mailbox becomes everyone's capability, revocation all-or-nothing); MCP for a single-machine need (resident schema tokens in every consumer's context, finite tool budgets); AXI for a multi-consumer need (N credential copies, no central revocation, unreachable from in-cluster agents); human-shaped CLI for an agent caller (help text instead of data, prompts that hang unattended runs, turns burned on every call).

• The measured economics, attributed per arm — browser benchmark, 490 runs (14 tasks × 7 conditions × 5 repeats), Claude Sonnet 4.6:

  Class	Condition	Cost/task	Input tokens/task	Success	Turns
  AXI	chrome-devtools-axi	$0.074	~79K	100%	4.5
  CLI (raw baseline)	agent-browser	$0.088	~93K	99%	4.8
  MCP	chrome-devtools-mcp	$0.100	~185K	99%	6.2

  With the mechanism, which is the part that generalises: tool schemas are resident in context (~28.5% of input tokens in that run), so MCP pays them every turn whether or not a tool is called — the ~2.3× token gap. The section also says plainly that these are the standard author's own runs and should be read as an order-of-magnitude signal, per this skill's own rule about dated, sourced capability claims.

• The worked example the program plan supplies (§2.5): chrome-devtools-axi for local workstation browsing vs a federated browserless / Playwright-MCP for VK-scoped cluster browsing. Both stay — chosen by caller, not by capability. Plus the general corollary: availability in one class is not an argument for removing another.

• The pre-existing rules survive unchanged — MCP canonical + CLI as a thin wrapper for shared capabilities, and the off-the-shelf-first default that follows.

Sources (G-2: pinned)

Verified 2026-08-17 against kunchenguid/axi@408a6536625e5b05e5c56e6c4a04fe83e1f510a5 (2026-08-16):

• .agents/skills/axi/SKILL.md — the 10 principles
• README.md — summary results table
• bench-browser/published-results/report.md — per-condition figures and the schema-overhead limitation (it reports the MCP arm at $0.1005; the README summary rounds to $0.101 — the skill notes both)

Upstream was read only; nothing was posted to kunchenguid/* (guardrail G-5).

Noted deltas (mechanical — flag if unwanted)

Two pointers named the old two-class table by shape, so they would have taught the superseded rule:

1. skills/mcp-server-design/SKILL.md — "the full MCP-vs-CLI decision table" → the three-class table, plus one sentence: a capability whose credential must never leave one machine belongs in an AXI. Description updated to match.
2. templates/AGENTS.md — the ## Interface boundaries block, so a newly onboarded consumer inherits the three-class rule rather than the two-class one.

Both are one-paragraph edits within the same doctrine; drop either if you'd rather keep this PR to the single skill.

Not touched: .claude-plugin/plugin.json's name/repository fields still read harmony-crew / ductiletoaster — that is M0.2's in-flight work, deliberately left alone to avoid a collision.

Checks (run locally)

python3 scripts/check_skills.py · render_roles.py --check · check_skill_refs.py · gen_catalog.py --check · templates YAML parse — all pass. gitleaks detect --no-git clean (G-3). Version 0.23.0 → 0.24.0 in both plugin.json and package.json per docs/MAINTAINERS.md; docs/CATALOG.md regenerated. Minor rather than patch: this adds a class to a decision framework consumers route real design decisions through.

Skills only — crew stays declarative, no executable behavior added.

---

Task A3.2, PixelOven Agent Stack — Program Plan v3.5 (Phase 1). Feeds pulse C1.2 (observation AXI profile) and the harmony-side mapping in plan §2.5.