> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Documentation Contributions

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:

| Content                                                                                       | Owning section  |
| --------------------------------------------------------------------------------------------- | --------------- |
| Installation, prerequisites, and first successful run                                         | Get Started     |
| Configuration, commands, operation, results, and troubleshooting                              | User Guide      |
| Architecture, source contracts, extension implementation, validation, and contribution policy | Developer Guide |

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:

```text theme={"system"}
docs/en/developer_guide/extensions/example_integration.mdx
docs/zh/developer_guide/extensions/example_integration.mdx
```

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:

```mdx theme={"system"}
---
title: "Example Integration"
---

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:

```mdx theme={"system"}
[Testing and Validation](/en/developer_guide/contributing/testing)
[测试与验证](/zh/developer_guide/contributing/testing)
```

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](/en/developer_guide/contributing/testing) 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:

```bash theme={"system"}
cd docs
mint broken-links
mint validate
```

Preview changes that affect navigation, MDX components, tables, tabs, styling, or command layout:

```bash theme={"system"}
cd docs
mint dev
```

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](/en/developer_guide/contributing/testing#run-the-basic-checks). 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](/en/developer_guide/contributing/testing) for implementation and test evidence, and complete the [Pull Request Checklist](/en/developer_guide/contributing/pull_request_checklist) before requesting review.