chore: rename the .ai folder to .agents

.agents/README.md

@@ -0,0 +1,44 @@
+# AI Collaboration Guide
+
+This directory stores repo-local guidance for AI agents working in `pingcap/docs-cn`, the source repository for the Chinese TiDB documentation.
+
+## Structure
+
+- `.agents/shared/`: reusable repo policy, Chinese writing guidance, and EN -> ZH translation guidance
+- `.agents/skills/`: workflow-specific instructions for recurring tasks in this repo
+
+## Shared guidance
+
+Read only the files that apply to the task:
+
+- `.agents/shared/repo-conventions.md`: repository scope, branch and version rules, file naming, TOC expectations, AI/TiDB Cloud content boundaries, cross-repo (docs <-> docs-cn) traceability, and validation habits
+- `.agents/shared/writing-style.md`: document structure, Chinese-language wording and punctuation, formatting, headings, front matter, and repo-compatible writing style for Chinese docs
+- `.agents/shared/translation-rules.md`: EN (`pingcap/docs`) -> ZH (`pingcap/docs-cn`) translation constraints, traceability, structure preservation, and workflow expectations
+- `.agents/shared/translation-terms.md`: quick terminology reference for frequent translation terms
+
+Use `resources/tidb-terms.md` (the TiDB 中英术语表) when terminology is uncertain or not covered by the quick reference.
+
+## Current skills
+
+- `.agents/skills/write-update-tidb-docs/`: write new Chinese TiDB documentation or update existing documentation based on code PRs, issues, design docs, product specs, or feature descriptions; includes separate reference files for creating new docs (`ref-create-new-doc.md`) and updating existing docs (`ref-update-existing-doc.md`)
+- `.agents/skills/review-doc-pr/`: review documentation PRs and Markdown diffs for factual accuracy, user usefulness, completeness, version fit, related-doc impact, links, and Chinese writing style
+- `.agents/skills/docs-pr-metadata-guard/`: guard PR template structure when creating or editing pull requests, such as version checkboxes, required sections, HTML comments, related-link fields, and cherry-pick conventions
+- `.agents/skills/docs-issue-metadata-guard/`: guard issue template structure when creating or editing issues, such as template selection, required fields, scope boundaries, and label hygiene
+
+## Repo automation worth knowing
+
+This repository already automates several workflows. Prefer these over ad hoc processes:
+
+- `.github/workflows/sync-doc-pr-en-to-zh.yml`: syncs translated changes from an English source PR in `pingcap/docs` into an **existing** Chinese target PR in `pingcap/docs-cn` (it requires both `source_pr_url` and `target_pr_url`; it does not create the target PR). Manual dispatch only, restricted to authorized accounts.
+- `.github/workflows/sync-ai-docs-en-to-zh.yml`: weekly AI translation of `ai/` content and `TOC-ai.md` from `pingcap/docs` (`release-8.5`) into this repo. Do not hand-edit the Chinese `ai/` content; fix the English source in `pingcap/docs` instead.
+- `.github/workflows/doc_review.yml`: AI doc review triggered by a `/bot-review` comment, driven by `doc-review-prompt.txt`.
+
+## How to use it
+
+Use progressive loading so the task stays grounded but efficient:
+
+1. Start with the relevant shared guidance.
+2. Load a skill only when the task matches that workflow.
+3. Validate the files you changed with the repo's existing checks (`./scripts/markdownlint`, `./scripts/verify-links.sh`) when practical.
+
+Keep the task grounded in the existing repository rules, templates, scripts, and workflows.

.ai/shared/repo-conventions.md → .agents/shared/repo-conventions.md

@@ -116,8 +116,8 @@ Use them as references for expected behavior, even when local credentials, permi
 
 ## Agent behavior in this repository
 
-- Read the shared guidance in `.ai/shared/` before making non-trivial changes.
-- Use a matching skill in `.ai/skills/` when the task is workflow-specific.
+- Read the shared guidance in `.agents/shared/` before making non-trivial changes.
+- Use a matching skill in `.agents/skills/` when the task is workflow-specific.
 - Prefer minimal, targeted edits over broad rewrites.
 - Reuse existing wording, terminology, and document structure when they are already correct.
 - When unsure, check nearby docs, templates, and repository patterns before introducing a new approach.

.ai/shared/translation-rules.md → .agents/shared/translation-rules.md

@@ -27,7 +27,7 @@ Do not invent new product behavior, prerequisites, warnings, or version claims.
 
 ## Chinese-language quality
 
-After translating, the Chinese text must read as native documentation, not literal word-for-word conversion. Apply `.ai/shared/writing-style.md`:
+After translating, the Chinese text must read as native documentation, not literal word-for-word conversion. Apply `.agents/shared/writing-style.md`:
 
 - Add a space between Chinese and adjacent English words, numbers, or inline code.
 - Use full-width Chinese punctuation in prose and half-width punctuation inside code.
@@ -36,7 +36,7 @@ After translating, the Chinese text must read as native documentation, not liter
 ## Terminology
 
 - Use `resources/tidb-terms.md` (the TiDB 中英术语表) as the source of truth for terminology.
-- Use `.ai/shared/translation-terms.md` as a quick reference for high-frequency terms.
+- Use `.agents/shared/translation-terms.md` as a quick reference for high-frequency terms.
 - If a term is missing or ambiguous, keep the source term until you can verify the preferred translation.
 
 ## PR traceability

.ai/shared/writing-style.md → .agents/shared/writing-style.md

@@ -45,7 +45,7 @@
 
 ## 元数据
 
-- 发布的正文 Markdown 文档开头必须包含元数据（front matter）。`TOC*.md`、`README.md`、`resources/doc-templates/` 以及 `.ai/` 等非发布文档不要求遵循此项。
+- 发布的正文 Markdown 文档开头必须包含元数据（front matter）。`TOC*.md`、`README.md`、`resources/doc-templates/` 以及 `.agents/` 等非发布文档不要求遵循此项。
 - 元数据必须使用 `---` 包裹。
 - 元数据至少包含 `title` 和 `summary`。
 - `title` 必须与一级标题一致。

.ai/skills/docs-pr-metadata-guard/SKILL.md → .agents/skills/docs-pr-metadata-guard/SKILL.md

@@ -18,7 +18,7 @@ Before changing a PR body, read `.github/pull_request_template.md`.
    - Review the local file against the template before calling `gh`.
 3. Fill in the required sections with concrete information.
    - **What is changed, added or deleted? (Required)**: describe what changed and why in clear, specific language. Do not leave this blank or fill it with a generic placeholder.
-   - **Which TiDB version(s) do your changes apply to? (Required)**: check at least one version checkbox. Follow the affected-version rules in `.ai/shared/repo-conventions.md` and `CONTRIBUTING.md` (版本选择指南):
+   - **Which TiDB version(s) do your changes apply to? (Required)**: check at least one version checkbox. Follow the affected-version rules in `.agents/shared/repo-conventions.md` and `CONTRIBUTING.md` (版本选择指南):
      - Default to `master` only for general improvements, wording fixes, missing-content additions, and corrections not tied to a specific released behavior.
      - Check the affected release version(s) together with `master` when the change involves version-specific behavior, compatibility changes, changed defaults, or fixes in published docs.
    - **What is the related PR or file link(s)?**: fill in the source link under `This PR is translated from:` when the PR is a translation from `pingcap/docs`. Fill in other reference links such as product PRs, issues, or related doc PRs under `Other reference link(s):`.
@@ -27,7 +27,7 @@ Before changing a PR body, read `.github/pull_request_template.md`.
 4. Choose the correct base branch.
    - Default to `master` for most documentation PRs.
    - Use a specific `release-X.Y` branch when the change is scoped to a single published version and does not apply to `master`.
-   - Do not open PRs for the Chinese `ai/` content: it is auto-translated weekly from `pingcap/docs` (see `.ai/shared/repo-conventions.md`). Fix the English source instead.
+   - Do not open PRs for the Chinese `ai/` content: it is auto-translated weekly from `pingcap/docs` (see `.agents/shared/repo-conventions.md`). Fix the English source instead.
 5. For an existing PR, update only the mutable sections.
    - Safe targets: the description text under "What is changed, added or deleted?", the version checkboxes, the related-link fields, and the description checkboxes.
    - Do not rename headings, reorder sections, or rewrite the template wholesale.

.ai/skills/review-doc-pr/SKILL.md → .agents/skills/review-doc-pr/SKILL.md

@@ -17,9 +17,9 @@ Use this skill when the task is to review a documentation PR, a Markdown diff, o
 
 Read only the files that matter for the current review:
 
-- `.ai/shared/repo-conventions.md`
-- `.ai/shared/writing-style.md`
-- `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md` when the PR is a translation from `pingcap/docs`
+- `.agents/shared/repo-conventions.md`
+- `.agents/shared/writing-style.md`
+- `.agents/shared/translation-rules.md` and `.agents/shared/translation-terms.md` when the PR is a translation from `pingcap/docs`
 - `doc-review-prompt.txt` when you need to mirror the repo's AI review behavior
 - `resources/tidb-terms.md` when terminology is uncertain
 - `resources/doc-templates/<relevant-template>.md` if the doc type matters
@@ -33,7 +33,7 @@ Review from the user's perspective, not only the author's.
 Treat this skill as having two equally important responsibilities:
 
 1. Act as a TiDB expert and check for technical, accuracy, logic, consistency, and user-impact issues.
-2. Act as a senior Chinese technical writer: check whether the content is clear, concise, and easy to understand, and review it against `.ai/shared/writing-style.md`, including Chinese terminology (`resources/tidb-terms.md`), Chinese/English spacing, and full-width punctuation.
+2. Act as a senior Chinese technical writer: check whether the content is clear, concise, and easy to understand, and review it against `.agents/shared/writing-style.md`, including Chinese terminology (`resources/tidb-terms.md`), Chinese/English spacing, and full-width punctuation.
 
 Do not treat writing-style review as optional after the technical review. Both are part of the default review scope. When the content does not meet the bar for technical writing quality, improve it so the content becomes more logical, clear, concise, and easy to understand, while preserving technical meaning and scope.
 

.ai/skills/write-update-tidb-docs/SKILL.md → .agents/skills/write-update-tidb-docs/SKILL.md

@@ -22,7 +22,7 @@ This is an overview of the full workflow below — the create-vs-update decision
 
 Decide early whether this content should originate in English:
 
-- Many TiDB docs are authored in English in `pingcap/docs` and then translated into `pingcap/docs-cn`. If the same content is needed in both languages, coordinate so the English and Chinese sides stay traceable. When the English source already exists or is being written, prefer translating it (see `.ai/shared/translation-rules.md`) over writing an independent Chinese version that can drift.
+- Many TiDB docs are authored in English in `pingcap/docs` and then translated into `pingcap/docs-cn`. If the same content is needed in both languages, coordinate so the English and Chinese sides stay traceable. When the English source already exists or is being written, prefer translating it (see `.agents/shared/translation-rules.md`) over writing an independent Chinese version that can drift.
 - The `ai/` content is AI-translated weekly from `pingcap/docs` (`release-8.5`). Do not write or edit it directly here; author the English source in `pingcap/docs`.
 - Some Chinese-original content has no English counterpart. In that case, write it directly in this repository following the workflow below.
 
@@ -54,19 +54,19 @@ Multiple inputs can be combined. More context = fewer questions needed.
 - Inspect first, confirm when uncertain, then edit.
 - Prefer updating existing docs over creating new pages.
 - Not every code change needs a doc update. Documentation must justify its maintenance cost.
-- Write in Chinese, following `.ai/shared/writing-style.md` and `resources/tidb-terms.md`. Keep product names, commands, flags, paths, and config keys in English.
+- Write in Chinese, following `.agents/shared/writing-style.md` and `resources/tidb-terms.md`. Keep product names, commands, flags, paths, and config keys in English.
 - If the user asks about local changes without naming files, start with `git status -u` or `git show --name-status`.
 
 ## Step 1: Load shared context
 
 Always read before making any doc changes:
 
-- `.ai/shared/repo-conventions.md`
-- `.ai/shared/writing-style.md`
+- `.agents/shared/repo-conventions.md`
+- `.agents/shared/writing-style.md`
 
 Read only when relevant:
 
-- `.ai/shared/translation-rules.md` and `.ai/shared/translation-terms.md` — when translation from `pingcap/docs` is involved
+- `.agents/shared/translation-rules.md` and `.agents/shared/translation-terms.md` — when translation from `pingcap/docs` is involved
 - `resources/tidb-terms.md` — when terminology is uncertain
 
 ## Step 2: Analyze the input
@@ -116,7 +116,7 @@ Extract key user-facing facts. Ask focused questions only for facts that cannot
 | Version-specific behavior across maintained versions | `master` + `needs-cherry-pick-release-X.Y` labels |
 | `ai/` content | Do not edit here; author the English source in `pingcap/docs` |
 
-Follow the repository's cherry-pick model (see `.ai/shared/repo-conventions.md`): default to a single PR on the latest applicable branch (usually `master`) and rely on cherry-pick labels for other maintained versions, rather than opening parallel PRs per branch. When in doubt, target `master`.
+Follow the repository's cherry-pick model (see `.agents/shared/repo-conventions.md`): default to a single PR on the latest applicable branch (usually `master`) and rely on cherry-pick labels for other maintained versions, rather than opening parallel PRs per branch. When in doubt, target `master`.
 
 ### Version number for "从 vX.Y 起" notes
 
@@ -169,7 +169,7 @@ This skill produces **local edits + validation + a completion report**. It does
 | Guard PR template metadata when opening the PR | `docs-pr-metadata-guard` skill |
 | Guard issue template metadata | `docs-issue-metadata-guard` skill |
 | Review the resulting documentation PR | `review-doc-pr` skill |
-| Translate an English PR from `pingcap/docs` into Chinese | `.github/workflows/sync-doc-pr-en-to-zh.yml` (see `.ai/shared/translation-rules.md`) |
+| Translate an English PR from `pingcap/docs` into Chinese | `.github/workflows/sync-doc-pr-en-to-zh.yml` (see `.agents/shared/translation-rules.md`) |
 | Keep `ai/` content in sync | `.github/workflows/sync-ai-docs-en-to-zh.yml` |
 
 ## Output format

.ai/skills/write-update-tidb-docs/ref-create-new-doc.md → .agents/skills/write-update-tidb-docs/ref-create-new-doc.md

@@ -1,10 +1,10 @@
 # Create New TiDB Documentation
 
-Self-contained workflow for creating a new Chinese documentation page in `pingcap/docs-cn`. Follow these steps sequentially if the [write-update-tidb-docs](/.ai/skills/write-update-tidb-docs/SKILL.md) skill has determined that a new page is needed.
+Self-contained workflow for creating a new Chinese documentation page in `pingcap/docs-cn`. Follow these steps sequentially if the [write-update-tidb-docs](/.agents/skills/write-update-tidb-docs/SKILL.md) skill has determined that a new page is needed.
 
 ## Confirm the decision to create
 
-This is a final sanity re-check of the create-vs-update decision already made in Step 4 (the authoritative decision point) of the [write-update-tidb-docs](/.ai/skills/write-update-tidb-docs/SKILL.md) skill — not a second, independent decision. If any criterion below fails, switch to `ref-update-existing-doc.md`.
+This is a final sanity re-check of the create-vs-update decision already made in Step 4 (the authoritative decision point) of the [write-update-tidb-docs](/.agents/skills/write-update-tidb-docs/SKILL.md) skill — not a second, independent decision. If any criterion below fails, switch to `ref-update-existing-doc.md`.
 
 A new page is justified when all of these are true:
 
@@ -102,7 +102,7 @@ Every navigable page needs a TOC entry.
 Copy the front matter from the template you selected in Step 1 — do not retype a generic block, because the fields differ by template. For example, `resources/doc-templates/template-task.md` includes a `category` field (such as `category: how-to`), while `resources/doc-templates/template-new-feature.md` uses only `title` and `summary`.
 
 - `title` must match the H1 exactly.
-- `summary` must be a complete sentence ending with a period, concisely summarizing the page, and must not start with `>`, `*`, `#`, `-`, or `[` (if it must, wrap the summary in quotation marks). See `.ai/shared/writing-style.md` (元数据).
+- `summary` must be a complete sentence ending with a period, concisely summarizing the page, and must not start with `>`, `*`, `#`, `-`, or `[` (if it must, wrap the summary in quotation marks). See `.agents/shared/writing-style.md` (元数据).
 - Keep any other field the chosen template defines (for example, `category`); do not drop it.
 - Add `aliases` only if replacing an older page URL.
 
@@ -115,7 +115,7 @@ Copy the front matter from the template you selected in Step 1 — do not retype
 - Define jargon on first use.
 - Include realistic, runnable examples.
 - End with related resources or next steps.
-- Apply Chinese writing conventions from `.ai/shared/writing-style.md`: Chinese/English spacing, full-width punctuation in prose, and terminology from `resources/tidb-terms.md`.
+- Apply Chinese writing conventions from `.agents/shared/writing-style.md`: Chinese/English spacing, full-width punctuation in prose, and terminology from `resources/tidb-terms.md`.
 
 ### Structure by doc type