docs+fix: reconcile 22 documentation claims with the code; emit the contact phones the docs promised

[sweetrb]

Audit of every documentation surface against the live 50-tool inventory (dumped from the built server over MCP, not inferred). 22 findings, each adversarially verified before landing.

The one that is a real bug, not a doc bug

search-contacts promised phone numbers in four places — the tool description twice (Use when: … find their email address(es)/phone(s) and Returns: … and phone numbers), the README, and CLAUDE.md — and returned them in zero. contactsDb already read phones in the same SQL that reads emails; the handler discarded them one line before serialization, from both the text and structuredContent.

Same class as 2.10.1's colorApplied: false: a documented output contract the handler silently fails. An agent asked for someone's number got a result with no phone and could only conclude none was on file.

Verified against the real Contacts DB after the fix:

  - Mark Higdon (no email; (269) 275-5709)

That contact returned "emails": [] and nothing else before — the phone was read and thrown away.

Contradicted by the code

Doc	Claimed	Actual
README search-contacts	limit param, default 10	no such param; results uncapped — a complete set reads as clipped
README get-unread-count	omit mailbox → total	INBOX only since 2.8.15 (summing double-counted on Gmail)
README Known Limitations	"No smart mailboxes"	four smart-mailbox tools shipped in 2.9.0 — documented in the same README
README fetch-attachment	numeric ids only	schema and handler accept imap: ids
skills/apple-mail/SKILL.md	resolve-message-id "needed for flag colors"	8th surviving copy of the text 2.10.1 fixed everywhere else

That last one is the most consequential: an agent planning from the skill's tool table would resolve imap: ids purely to color a flag, reintroducing the AppleScript/TCC dependency 2.10.0 removed — the one that previously killed four consecutive scheduled jobs.

Missing

• get-message's mailbox/account params — the documented cure for large-folder timeouts, undiscoverable because the table omitted them
• search-contacts needs Node 22.5+ (node:sqlite) and Full Disk Access, and returns an empty list rather than an error without them — so "no contacts found" could mean "cannot read Contacts"
• Smart-mailbox tools need Full Disk Access; every read failure surfaced as "no smart mailboxes"
• get-mail-stats's account scope (documented as "Parameters: None")
• flagColorIndex — the only way to read a flag color — existed only in the CHANGELOG
• SKILL.md had no smart-mailbox section at all; added one

Obsolete

• docs/IMAP-SETUP.md still taught the pre-2.6.0 rule that reads need a matching account to route to IMAP — since 2.6.0 they prefer IMAP automatically and fan out across configured accounts
• Development block told contributors npm install, which package.json's own preinstall guard hard-fails
• SECURITY.md documented a numeric-only message-id regex superseded by imap: ids
• Antigravity marketplace still advertised the removed Hermes packaging

Corrected privacy claim

SECURITY.md and the README both said no data is sent to external servers. That is false once the opt-in IMAP/SMTP backends are configured — they connect to your provider, which is the point. Reframed as no third parties: nothing reaches this project or anyone else, and with the default AppleScript backend everything stays on-device.

Verification

• lint 0 errors (10 pre-existing no-explicit-any warnings, count unchanged), typecheck, format:check, 417 tests, plugin-manifest sync, skills drift check, bundle-matches-source — all pass
• skills/ edited at the canonical root only, then pnpm run sync:skills
• Real-data check of the search-contacts change against the live Contacts DB (above)

Checklist

• Version bumped 2.10.2 → 2.10.3 with a real ## [2.10.3] CHANGELOG heading (tool descriptions and handler output are shipped bytes)