opencode/packages/docs/AGENTS.md

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.