EVO's docs cover two products on one page — the private-beta EVO Router API and the open-source evo plugin/CLI. The prose is unusually well-written, but the two authoritative sources (docs site and GitHub README) contradict each other on install behavior and supported hosts, the Router API reference has a one-sentence error section and an example response that uses an undocumented state, and version references are frozen several releases behind the shipped CLI.
1. Docs and GitHub README state opposite defaults for Codex hook trust (critical)
Problem: The docs say: "Codex requires manual approval for plugin hooks. After installing, run /hooks inside codex to trust evo's hooks — or pass --trust-hooks at install time to skip the prompt." The README on the main branch says the exact opposite: "evo install codex trusts evo's hooks for you. To review them yourself first, pass --no-trust-hooks, then approve via /hooks inside codex." Opposite defaults, opposite flags (--trust-hooks vs --no-trust-hooks).
Consequence: The docs themselves state the stakes: "With the host hooks untrusted on Codex, the mid-run directive channel will not fire, so the agent won't receive directives you send while a run is in flight." A developer who reads the README and assumes hooks are auto-trusted gets a run that silently ignores every mid-run directive. A developer following the docs passes a flag that may no longer exist. Either way, the failure is silent by the docs' own admission.
The fix: Determine the actual current default, update whichever source is stale, and have the docs state the flag(s) valid for the current release. Add a version note if the default changed between releases.
2. API probe example returns an undocumented policy stage "shadow" (critical)
Problem: The rollout documentation defines exactly three stages — "Observe," "Qualify," "Route" — and says "EVO works through three stages on its own." But the API reference's probe example returns "policy": { "policy_id": "pol_...", "stage": "shadow" }. "shadow" appears nowhere else in the documentation, and the documented stage names never appear in any API response example.
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
Consequence: The probe endpoint is explicitly for checking "the active policy and its stage" — i.e., for building tooling and dashboards on. A developer (or coding agent) branching on the documented stage names observe/qualify/route will never match shadow, and has no way to know whether the wire values are a different vocabulary, lowercase variants, or a fourth undocumented state. Humans might guess "shadow ≈ qualify"; agents fail silently.
The fix: Publish the enum of wire-level stage values in the API reference and map each one to the Observe/Qualify/Route stages used in the prose. If "shadow" is a real stage, document it on the rollout page too.
3. Router API error documentation is one sentence — no EVO-native errors, status codes, or rate limits (critical)
Problem: The entire error documentation for a hosted inference API is: "Upstream provider errors are returned as the provider sent them, with the original status code. If a candidate route errors or rate-limits, the request is retried on the incumbent rather than failing." Nothing documents EVO's own failure modes: what an invalid or revoked EVO_API_KEY returns, what happens on an unknown evo-auto/ model string or malformed prefix, what an unrecognized workload in the path form returns, whether EVO itself rate-limits, or what the probe endpoint returns on error.
Consequence: Developers putting a proxy in front of production traffic cannot distinguish "my EVO key is bad" from "the upstream provider is down," cannot write retry logic against EVO-specific status codes, and cannot pre-handle limits they don't know exist. For a product whose pitch is "an SDK cannot tell the difference," the one place the difference is guaranteed to show up — EVO-originated errors — is undocumented.
The fix: Add an error reference: EVO-native status codes and body shapes (401/403 auth, invalid model prefix, unknown workload), rate-limit behavior and headers if any, and probe-endpoint error responses.
4. README supports Kimi as a host; the docs never mention it (significant)
Problem: The README lists "Runs on Claude Code, Codex, Cursor, Kimi, OpenClaw, Hermes, Opencode, or Pi," gives Kimi install commands, and includes kimi in the evo install <host> enum. The docs' Supported hosts table, evo install comment, evo doctor list, evo update host list, and evo host set enum all list seven hosts — no Kimi anywhere.
Consequence: A Kimi user landing on the docs concludes the host is unsupported; a README reader who then consults the docs for evo doctor kimi or invocation syntax finds nothing. Which source reflects the shipped CLI is unguessable.
The fix: Add Kimi to the docs' host tables (install name, doctor, update, host set, invocation syntax) or remove it from the README if support is unreleased.
5. evo init --host enum omits cursor while the same page says evo host set "uses the same host names" (significant)
Problem: The evo init signature documents --host <claude-code|codex|opencode|openclaw|hermes|pi|generic> — no cursor. The same page later says: "set it with evo host set <claude-code|codex|cursor|opencode|openclaw|hermes|pi|generic>. This uses the same host names as evo init --host." The two enums differ by exactly cursor, and the Install page markets Cursor as a fully supported host.
Consequence: A self-contradiction on one page: either evo init --host cursor works and the signature is wrong, or Cursor workspaces cannot be initialized with the documented flag. An agent generating an evo init invocation from the documented enum will refuse or mis-set the host for Cursor users.
The fix: Make the two enums identical, and reconcile both with the Supported hosts table on the Install page.
6. Documented dashboard restart command requires a source checkout most users don't have (significant)
Problem: Both pages give the manual restart command as uv run --project /path/to/evo/plugins/evo evo dashboard --port 8080. That --project path only exists in a git clone of the evo repository, but the documented install path is uv tool install evo-hq-cli, which puts an evo binary on PATH and creates no such directory. Neither page explains what /path/to/evo/plugins/evo is or notes that tool-install users should run the command differently.
Consequence: The one command a user reaches for at their lowest moment — the dashboard died and .evo/dashboard.dead exists — fails for everyone who installed the documented way, with a uv error about a missing project. It's a copy-paste trap in the recovery path.
The fix: Document the restart command for the standard install (evo dashboard --port 8080 if that works from PATH), and reserve the uv run --project form for the Dev install section with an explicit note.
7. Docs version references are frozen at 0.4.x while the shipped CLI is 0.8.0, and a known 0.5.1 fix exists only in the README (significant)
Problem: The docs' migration guidance is "Migrating from any pre-0.4.4 version," the pinning examples use 0.4.1 / 0.4.1a2 / 0.4.1-alpha.2, and nothing on the docs site states which CLI version the documentation describes. PyPI's latest release is 0.8.0. Meanwhile the README documents a real failure mode — "Hooks failing with exit 127. The host lost evo's hook binary. Fixed in 0.5.1; reinstall the host to repair" — that is absent from the docs' Troubleshooting page entirely.
Consequence: Users on 0.5–0.8 can't tell whether the documented flags, config fields, and behaviors match their install — exactly the "CLI and skill drift fails silently" problem the docs warn about. Anyone hitting the exit-127 hook failure and searching the docs' Troubleshooting page finds nothing, though the fix is one command.
The fix: State the documented CLI version on the docs site, refresh version examples, and port the exit-127 entry (and any other README-only fixes) into Troubleshooting.
8. No llms.txt, no sitemap, and no machine-readable spec for the Router API (significant)
Problem: Probing /llms.txt, /llms-full.txt, /docs/llms.txt, and /sitemap.xml at both the root and docs paths returns 404. The entire documentation is one JS-styled HTML page with anchor navigation, and the Router API reference is prose tables only — there is no OpenAPI/Swagger spec for api.evo-hq.com, despite the product being an OpenAI-compatible endpoint whose surface (paths, headers, probe schema) is trivially specifiable.
Consequence: Coding agents — the audience EVO explicitly courts, given the product runs inside Claude Code and Codex — cannot efficiently index the docs or programmatically discover the Router's endpoints, headers, and probe response schema. Every integration detail must be scraped from one 130 KB HTML page.
The fix: Publish llms.txt/llms-full.txt (the single-page structure makes this nearly free), add a sitemap, and ship an OpenAPI document covering the three base paths, the workloads path form, and the probe endpoint.
9. Framework examples silently diverge: CrewAI and Pydantic AI omit the workload header, Spring AI drops /v1 (significant)
Problem: Framework recipes like LangChain, LlamaIndex, and Semantic Kernel all set x-evo-workload; the CrewAI and Pydantic AI examples set no workload header and include no note about it or the path-form workaround. The Spring AI example uses base-url: https://api.evo-hq.com — the only example without /v1 — again with no explanation. The docs elsewhere stress the header is how you control workload grouping, and the API reference offers a path-based alternative for "callers [that] cannot set custom headers."
Consequence: A developer copy-pasting the CrewAI or Pydantic AI snippet silently falls back to inferred workload grouping — "which works but gives you less control" — without knowing they diverged from every other example. A Spring AI user who "fixes" the base URL to match the other examples by appending /v1 ends up with a doubled path segment and opaque failures.
The fix: Add one-line notes: why Spring AI's base-url excludes /v1 (the client appends it), and how CrewAI/Pydantic AI users should attach a workload (header pass-through if supported, otherwise the /workloads/<name>/v1 path form).
10. /evo:report and /evo:ship are part of the documented workflow but have no reference pages (minor)
Problem: The Quickstart says: "After a run, ask the agent for /evo:report when you want a read-only summary, or /evo:ship when you are ready to turn a result into a clean change." But the Reference section of the sidebar documents only evo:discover, evo:optimize, the CLI reference, Upgrading, and Troubleshooting — there is no reference page for report or ship, and the "Start here" page frames the surface as "two commands."
Consequence: The two skills that turn a run into a shippable change have no invocation reference, parameter list, or host-syntax table, unlike discover and optimize — users must reverse-engineer them from workflow narrative scattered across other pages.
The fix: Add reference pages (or sections) for evo:report and evo:ship matching the discover/optimize reference format.
11. Marketplace alpha tag format differs between docs and README (minor)
Problem: The docs say "the marketplace tag uses the dash form (0.4.1-alpha.2)"; the README says "the marketplace tag uses the dash form (v0.4.1-alpha.2)" — with a leading v. Both stress that "Both must point at the same release."
Consequence: In the one workflow where the docs insist exact tag formats matter, the two sources disagree on the format by a leading v; a wrong guess yields a failed pin or a version-drifted install of exactly the kind the page warns about.
The fix: Verify the actual tag scheme and make both sources match, showing one literal working example.
12. API key management is described against a console that is never linked (minor)
Problem: The key page describes UI locations — "API keys, under the workspace nav. Create a key, copy it once, and revoke it here if it leaks" — but no URL for this workspace/console appears anywhere in the docs. The only linked entry point is the beta request form, which promises "an API key and a base URL when your slot opens."
Consequence: A provisioned beta user reading the docs has no documented way to reach the surface where keys are created and revoked — the docs describe a UI without saying where it lives.
The fix: Link the workspace/console URL wherever its UI is referenced, even if access is gated to provisioned accounts.
What they do well
Failure-mode honesty: the gates documentation explains exactly how exit-code-only gates get gamed, and Troubleshooting explains why fixes work (plugin cache, wire-format lockstep), not just what to type.
Framework and gateway coverage is broad and mostly copy-pasteable — eleven frameworks and seven gateways with concrete, header-complete snippets.
Conceptual layering is strong: prefix vs. workload, provider auth vs. runtime env, and pre vs. post gates each get a crisp distinction a reader can act on.
Top 3 recommendations
Reconcile the docs site with the GitHub README — Codex hook-trust default, Kimi support, the exit-127 fix, and the alpha tag format are four live divergences between the two sources users actually read.
Give the Router API a real contract: EVO-native error codes, rate limits, the wire-level stage enum (including "shadow"), and an OpenAPI spec.
Version-stamp the docs and refresh 0.4.x-era references — the shipped CLI is at 0.8.0 and the docs never say which release they describe.