A real-looking docs site with strong conceptual depth (cryptography, consensus, tokenomics) — but the build-side surface is fractured: a Leo 4.0 syntax overhaul that hasn't propagated to the SDK guides, multiple placeholder pages exposed in nav, a misspelled package name shipped as install instructions, an undocumented SDK subpath split, and no central REST endpoints page despite SDK guides hardcoding one URL.
1. Leo 4.0 syntax migration is half-applied — SDK guides still teach removed keywords (critical)
Location:/build/sdk/guides/deploy_programs/ and /build/sdk/guides/managing_state/ vs. /build/leo/guides/migration-3-5-to-4-0/ and /build/leo/language/cheatsheet/
Problem: The migration guide explicitly states Leo 4.0 removes transition, async, function, and Future in favor of fn, final, and Final, and the cheatsheet uses the new program hello.aleo { ... } block syntax. But the SDK's Deploy Programs guide still teaches:
and the Managing State guide still uses the pre-4.0 dual-block function transfer_public: ... finalize self.signer r0 r1; model — not the final { ... } block 4.0 introduces.
Consequence: A developer following the SDK quickstart writes code with transition, hits a compiler error from the current Leo toolchain, and has no signal that they're reading documentation for a deprecated language version. Worse, agents scraping these pages will produce broken code with high confidence because the pages don't carry a version banner.
The fix: Add a "Leo version" banner to every SDK and example page, rewrite all SDK code samples to 4.0 syntax (fn, final { ... }, program X.aleo { ... }), and cross-link to the migration guide from each affected page. Either that, or fork the SDK guides into "Leo 3.5 (legacy)" and "Leo 4.0" tracks.
2. Wallet adapter install commands ship a misspelled package name (critical)
Either the published packages are actually adaptor (and the rest of the docs/page titles are wrong) or the install commands are wrong. Either way, a developer's first action — copying the install line — has a coin-flip chance of failing.
Consequence:npm install either 404s on the registry or installs unexpected packages. AI agents copying these commands inherit the inconsistency and write code referencing the wrong package name.
The fix: Pick a spelling (the JS standard is "adapter"), publish or rename packages accordingly, and search/replace the docs so the page title, prose, and install commands all match.
3. Interactive setup code block renders as "Loading..." (critical)
Location:/build/wallets/wallet-adapter/getting-started/, under "Setup"
Problem: The Setup section reads:
Wrap your application with the AleoWalletProvider:
Loading...
Options configured on the page header are reflected in the code above.
The code that's supposed to teach the most important integration step — wrapping the app in the provider — never renders. The page describes options that are "reflected in the code above" but there is no code above.
Consequence: The single most-important snippet on the wallet adapter getting-started page is missing in the production output. A developer has no canonical setup example to copy.
The fix: Ship a static fallback code block that renders regardless of the interactive widget state, and add an SSR check so the interactive variant only replaces it after hydration.
4. SDK import paths disagree across pages, with no documentation of the subpath split (critical)
Location:/build/sdk/api-reference/account/ vs. /build/sdk/guides/create_account/ vs. /build/sdk/overview/
Problem: The Account API reference imports from @provablehq/sdk/testnet.js:
import { Account } from "@provablehq/sdk/testnet.js";
The Create Account guide — the page most JS developers will land on first — imports from @provablehq/sdk with no subpath:
import { Account } from '@provablehq/sdk';
The SDK overview page only refers to the package as @provablehq/sdk and never mentions network-specific entry points (testnet.js, presumably mainnet.js, canary.js). Nothing in the surveyed pages explains when to use which.
Consequence: A developer copies the guide's import, then copies an example from the API reference, and ends up with two import paths in the same file — one of which may import an entry point that doesn't exist for their target network. Agents generating SDK code will pick whichever they saw first and silently target the wrong network.
The fix: Document the network entry-point convention in the SDK overview (@provablehq/sdk vs. @provablehq/sdk/testnet.js vs. mainnet/canary equivalents, with explicit guidance on which to use for which target). Then sweep every guide and API reference page to use the same import path or to explain why theirs differs.
5. CLI reference exposes two distinct broken-flag categories under the same warning style (significant)
Location:/build/leo/cli/cli_add/ and /build/leo/guides/deploy/
Problem: The CLI reference mixes two different "do not use" conditions without distinguishing them:
--base-fees on leo deploy is labeled [UNUSED] in the option help text — meaning the flag is parsed but does nothing.
--clear on leo add carries the warning "This feature is currently bugged and is non-functional." — meaning the flag is wired up but actively broken.
--edition on leo add carries "Do not use this feature unless you know what you are doing!" — meaning the flag works but is dangerous.
Three different failure modes, surfaced as three differently-worded inline warnings, with no issue links, target fix versions, or guidance on what to do instead.
Consequence: Developers can't tell whether --clear will work next week or next year, whether --base-fees will be wired up at all, or whether --edition is dangerous-but-correct or dangerous-and-broken. Agents reading the reference may emit these flags into generated scripts.
The fix: Separate the two categories. For [UNUSED] flags (parsed but no-op), either remove them from the public CLI surface or label them as "reserved — not yet implemented" with a tracking issue. For "bugged and non-functional" flags, hide them from --help until fixed, or link to a tracking issue and ETA. For genuinely advanced flags, document the exact failure mode that warrants the warning.
6. leo debug is listed as a top-level CLI command but only exists to say it was removed (significant)
Location:/build/leo/cli/cli_debug/
Problem: The CLI nav lists leo debug alongside live commands (leo deploy, leo add, leo clean, etc.). The page body is entirely a removal notice:
warning: leo debug has been removed in Leo 4.0. The interactive interpreter is no longer available.
Consequence: A developer skimming the CLI section believes leo debug is a current command and clicks in expecting documentation. Agents indexing the sitemap treat it as a valid command. This is a navigation lie.
The fix: Remove the page from CLI navigation. Keep a single "Removed commands" entry under a release-notes/migration section that points to leo test as the replacement.
7. Three navigation-prominent pages are empty placeholders ("Coming soon!") (significant)
Problem: Each of these pages contains only a title and "Coming soon!" — yet they appear as full entries in the left-nav. The Standards section presents ARC-20 (the most consequential token standard for any chain) as if it's documented; it isn't. Batch Payments is listed under Common Uses next to fully-fleshed pages like Multisig and Private Stablecoins.
Consequence: Anyone evaluating Aleo for token launches clicks "ARC-20 (Tokens)" expecting a spec and gets nothing. Search engines and agent crawlers index these as legitimate docs pages. Confidence in the docs collapses the second a reader hits the third blank page.
The fix: Either remove these pages from navigation until content exists, or replace the body with a one-paragraph "Status: in progress — see [external repo or ARC PR]" pointing to anything authoritative. Don't keep Coming soon! pages in the public nav.
8. No central "Network endpoints" reference — REST URL is hardcoded in SDK guides only (significant)
Problem:https://api.explorer.provable.com/v1 appears as the network endpoint in SDK examples and as the --endpoint value in the validator bonding command — but the docs have no dedicated page listing endpoints per network (Mainnet, Testnet, Canary), per environment, with rate limits or auth requirements. The llms.txt sitemap confirms there is no /api/ or endpoints page. Separately, /build/sdk/guides/delegate_proving/ introduces a second base URL (https://api.provable.com/v2) for the Delegated Proving Service, again without a central reference.
Consequence: Developers building against the network can't find a canonical answer for "what URL do I use for Testnet vs. Canary," and agents have no structured place to discover endpoint metadata. The two distinct api.*.provable.com domains (api.explorer.provable.com/v1 vs api.provable.com/v2) are easy to confuse and there's no page disambiguating them.
The fix: Create a single /build/reference/endpoints/ page (or similar) with a table: service × network × base URL × auth × rate limit × OpenAPI link. Link to it from every SDK guide and from the validator setup page.
9. No machine-readable API spec for AleoNetworkClient REST surface (significant)
Problem: The page describes the AleoNetworkClient as a "Client library that encapsulates REST calls to publicly exposed endpoints of Aleo nodes," and lists 30+ methods (getBlock, getProgram, findUnspentRecords, getDeploymentTransactionForProgram, etc.). But the underlying REST endpoints, their HTTP verbs, paths, request/response schemas, status codes, and error shapes are not documented anywhere on the site. The Client node page describes a REST API on port 3030 with no endpoint reference either.
Consequence: Anyone not using the JS SDK — Go, Rust, Python developers, or anyone integrating from a backend — has to read snarkOS source to discover the API. AI coding agents can't generate non-JS API clients without hallucinating paths. The llms.txt sitemap confirms there's no /api/ section to crawl.
The fix: Publish an OpenAPI spec for the snarkOS REST server (port 3030) and link it from the AleoNetworkClient reference and the Client node page. Generate the SDK method docs from the same spec so they stay in sync.
10. No error code / error reference anywhere across the docs (significant)
Location: Site-wide, but conspicuously absent at /build/aleo-instructions/reference/, /build/aleo-instructions/reference/finalize-operations/, /build/aleo-instructions/reference/programs/, and all SDK guides
Problem: Multiple pages reference runtime errors and halting behavior:
Finalize ops: "Attempting to access [program_owner] will result in a runtime error."
Standard operations table is full of halts on overflow, halts on zero, halts on non-residues, halts past boundary.
leo deploy, leo execute, the Account API, the Delegated Proving API all surface errors implicitly.
No page lists error codes, exception types, the halt taxonomy, or what an end-user/operator sees when one of these failures triggers. There is no "Errors" reference.
Consequence: A developer hitting a runtime halt has nothing to grep for in the docs. Agents writing error handling have no error type to catch and no documented retry semantics.
The fix: Add an /build/reference/errors/ page that enumerates AVM halt categories, Leo compiler errors, SDK exception types, and REST API error responses, each with a code, a one-line cause, and a recommended remediation.
11. Delegated Proving guide points to undocumented "Provable API documentation" and an unnamed POST {baseUrl}/consumers endpoint (significant)
Location:/build/sdk/guides/delegate_proving/
Problem: The Credentials section says:
API key and consumer ID — Obtain these by registering a consumer (e.g. POST {baseUrl}/consumers). See Provable API documentation for details.
"Provable API documentation" is not hyperlinked. The llms.txt sitemap shows no Provable API reference under docs.aleo.org. The /consumers endpoint is mentioned in passing but not documented in any reference table on this site (request body, auth scheme, response shape, error codes — all absent).
Consequence: A developer cannot complete step 1 of the delegated-proving onboarding from the docs alone. They must guess at the request shape or search the Provable website separately. Agents cannot generate working DPS integration code from these docs.
The fix: Either (a) host the Provable API reference on docs.aleo.org and link directly to /consumers, or (b) embed the request/response schema for POST /v2/consumers inline in the Delegated Proving guide, including the JWT flow.
12. Validator setup silently mixes leo and snarkos toolchains with no compatibility guidance (significant)
Location:/participate/run-a-node/validator/
Problem: The validator setup steps go: clone snarkOS → ./build_ubuntu.sh → cargo install --locked --path . → snarkos account new → then, for bonding:
The page never explains that a validator operator needs both snarkos and leo installed, where to get the leo binary, which versions of each are compatible, or why bonding goes through leo execute rather than snarkos.
Consequence: A node operator who's followed the page line-by-line hits "command not found: leo" at the bonding step with no signal about which Leo version to install. Operators on the wrong Leo version will write transition/finalize examples from neighboring pages and produce broken bonding transactions.
The fix: Add a "Prerequisites" block at the top of the validator setup with explicit install instructions for both snarkos and leo, pinned versions, and an explanation that bonding is a Leo program execution against credits.aleo rather than a node-internal command.
13. Upgradability annotations are load-bearing but missing from the Leo cheatsheet (significant)
Location:/build/leo/guides/upgradability/ vs. /build/leo/language/cheatsheet/
Problem: The upgradability guide documents four constructor annotations — @noupgrade, @admin, @checksum, @custom — that determine whether and how a deployed program can be upgraded. These are the highest-stakes annotations in Leo: pick the wrong one and you either trap your program forever or hand the upgrade key to the wrong party. The Leo cheatsheet, which is where most developers go for a one-page reference, does not list them at all.
Consequence: A developer using the cheatsheet as their language reference will not know these annotations exist, will not include a constructor, and will discover at deploy time (or worse, at upgrade time) that they've made an irreversible decision. Agents generating Leo programs from the cheatsheet will omit upgrade policy entirely.
The fix: Add an "Annotations" section to the cheatsheet with each upgradability annotation, a one-line semantics summary, and a link to the upgradability guide. Same for any other load-bearing annotations.
14. cli_account carries a key-recovery danger: banner; the SDK equivalent does not (significant)
Location:/build/leo/cli/cli_account/ vs. /build/sdk/guides/create_account/
Problem: The CLI page for leo account opens with a strong safety banner:
danger: We urge you to exercise caution when managing your private keys. leo account cannot be used to recover lost keys.
The SDK guide for create_account — where the majority of JS developers will create their first Aleo account — has only a mild "All keys are considered sensitive information and should be stored securely!" warning. No mention that lost keys are unrecoverable.
Consequence: A developer onboarding via the SDK doesn't see the "no recovery" framing, treats key storage as a normal credential problem, and loses funds the first time they wipe browser storage or rotate machines. The safety surface is inconsistent across language tracks.
The fix: Hoist the danger: banner from cli_account into the SDK create-account guide (and into the Account API reference). The "no recovery" warning belongs anywhere a private key is first generated, not only in the CLI section.
15. Forward reference to "Aleo Stack v4.6.0" with no version page or changelog (minor)
The maximum array size is 2,048 elements (increased from 512 in Aleo Stack v4.6.0 to support verifying keys and proofs used by snark.verify).
"Aleo Stack" appears nowhere else as a versioned product in the surveyed pages. There is no changelog, no version page, no link explaining what release line "v4.6.0" refers to (snarkVM? snarkOS? Leo? something else?).
Consequence: A developer reading the constraint cannot tell which network/toolchain version they need to be on to rely on the 2048-element limit. Agents can't reason about feature gates by version.
The fix: Add a "Release notes" or "Versions" page anchoring "Aleo Stack" to a concrete version scheme (snarkVM commit/tag, mainnet activation height, etc.), and link the inline mention.
16. Embedded wallets feature limitation is buried in a comparison table (minor)
Location:/build/wallets/embedded-wallets/
Problem: The page's comparison table lists:
Message Signing: Not yet supported (v4.83)
This is a versioned, dated limitation of the embedded-wallet integration, parked inside a row of a feature comparison table. There is no "Known limitations," "Release notes," or "What's not yet supported" surface on the embedded-wallets page or elsewhere in the wallets section.
Consequence: An integrator planning to use message signing for off-chain auth won't see the limitation unless they read the table closely. Agents summarizing wallet capabilities will overstate what embedded wallets can do.
The fix: Add a "Known limitations" section to the embedded wallets page that surfaces the message-signing gap explicitly, with the version it applies to and a link to the upstream tracker. Same pattern for any future feature gaps.
17. Record Scanning terminology drifts between the SDK guide and the Learn page (minor)
Location:/build/sdk/guides/record_scanning/ vs. /learn/advanced/record-scanning/
Problem: The SDK guide names the service "Record Scanning Service (RSS)" and uses that abbreviation throughout. The Learn page describes the same concept as "delegated scanning service" and never uses "RSS" or "Record Scanning Service." Neither page links to the other.
Consequence: A developer searching the docs for "RSS" won't find the conceptual page; a developer reading the conceptual page won't know the SDK guide exists. Agents indexing the docs will treat these as two distinct services.
The fix: Pick one canonical name ("Record Scanning Service / RSS"), use it on both pages, and cross-link the SDK guide and the Learn page in both directions.
18. Typo in Aleo Instructions overview: "Compliation Pipeline" (minor)
Location:/build/aleo-instructions/overview/
Problem: The H2 heading reads Compliation Pipeline instead of Compilation Pipeline.
Consequence: Damages credibility on a top-of-funnel reference page; section anchors/links built from the heading slug will encode the typo.
The fix: Correct the heading and audit for any internal links that anchor to the misspelled slug.
19. No llms-full.txt — llms.txt is a sitemap only (minor)
Location:/llms.txt
Problem: The site exposes llms.txt as a list of URLs, which is the index variant. There is no llms-full.txt that bundles content for agent ingestion. (Individual page fetches happen to return llms-full.txt-style content per route, but the standard companion file isn't at the root.)
Consequence: Agents that look for llms-full.txt at the canonical location won't find it and have to crawl page-by-page, increasing token cost and missing the structured ingestion path the standard suggests.
The fix: Publish /llms-full.txt at the root, concatenating the build/learn/participate sections so agents can ingest the corpus in one fetch.
What they do well
Strong conceptual ladder. Background → How Aleo Works → Public/Private State → Transitions → Key Derivation lets a reader walk from "what's a blockchain" all the way to Poseidon domain-separated scalar derivation in one site.
Tokenomics and node-operator specifics are concrete. Hardware tables, port maps, the ARC-46 prover stake schedule by quarter, the 10-year coinbase decay table — these are the kinds of numbers most chains hand-wave on.
Cryptography depth is unusual. The Aleo Curves page and the zkSNARKs page actually explain the Fr/Fq relationship and the Varuna AHP/SonicKZG10 stack, not just brand names.
Top 3 recommendations
Run a Leo-4.0 sweep across every SDK and example page. A migration guide that contradicts the very next page in the nav is worse than no migration guide. Add a version banner to every page and convert all snippets.
Publish a single "Endpoints, errors, and machine-readable schemas" reference. OpenAPI for the snarkOS REST API + DPS API, a network-by-network endpoints table, and a halt/error taxonomy. Right now agents and non-JS clients are flying blind.
Make the SDK import path explicit and consistent. Document the @provablehq/sdk vs. @provablehq/sdk/testnet.js split in the SDK overview, then sweep guides and API references so the same code path appears everywhere.