obot

# CLAUDE.md

Guidance for AI agents working in the `docs/` directory. The root `CLAUDE.md` covers the rest of the repository.

## Layout

The `docs/` directory holds the Docusaurus 3 site published at docs.obot.ai. It contains one editable set of docs plus a read-only snapshot for each past release.

- `docs/` holds the current, unreleased documentation. It is served at `/next/` and is excluded from search indexes.
- `versioned_docs/version-vX.Y.Z/` holds the snapshot taken when that release was cut. The first entry in `versions.json` is the latest release, and it is served at the site root.
- `versioned_sidebars/` holds one sidebar snapshot per version, and `sidebars.ts` is the sidebar for `docs/`.
- `plugins/` holds two custom plugins, `canonical-urls.ts` and `structured-data.ts`, along with the shared `PATH_REDIRECTS` map in `utils.ts`.
- `static/` holds images and downloadable files, and it is not versioned.

## Never link to a doc page with an absolute path

Write every link to another doc page as a relative path to the markdown file, and keep the `.md` extension.

```markdown
[MCP Servers](./mcp-servers.md)                        <!-- same folder -->
[User Roles](../configuration/user-roles.md)           <!-- different folder -->
[Auditor Role](../configuration/user-roles.md#auditor) <!-- a heading on another page -->
```

Never write the link as a site path like `[MCP Servers](/functionality/mcp-servers/)`.

An absolute path always resolves to the latest release at the site root, no matter which version the page lives in. A page inside `versioned_docs/version-v0.23.0/` that links to `/functionality/mcp-servers/` therefore sends the reader to the v0.25.0 page instead of the v0.23.0 one. The link also breaks the whole build as soon as someone renames or removes that page in a later release, because `onBrokenLinks` is set to `throw`. A relative markdown link resolves inside the version that contains it, so every snapshot keeps pointing at its own pages.

Images and downloads are the exception. Files under `static/` are shared by every version, so link them with an absolute path, e.g. `![Add a server](/img/add-mcp-server-type-selector.png)`.

## Edit the current docs, not the snapshots

Make ordinary content changes in `docs/` only. A file under `versioned_docs/` is a published snapshot of a release, so leave it alone unless you are fixing something that breaks the site across versions, such as a bad link.

When you fix a page in `docs/` that also exists in a released version, prefer to leave the released version as it was. Backport a change into `versioned_docs/` only for a correction serious enough to mislead someone running that release.

## Adding a page

Create the markdown file under `docs/` with `title` frontmatter, then add its id to `sidebars.ts`, which is a manual list rather than an autogenerated one. Note that `sidebars.ts` is indented with tabs. The id is the file path without the extension, e.g. `functionality/mcp-tunnels`.

Two pages set explicit routes in their frontmatter: `overview.md` uses `slug: /`, and `installation/overview.md` uses `slug: /installation/overview`. Preserve those routes when renaming or replacing either page.

A leading number in a filename is stripped from the generated document ID and URL, e.g. `installation/reference-architectures/02-aws-eks.md` is served at `/installation/reference-architectures/aws-eks/`. Sidebar order comes from the entry position in `sidebars.ts`, not the filename. Keep the number when writing a relative link because the link points to the file itself.

## Renaming or removing a page

Add a redirect to the `redirects` array of `@docusaurus/plugin-client-redirects` in `docusaurus.config.ts` so the old URL still works.

Add an entry to `PATH_REDIRECTS` in `plugins/utils.ts` that maps the old path to the new one, written without leading or trailing slashes. An empty string means the canonical URL falls back to the site root. Both `canonical-urls.ts` and the swizzled `src/theme/DocItem/Metadata` component read the map, so it is what gives the older copies of the page a canonical URL that resolves. Without an entry, the build prints `[canonical-urls] No valid canonical target for ...` and falls back to the site root.

Leave `versioned_docs/` alone. Each snapshot keeps its own copy of the page under the old name, and the relative links inside it keep working.

## Verifying changes

Run `npm run build` from `docs/` after any change to links, filenames, or the sidebar. A broken link fails the build because `onBrokenLinks` is `throw`, and `.github/workflows/docs.yml` runs the same build on every pull request that touches `docs/**`.

For a live preview, run `make serve-docs` from the repository root, or `npm run start` from `docs/`.

## Cutting and dropping a version

Both commands run from the repository root.

- `make gen-docs-release version=v0.26.0` snapshots `docs/` into a new version.
- `make remove-docs-version version=v0.22.0` deletes a version and needs `jq` on the PATH.

Include the `v` prefix in `version=`. The convention is to keep the latest release plus the three before it, so pair each new cut with a removal of the oldest.

You don't need to edit `docusaurus.config.ts` when you add or drop a version. It reads `versions.json` at build time to build the version dropdown, `lastVersion`, and the sitemap ignore list.

More agent context in obot-platform/obot

6 other files this repository gives its agents.