docs: fix stale/inaccurate documentation from a repo-wide audit

[jiashuoz]

Summary

Scheduled documentation audit across all .md files in the repo (READMEs, docs/, examples, plugin/skill docs), cross-checked against current code. docs/design/** and docs/superpowers/** (dated design docs/plans) were intentionally excluded — staleness there is expected and out of scope.

Before starting, I checked for prior unmerged doc-audit work: no currently open PR touches documentation. Six earlier claude/relaxed-cerf-* doc-audit branches still exist on the remote, but pull_request_read on each of their PRs (#716, #666, #731, #763, #812, #905) confirms merged: true and their content is already present on main — nothing in this PR duplicates them. (Note: the list-PRs API's merged field reported false for all of these, which is misleading — pull_request_read/the PR page is the reliable source.)

Changes by file

• cli/README.md, cli/CHANGELOG.md, cli/src/commands/send.ts — all three said a review hold caused a scheduled self-send to drop its --send-at schedule entirely. That's backwards: internal/agent/schedule_hold_test.go's TestDeliverOutbound_HoldPreservesScheduledAt (feat(api): preserve send_at across a review hold instead of discarding it #815) and the server's own field docs (internal/httpapi/reviews.go, internal/httpapi/outbound.go) confirm a schedule caught by a hold survives it — the held message keeps its send_at, and approving it submits at that instant if still future, or immediately if it's passed. The TS/Python SDK READMEs already documented this correctly; only the CLI docs and a matching source comment had it backwards.
• docs/api.md — the beta-operation-count summary line said "29 beta operations," but the table right below it lists 31 (the getAgentMetrics/getAccountMetrics delivery-metrics endpoints were added to the table without updating the count above it). Fixed to 31.
• README.md — the GA banner's explicit beta-surface list omitted delivery metrics, which is marked x-stability-level: beta in the spec and listed as beta in docs/api.md's own table. Added it. Also softened the self-host "every feature works the same" claim, which directly contradicted the Content screening section's note a few paragraphs later that screening isn't yet enabled on the hosted service.
• docs/runbooks/mcp-server.md — said MCP_ALLOWED_HOSTS defaults to api.e2a.dev. That literal default was removed in fix: stop defaulting to the operator's infrastructure #918 ("stop defaulting to the operator's infrastructure"); mcp/src/bin/http.ts now derives the allowlist from MCP_PUBLIC_URL's host if set, or refuses to start. mcp/README.md was already updated for this; this runbook line wasn't.
• plugins/e2a/skills/e2a-integrate/references/rest-openapi.md — pointed the canonical OpenAPI contract link at api.e2a.dev. Every other reference to this doc in the repo (plugins/e2a/docs/{auth,setup,sdk,templates}.md, llms.txt, and their web/public/ mirrors) uses e2a.dev, matching the doc set's own stated host split ("Documentation … lives on e2a.dev. The REST API and MCP server live on api.e2a.dev.").

Everything else audited (root docs, docs/, CLI/SDK docs, MCP + example docs, web/plugin docs, tool counts, mirrored-doc sync) checked out against current code — no other high-confidence issues found. One additional stale item was found but deliberately excluded as out of scope for a docs-only PR: the root VERSION file still reads 1.0.0 against the current v1.7.12 release-tag line, and is read as a build-tag fallback by .github/workflows/publish-mcp-http.yml — bumping it has functional CI-tagging impact and no clear "correct" target value, so it's left for a maintainer decision rather than guessed at here.

Docs/comment-only change (the send.ts edit is a docstring only, no behavior change), so the client-surface checklist doesn't apply.

Test plan

• bash scripts/check-repository-text-integrity.sh — passes
• Every changed claim cross-checked against the cited source file/line (server tests/field docs for the schedule+hold behavior, api/openapi.yaml's x-stability-level markers for the beta count, mcp/src/bin/http.ts for the allowlist default, and the doc set's other OpenAPI links for the host convention)

---

🤖 Generated with Claude Code

---

Generated by Claude Code

[AmirF194]

I ran this against c02bfca in a clean container.

CI's "Package and manifests" job is red on this PR (run 32751177659), and it is caused by this diff. scripts/check-plugin-version-bump.mjs requires a version bump in plugins/<name>/.claude-plugin/plugin.json whenever any file under plugins/<name>/ changes. This PR edits plugins/e2a/skills/e2a-integrate/references/rest-openapi.md but leaves plugins/e2a/.claude-plugin/plugin.json at 0.9.1.

$ node scripts/check-plugin-version-bump.mjs e1f8b1839b3817029bfc3b43f606f91582ff69f4
Changed plugins must bump their versions:
  - e2a remains at 0.9.1
EXIT:1

Bumping plugins/e2a/.claude-plugin/plugin.json's version to 0.9.2 clears it:

$ node scripts/check-plugin-version-bump.mjs e1f8b1839b3817029bfc3b43f606f91582ff69f4
Plugin version bumps are current: e2a
EXIT:0

[jiashuoz]

Thanks @AmirF194! Bumped the plugin to 0.9.2 and regenerated the manifests — the version-bump gate is now green. Appreciate the catch.

[AmirF194]

Confirmed, thanks for the quick turnaround.