Docs Authoring Guide: Mintlify Rules and i18n Policy

Docs Guide

This directory handles documentation authoring, Mintlify link rules, and the i18n policy for docs.

Mintlify Rules

The openclaw/docs mirror is where docs get published to https://docs.openclaw.ai.
Internal doc links in docs/**/*.md must stay root-relative, without any .md or .mdx suffix, for example [Config](/ai-agents/integrations/open-claw/docs/gateway/configuration).
For cross-references between sections, use anchors on root-relative paths, such as [Hooks](/ai-agents/integrations/open-claw/docs/gateway/configuration-reference#hooks).
Because Mintlify anchor generation is fragile there, doc headings should avoid em dashes and apostrophes.
README files and other GitHub-rendered docs should use absolute docs URLs so links function outside Mintlify.
Keep docs content generic: no personal device names, hostnames, or local paths; use placeholders like user@gateway-host instead.

Docs Content Rules

For docs, UI copy, and picker lists, arrange services/providers alphabetically unless the section specifically describes runtime order or auto-detection order.
Bundled plugin naming must align with the repo-wide plugin terminology rules found in the root AGENTS.md.
JSON5/JSON config fences that resemble complete openclaw.json documents undergo schema validation in CI with pnpm docs:check-config-examples; intentionally partial or legacy snippets opt out by adding validate=false to the fence info string.
Never hand-edit generated docs: docs/plugins/reference/**, docs/plugins/reference.md, and docs/plugins/plugin-inventory.md derive from pnpm plugins:inventory:gen, while docs/maturity/** comes from pnpm maturity:render.
During publishing and packaging, the public and packaged docs map is generated from pnpm docs:list --headings. Keep only the small source stub at docs/docs_map.md; never commit the expanded heading mirror.

Internal Docs

Long-lived private operator docs belong in ~/Projects/manager/docs/.
Repo-local internal scratch or mirror docs may live under ignored docs/internal/.
Never add docs/internal/** pages to docs/docs.json navigation or link them from public docs.
If a page is force-added later, scripts/docs-sync-publish.mjs excludes and prunes docs/internal/** from the public openclaw/docs publish repo.
Internal docs may reference repo paths, private app names, 1Password item names, and runbooks, but must never contain secret values.

Maturity Scorecard Editing

taxonomy.yaml and qa/maturity-scores.yaml serve as the source inputs; generated maturity docs under docs/maturity/ are projections and should not be hand-edited for score, LTS, taxonomy, QA profile, or evidence tables. Generation is owned by scripts/qa/render-maturity-docs.ts; use pnpm maturity:render to refresh committed docs and pnpm maturity:check to verify them. Artifact previews are rendered by .github/workflows/maturity-scorecard.yml, which can also open generated-doc PRs; .github/workflows/openclaw-release-checks.yml dispatches it for release QA. Keep deterministic qa-evidence.json.scorecard data in GitHub Actions artifacts unless a maintainer explicitly requests a sanitized committed projection. Human overrides must change source state in a PR, with the reason and public or redacted evidence explained.

Docs i18n

This repo does not maintain foreign-language docs. The generated publish output lives in the separate openclaw/docs repo, often cloned locally as ../openclaw-docs.
Do not add or edit localized docs under docs/<locale>/** here.
Treat English docs in this repo plus glossary files as the source of truth.
Pipeline: update English docs here, update docs/.i18n/glossary.<locale>.json as needed, then let the publish-repo sync and scripts/docs-i18n run in openclaw/docs.
Before rerunning scripts/docs-i18n, add glossary entries for any new technical terms, page titles, or short nav labels that must stay in English or use a fixed translation.
pnpm docs:check-i18n-glossary is the guard for changed English doc titles and short internal doc labels.
Translation memory lives in generated docs/.i18n/*.tm.jsonl files in the publish repo.
See docs/.i18n/README.md.