Gigabrain Documentation Audit

One line: a genuinely well-structured Mintlify site with an OpenAPI spec and per-page .md endpoints — but the developer surface is riddled with cross-page contradictions (auth-critical model fields, private-key handling, error codes, pricing units), and the two machine-readable assets agents lean on most — the llms.txt index and the OpenAPI security schemes — quietly omit the SuperAgents product and the X-API-Key auth path the prose advertises.

1. FAQ tells you to export private keys before deleting; the SuperAgents API says keys are never exposed (critical)

Location: /support/faqs vs /developers/superagents-api, /api-reference/superagent-lifecycle/restart-superagent (Get wallet), and /guides/superagents-setup

Problem: The FAQ states: "If you delete an agent without first exporting the wallet's private keys, any remaining funds in that wallet are permanently lost… Always go to the agent's Settings page and export your private keys before deleting." But the SuperAgents API page says "private keys are never returned," the Get-wallet endpoint says "No private keys are exposed," and the Setup guide's Destroy step says only "withdraw any remaining funds from its wallets" — no mention of a private-key export at all. Wallets are described as Privy-managed.

Consequence: This is the single most dangerous contradiction in the docs, and it's about losing money. A user who trusts the FAQ goes hunting for a "Settings → export private keys" flow that the rest of the docs say does not exist, and may either (a) believe their funds are unrecoverable when they only needed to withdraw, or (b) delay deleting while looking for a non-existent export. The instructions for protecting funds before an irreversible destroy directly contradict each other.

The fix: Pick one model and make it authoritative everywhere. If wallets are Privy-managed and keys are never exposed, delete the FAQ's "export private keys" instruction entirely and replace it with the Setup guide's "withdraw remaining funds first." If key export does exist via the dashboard, document it on the wallet/lifecycle pages and stop saying keys are never returned.

2. Both SuperAgent "Quick Start" launch snippets omit the required model and model_provider fields (critical)

Location: /developers/superagents-api (Python + bash Quick Start) vs /api-reference/superagents/launch-superagent and /openapi.json

Problem: Both Quick Start launch snippets on the SuperAgents API page (Python and bash) send only name (plus optional soul_md): json={"name": "ETH Scalper", "soul_md": "..."}. But the Launch reference page and the OpenAPI spec's LaunchSuperagentRequest both mark name, model, and model_provider as required. The reference example correctly sends { "name": "...", "model": "gpt-4o", "model_provider": "openai" }.

Consequence: A developer (or coding agent) who copy-pastes the Quick Start to launch their first agent gets a 400 — "name is required"-style validation error, because two required fields are missing. The first thing a new user runs is guaranteed to fail. This is the canonical agent-failure case: the example contradicts the schema and the agent can't tell which is right.

The fix: Add model and model_provider to both Quick Start launch snippets so they match the schema, or make those fields genuinely optional in the API and update the reference + OpenAPI required array. The examples and the spec must agree.

3. SuperAgents bash "Chat" example posts to a malformed URL with a double slash and no agent ID (critical)

Location: /developers/superagents-api (bash Quick Start, Chat step)

Problem: The chat curl reads: curl -X POST "$BASE//chat" -H "Authorization: Bearer $KEY" ... -d '{"message": "..."}'. $BASE is https://api.gigabrain.gg/v1/superagents, so this resolves to …/v1/superagents//chat — a double slash and no {agent_id} segment. Every other chat-style endpoint in the docs is per-agent (e.g. /v1/superagents/{agent_id}/...), and the Python quickstart just above captures agent_id from the launch response.

Consequence: The snippet is uncopyable. It either 404s or hits the wrong route, and a reader can't infer the correct path from this example alone because the {agent_id} interpolation was dropped. Agents extracting this command will fail silently.

The fix: Correct the URL to "$BASE/$AGENT_ID/chat" (matching the Python flow that sets agent_id), and add the AGENT_ID= assignment to the bash example so it's runnable end-to-end.

4. "$100 minimum credits to launch" contradicts "$5" pricing and "fund later" setup (significant)

Location: /developers/superagents-api vs /pricing and /guides/superagents-setup

Problem: The SuperAgents API page states "Minimum credits: $100 to launch a SuperAgent through the API." But the Pricing page says you can "Start using Gigabrain for as low as $5," prices SuperAgent compute at "$0.17/day (~$5/month)," and its own example cost tiers start at ~$20/mo. The Setup guide explicitly lists funding as "optional, you can set up the agent first and fund later" and provisions the agent in ~30 seconds before any funding step.

Consequence: A developer can't tell whether they need $5, $100, or $0 to create an agent. Someone budgeting via the pricing page is blindsided by a $100 wall at the API; someone trusting the setup guide's "fund later" tries to launch via the API and is rejected. This is a hard onboarding blocker with three different answers.

The fix: State the actual minimum balance required to launch (if any) once, on the pricing page, and reference it consistently from the API and setup pages. If the $100 minimum is API-only, label it clearly as such and explain why it differs from dashboard creation.

5. Four different HTTP status-code sets for the same API, and the OpenAPI spec omits codes the docs advertise (significant)

Location: /developers/introduction, /developers/superagents-api, /openapi.json, /openclaw/brain

Problem: The four authoritative sources disagree on which status codes exist:

• Auth & Basics (/developers/introduction): 200, 201, 400, 401, 404, 429, 500, 504
• SuperAgents API: 400, 401, 403, 404, 429, 500 (adds 403, drops 201/504)
• OpenAPI /v1/chat: only 200, 401, 429, 504 — no 400, 404, or 500 defined
• Brain SKILL.md (/openclaw/brain): 401, 429, 500/503, 504 (introduces 503, which appears nowhere else)

Consequence: Error handling is exactly what coding agents lean on the machine-readable spec for, and the spec disagrees with the prose. An agent generating retry logic from openapi.json won't handle 400/404/500 on /v1/chat; one reading the SKILL.md will branch on a 503 that no other page acknowledges; one reading the SuperAgents page expects a 403 the chat API never lists. Error codes here are a folk tradition, not a contract.

The fix: Define one canonical error-code table per endpoint group and make the OpenAPI spec the source of truth. Add 400/404/500 response objects to /v1/chat in the spec (or confirm they truly can't occur), reconcile 403 and 503, and have the SKILL.md and prose pages cite the spec rather than restating divergent lists.

6. X-API-Key auth is documented in prose but absent from the OpenAPI security schemes (significant)

Location: /developers/introduction vs /openapi.json

Problem: The Auth & Basics page explicitly offers two authentication methods: Authorization: Bearer gb_sk_... and, as an alternative, X-API-Key: gb_sk_.... But the OpenAPI spec's securitySchemes defines only bearerAuth (type: http, scheme: bearer). There is no apiKey/header scheme for X-API-Key anywhere in the spec.

Consequence: This is the same prose-vs-spec divergence as the error-code finding, applied to authentication — arguably more severe, because auth is the first thing any integration wires up. An agent or SDK generator that builds its auth layer from openapi.json will only ever emit a Bearer header and never offer X-API-Key, even though the human-facing docs present it as a supported option. A developer who picks X-API-Key from the prose has no machine-readable confirmation it's valid.

The fix: Add an apiKeyAuth security scheme to the spec (type: apiKey, in: header, name: X-API-Key) and list it alongside bearerAuth on the relevant operations — or, if X-API-Key is not actually supported, remove it from the introduction page so prose and spec agree on exactly one auth mechanism.

7. "No restart needed" for soul/model changes contradicts the Restart endpoint (significant)

Location: /api-reference/superagent-lifecycle/restart-superagent vs /developers/superagents-runtime and /core-features/superagents

Problem: The Restart endpoint is documented as "Useful after updating soul or model." But two other pages insist no restart is required: Runtime says "Switch models anytime… no restart needed" and "Soul.md and model changes take effect immediately — no restart needed"; the core-features Superagents page says soul.md "Changes take effect in seconds."

Consequence: Users get conflicting operational guidance about the exact actions the restart endpoint exists for. Someone debugging why a soul.md edit "didn't take" can't tell whether they must call restart or just wait — and an agent automating config updates won't know whether to issue a restart after PUT /soul.

The fix: State the actual behavior precisely: e.g., "soul.md and model changes apply on the next message automatically; use restart only to force-apply immediately or to recover a stuck container." Align all three pages to that wording.

8. The FAQ describes the sunset V1 "Scheduled Agents" model as if it's the current product (significant)

Location: /support/faqs vs /guides/migrate-to-superagents and the SuperAgents pages

Problem: The FAQ describes agents using V1 concepts as current: you "set the strategy in the Instructions," every run "produces a reasoning trace in the Reasoning tab," you refine "based on what you learn from the Learnings tab," and you "connect your exchange." But the Migrate page explicitly says "Scheduled (V1) agents are being sunset," that "new scheduled agent creation is disabled," and contrasts V1's "Goal + instructions fields" and "System-managed memory" against SuperAgents' "soul.md" and "Agent-managed persistent memory."

Consequence: A new user reading the FAQ to understand the product learns the interface of a deprecated system they can no longer create. They'll look for an Instructions field, a Reasoning tab, and a Learnings tab that don't exist in the SuperAgents flow they're actually being funneled into.

The fix: Rewrite the FAQ around the SuperAgents model (soul.md, agent-managed memory, provisioned wallets, Telegram), and either remove V1-specific answers or clearly fence them under a "Legacy Scheduled Agents" heading that links to the migration guide.

9. Webhook and Alpha costs are quoted in "credits"; the rest of pricing is in dollars, with no conversion (significant)

Location: /developers/webhooks and /developers/alpha-overview vs /pricing

Problem: Webhooks are priced at "0.5 credits per real delivery" (alpha) and "0.1 credits" (radar); the Alpha overview repeats this. But the Pricing page never mentions "credits" as a denominated unit — it quotes dollars ($5, $0.17/day, $0.05/call, 10% markup) and says only that "Credits are consumed per query based on complexity." No page defines how many dollars a credit is, or how many credits a dollar buys.

Consequence: A developer cannot compute what their webhook volume will cost. "0.5 credits per delivery" is unbudgetable without a conversion rate, and the API page's "$100 minimum credits" mixes the two units in a single phrase. This blocks any cost estimate for automated integrations.

The fix: Publish the credit↔dollar conversion once on the Pricing page (e.g., "1 credit = $X") and link every credit-denominated cost back to it, or convert all costs to a single unit.

10. Advertised model names don't match the model IDs in the API examples, and "subscription" auth isn't a valid provider (significant)

Location: /developers/superagents-runtime, /api-reference/superagents/launch-superagent, /guides/integrations

Problem: The Runtime model table advertises "GPT-5.4 / GPT-5.4 Pro / o3 / o4-mini," "Claude Opus 4.6, Sonnet 4.6," and "Grok 4.20." But the Launch reference example uses model: "gpt-4o", and the Integrations custom-model examples use claude-sonnet-4-20250514 and anthropic/claude-sonnet-4 — none of which match the advertised "Sonnet 4.6" / "GPT-5.4" branding. Separately, Runtime advertises "ChatGPT Plus/Pro — paste your token to use GPT and o-series models via your subscription," but the only model_provider enum values in the API/spec are openai, anthropic, xai, openrouter, venice — there is no subscription/ChatGPT-token provider.

Consequence: A developer can't tell what string to actually put in the model field — the marketing name ("Sonnet 4.6"), the dated ID (claude-sonnet-4-20250514), or gpt-4o. And anyone who follows the "paste your ChatGPT token" pitch has no API path to do so, because no provider enum accepts it. Both lead to failed requests with no obvious cause.

The fix: Publish a canonical list of valid model IDs per provider (the exact strings the API accepts) and use only those in every example. Either add the subscription auth path to the API and document its provider value, or scope the "paste your ChatGPT token" feature to the dashboard and say so explicitly.

11. It's unclear whether a SuperAgent trades from its own provisioned wallet or a user-connected exchange (significant)

Location: /guides/superagents-setup and /guides/migrate-to-superagents vs /guides/integrations and /core-features/chat

Problem: The Setup guide and Migrate table say SuperAgents get "dedicated wallets provisioned automatically" (EVM + Solana, Privy-managed) that you fund by sending USDC to the agent's address. But the Integrations page says "Hyperliquid is the primary execution venue for Gigabrain Agents… Connect your wallet and sign transactions to authorize," and the Chat page says "Connect your exchange account to enable direct trade execution." HyperLiquid is named as a trading venue for SuperAgents, but the provisioned-wallet model only lists EVM and Solana.

Consequence: A user can't tell how their agent actually executes a HyperLiquid trade: from the agent's own provisioned wallet, or from a separately-connected personal Hyperliquid account? This determines where funds live, what the agent can access, and the blast radius if something goes wrong — exactly the thing you must understand before funding an autonomous trader.

The fix: Add one diagram/section to the Setup or Runtime page mapping each venue (HyperLiquid, Solana, EVM, Polymarket) to the wallet/account it trades from, and clarify whether the legacy "connect your exchange" flow applies to SuperAgents or only to V1/Chat.

12. The second product is named three different ways, including a leftover reference to a different product (significant)

Location: /index, /guides/integrations, and the SuperAgents pages

Problem: The landing page names the same product both "Gigabrain Agents" and "Gigabrain SuperAgents" in one document. The Integrations page calls it "Agents" / "Gigabrain Agents" throughout, while the rest of the docs standardize on "SuperAgents." Worse, the Integrations page contains a leftover sentence referencing a different product entirely — "At momentum we don't support unified accounts yet" — alongside typos like "generate apis wallet" and "diable [the unified account]."

Consequence: "Agents" vs "SuperAgents" is not cosmetic here — the docs also have a distinct, deprecated "Scheduled Agents (V1)" product, so a reader genuinely cannot tell whether an "Agents" page refers to the legacy product or the new one. The stray "momentum" reference signals copy-pasted content from another project and undermines confidence that the Hyperliquid setup steps are even Gigabrain's.

The fix: Standardize on one product name ("SuperAgents") everywhere except where you deliberately mean legacy V1 "Scheduled Agents," and reserve "Agents" for that legacy context. Scrub the "momentum" reference and fix the typos on the Integrations page.

13. The llms.txt index omits the entire SuperAgents developer surface (significant)

Location: /llms.txt

Problem: The published llms.txt index lists only developers/introduction, developers/overview, guides/migrate-to-superagents, index, the two legal pages, openclaw/brain, openclaw/overview, pricing, quickstart, support/contact, support/faqs, support/risk-disclosure, api-reference/brain/chat-with-the-brain, and openapi.json. It omits the entire SuperAgents developer and reference surface that the rest of the docs are built around: developers/superagents-api, developers/superagents-runtime, developers/webhooks, developers/alpha-overview, guides/superagents-setup, guides/integrations, all of core-features/* (skills, superagents, chat), and the api-reference/superagents/* and api-reference/superagent-lifecycle/* endpoints (launch, soul, skills, wallet, restart, destroy). (Confirm the scrape didn't truncate the file; on the captured inventory, these pages are absent.)

Consequence: llms.txt is precisely the entry point a coding agent uses to index a docs site. An agent that follows it would never discover how to launch, fund, or run a SuperAgent — the flagship product. The docs ship the machine-readable index agents are told to read, then leave the most important half of the product out of it; the gap is invisible to a human browsing the rendered nav and catastrophic for an agent indexing via the file.

The fix: Regenerate llms.txt from the full published page set so every SuperAgents developer page, guide, core-feature page, and lifecycle/launch endpoint appears in the index — and add a CI check that fails when a published page is missing from llms.txt.

14. OpenRouter model count is "200+" on one page and "400+" on two others (minor)

Location: /developers/superagents-runtime ("200+ models") vs /guides/integrations and /core-features/chat ("400+ models")

Problem: The Runtime page's provider table lists OpenRouter as "200+ models," while the Integrations page ("400+ models from all providers with one key") and the Chat page ("400+ models via OpenRouter") both say 400+.

Consequence: Minor on its own, but it's a visible, easily-fixed factual inconsistency about a headline capability number — the kind of discrepancy that erodes trust in every other number on the page. A user comparing model breadth gets two different answers in the same docs set.

The fix: Use one figure (or "hundreds of models") sourced from OpenRouter's actual catalog, and update all three pages together.

15. Webhook headers are duplicated, mis-cased, and the event-type values don't match the body (minor)

Location: /developers/webhooks

Problem: Three issues on one page: (1) X-GigaBrain-Webhook-Id and X-GigaBrain-Delivery-Id are both described as "Delivery id" — so it's unclear what the Webhook-Id actually identifies. (2) The headers and env var use a capital-B "GigaBrain" (X-GigaBrain-Signature, GIGABRAIN_WEBHOOK_SECRET) while the product is "Gigabrain" everywhere else — header names are case-insensitive but the env var and signature-verification code are not. (3) The X-GigaBrain-Event-Type header is documented as radar or alpha, but the body field event_type is alpha.created / radar.created.

Consequence: A developer writing a webhook handler can't distinguish the two *-Id headers, may switch on the wrong event value (header alpha vs body alpha.created), and risks a typo'd env var name. Signature verification copy-pasted with the wrong casing fails opaquely.

The fix: Give each header a distinct, accurate description (what is Webhook-Id vs Delivery-Id?), confirm and standardize the GigaBrain/Gigabrain casing for the env var and code sample, and document the exact relationship between the header event value and the body event_type value.

16. The two skill registries are named four different ways across pages (minor)

Location: /core-features/skills, /developers/superagents-runtime, /core-features/superagents, /openclaw/overview

Problem: The ~2,800-skill registry is called "ClawHub (2,800+)" (Runtime page), "OpenClaw's registry" (skills page), "ClawHub (clawhub.ai)" (core-features/superagents), and "OpenClaw" (overview). The ~110,000-skill registry is "skills.sh" on the Runtime page but only "Vercel's open directory" on the skills page — which never gives the skills.sh URL. Counts also drift ("2,800+ curated" vs no count).

Consequence: A user trying to browse skills doesn't know whether ClawHub and OpenClaw are the same site, and the skills page sends them to "Vercel's open directory" without a URL. This makes the install-from-registry instructions hard to follow.

The fix: Name each registry once, canonically, with its URL (e.g., "skills.sh" and "ClawHub / clawhub.ai"), and reuse that exact name and link on every page that mentions it.

17. The list of "compatible platforms" differs between the skills pages and the OpenClaw overview (minor)

Location: /core-features/skills and /core-features/superagents vs /openclaw/overview

Problem: The skills page and the core-features Superagents page both enumerate the same named set — "Claude Code, OpenClaw, Cursor, GitHub Copilot, Windsurf, Gemini CLI, and 26+ other platforms." The OpenClaw overview lists a different named set — "OpenClaw, Claude Code, Cursor, GitHub Copilot, OpenAI Codex, Gemini CLI, Windsurf, and 26+ other platforms" — adding OpenAI Codex to the explicitly-named tools.

Consequence: A developer checking whether their specific agent (e.g. OpenAI Codex) is supported gets a different answer depending on which page they land on. It's minor, but inconsistent example sets for the same "Agent Skills" compatibility claim read as carelessness next to a feature the docs lean on heavily.

The fix: Maintain one canonical list of named example platforms (and the "+N others" count) and reuse it verbatim on all three pages.

18. The Brain is described with two incompatible taxonomies (minor)

Location: /index vs /openclaw/brain

Problem: The landing page presents the Brain as "30+ data categories" organized into a six-row table (Market Data, Onchain, Macro, Derivatives, Research, Sentiment). The Brain SKILL.md instead presents it as "7 specialists / analysts" with a different seven-item breakdown (Macro, Microstructure, Fundamentals, Market State, Price Movement, Trenches, Polymarket). The SKILL.md's own description ("Covers 7 specialists and 30+ data categories") references both, but never maps one onto the other.

Consequence: A developer trying to predict which part of the Brain answers a given question has two non-matching mental models: the homepage's "Derivatives"/"Sentiment" buckets don't line up with the SKILL.md's "Microstructure"/"Market State"/"Trenches" analysts. Minor, but it makes targeting queries (and writing prompts that name a domain) guesswork.

The fix: Pick one taxonomy as primary and show how the other rolls up into it — e.g. a single table mapping the six homepage categories onto the seven analysts — so both pages describe the same structure.

19. Terms document is titled, named, and linked three inconsistent ways (minor)

Location: /legal/terms-and-conditions, /legal/privacy-policy, /llms.txt

Problem: The docs publish the agreement as "Terms and Conditions" at /legal/terms-and-conditions (confirmed by llms.txt), but its body opens "These Terms of Service (the 'Terms')," and the Privacy Policy links to a "Terms of Service" at the absolute URL https://gigabrain.gg/legal/terms-of-service — a different path. Cross-references are also mixed absolute/relative: the Privacy Policy uses an absolute terms link while the Terms page self-references the Privacy Policy with a relative /legal/privacy-policy.

Consequence: The Privacy Policy's link to gigabrain.gg/legal/terms-of-service points to a different path than the docs' actual /legal/terms-and-conditions, so a user clicking "Terms of Service" from the privacy page likely hits a wrong page or a dead link — a real broken cross-reference on a legal document, not merely a style nit.

The fix: Pick one title ("Terms of Service" or "Terms and Conditions") and one canonical URL, update the body heading to match, and make all cross-links point to that single path.

20. Contact page has a mis-cased support email, a possible-typo X handle, and outdated twitter.com links (minor)

Location: /support/contact vs /developers/introduction

Problem: The Contact page lists "Support@gigabrain.gg" (capital S), while the Auth & Basics page and everywhere else use lowercase support@gigabrain.gg. The "Alpha Agent" handle is listed as @aksgigabrain, which reads like a transposition of "ask" — but no scraped page confirms the intended handle, so this is a flag to verify, not a confirmed error. Both social links also use twitter.com/... rather than x.com/....

Consequence: Email local-parts are technically case-insensitive so the address still works, but the inconsistency looks unmaintained; if @aksgigabrain is in fact a typo, it sends users hunting for alpha signals to the wrong (or non-existent) account.

The fix: Lowercase the support email to match the rest of the docs, verify that @aksgigabrain is the real, intended handle (and correct it if not), and update both links to x.com.

What they do well

• A real machine-readable surface exists where it counts: a published openapi.json and per-page .md endpoints give agents the raw materials to index the docs — ahead of most platforms this size. (The llms.txt that should tie them together is incomplete; see Finding 13.)
• Response-time and rate-limit expectations are unusually concrete: the Auth & Basics page gives real latency bands (40–60s simple, up to ~600s), the exact rate-limit headers, and "set your client timeout to ≥600s" — genuinely useful, hard-won operational detail.
• The Brain "analysts" SKILL.md and the V1→SuperAgents migration table are clear and well-scoped — when a single page owns a topic without competing against another page, the writing is precise and developer-friendly.

Top 3 recommendations

1. Resolve the money-losing private-key contradiction first (Finding 1). A user following the FAQ before deleting an agent can act on false information about recovering funds. One authoritative wallet-lifecycle section should replace every divergent statement.
2. Make examples match the schema (Findings 2, 3, 10). Add the required model/model_provider to both launch snippets, fix the $BASE//chat URL, and publish the exact valid model ID strings. The first commands a new user runs must succeed on copy-paste.
3. Designate single sources of truth for the agent-facing assets and reconcile everything to them (Findings 5, 6, 13). Let the OpenAPI spec own status codes and both auth schemes (add X-API-Key), regenerate llms.txt to cover the whole SuperAgents surface, and have every prose page cite the spec rather than restate it — so the next contradiction can't drift back in and an agent indexing the docs sees the same product a human does.