The docs cover a coherent install path (Quickstart → CLI → Tool Files → Components → Limits & Billing) and lean hard into AI-IDE setup, but the marketing surface keeps promising more than the product ships: a three-model picker behind plans that all ship one model, a "framework agnostic" headline above a matrix where only Next.js is live, and "credits" — the unit every plan is priced in — that the docs never define in tokens or dollars. A second cluster of contradictions (provider naming, authToken shape) sits in the agent-ingested setup file, but the scrape captured only editorial descriptions of those pages, not their body text — so those findings are flagged below with a lower-confidence evidence note.
1. Homepage advertises three models; every plan ships exactly one (critical)
Problem: The homepage renders a model picker with three separately-priced, selectable-looking options — claude-sonnet-4.6 · default · $3 / 1M, claude-haiku-4.5 · fast · $0.80, and claude-opus-4.5 · smart · $15 — and labels Sonnet the "Default model," which implies the others are choosable. Yet every pricing tier lists exactly one model: Free, Starter, and Plus all read "Hosted Sonnet 4.6." Nothing on the page tells a buyer how to select Haiku or Opus.
Consequence: A developer who picks BetterAgent specifically to route hard reasoning to Opus ("smart") or cheap turns to Haiku ("fast") finds no model selection anywhere — only hosted Sonnet. An AI agent parsing the site cannot determine which models are actually available: the picker says three, the plans say one. The per-1M prices shown ($3 / $0.80 / $15) also have no documented relationship to the "credits" the plans actually bill in (see Issue 3).
The fix: Make the model picker reflect reality. If only Sonnet 4.6 is hosted, remove Haiku and Opus or clearly label them "coming soon / BYO-key only." If multiple models are selectable, document where and how a developer chooses one (config flag, tool-file field, provider prop) and reconcile that with the plan bullets.
2. "Framework agnostic" headline contradicts the Next.js-only support matrix (significant)
Problem: The homepage headlines "Framework agnostic," then immediately undercuts it one line down: "Next.js today. Same protocol, different adapter for every other stack." The accompanying support matrix shows only Next.js as , with — i.e., one framework actually works. The docs landing page reinforces the Next-only reality ("reads your routes and server actions"), and the Quickstart installs "the React and Next.js SDKs."
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: "Framework agnostic" is a top-of-funnel promise a Vue, Remix, Express, or Hono developer will act on — they adopt, start integrating, and only then discover their stack is "soon" or "beta," not shipped. This is the same marketing-promises-what-the-product-doesn't-ship trap as Issue 1, and an AI agent reading the headline will confidently scaffold for a framework that has no working adapter.
The fix: Lead with the truth: "Next.js today; other frameworks in progress." Move "framework agnostic" to a roadmap/vision framing, and keep the per-framework status badges visible at the point of the claim so no reader sees "agnostic" without immediately seeing "Next.js SHIPPED, everything else soon/beta."
3. "Credits" — the unit every plan is priced in — is never defined (significant)
Problem: Every plan is denominated in credits (Free 500, Starter 1,500, Plus 4,000), and the Limits & Billing page states limits only in credit terms — but a credit is never defined in tokens, conversations, or dollars. The only quantitative anchors on the site are mutually inconsistent: the homepage equates "500 credits a month" with "~25 conversations" (≈20 credits/conversation), the hard caps are stated in tokens ("80k tokens / conv"), and the only credit-to-dollar anchor is Plus's overage rate of "$10 per 1,000 additional credits" (= $0.01/credit). At that overage rate, Starter's 1,500 credits would be "worth" $15 — yet Starter costs $0.99, roughly a 15× gap between the in-plan and overage credit price.
Consequence: A developer cannot answer the first question they have before adopting a usage-billed platform: what will this cost me? With no credit→token or stable credit→dollar conversion, and an overage rate ~15× the in-plan rate, cost estimation and budget-alert thresholds are guesswork. Agents and finance teams can't model spend at all.
The fix: Define a credit precisely on the Limits & Billing page (e.g., "1 credit = N tokens" or "1 credit = 1 tool call"), give a worked example converting a typical conversation to credits to dollars, and reconcile the in-plan credit price with the overage rate (or explain why they differ).
4. The React provider appears under two different names across setup paths (significant)
Location: docs.betteragent.dev/quickstart vs. AI Setup page / betteragent.dev/agent-setup.md
Problem: Per the scraped page descriptions, the manual Quickstart wires up the chat UI with a generated wrapper named AgentProvider, while the AI Setup prompt and the agent-setup.md file it embeds use BetterAgentProvider (the SDK component) for the same step — the same required component under two names. Evidence note: the scrape captured the editorial descriptions of /quickstart and agent-setup.md, not their full body text; the two conflicting import lines were not captured verbatim. This finding therefore rests on a second-hand description and should be confirmed against the live pages before being treated as a hard build-breaker — which is why it is rated significant rather than critical.
Consequence: If the split is real, a developer who starts in the AI IDE (importing BetterAgentProvider) and then cross-references the Quickstart (referencing AgentProvider), or vice versa, hits an unresolved import and a build that won't compile, with no note explaining that one is a generated wrapper around the other. Because agent-setup.md is fed directly to Claude Code / Cursor, the coding assistant may scaffold BetterAgentProvider while every manual doc example says AgentProvider.
The fix: Pick one canonical name and use it everywhere, or explicitly document the relationship ("the CLI generates an AgentProvider wrapper around the SDK's BetterAgentProvider; import the wrapper") in both the Quickstart and the AI-setup file. Single-source both artifacts so the names can't drift.
5. Quickstart appears to omit the authToken Function variant the agent-setup file documents (significant)
Location: docs.betteragent.dev/quickstart vs. AI Setup page / betteragent.dev/agent-setup.md
Problem: Per the scraped page descriptions, the Quickstart documents authToken as accepting only a String or an Object, while the AI Setup prompt and agent-setup.md additionally document a Function variant for the same prop — so the manual path is missing one of three accepted forms. Evidence note: as with Issue 4, the scrape captured the descriptions of these pages, not the prop's type signature verbatim. Confirm against the live Quickstart and agent-setup.md before treating the omission as definitive; this is why it is rated significant rather than asserted with full confidence.
Consequence: If the omission is real, dynamic-token use cases — refreshing a short-lived token, resolving it lazily per request — are exactly what the Function variant exists for. A developer following the Quickstart concludes that capability doesn't exist, hardcodes a static string or stale object, and ships an auth flow that breaks when the token rotates. Two developers on the same team can read two official docs and disagree about whether authToken accepts a function.
The fix: Document all three authToken shapes (String, Object, Function) on the Quickstart, with a one-line example of the Function form and when to reach for it. Single-source the prop's accepted types so the Quickstart and agent-setup.md can't drift.
6. The agent-ingested setup file is served from the marketing host, not the docs domain (minor)
Problem: The canonical machine-readable setup artifact — the file the docs tell you to paste into Claude Code or Cursor — is served from the marketing host (www.betteragent.dev/agent-setup.md) and linked from the docs as betteragent.dev/agent-setup.md without the www. Both hosts resolve and the link works, so nothing is broken today, but the artifact most likely to be ingested verbatim by an AI IDE lives in marketing collateral rather than under the documentation domain, separate from the source that generates the Quickstart.
Consequence: Hosting the agent file apart from the docs pipeline is the structural reason the naming and authToken discrepancies in Issues 4–5 can exist at all: there is no single source guaranteeing the human Quickstart and the agent file stay identical. It also leaves the canonical agent artifact on a URL the docs reference inconsistently.
The fix: Treat agent-setup.md as a first-class doc: host it under the docs domain (or canonicalize the URL the docs link to), and generate it from the same source as the Quickstart so component names and prop signatures are guaranteed identical across the human and agent paths.
7. Operational hard caps live on the marketing page, where tool-file authors won't find them (minor)
Problem: The homepage states concrete per-run limits a tool-file author must design against — "20 turns / conv," "80k tokens / conv," "8KB / tool result," "30s route timeout" — but presents them as a marketing "Hard caps & budgets" panel rather than surfacing them where a developer is actually writing tool files.
Consequence: A developer writing a tool that returns a large JSON payload needs to know the 8 KB tool-result ceiling and the 30 s route timeout before they design the tool, not after a run is silently truncated or times out. Limits discovered on a pricing page rather than in the Tool Files reference get missed.
The fix: Mirror these caps in the Tool Files reference and Limits & Billing docs, in a parseable table, next to guidance on what happens when each is exceeded (truncation? error? which error code?).
8. The hard-caps widget shows a 10,000-credit budget that maps to no plan (minor)
Problem: The budget widget reads "8,234 / 10,000 — 82.3%," displaying a 10,000-credit ceiling. But the highest published tier is Plus at 4,000 credits/month; no plan on the pricing page offers 10,000 credits. The 10,000 figure is presented without explanation — most likely a bring-your-own-key budget, but the page never says so.
Consequence: A developer reading the example anchors their mental model of plan capacity to 10,000 credits, a number none of the purchasable plans deliver. Combined with the undefined-credit problem in Issue 3, it deepens the confusion about how much runway any given plan actually buys.
The fix: Either use a number that matches a real plan in the example widget, or label the 10,000-credit budget explicitly (e.g., "example BYO-key project budget") so readers don't mistake it for a plan limit.
What they do well
Agent-first onboarding is a real feature, not an afterthought: shipping a paste-able agent-setup.md for Claude Code / Cursor is exactly the right instinct for 2026 doc consumers.
Hard caps and per-project budgets that "shut off before they bill you" are stated up front — more honest cost-control framing than most usage-billed platforms offer.
"Observable by default" — logging "every run, every token, every tool call" as a queryable surface — is the right posture for a platform developers must debug in production.
Top 3 recommendations
Make the marketing surface match the product — reconcile the three-model picker and the "framework agnostic" headline with the reality that plans ship one model on Next.js, so neither a buyer nor an AI agent is misled about what's available.
Define a credit — give credits a concrete token/dollar conversion and a worked cost example on Limits & Billing, reconcile the in-plan vs. overage credit price, and explain the 10,000-credit budget shown in the example.
Single-source the setup artifacts — generate the Quickstart and agent-setup.md from one source so the provider name and authToken signature can never diverge, host the agent file under the docs domain, and then confirm and close out the naming/authToken discrepancies against the live pages.