Premium db auditing doc improvement (don't merge)

.agents/README.md

@@ -0,0 +1,54 @@
+# Agent Collaboration Guide
+
+This directory stores repo-local guidance for AI agents working in `pingcap/docs`.
+
+## Structure
+
+- `.agents/shared/`: reusable repo policy, writing guidance, and 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 rules, file naming, TOC expectations, TiDB Cloud boundaries, and validation habits
+- `.agents/shared/writing-style.md`: document structure, wording, formatting, headings, front matter, and repo-compatible writing style
+- `.agents/shared/translation-rules.md`: EN -> ZH translation constraints, traceability, structure preservation, and workflow expectations
+- `.agents/shared/translation-terms.md`: quick terminology reference for frequent translation terms
+
+Use `resources/terms.md` when terminology is uncertain or not covered by the quick reference.
+
+## Current skills
+
+- `.agents/skills/add-related-resources/`: produce and merge related resources cards for TiDB docs pages using the RelatedResources and ResourceCard MDX components for blog, video, and TiDB Lab links in English, Simplified Chinese, and Japanese docs
+- `.agents/skills/review-doc-pr/`: review documentation PRs and Markdown diffs for factual accuracy, user usefulness, completeness, version fit, related-doc impact, links, and style
+- `.agents/skills/create-or-update-zh-translation-pr/`: create a new docs translation PR or update an existing one by combining repo-local scripts with minimal-edit translation rules and incremental source-diff handling
+- `.agents/skills/writing-doc-summaries/`: write or update the `summary` front matter field in a document following the repo's 115-145 character SEO-friendly sentence rules
+- `.agents/skills/write-update-tidb-docs/`: write new 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/write-review-translate-release-notes/`: write, review, revise, and translate TiDB release note entries for the Feature details/Features, Compatibility changes, Improvements, and Bug fixes sections in English and Chinese
+- `.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
+
+The related resources skill includes bundled scripts under `.agents/skills/add-related-resources/scripts/` for:
+
+- fetching card metadata from blog, YouTube, and TiDB Lab URLs
+- validating `RelatedResources` blocks and `ResourceCard` formatting in modified docs
+
+The translation skill includes bundled scripts under `.agents/skills/create-or-update-zh-translation-pr/scripts/` for:
+
+- preparing structured translation inputs from a source PR
+- preparing structured translation inputs from either a full source PR or an update commit range
+- creating or reusing the translation branch
+- applying high-confidence deterministic updates before AI editing
+- committing, pushing, and creating or updating the PR with `gh`
+
+## 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. If the selected skill includes bundled scripts, prefer the scripts over retyping ad hoc commands.
+4. Validate the files you changed with the repo's existing checks when practical.
+
+Keep the task grounded in the existing repository rules, templates, scripts, and workflows.

.agents/shared/repo-conventions.md

@@ -0,0 +1,116 @@
+# Repo Conventions
+
+This file captures the repository-specific rules that agents should follow in `pingcap/docs`.
+
+## Repository scope
+
+- `pingcap/docs` stores the English TiDB documentation source.
+- `pingcap/docs-cn` stores the Chinese documentation source.
+- This repository is the source for the English TiDB documentation published on the PingCAP documentation website.
+- TiDB documentation and TiDB Cloud documentation do not always follow the same maintenance model. Do not assume they use the same branch, scope, or publication rules.
+
+## Repository versions and branches
+
+- The `master` branch tracks the latest development version of TiDB documentation.
+- Published TiDB documentation is maintained in the corresponding `release-<version>` branches.
+- Archived documentation is no longer maintained and should not receive normal documentation updates.
+- By default, target `master` unless the change clearly belongs to a maintained release branch.
+- Preserve branch intent. Do not treat release-branch behavior as the default development behavior, and do not move dev-only content into release branches.
+
+## Choosing affected versions
+
+Follow the repository's affected-version model when proposing or reviewing changes.
+
+- By default, affected versions should be `master` only for documentation enhancements, missing-content additions, wording fixes, refactors within a topic, and general corrections that are not tied to a specific released behavior.
+- Choose the affected release branch or branches together with `master` when the change involves version-specific behavior, compatibility changes, changed default values, changed system variable behavior, display fixes, or broken-link fixes in published docs.
+- If a change applies to multiple maintained versions, prefer the latest applicable branch and use cherry-pick labels instead of opening parallel PRs by default.
+- If most of the change can be cherry-picked but some branches require different wording or follow-up edits, account for version-specific follow-up work and the relevant reminder labels.
+
+## Cherry-pick and branch-follow-up conventions
+
+- Use the repository's cherry-pick label workflow instead of inventing a custom multi-branch process.
+- If a change applies only to one documentation version, use that branch directly and do not add unnecessary cherry-pick labels.
+- If a change applies to multiple documentation versions, prefer a single PR on the latest applicable branch and rely on cherry-pick labels for the remaining maintained versions.
+- If branch-specific differences are expected, flag that clearly so reviewers know follow-up edits are required in the cherry-picked PRs.
+
+## Repository layout and navigation
+
+- Use the existing repository structure and nearby documents as the primary guide for where new content should live.
+- New navigable documents usually require a matching update in the appropriate `TOC.md` file.
+- When a document is added, removed, moved, or renamed, check whether related TOC files, aliases, links, and cross-document references also need updates.
+- Reuse existing document patterns in the same area before introducing a new structure.
+
+## TiDB Cloud conventions
+
+- In this repository, TiDB Cloud documentation is maintained in the `release-8.5` branch for content reuse.
+- To contribute to TiDB Cloud documentation, make sure the PR is based on `release-8.5`.
+- Use `TOC-tidb-cloud.md` and `TOC-tidb-cloud-*.md` to understand which documents are TiDB Cloud-only and which TiDB documents are reused by TiDB Cloud.
+- If a path in `TOC-tidb-cloud.md` or `TOC-tidb-cloud-*.md` starts with `/tidb-cloud/`, it is TiDB Cloud-only content.
+- If a path in `TOC-tidb-cloud.md` or `TOC-tidb-cloud-*.md` does not start with `/tidb-cloud/`, it is reused from TiDB documentation.
+- Be careful with `CustomContent` tags such as `<CustomContent platform="tidb">` and `<CustomContent platform="tidb-cloud">`. Do not change, remove, or expand them casually, because they control platform-specific rendering behavior.
+- When editing shared TiDB and TiDB Cloud content, verify whether the change applies to both platforms or only one.
+
+## Contribution model
+
+- New documents should follow the templates in `resources/doc-templates/` when applicable.
+- Keep PR descriptions compatible with `.github/pull_request_template.md`.
+- Keep changes scoped to the requested task. Do not broaden a focused doc update into unrelated cleanup.
+- Prefer existing repository workflows, labels, and conventions over ad hoc alternatives.
+- When contributing diagrams, follow the existing diagram-style guidance rather than introducing a new visual style.
+
+## File naming rules
+
+- Use file names that briefly describe the document content, for example, `destroy-tidb-cluster.md`.
+- Keep file names concise and general. Avoid overly specific wording that might require frequent renaming and cause unnecessary URL changes.
+- Except for special files such as `TOC.md`, `CONTRIBUTING.md`, and `README.md`, use lowercase letters only in file names.
+- If a file name contains multiple English words, separate them with hyphens (`-`).
+- Do not use underscores (`_`) in file names.
+- Use lowercase file extensions only.
+- Markdown files must use the `.md` extension.
+
+## Content boundaries
+
+- Preserve product behavior, version numbers, links, anchors, file intent, and branch intent unless the task explicitly requires changing them.
+- Do not silently change technical meaning while improving wording.
+- Avoid changing commands, code samples, UI strings, configuration names, API fields, JSON, EBNF content, or generated helper files unless the task directly requires it or they are factually wrong.
+- When editing syntax-related content, be careful not to break EBNF or other structured source formats.
+- Keep cross-repo translation traceability when work maps between `docs` and `docs-cn`.
+- When a translation-related task maps content across repositories, preserve the source PR relationship, terminology intent, and affected-file mapping.
+
+## Front matter and document metadata
+
+- Preserve existing front matter structure unless the task requires a metadata change.
+- When front matter is present, keep `title`, `summary`, `aliases`, and other metadata aligned with the document content.
+- If a file is moved or renamed, check whether `aliases` should be updated to preserve inbound links.
+- Do not add or remove metadata fields casually. Follow existing patterns in nearby documents.
+
+## Linking and cross-document consistency
+
+- Preserve repository-relative absolute links when that is the repository convention.
+- When editing a document that summarizes or references other docs, check whether those related docs also need updates.
+- If a term, version statement, feature behavior, workflow, or compatibility note changes in one place, check nearby overview, task, reference, and release-note content for possible follow-up updates.
+- When changing headings, verify whether anchors, intra-repo links, TOC entries, or external references might be affected.
+
+## Validation habits
+
+Use existing repository checks instead of inventing new ones.
+
+- `./scripts/markdownlint <files>` for Markdown formatting
+- `./scripts/verify-links.sh` for link validation when links, anchors, moved files, or renamed files are involved
+- targeted repository scripts when the task touches glossary terms, keywords, anchor conflicts, or other specialized checks
+
+If a full check is too expensive for the task, validate the files you changed and any directly affected TOC or link targets.
+
+## Existing helpers
+
+Look for established scripts and workflows before automating from scratch.
+
+Use them as references for expected behavior, even when local credentials, permissions, or secrets prevent direct execution.
+
+## Agent behavior in this repository
+
+- 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.

.agents/shared/translation-rules.md

@@ -0,0 +1,44 @@
+# Translation Rules
+
+Use this file for EN -> ZH translation work that starts from changes in `pingcap/docs`.
+
+## Scope
+
+- This guidance is for mapping English docs work in `pingcap/docs` to Chinese docs work in `pingcap/docs-cn`.
+- Keep the translation faithful to the source change unless the target repo or branch requires a documented difference.
+
+## Preserve structure
+
+Keep the following stable unless translation requires a language-only adjustment:
+
+- heading hierarchy
+- lists and numbering
+- tables and column order
+- code fences and info strings
+- links, anchors, and repo paths
+- commands, flags, API names, config keys, and version numbers
+- product names and branch names
+
+Do not invent new product behavior, prerequisites, warnings, or version claims.
+
+## Terminology
+
+- Use `resources/terms.md` as the source of truth for terminology.
+- 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
+
+When preparing a translation PR:
+
+- reference the source English PR or file links
+- preserve the intended affected versions as much as the target repo allows
+- keep the PR body compatible with `.github/pull_request_template.md`
+- make the relationship to the source PR explicit
+
+## Workflow expectations
+
+- Identify the source files and the target files before translating.
+- Check whether the target branch should be `master` or a release branch.
+- If a helper script is available, prefer adapting it over rewriting the workflow from scratch.
+- If local automation depends on unavailable tokens or secrets, still prepare the branch, file list, PR body, and follow-up instructions so a human can finish the workflow quickly.

.agents/shared/translation-terms.md

@@ -0,0 +1,52 @@
+# Translation Terms
+
+Use this file as a quick terminology reference for EN -> ZH translation work in the TiDB docs workflow.
+
+For anything missing or unclear, check `resources/terms.md` before making a translation choice.
+
+## High-frequency terms
+
+| English | Preferred Chinese |
+| :-- | :-- |
+| cluster | 集群 |
+| node | 节点 |
+| instance | 实例 |
+| component | 组件 |
+| deployment | 部署 |
+| upgrade | 升级 |
+| configuration item | 配置项 |
+| parameter | 参数 |
+| system variable | 系统变量 |
+| feature | 特性 |
+| experimental feature | 实验特性 |
+| compatibility | 兼容性 |
+| limitation | 限制 |
+| high availability | 高可用 |
+| disaster recovery | 容灾 |
+| backup | 备份 |
+| restore | 恢复 |
+| migration | 迁移 |
+| replication | 复制 |
+| transaction | 事务 |
+| statement | 语句 |
+| table | 表 |
+| schema | 数据库模式 |
+| index | 索引 |
+| query | 查询 |
+| SQL statement | SQL 语句 |
+| access | 访问 |
+| authentication | 身份验证 |
+| authorization | 授权 |
+| privilege | 权限 |
+| role | 角色 |
+| monitoring | 监控 |
+| alert | 报警/告警 |
+| log file | 日志文件 |
+| troubleshooting | 故障排查 |
+| glossary | 术语表 |
+
+## Usage notes
+
+- Keep product and feature names in English when that is the established repo usage.
+- Keep commands, flags, file paths, and configuration keys unchanged.
+- Prefer consistency with the target repo over ad hoc wording improvements.