# V2 documentation guide

## Structure

- This directory is a standalone Mintlify site deployed from `packages/docs` on the `dev` branch.
- Write documentation in MDX. Every page should have `title` and `description` frontmatter.
- `docs.json` owns site configuration and navigation. Add, move, or remove its page entries whenever the corresponding MDX pages change.
- Put static files in `assets/` and reference them with root-relative paths such as `/assets/example.svg`.
- The API endpoint reference is generated by Mintlify from `openapi.json`; do not duplicate endpoint documentation as hand-written MDX.
- Keep documentation aligned with the V2 packages. Do not use `packages/opencode` as the source of truth unless the task explicitly concerns V1.

## Local development

- At the start of documentation work, launch `bun dev` from `packages/docs` using the shell tool with `background: true`. Never run the dev server in a foreground shell call and do not poll the process; wait for the background completion notification.
- Preview the site at `http://localhost:3333`. Mintlify does not expose a host option and binds the preview to all network interfaces. The server reloads changes to MDX and `docs.json` automatically.
- Use the running preview to verify navigation, links, Mintlify components, code blocks, and desktop and mobile layout.

## Validation

- Run `bun validate` from `packages/docs` after making documentation or configuration changes.
- Run `bun broken-links` from `packages/docs` when pages, navigation, headings, or links change.
- Treat validation errors and broken internal links as blockers. Also verify external links relevant to the change when practical.