Contribute and maintain docs

This page explains how to build, edit and check this documentation site. The site is built from Markdown guides, visual explainers and package manifests, and renders pages with search, a sidebar, an on-this-page outline, code copying and a mobile menu.

Build and preview

From the Condensate repository root:

bun run docs:build
bun run docs:dev

docs:build writes a static site to apps/docs/dist. Next to each page's index.html it writes an index.md, a Markdown copy for agents. At the root it writes llms.txt, an index of those copies, and llms-full.txt, every page in one Markdown file. docs:dev builds once, then serves that output at http://127.0.0.1:5192. DOCS_PORT can choose another port. The server does not watch files. After you edit a page, run bun run docs:build again while it runs, which updates existing routes. Restart the server when you add a page, because it reads its route list at startup.

The static output needs a host that serves directory indexes and uses 404.html for missing paths. It needs no model credentials, API proxy, or live runtime, and building it does not publish it. The build reads the checkout's git HEAD, so run it from a git checkout that has at least one commit.

Edit a guide

Curated pages are Markdown files in apps/docs/content. A page is published only when apps/docs/src/catalog.ts lists it, with its navigation group, summary, and the implementation files it describes. A Markdown file with no catalog entry is ignored.

Package reference pages are generated. The build reads every package.json under packages/ and apps/ and takes the scripts, exports, and workspace dependencies from it. To change the one-line summary of a generated page, edit its entry in descriptions in catalog.ts. Do not write those pages by hand.

Two markers in a page are replaced at build time:

Keep claims tied to the implementation. Distinguish an engine from a provider transport, a durable thread from a live session, and an implemented runner from a configured deployment. A proposed design belongs in an explicitly labelled historical or design record.

Each catalog entry's sources list names the files a page describes. The build fails if a listed path is not a file in the repository, and names each page and path. It links a file only when that file is committed at HEAD, so a new, uncommitted file is left out of the links without an error. These links appear in an Implementation panel on the page. The public site build removes that panel, so readers see the links only in the local preview.

bun run docs:check compiles every ts and typescript fence in the authored pages against the real workspace packages, each block as its own module. A block can import what apps/docs depends on: @condensate/agents-sdk and effect. The check prints each compiler error as page:line and fails. A block that cannot compile on its own, such as a condensed excerpt of internal code, opts out with a // @noErrors: <reason> line. The reason is required. The CI site job runs the check before the build.

content/http-routes.md is generated from the routers that packages/agents-host/src/main.ts joins into the runtime's listener. apps/docs/src/http-routes.ts lists those files. Do not edit the page by hand. Run bun run docs:http-routes after changing a route, and commit the page. The generator fails when a file in packages/agents-host/src registers a route but is not in its list. Add the file to routeSources if main.ts joins its router, or to otherListeners with the reason if it does not. The CI site job runs bun run docs:http-routes -- --check and fails when the page is out of date.

content/errors.md is generated from the tagged errors in packages/agents-sdk/src. Each error class carries static readonly facts (its stage and whether to retry), typed by ErrorFacts in errors.ts. Do not edit the page by hand. Run bun run docs:errors after adding or changing an error, and commit the page. The command fails when an SDK error has no entry in the catalog. The CI site job runs bun run docs:errors -- --check and fails when the page is out of date.

The build also rejects unknown markers, duplicate routes, and internal links that match no page. It checks the links in the HTML pages, and the condensate.dev links in llms.txt, llms-full.txt and each index.md. Relative links in a page body that point at repository files become GitHub links at HEAD. Avoid them. The site build's privacy check fails on GitHub URLs for the repositories in apps/site/private-repos.txt, and condensate is listed there.

Validate changes

bun run --cwd apps/docs typecheck
bun run --cwd apps/docs test
bun run docs:check
bun run docs:build
bun run typecheck
bun run test
bun run lint:slop:ratchet

apps/docs/tests/build.test.ts covers the link check, HTML escaping, explainer names, and code colouring. Check search, direct page URLs, mobile navigation, keyboard access, and a page with a long code example. Do not mark repository gates green when unrelated failures remain.

The docs are served at the root of condensate.dev. The CI site job installs the workspace, runs bun run docs:check and bun run docs:build, then bun run site:build and bun run site:check -- --external, and uploads apps/site/dist as the seven-day condensate-site artifact. CI never deploys it.

bun run site:build mounts the docs at the root of apps/site/dist, and old /docs/ addresses redirect to the same page at the root. It fails when apps/docs/dist is missing. It also checks the vendored forkit copy, internal links, and private repository URLs. bun run site:dev builds the docs and the site, then previews them on port 5193.

READMEs and architecture records

Repository and workspace READMEs stay short entrypoints with setup context. They point readers to the guides in docs/. Architecture records in docs/architecture describe the system in more depth than the guides. Do not copy their claims into a guide until you have checked them against the source.

Public guides cover implementations verified against the repository. Keep unpublished designs, local deployment notes, and historical audits out of the site catalog.