# Contribute and maintain docs (https://condensate.dev/operations/contributing/)

> Build, edit and check this documentation site.

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:

```sh
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:

| Marker | Replaced with |
| --- | --- |
| `<!-- diagram:NAME -->` | A visual explainer from `apps/docs/src/explainers.ts`. Names: `architecture`, `harness`, `lifecycle`, `windows`, `middleware`, `workspace`, `accounts`. |
| `<!-- example:NAME -->` | A TypeScript file from `apps/docs/src/examples`. Names: `client`, `list`, `follow`, `send`. |

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

```sh
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.