docs: add page title and description conventions for agents

.cursor/rules/docs-frontmatter.mdc

@@ -0,0 +1,73 @@
+---
+description: Frontmatter rules for docs MDX pages: titles and descriptions that read clearly in search results and help users identify page content
+globs: "**/*.mdx"
+alwaysApply: false
+---
+
+# Page titles and descriptions (frontmatter)
+
+Every page's `title` and `description` frontmatter is what users see in search
+results, browser tabs, and link previews. A generic title ("Overview", "Tips")
+or a vague description means users cannot tell what the page covers before
+clicking. Write them for someone scanning a list of results.
+
+## Title rules
+
+- Lead with the specific subject: the model, tool, or feature name. Generic
+  words like Overview, Tips, FAQ, or Getting Started are not enough on their
+  own. Pair them with the subject: "Custom node development tips",
+  "Get started with Comfy CLI".
+- When a model has an official product name, lead with it: "Wan Animate 2:
+  Motion Transfer", "FastVideo FastH3: ComfyUI Workflow Examples".
+- Say what the page helps the user do when the name alone does not.
+- Keep titles under about 60 characters so they do not truncate in results.
+- Never leave the title identical to the sidebar title when the sidebar is a
+  bare generic word; the title can be longer and more specific.
+- Localize titles for zh/ja/ko: translate meaning, keep the official product
+  name untranslated.
+
+## Description rules
+
+- Every page must have one. A missing description makes search engines invent
+  their own snippet from random page text.
+- 40 to 160 characters. Under 40 is too thin to be useful; over 160 gets cut
+  off in search results. Aim for 120 to 155.
+- Describe what the user will find and do on the page, covering the page's
+  actual scope (for a model page: what generation tasks it handles, what
+  workflows are shown).
+- Do not copy the title into the description. The description adds information
+  the title does not already say.
+- Put the key facts in the first 120 characters: search results may truncate
+  mid-sentence on narrow screens.
+- No marketing superlatives ("best", "ultimate", "powerful"). State facts.
+- Quote the value when it contains a colon followed by a space, or any other
+  YAML-special sequence. Unquoted `key: value` text inside a description
+  breaks frontmatter parsing.
+- Localize descriptions for zh/ja/ko: they must convey the same scope, not be
+  a character-for-character translation. Localized dates format automatically.
+
+## Anti-patterns and fixes
+
+| Bad | Why | Better |
+|---|---|---|
+| `title: Overview` | Says nothing about which overview | `title: "ComfyUI Manager Configuration"` |
+| `title: Tips` | Unfindable in search | `title: "Custom Node Development Tips"` |
+| `description: Using ComfyUI as a Developer` | 5 words, tells the user almost nothing | `description: "Build on ComfyUI with official Python and TypeScript SDKs, run it as a server, call Cloud APIs, or connect AI agents via MCP."` |
+| description duplicating the title word for word | Wastes the snippet slot | Cover scope the title leaves out |
+| `description: The best guide to everything ComfyUI` | Superlatives + overbroad scope | List what the page actually covers |
+
+## Examples
+
+Good model page:
+
+```yaml
+title: "Wan Animate 2: Motion Transfer"
+description: "Animate a still character using a driving video with Wan Animate 2, transferring motion directly from video frames without pose extraction or skeleton preprocessing"
+```
+
+Good reference page:
+
+```yaml
+title: "Custom Node Development Tips"
+description: "Practical tips for developing custom nodes for ComfyUI, including frontend/backend separation, packaging, and common API pitfalls"
+```

.cursor/skills/docs-i18n-translate/SKILL.md

@@ -27,6 +27,14 @@ pnpm translate:sync-docs-json       ← mirror nav paths in docs.json (opt-in)
 ```
 Incremental: each file stores `translationSourceHash` in frontmatter. Unchanged English → skip.
 
+### Title / description frontmatter (localized pages)
+
+`title` and `description` frontmatter carry localized meaning, not word-for-word
+translation. Localized titles keep the official product name untranslated;
+descriptions convey the same scope as EN within 40-160 chars. When an EN page's
+title/description changes in this repo, the zh/ja/ko values are updated in the
+same commit. Rules and examples: [.cursor/rules/docs-frontmatter.mdc](../../.cursor/rules/docs-frontmatter.mdc).
+
 ## Environment (`.env.local`)
 
 | Variable | Purpose |

AGENTS.md

@@ -26,6 +26,22 @@ When writing or editing English documentation, follow [.cursor/rules/docs-prose.
 **Instead of:** `**Discord** — #channel for questions.`  
 **Prefer:** `**Discord**: #channel for questions.`
 
+## Page titles and descriptions (frontmatter)
+
+Every MDX page's `title` and `description` frontmatter is what users see in
+search results and link previews. Generic titles ("Overview", "Tips") and
+vague or missing descriptions stop users from identifying page content before
+clicking. Follow [.cursor/rules/docs-frontmatter.mdc](.cursor/rules/docs-frontmatter.mdc)
+for every new or edited page:
+
+- Title leads with the specific subject (model/tool name or feature); a bare
+  generic word is not enough.
+- Description: 40 to 160 chars (target 120 to 155), states what the page
+  covers, never duplicates the title, no marketing superlatives.
+- Quote the description value when it contains a colon-space sequence.
+- zh/ja/ko pages carry localized titles/descriptions conveying the same scope;
+  sync them in the same commit as the EN change.
+
 ## Reference docs
 
 | Topic | Doc |