Gigabrain Documentation Audit

The docs are competent on shape — there's an OpenAPI spec, an llms.txt, structured rate-limit and status-code tables, a webhook signing scheme. The problems are about what's in those structures: an OpenAPI surface that disagrees with the migration page about which product is alive, model identifiers that violate the literal-ID convention the API reference itself establishes, a webhook signature format mangled by markdown, FAQ pages whose questions don't render, and a risk disclosure that references features the product docs never describe.

1. OpenAPI exposes a full Scheduled-Agents API the migration page says is being retired (critical)

Location: https://docs.gigabrain.gg/openapi.json vs https://docs.gigabrain.gg/guides/migrate-to-superagents

Problem: The OpenAPI spec documents a complete /v1/agents/* surface — POST /v1/agents ("Costs $0.20 in credits"), POST /v1/agents/{id}/enable, /disable, /wallet, /wallet/activate, /wallet/send, /v1/agents/suggest, /v1/agents/{id}/runs. Meanwhile the migration page states: "Scheduled (V1) agents are being sunset… new scheduled agent creation is disabled." The tags block even still lists Agents, Wallet, and Agent Chat & Monitoring as first-class taggings alongside SuperAgents.

Consequence: Any agent or developer that uses the OpenAPI as the source of truth (Postman import, codegen, an LLM doing tool discovery) will generate clients against deprecated endpoints. POST /v1/agents will fail because creation is disabled — but there's no deprecated: true, no error code listed for the disabled state, and no link from the OpenAPI back to the migration guide. This is the worst kind of contradiction: agents won't notice.

The fix: Mark every /v1/agents/* path (excluding the SuperAgent endpoints) as deprecated: true in the OpenAPI, add a top-level description noting the sunset, document the specific HTTP response returned when POST /v1/agents is called against a disabled product, and remove the now-stale Agents/Wallet/Agent Chat & Monitoring tags or rename them with a "(Legacy)" suffix.

2. Runtime page violates the literal-model-ID convention the API reference establishes (critical)

Location: /developers/superagents-runtime (Models section) vs /api-reference/brain/chat-with-the-brain

Problem: The API reference page for POST /v1/chat is explicit: the model parameter is "Model ID from the provider's API. Use the exact ID the provider uses — e.g. gpt-4o for OpenAI, claude-sonnet-4-20250514 for Anthropic, anthropic/claude-sonnet-4 for OpenRouter." The Runtime page, which is where a developer goes to pick a model, lists supported models as: Anthropic "Claude Opus 4.6, Sonnet 4.6"; OpenAI "GPT-5.4, GPT-5.4 Pro, o3, o4-mini"; xAI "Grok 4.20"; OpenRouter "200+ models"; Venice "Privacy-focused models." None of those are literal provider IDs in the claude-sonnet-4-20250514 style the API reference requires.

Consequence: A developer (or agent) reading the Runtime page can't construct a working model parameter for the API. The page never gives the literal string to pass into the request, and the marketing-style names won't pass through to the provider verbatim. The two pages disagree on what the value of model actually is — prose label vs. canonical ID.

The fix: Replace the prose model list with a parseable table of the literal model IDs accepted by the API for each provider (matching the claude-sonnet-4-20250514 style from the API reference), maintained programmatically so it doesn't drift. If you want marketing names, put them in a second column — but the column the agent reads must be the exact provider ID.

3. Webhook signature format is corrupted in the rendered docs (critical)

Location: /developers/webhooks

Problem: The Headers table documents X-GigaBrain-Signature as "HMAC signature, formatted as t=,v1=". The placeholders for the timestamp and signature values appear to have been eaten by markdown rendering — what's published is literally t=,v1= with no <timestamp> or <signature> content. The verification example then parses parts.t and a v1 field, but the header format documentation never shows what a real header value looks like. The signature algorithm is described as HMAC_SHA256(secret, timestamp + "." + raw_body), but the relationship between v1 and "v1" naming, scheme versioning, and signature payload is never spelled out.

Consequence: Developers writing their own verifier (the docs say verification is "optional but recommended" — and webhook verification is exactly the kind of thing developers must get right for a non-custodial trading service) have to reverse-engineer the format from the partial TypeScript snippet. Skipping it leaves trade-execution webhooks vulnerable to forgery.

The fix: Render a real example header: X-GigaBrain-Signature: t=1717000000,v1=8f3a…. Document the meaning of v1 (scheme version vs. signature key), and complete the truncated verification snippet end-to-end including the timing-safe comparison.

4. Risk Disclosure names "autotrade" and "vault participation" features that don't appear anywhere in the product docs (critical)

Location: /support/risk-disclosure vs llms.txt / feature pages

Problem: The Risk Disclosure (§7) states: "Certain features may allow you to configure workflows, rules, alerts, autotrade, vault participation, or other automated actions that may submit orders or take actions based on your prior configuration." Neither "autotrade" nor "vault participation" appears in the sitemap (llms.txt), the SuperAgents pages, the Chat page, the Integrations page, or the API reference. There is no documented endpoint, dashboard surface, or skill for either feature.

Consequence: This is the inverse of a normal docs gap: the legal copy describes capabilities the product docs don't. For a non-custodial trading service, the document users sign liability against names automation modes that have no published interface, scope model, revocation path, or risk profile. A developer can't audit what they cannot find; a user agreeing to the disclosure can't tell what they've consented to.

The fix: Either (a) document autotrade and vault participation as first-class features with their own pages — what they do, how to enable/disable them, what permissions they require, how to revoke — or (b) remove the references from the Risk Disclosure if they describe features that no longer exist. The Risk Disclosure cannot be the only place a feature is named.

5. "Bring your own ChatGPT subscription" is described in one sentence with no setup, token-type, or failure-mode docs (significant)

Location: /developers/superagents-runtime (Bring your own subscription)

Problem: The docs claim: "Already paying for ChatGPT? Use it with your SuperAgent: ChatGPT Plus/Pro — paste your token to use GPT and o-series models via your subscription." That's the entire spec. No page explains what "token" means here, where it is obtained, how it differs from a standard OPENAI_API_KEY, how to rotate it, what happens when it expires, or which surface accepts it.

Consequence: A developer cannot operationalize this feature from the docs. Worse, a SuperAgent is a 24/7 trading process — if the "token" is a session credential that silently expires, the failure mode is a stalled live agent with no diagnostic guidance.

The fix: Either remove the bullet, or write a dedicated page covering the exact token type, where to obtain it, how the platform stores it, the supported lifetime, and the precise error/behavior when the token becomes invalid mid-run.

6. The pricing page omits two material API-only costs (significant)

Location: /pricing vs /developers/superagents-api vs /openapi.json

Problem: The SuperAgents API overview states "Minimum credits: $100 to launch a SuperAgent through the API". The OpenAPI POST /v1/agents description states "Costs $0.20 in credits." Neither figure appears anywhere on /pricing. The pricing page covers compute ($0.17/day), Brain Intel ($0.05/call), LLM markup (10%), and the 0.05% builder fee — but a developer evaluating the API cannot reconcile the $100 floor from the dashboard pricing.

Consequence: A developer estimating cost from /pricing will undershoot the actual cash required to launch via API by ~$95, and won't know that legacy agent creation costs $0.20 per call. They learn the floor only after hitting a 4xx.

The fix: Add an "API-specific costs" section to /pricing that includes the $100 SuperAgent launch minimum, the per-creation cost for legacy agents, and a pointer to the rate limits/per-call pricing. Keep these numbers in one canonical place — ideally a JSON file the OpenAPI references — so the API docs and pricing page can't drift.

7. Token-gated tier claims "unlimited access" but the cost table charges token-gated users (significant)

Location: /pricing

Problem: The page says: "Hold 1M BRAIN tokens to unlock unlimited access." The example cost table for "Light/Moderate/Heavy" agent usage still shows monthly cost columns, and a footnote then admits: "Token-gated users receive monthly credits that offset intel costs." That's not unlimited — that's a credit allowance.

Consequence: A potential customer making a five-figure token purchase based on "unlimited access" later discovers there's a credit cap. This is the kind of marketing-vs-mechanics gap that ends up in support tickets and worse.

The fix: Replace "unlimited access" with the actual policy — "monthly credit allowance of $X, then pay-as-you-go" — and quantify the allowance. If there really is a tier with no credit metering, name it explicitly and define the rate-limit it operates under.

8. Hyperliquid integration page has broken English and a stale product name (significant)

Location: /guides/integrations

Problem: Multiple defects in a setup section for a real-money trade execution venue:

• "Connect your wallet and sign transactions to authorize generate apis wallet to trade on your behalf." — grammatically incoherent.
• "For new account Hyperliquid will create a unified account for you. At momentum we don't support unified accounts yet." — "At momentum" appears to be a leftover product name from a prior brand ("Momentum"), or a typo for "at the moment."
• "You can diable the unified account in hyperliquid settings." — typo for "disable."

Consequence: The setup step that grants on-chain trading authorization is the highest-stakes paragraph in the docs. Typos and incoherence at this point both erode trust and make it ambiguous what the user is being asked to sign. A reader who pattern-matches "momentum" to a different product may abandon the flow entirely.

The fix: Rewrite the entire Hyperliquid Setup section with copy review. Confirm whether "momentum" is a stale brand reference (search and purge) or a typo, and add a callout box around the unified-account warning since it's the actual blocker.

9. OpenRouter model count contradicts itself across three pages (significant)

Location: /developers/superagents-runtime, /guides/integrations, /core-features/chat

Problem: The Runtime page says OpenRouter: 200+ models. The Integrations page table says OpenRouter: 400+ models from all providers with one key. The Chat core feature page says 400+ models via OpenRouter. Same provider, three pages, two different numbers.

Consequence: Minor in isolation, but it's a symptom: there's no single source of truth for provider/model facts, which is the same root cause as issue #2. Agents indexing the docs will surface conflicting answers to "how many OpenRouter models are supported?" with no way to choose.

The fix: Replace the count with a link to OpenRouter's own model list, or pull the count from their API at build time. Never hard-code the same fact in three places.

10. Wallet management story contradicts itself between SuperAgents API and FAQ (significant)

Location: /developers/superagents-api vs /support/faqs

Problem: SuperAgents API page: "The API only exposes public addresses — private keys are never returned. Use the dashboard to manage funds." FAQ: "If you delete an agent without first exporting the wallet's private keys, any remaining funds in that wallet are permanently lost." The FAQ implies private-key export is the recommended pre-deletion safety step; the API page implies private keys are never accessible at all. The FAQ also doesn't disclaim whether this applies only to legacy V1 agents or also to SuperAgents.

Consequence: A user deleting a SuperAgent following the API doc's "use the dashboard" guidance may believe the platform retains a recovery path. A user following the FAQ may believe they can export keys via the SuperAgents API and find no such endpoint. Either misunderstanding loses funds.

The fix: Be explicit about which agent type each statement applies to. State unambiguously for SuperAgents: where private keys live (Privy), whether they're exportable, and the exact pre-deletion procedure to drain the wallet. Cross-link from FAQ to a single canonical wallet-lifecycle page.

11. Both the migration page and the FAQ page render answers with no questions (significant)

Location: /guides/migrate-to-superagents and /support/faqs

Problem: Two separate pages have the same broken FAQ component — bare answers float without question text. On /guides/migrate-to-superagents: "Yes, existing scheduled agents continue to work…", "No. SuperAgents get new wallets provisioned automatically…", "V1 agent learnings don't carry over…", "Migrate them one at a time…". On /support/faqs, after a few correctly-rendered Q&As, the page produces orphaned assertions like "Currently supported exchanges are listed in the Integrations section…" and — load-bearing for security — "No. APIs wallets used for trade execution does not have withdrawal permissions."

Consequence: "Yes/No" answers floating without their questions are read as raw assertions. The orphaned withdrawal-permissions sentence is a security claim about what API-provisioned wallets can and can't do — but with no question anchoring it, a developer can't tell whether it refers to SuperAgents, V1 agents, the user's own wallet, or all of the above. An LLM scraping this page indexes a permission guarantee without scope.

The fix: Fix the FAQ component so question text actually renders, on both pages. The withdrawal-permissions claim in particular should be moved into a dedicated, scope-explicit security section and not survive as a stray sentence.

12. Webhook event type appears in two incompatible forms (significant)

Location: /developers/webhooks

Problem: The headers table documents X-GigaBrain-Event-Type as taking values radar or alpha. The "Retries and Billing" table immediately below uses event_type values of alpha.created and radar.created. There's no statement of whether the header sends the namespace (alpha) and the body sends the qualified form (alpha.created), or whether one is a typo.

Consequence: A developer routing webhooks by header value will write if (req.headers['x-gigabrain-event-type'] === 'alpha.created') and silently drop every event because the header actually says alpha. The other direction also breaks.

The fix: State explicitly: "The header carries the namespace; the body's event_type field carries the qualified <namespace>.<action> form." Show a real example payload alongside the headers.

13. Quickstart has no developer on-ramp (significant)

Location: /quickstart vs /developers/introduction

Problem: The Quickstart is entirely dashboard-driven: open the Terminal, connect a web3 wallet, click into Chat, click into Alpha Feed, click into SuperAgents. There is no mention of the API, no link to /developers/introduction, and no path from "I'm a developer evaluating this" to a working curl/SDK call. The llms.txt lists Quickstart as a top-level entry, so an agent indexing the docs will land here and find nothing programmatic.

Consequence: For a docs site whose developer surface is non-trivial — Brain API, SuperAgents API, webhooks, OpenAPI — the canonical Quickstart not surfacing any of it is a real discoverability gap. Developers and agents alike route through the wrong door first.

The fix: Add a second track to /quickstart ("From the API: get a key → first POST /v1/chat request → response") with a working curl example and a link to /developers/introduction. Keep the dashboard track for non-developer users.

14. Chat trade execution authorizes free-form prompts with no scope or revocation docs (significant)

Location: /core-features/chat

Problem: The page documents triggering real trades by typing prompts like "Buy 0.1 ETH at market price", "Long BTC with $500, 3x leverage", "Close 50% of my ETH position". The only safety guidance is one sentence: "Only connect exchanges you trust and understand the API permissions you're granting." There is no documentation of (a) what API permissions Chat actually requests on Hyperliquid, (b) how Chat distinguishes a confirmed trade intent from a model hallucination of a trade command, (c) the structure of the confirmation step, or (d) the revocation flow when the user wants to disconnect.

Consequence: Chat is presented as a natural-language trade execution surface for real money, but the docs leave the permission and confirmation model implicit. Developers integrating against this — and risk-aware users — have nothing to audit. A model that suggests a trade rendered as a command is indistinguishable in prose from a user issuing one.

The fix: Document the exact permission scope Chat requests on each integration, the confirmation UI (with a screenshot of the confirm step), the revocation path, and the behavior when the model "suggests" a trade in its prose vs. when the user issues one. Cross-link to the Risk Disclosure.

15. Index page brand-name conflict: "Gigabrain Agents" vs "SuperAgents" (minor)

Location: / (docs index)

Problem: The home page sentence reads: "It has two core products: Gigabrain Intel for market intelligence and Gigabrain Agents for autonomous trading." The next heading is "Gigabrain SuperAgents". Every other page in the docs uses "SuperAgents." The legacy product (per the migration page) is the unnamed-on-this-page "Scheduled Agents."

Consequence: A first-time visitor doesn't know whether "Gigabrain Agents" is a third product, an umbrella term, or just a stale name for SuperAgents.

The fix: Pick one canonical name. If "SuperAgents" is the product, say "Gigabrain Intel for market intelligence and SuperAgents for autonomous trading."

16. API key placeholder format is ambiguous for agent extraction (minor)

Location: /developers/introduction, /developers/brain-api-overview

Problem: Every code example uses gb_sk_ or Bearer gb_sk_... with no clear placeholder marker. The ellipsis isn't a documented convention and the bare gb_sk_ (no body, no <your-key> token) reads as a literal string.

Consequence: An LLM extracting the example as a copy-paste snippet will copy gb_sk_... verbatim into a generated request, sending a literal three-dot key to the API and earning a 401 with no obvious explanation.

The fix: Use a documented placeholder convention everywhere — gb_sk_YOUR_API_KEY_HERE or gb_sk_<your_key> — and call out the placeholder syntax once in the Auth & Basics page.

17. Skills page references an unknown platform "OpenClaw" (minor)

Location: /core-features/skills

Problem: "The same skill format supported by Claude Code, OpenClaw, Cursor, GitHub Copilot, Windsurf, Gemini CLI, and 26+ other platforms." "OpenClaw" doesn't match any known coding-agent platform; this reads as a typo (perhaps for OpenCode, or an internal codename that escaped).

Consequence: Erodes credibility on a page whose entire purpose is to claim cross-platform interop. A reader who notices the typo discounts the rest of the compatibility claim.

The fix: Correct the name. If "OpenClaw" was intentional, link to it the first time it's mentioned.

18. API Credits expiration is stated in broken English with no anchor on when the clock starts (minor)

Location: /support/faqs

Problem: Under "Do API credits expire?": "API Credits purchased has expiry date of 1 year." This is a material commercial term — credits expire — expressed ungrammatically, with no statement of whether the 1-year clock starts at purchase, at first use, at last use, or rolls per top-up. The term does not appear on /pricing.

Consequence: A developer prepaying for API credits cannot determine how long their balance is good for or when it disappears. The grammar also fails copy-paste readability for any agent trying to summarize the policy back to a user.

The fix: Rewrite as a clear sentence ("API credits expire 12 months from the date of purchase. Credits from different purchases expire independently."), specify the clock-start rule, and mirror the policy to /pricing so it's not buried in a FAQ.

What they do well

• An llms.txt exists at the root and lists API-reference pages in clean .md form — better than most peers.
• The Auth & Basics page is structured: base URL, key prefix, dual header support, response-time tiers, and a status-code table that includes the unusual 504 case.
• The webhook page documents the signing algorithm, retry policy, per-event credit cost, and the "charged before send / not double-charged on retry" semantics — those are the right things to publish.

Top 3 recommendations

1. Reconcile the OpenAPI with the product reality. Mark deprecated /v1/agents/* endpoints as deprecated, remove stale tags, and document the disabled-creation error path. This is the single biggest agent-parsing risk in the docs.
2. Establish a single source of truth for model IDs and counts. Replace marketing-style model names with literal provider IDs maintained in one place, and pull provider model counts at build time. The Runtime page must give a developer the same string the API reference says to send.
3. Audit the trade-execution, risk-disclosure, and webhook sections line-by-line. Fix the corrupted t=,v1= signature placeholder, the "generate apis wallet" sentence, the "diable"/"At momentum" typos, the wallet-on-delete contradiction, the FAQ render bug on both pages, and either document or remove the autotrade/vault participation references in the Risk Disclosure. These pages handle real money and currently read like a first draft.