Aleo's docs (docs.aleo.org) have a clean Learn/Build/Participate structure and genuinely good conceptual writing, but the build path is riddled with holes: a quickstart whose critical funding step points at nothing, a flagship "Leo Language" link that lands on a two-paragraph stub, contradictory version requirements on the same page, and a docs surface that is fully walled off from non-browser clients — no llms.txt, no sitemap, no raw fetch without a Cloudflare challenge.
1. Docs are unreachable to AI agents and scripts — Cloudflare challenge on every plain fetch, no llms.txt, no sitemap (critical)
Problem: Direct HTTP probes of /llms.txt, /llms-full.txt, and /sitemap.xml all return HTTP 403, and the docs root serves a Cloudflare "Just a moment..." challenge page (<title>Just a moment...</title> with challenges.cloudflare.com scripts) to any non-browser client. There is no machine-readable index of the documentation at all.
Consequence: AI coding agents (Claude Code, Cursor, Copilot) and any curl/CI tooling cannot fetch a single docs page, let alone index the site. For a platform whose primary audience is developers writing zero-knowledge programs — often with agent assistance — the entire documentation corpus is invisible to the tools those developers use. Ordinary crawlers can't even discover pages via sitemap.
The fix: Publish /llms.txt and /llms-full.txt, expose sitemap.xml, and configure the Cloudflare ruleset to allow plain GET requests to documentation paths (or at minimum to the llms/sitemap/text assets).
2. Quickstart's mandatory funding step points at nothing — "use the official faucet" with no faucet named or linked (critical)
Problem: The deployment walkthrough states "Deployment requires an account with Aleo credits," then the Faucet step reads, in full: "Once you have your account, use the official faucet to get some Aleo credits:" — followed by nothing. No faucet name, no URL. The same page has two more sentences that end where a target should be: "Lastly, we've initialized a local instance of your React application at." and "Navigate to and open up the developer console in your browser".
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 one step of the quickstart a developer cannot improvise — getting testnet credits — is a dead end. Everything after it (deploying helloworld) is blocked. New builders leave the funnel to go search Discord or Google for "Aleo faucet," and agents following the tutorial fail silently at the funding step.
The fix: Name and link the official faucet in the Faucet section, and restore the missing localhost URL (e.g. http://localhost:5173) in the two truncated sentences. These read like MDX components or links that were dropped during a migration — audit the page's rendered output against its source.
3. Homepage "Leo Language" card links to a near-empty reference stub (critical)
Problem: The homepage's primary "Leo Language" entry point resolves to a page titled "The Leo Language Reference" whose entire body is two short sections — "Statically Typed" (four sentences) and "Pass by Value" (one sentence). Meanwhile a full Leo reference (Language, CLI, Testing, Guides, SDK, Provable API) lives on a separate site, https://docs.leo-lang.org, which this page never mentions. The page's meta description is also broken markdown: description: [general tags]: # "syntax".
Consequence: A developer clicking the flagship "Leo Language" link from the docs homepage gets ~100 words and no pointer to the real reference. Aleo Instructions pages on the same site link to this stub as "the recommended high-level language for writing Aleo programs," compounding the dead end.
The fix: Either host the actual Leo language reference at this path or make the page an explicit signpost to docs.leo-lang.org. Fix the leaked [general tags]: # frontmatter.
4. Node.js version requirement contradicts itself on the same page — minimum 20 vs "version 18+" (significant)
Problem: One note says "the Provable SDK requires a minimum of Node.js version 20 and recommends using version 22+ for best performance." A few sections later, the scaffolding note for create-leo-app (which installs and runs the same SDK) says "Compatibility: Node.js version 18+."
Consequence: A developer on Node 18 following the scaffolding note will scaffold an app whose core dependency requires Node 20 — and hit runtime failures the docs told them wouldn't happen. Agents extracting requirements get two different answers from a single page.
The fix: Reconcile to one minimum version (presumably 20) and state it once, in a single "Requirements" block at the top of the page.
5. Staking commands shown in two different, incompatible calling conventions across pages (significant)
Problem: The staking page presents bare invocations with no tool at all: credits.aleo/bond_public <validator_address> <withdrawal_address> <amount_in_microcredits> — not a runnable command in any shell. The validator page, for the sibling operation, shows the full working form: leo execute credits.aleo/bond_validator ... --network mainnet --endpoint https://api.explorer.provable.com/v1 --broadcast.
Consequence: A delegator copying the staking page's "command" gets a shell error. They must reverse-engineer the leo execute ... --broadcast wrapper from a different page written for validators, including which network/endpoint flags are required.
The fix: Show the complete leo execute invocation (with --network, --endpoint, --broadcast) for bond_public, unbond_public, and claim_unbond_public on the staking page, matching the validator page's convention.
6. SDK proof-verification example is unrunnable — key material stubbed as "..." and an unexplained hardcoded block height (significant)
Problem: The example constructs keys with ProvingKey.fromString("...") and VerifyingKey.fromString("...") — placeholder ellipses with no explanation of where proving/verifying key strings come from — and ends with const blockHeight = 9000000; programManager.verifyExecution(executionResponse, blockHeight); where the comment only says "(requires block height parameter)" without saying which block height is correct or why it matters.
Consequence: The example cannot be copied and run, and there is no path from the placeholder to real values. An agent extracting this snippet will produce code that throws on the first fromString call. Developers can't tell whether 9000000 is load-bearing or arbitrary.
The fix: Show how to obtain the keys (e.g. via synthesizeKeys or downloading from the key provider) and document what block height verifyExecution expects (e.g. current chain height, and how to fetch it via the network client).
7. Wallet Adapter page ships a "Loading..." placeholder where the core setup code should be, and a heading with the component name missing (significant)
Problem: The Setup section — "Wrap your application with the AleoWalletProvider:" — renders only "Loading..." to any non-JS consumer; there is no static code fallback for the page's central example. Further down, the WalletMultiButton section heading renders as an empty inline code span: the heading extracts as "## Component" and the page's own table of contents shows "[ Component]".
Consequence: The single most important snippet on the page (the provider wiring) is invisible to crawlers, agents, and anyone whose interactive block fails to hydrate. The blank heading breaks in-page navigation and looks like an MDX escaping bug (<WalletMultiButton /> swallowed as JSX).
The fix: Render a static default code sample inside the interactive block (progressive enhancement), and escape the component name in the heading (e.g. `WalletMultiButton` Component).
8. Developer surface is fragmented across three doc properties with no map — and docs.aleo.org has no API reference at all (significant)
Problem: Core content is split across docs.aleo.org, docs.leo-lang.org (the full Leo reference plus "Provable API. Endpoints to query and interact with mainnet and testnet"), and docs.explorer.provable.com (the SDK README's "SDK Guide" link and the staking page's "Explorer API" link both point there). docs.aleo.org itself has no REST API section — yet its own examples depend on https://api.explorer.provable.com/v1 (validator bonding, SDK .env, ProgramManager constructor) without documenting a single endpoint.
Consequence: A developer who needs to query a mapping, check a transaction, or understand the endpoint their .env points at must discover two other documentation sites on their own. The official SDK README routes new users away from docs.aleo.org entirely. Agents indexing one property miss the reference material that lives on the others.
The fix: Add an API reference section (or an explicit, prominent cross-property map) to docs.aleo.org, and align the SDK README's "Start Building" links with the canonical docs site.
9. Broken frontmatter leaks raw markdown into page meta descriptions (minor)
Problem: Both pages emit literal markdown reference-link syntax as their meta description: description: [general tags]: # "syntax" and description: [general tags]: # "installation, install_leo".
Consequence: Search results and social cards for these pages show gibberish, and it signals unprocessed migration artifacts at the top of key Leo pages.
The fix: Move the tag comments out of the description field and write real one-line descriptions.
10. Docs homepage H1 is garbled text to any non-JS consumer (minor)
Problem: The homepage's top-level heading extracts as # #$%& ?@!# — apparently a JavaScript text-scramble animation with no static or accessible fallback. This is the literal H1 crawlers, agents, and screen readers receive on the documentation root.
Consequence: The most important heading on the docs site is noise to search engines, LLM indexers, and assistive technology.
The fix: Server-render the real heading text and apply the scramble effect progressively on top of it.
11. Typo and grammar cluster on build-path pages, including a misspelled section anchor (minor)
Problem: "Compliation Pipeline" is both a section heading and its anchor (#compliation-pipeline); execute_programs has "you'll likely want define", "Once everything's been intialized", "When the developer simply wants see", and "This approach is will not work"; the staking page has "You can delegate to single validator at a time"; the quickstart closes with "you've deployed an Aleo program and can how create a decentralized, private application!".
Consequence: Individually trivial, but the density on exactly the pages new developers read first erodes trust — and the misspelled anchor will break any deep links if it's ever corrected without a redirect.
The fix: Copy-edit the build and participate sections; when fixing #compliation-pipeline, keep the old anchor as an alias.
What they do well
The Learn section (background, accounts/keys, public vs private state, consensus) is genuinely well-written conceptual material with concrete formats, key prefixes, and footnoted protocol changes (e.g. sender_ciphertext as of Consensus V8).
The SDK network-selection guidance is exemplary: an explicit caution that bare @provablehq/sdk silently resolves to testnet, with per-network entry points and a runtime dynamic.js option.
Operational tables (validator hardware, ports with exposure guidance like "REST server — Do not expose", staking key numbers) are structured and parseable rather than buried in prose.
Top 3 recommendations
Unblock machine access: allow plain GETs through Cloudflare, and publish llms.txt/llms-full.txt and a sitemap so agents and crawlers can index the docs.
Fix the quickstart's dropped links (faucet, localhost URLs) and the near-empty Leo Language reference — the two highest-traffic paths currently dead-end.
Consolidate or explicitly map the three documentation properties (docs.aleo.org, docs.leo-lang.org, docs.explorer.provable.com), and give docs.aleo.org an API reference for the endpoint every example depends on.