Skip to main content
Update AgentCompass documentation in the same pull request as the public behavior it describes, and keep every published page verifiable in both languages.

​
Plan the Documentation Change

Put information where its reader will look for it: Keep one page focused on one reader goal. Link to the canonical explanation instead of copying shared defaults, CLI signatures, result schemas, or provider behavior into several pages. Use these sources in order:
  1. docs/docs.json for the published site structure and navigation.
  2. Existing pages in the same section for terminology, depth, and style.
  3. AgentCompass implementation and configuration for behavior, defaults, fields, and supported components.
  4. Official upstream documentation for provider-specific behavior.
Do not infer flags, defaults, compatibility, or output fields from an old example. Use component discovery and generated configuration documentation when applicable, inspect the owning implementation for behavior that is not generated, and make sure public commands use syntax accepted by the current CLI. Publish only public provider and infrastructure information. Keep organization-specific deployment details, credentials, endpoints, images, mounts, and setup procedures outside the public documentation tree.

​
Organize Both Language Pages

Paths and localization. English and Chinese pages must use the same path relative to their locale root:
Within developer_guide/, place pages under the architecture/, extensions/, or contributing/ directory that matches their Mint navigation group. Name a group landing page overview.mdx. Complete both language pages in the same pull request unless maintainers explicitly approve staged localization; do not use mixed-language content as a temporary fallback. In Chinese pages, translate ordinary English terms while retaining product names, acronyms, code identifiers, and the project terms agent, Model, Benchmark, Harness, Environment, Recipe, runtime, provider, and sandbox. Keep each Chinese prose paragraph, list item, and prose block inside an MDX component on one source line so soft line breaks do not introduce visible spaces. When naming all four core components, use Model, Benchmark, Harness, Environment in that order. Preserve lowercase model when it is a code identifier, and preserve the actual BENCHMARK HARNESS MODEL positional order in CLI syntax. Frontmatter. Start every MDX page with a clear title and state the reader’s goal in the first paragraph:
Do not add a description or icon field to page frontmatter. The first paragraph supplies the summary, and navigation hierarchy supplies visual structure. Navigation and links. Add every published page to both locale trees in docs/docs.json at the equivalent hierarchy and position. Keep navigation shallow and use icons only for tabs and top-level section groups, not nested groups or individual pages. Use root-relative, extensionless internal links:
English pages link to /en/ targets and Chinese pages link to /zh/ targets. Update incoming links when a page moves, add a redirect for an already published path, and never simulate hierarchy with leading spaces in page or group titles. Check translated headings because generated fragment IDs can differ by locale; prefer the page root when a section anchor is unnecessary. Shared assets. Store images shared by both languages under docs/images/ and give each image descriptive alt text. Store reusable MDX or JSX components under docs/snippets/, import them with a root-relative path, and pass locale-specific copy explicitly. Use images, tables, tabs, or interactive components only when they make a relationship or choice easier to understand, and check both desktop and narrow layouts after changing them.

​
Write Code and Command Examples

Lead with the task the reader wants to complete, then provide accurate steps, expected output fields, and common failure boundaries. Use direct language and address the reader as “you.” For code and commands:
  • add a language identifier to every fenced block;
  • use real component IDs or clearly marked placeholders;
  • keep secrets in environment variables and use redacted values;
  • verify option spelling, default behavior, output paths, and accepted syntax against the current implementation;
  • put copyable commands and path templates in fenced blocks instead of long inline-code spans, keep source files separate from their symbols, and describe nested lookups one level at a time;
  • describe version-sensitive upstream behavior with the relevant supported version or official source.
Use Testing and Validation to distinguish discovery or dry-run checks from execution tests and to choose evidence for the changed contract. Do not paste complete result directories, large trajectories, generated datasets, credentials, or private infrastructure details into examples or assets.

​
Validate Documentation Changes

From the documentation root, run the required link and MDX checks:
Preview changes that affect navigation, MDX components, tables, tabs, styling, or command layout:
In the preview, check both locale routes, navigation placement, headings, code wrapping, links, tables, and responsive layout. Also run the repository pre-commit checks described in Testing and Validation. Fix validation errors rather than suppressing a page, asset, or link unless exclusion is the intended public behavior.

​
Provide Documentation Evidence

Record only the evidence specific to the documentation change in the pull request:
  • English and Chinese page paths;
  • affected docs/docs.json entries and redirects;
  • exact mint broken-links and mint validate outcomes;
  • preview evidence for material layout changes.
Use Testing and Validation for implementation and test evidence, and complete the Pull Request Checklist before requesting review.