Sourcebot

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.