Sourcebot Documentation Audit
Sourcebot's docs are broad and mostly well-structured — llms.txt, llms-full.txt, and a real OpenAPI spec all exist — but the corpus contradicts itself on the platform's own architecture, ships two blank pages in its navigation index, and its machine-readable exports silently drop the feature names from every paid-plan gating notice.
1. Embedded Postgres/Redis contradiction across three pages (critical)
Location: /docs/deployment/sizing-guide, /docs/misc/architecture, /docs/upgrade/v4-to-v5-guide
Problem: The V4→V5 upgrade guide states plainly: "Starting in v5, these embedded services have been removed. You must now provide your own Postgres and Redis instances... If either variable is missing, the container exits at startup with an error." The environment-variables reference agrees, marking DATABASE_URL and REDIS_URL as (required). But the sizing guide still says "We recommend using external managed Postgres and Redis instances rather than the ones embedded in the Sourcebot container, as this adds stability to your deployment" — implying embedded services still exist as a fallback. And the architecture page still lists "Postgres: transactional database" and "Redis Job Queue" as components of the single container run under supervisord, adding "You can use managed Redis / Postgres services that run outside of the Sourcebot container" as if that were optional.
Consequence: A developer planning a v5 deployment from the sizing guide or architecture page concludes that Postgres and Redis are bundled and external instances are an optional stability upgrade. Their container exits at startup. An AI agent reading llms-full.txt has no way to resolve the contradiction — two pages say embedded, two say removed — and will confidently generate a deployment that fails.
The fix: Update the sizing guide and /docs/misc/architecture to reflect the v5 topology: external Postgres and Redis are mandatory, and the container runs web server, worker, and Zoekt only. Reserve the embedded-services description for the versioned upgrade guide.
2. Two pages listed in llms.txt are completely empty (significant)
Location: /docs/deployment/k8s, /docs/deployment/infrastructure/architecture
Problem: llms.txt lists "Kubernetes (Helm)" and "Architecture Overview" as documentation pages, and multiple pages link to the former as a guide ("If you are looking to deploy onto Kubernetes, see the Kubernetes (Helm) guide"; "Deploy Sourcebot into your Kubernetes cluster using the official Helm chart"). In llms-full.txt both pages contain a title and nothing else — zero body content. The live /docs/deployment/k8s route (and its /docs/deployment/k8s.md export) returns HTTP 307 and silently redirects off-site to github.com/sourcebot-dev/sourcebot-helm-chart.
Consequence: Kubernetes is one of Sourcebot's two first-class deployment paths, and its docs page is blank in every machine-readable surface the site tells agents to use ("Fetch the complete documentation index at: https://docs.sourcebot.dev/llms.txt"). An agent asked "how do I deploy Sourcebot on Kubernetes" using llms-full.txt gets a heading with no content. Humans get bounced to a GitHub repo with no indication they've left the docs.
The fix: Either host real Helm/architecture content at these URLs, or remove them from llms.txt and replace in-docs links with explicit external links to the Helm chart repo so readers and agents know the guide lives on GitHub.
3. Machine-readable exports drop the feature name from every paid-plan notice (significant)
Location: llms-full.txt and all .md page exports (e.g. /docs/features/code-navigation.md, /docs/features/mcp-server, /docs/features/permission-syncing, /docs/configuration/audit-logs, /docs/configuration/idp, /docs/configuration/auth/roles-and-permissions, /docs/features/search/search-contexts)
Problem: In the rendered HTML, plan-gating callouts interpolate an MDX variable: "Code navigation is only available in a paid plan." In the exports that the docs explicitly tell agents to consume, the variable is either dropped — llms-full.txt renders "  only available in a paid plan. Please activate a license key to use this feature." with no subject — or leaks raw MDX: the .md export of the code-navigation page contains export const feature_0 = "Code navigation" / {feature_0} {verb_0 ?? "is"} only available in a paid plan.
Consequence: Licensing is the single most consequential fact on these pages (Ask Sourcebot, MCP, code navigation, and role management were all relicensed to paid in v5). An agent reading the exports sees a dangling "only available in a paid plan" note with no subject on at least seven pages and cannot tell whether it applies to the page, a subsection, or a specific auth method. The MCP page is the worst case: the same subject-less note repeats throughout — gating the MCP server itself at the top and the OAuth authorization method in each client-setup tab — and in the export those instances are indistinguishable.
The fix: Fix the MDX-to-markdown export so the feature/verb variables are interpolated (or inline the text), and regenerate llms-full.txt and the .md endpoints.
4. Search contexts: prose says context, the example and schema say contexts (significant)
Location: /docs/features/search/search-contexts
Problem: The page states "Search contexts are defined in the context object inside of a declarative config," while the JSON example on the same page — and the config-file schema list ("Search Contexts (contexts)") — use the key "contexts".
Consequence: A developer or agent who trusts the prose writes "context": {...} into config.json and gets a schema-validation failure (or a silently ignored block), then has to diff against the example to find the one-letter discrepancy. Agents extracting key names from prose will fail deterministically.
The fix: Correct the prose to contexts and lint config key names in docs against schemas/v3/index.json.
5. "All environment variables" reference omits the entire REDIS_TLS_* family (significant)
Location: /docs/configuration/environment-variables vs /docs/deployment/infrastructure/redis
Problem: The environment-variables page opens with "This page provides a detailed reference of all environment variables supported by Sourcebot," but the ten REDIS_TLS_* variables (REDIS_TLS_ENABLED, REDIS_TLS_CA_PATH, REDIS_TLS_CERT_PATH, REDIS_TLS_KEY_PATH, REDIS_TLS_REJECT_UNAUTHORIZED, etc.) documented on the Redis infrastructure page appear zero times on it.
Consequence: Anyone auditing their deployment config against the "all environment variables" reference — a natural thing for both platform teams and agents to do — concludes the TLS variables don't exist. Redis TLS is precisely the kind of setting an enterprise security review needs to find in one place.
The fix: Add the REDIS_TLS_* table to the environment-variables reference (or link out per-family), and stop claiming completeness unless it's generated from one source of truth.
6. Audit-log API example uses a header that doesn't exist in the OpenAPI spec, in a shell snippet that can't work (significant)
Location: /docs/configuration/audit-logs
Problem: The "Fetch audit logs" example is: curl --request GET '$SOURCEBOT_URL/api/ee/audit' --header 'X-Org-Domain: ~' --header 'X-Sourcebot-Api-Key: $SOURCEBOT_OWNER_API_KEY'. The X-Org-Domain header appears nowhere in sourcebot-public.openapi.json (which documents /api/ee/audit with bearerToken/apiKeyHeader security), and the single-quoted strings mean $SOURCEBOT_URL and $SOURCEBOT_OWNER_API_KEY are passed literally, never expanded. Meanwhile the API-reference Authentication page teaches only Authorization: Bearer <your-api-key> and never mentions the X-Sourcebot-Api-Key scheme this example relies on.
Consequence: Copy-pasting the snippet sends a request to the literal URL $SOURCEBOT_URL/api/ee/audit with an unexpanded literal API key — guaranteed failure. Developers are also left with three competing auth stories (Bearer-only on the auth page, X-Sourcebot-Api-Key here, both in the spec) and a phantom X-Org-Domain requirement.
The fix: Rewrite the example with double quotes and the documented Bearer header, drop X-Org-Domain (or document it in the spec if required), and mention the X-Sourcebot-Api-Key alternative on the Authentication page.
7. Plan gating for MCP vs anonymous access is circularly contradictory (significant)
Location: /docs/features/mcp-server, /docs/configuration/auth/access-settings
Problem: The MCP page opens with a note that the MCP server is "only available in a paid plan. Please activate a license key to use this feature." The access-settings page says "Anonymous access is only available in the free plan." Yet the MCP page states: "If anonymous access is enabled on your Sourcebot instance, no OAuth token or API key is required. You can connect directly to the MCP endpoint without any authorization."
Consequence: Read together, the docs describe an authorization mode (anonymous) that only exists on the plan (free) where the feature it unlocks (MCP) doesn't. A team on the free plan can't tell whether anonymous MCP works; a paid team can't tell why the anonymous-access instructions are on the page at all. Neither a developer nor an agent can derive a correct configuration from these three statements.
The fix: State the plan matrix explicitly on the MCP page: which plans can use MCP, and what the anonymous-access note means for each (e.g. legacy v4 behavior, or guest-role access on paid instances).
8. Hidden "declarative config" page duplicates the config-file page under different terminology (minor)
Location: /docs/configuration/declarative-config (linked from /docs/configuration/environment-variables CONFIG_PATH row and twice from /docs/features/search/search-contexts)
Problem: The CONFIG_PATH reference row says "the declarative configuration file. See this doc" — a live page titled "Configuring Sourcebot from a file (declarative config)" that is absent from llms.txt navigation and duplicates /docs/configuration/config-file with a thinner schema (its example even uses a different schema URL, refs/heads/main vs main). Every other page calls the same artifact the "config file."
Consequence: Readers following CONFIG_PATH land on a stub that omits the settings table, token syntax, and environmentOverrides that live on the real config-file page — and agents indexing via llms.txt never see the page that core reference links point to.
The fix: Redirect /docs/configuration/declarative-config to /docs/configuration/config-file and normalize on one term.
9. Inconsistent plan terminology: "paid plan" vs "enterprise license" vs "Pro" (minor)
Location: /docs/deployment/sizing-guide vs /docs/configuration/audit-logs, /docs/activating-a-subscription, sourcebot.dev
Problem: The sizing guide says "Audit logging is an enterprise feature and is only available with an [enterprise license]... If you are not on an enterprise plan, audit logs are not stored." Every other surface uses different tiers: the audit-logs and feature pages say "only available in a paid plan," the marketing site says "The Pro tier adds SSO, audit logs, and permission syncing," and the subscription page describes a single "paid plan."
Consequence: A buyer can't determine whether audit logging requires the Pro tier or some higher enterprise tier, and whether "paid plan" and "enterprise license" are the same purchase — a question that directly affects procurement.
The fix: Pick one tier vocabulary (Free/Pro, plus Enterprise only if it's a real distinct tier) and apply it to every gating note.
10. Typos and grammar errors in high-traffic reference tables (minor)
Location: /docs/configuration/environment-variables, /docs/activating-a-subscription, /docs/configuration/auth/roles-and-permissions
Problem: The required AUTH_SECRET row says "Genearte one with openssl rand -base64 33"; the subscription page has "sychronizing with our license server" and "until a successul ping is sent"; the roles table has "Members have access and to use all standard features" and "Guests are users that access Sourcebot without a account."
Consequence: Individually harmless, but these appear in the security-critical rows (required secrets, licensing downgrade behavior, permission model) where sloppiness erodes trust — and "Genearte" defeats a reader searching the page for "Generate."
The fix: Run a spellcheck pass over the reference tables; these five are quick wins.
What they do well
- First-class agent surfaces: llms.txt, a comprehensive llms-full.txt, per-page .md exports, and a real OpenAPI 3.0 spec (v5.1.7, 19 paths) with security schemes.
- The search syntax reference and MCP tool tables are precise, parameterized, and directly copy-pasteable.
- The V4→V5 upgrade guide is a model breaking-changes doc: who's affected, what changed, concrete migration steps including a pg_dump warning.
Top 3 recommendations
- Reconcile the v5 architecture story — fix the sizing guide and /docs/misc/architecture to match the upgrade guide's "embedded Postgres/Redis removed, external required."
- Fix the MDX export pipeline so paid-plan notes keep their feature names, and fill or delist the two empty pages (k8s, infrastructure/architecture) from llms.txt.
- Make the environment-variables page the actual single source of truth (add REDIS_TLS_*), and repair the audit-log curl example's quoting and phantom header.