Docs audit: three of five clients explain themselves, two do not, and usage is documented nowhere

v2.1.0 reconciliation — 20 September 2026

The earlier audit below describes an older product. Current contract:

• /account shows balance and Top up / Transfer / Usage. /account/usage includes transaction history; legacy browser Billing routes there (#1835, #1836).
• /account/clients explains IMAP/SMTP, XMPP and assistant API setup; /account/tokens explains tokens, OAuth registrations/callbacks and SSH keys (#1858).
• /developers documents product requests on /agent, /agent/, /inbox and /work using content negotiation (#1862).
• /api documents /api/v1//; /tools documents service tools through /mcp. Primary and x402 hosts retain the same service contract; x402 adds payment handling (#1861, #1862). Tokens restrict permissions rather than selecting catalogues.
• Services remains an operator directory. Do not add more public navigation or restore channel advertising on the landing to address this issue.

Remaining: verify the current README/served guidance against working examples, clarify usage charging where it is read, check the SSH example and stale package comments, and check authenticated client setup on mobile. Preserve existing compatibility routes. Subscription/pricing documentation belongs with #1867.

The old observations are retained as audit history, not assertions about v2.1.0.

---

The doc policy is deliberate and mostly working: two served pages (/about, /install), everything else in the repository, on the claim that the product explains itself rather than needing a manual. Audited that claim rather than assuming it.

Where it holds

• MCP — /tools is genuinely good. It explains connecting, gives a working ~/.cursor/mcp.json, covers Claude Desktop including the trap that pasting the URL into claude_desktop_config.json will not work, and lists every tool with a form to try one.
• API — /api exists and is derived from the same specs, so it cannot drift from what the tools actually do.
• Services — /services exists, one entry per service, generated.
• Web — needs no documentation; it is the thing you are looking at.
• Shell — /shell shows the exact ssh you@host line, computed from the configured port. Correct place for it.

Where it does not

1. The CLI had no discoverable commands — fixed in a560e877

mu --help printed the tool list and nothing else. login, ask, agent, setup, --url appear nowhere in it, because it is generated from the service catalogue and those are not services. The summary containing all of them was printed only when the tool fetch failed, so it was reachable only once something was broken.

Fixed: bare help is about the program, mu tools is the catalogue.

2. Usage and billing are documented nowhere

usage appears 0 times in both README.md and docs/INSTALL.md. It is a nav item and a thing people are charged for. PRICING.md covers what things cost and who pays, but it is repo-only and is about policy rather than about reading your own meter. Nothing tells somebody what /usage shows, when a call is charged, or how to see what they spent.

• Decide whether this belongs on /usage itself (probably — same argument as /tools) or in the README

3. The README lists Shell as a client and never shows the command

| **Shell** | SSH into your own machine, from a terminal | and, two lines later, SSH for a shell. Neither shows ssh you@micro.mu. The only place the command appears is /shell, behind sign-in, and docs/INSTALL.md covers only the operator half (SHELL_SSH_PORT).

Every other client has a worked example in the README — Email, CLI, App, Agent. Shell has a table row.

• One example in the README's client table or a short section, so the funnel says what the thing is

4. docs.go claims a page that is a redirect

The package comment says "So three: /about, which is what this is; /help, which is how you point an agent at it and what that costs; and /install". /help is a redirect to /tools — pages has two entries. The comment describes an arrangement that no longer exists, in the file that would tell the next person what the arrangement is.

• Correct the comment to two, or restore /help if it should exist

5. The inbox is undocumented for anyone who has not seen it

/inbox is sign-in only, which is right. But it is the centre of the product — "every conversation this account has had with an agent, on whichever client it arrived, in one record" — and nothing outside the repository says that. README.md mentions "inbox" four times, all in passing.

• Decide whether the landing page carries this. It is the strongest thing about the product and it is currently invisible until after signup.

Not a gap

INSTALL.md is 907 lines and covers systemd with socket activation, Docker, nginx, mail with DKIM and deliverability, IMAP, Tor, and every config var — with a test that fails when a var is undocumented. That is the strongest document in the repository and nothing here is a criticism of it.

Start by comparing README.md and the served guidance with the current contract in the issue, then inspect docs.go, docs/INSTALL.md, and the relevant client setup pages. Verify the working examples, usage charging explanation, SSH example, package comments, and authenticated mobile setup without changing compatibility routes. Done means each remaining gap is corrected or explicitly documented as belonging elsewhere.