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.

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.

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.