user_manual 模板

Do not modify AGENTS.md; it is managed by nitrogen and only `nitrogen update` regenerates it
With the user's explicit consent, you may modify the files referenced by AGENTS.md (`glossary.md`)
Do not describe features to be implemented in future versions, or add next-version TODO-style statements; stay limited to the present, always assume the current version is the final iteration.

## Product Documentation Positioning

The user manual targets end users. Its goal is to help users complete real work tasks, not to explain system implementation. Content should follow the main thread of "what I want to do → how to do it → what the result is", use fewer technical terms, and provide more UI paths, operation steps, and examples.

## doc-doc Usage Guidelines

- **`docdoc.json` configures the site**: `languages` maps language codes to display names (`{lang_code: name}`) and the first declared language is the default; `title` is an i18n map `{lang_code: site title}` resolved per page language (missing languages fall back to the first language, then `"文档"`); `copyright` sets the footer text (i18n map `{lang_code: text}`, falling back to the first language); `icon` accepts an emoji/short text, a remote URL, or a relative path to an image inside the docs root (local files are inlined as base64 at render time); when unset, the header falls back to a default document icon. Without a `docs` array, each `<lang>/` directory is one whole document and pages live at `<lang>/...`; the site root redirects to the first page
- **`docs` declares sub-documents, rendered as a horizontal tab bar under the top header**: each entry declares only `name` (URL segment, unique, snake_case) and `path` (source directory under the site root); the document's own manifest `<path>/doc.docdoc.json` carries `title` (i18n map `{lang_code: tab label}`), `languages` (must list every language the document ships — the document appears under a language only when declared there and `<path>/<lang>/` exists on disk), and an optional `renderer` — `tree` renders a collapsible outline sidebar, `submenu` renders a drill-down sidebar (breadcrumb chain + entries of the current directory; directories are entered by clicking, not expanded), `group` renders a grouped sidebar (directory titles as small group labels with all entries always expanded and no collapsing); in `submenu` and `group` forms, a directory's index page is listed as the first entry under the same title instead of selecting the directory row itself; defaults to `tree`. With `docs` declared, content roots live at `<path>/<lang>/` and URLs become `<lang>/<name>/...`; the site root redirects to the landing page of the first document. Format: `{"name": "my-site", "title": {"cn": "My Docs"}, "languages": {"cn": "简体中文", "en": "English"}, "docs": [{"name": "handbook", "path": "developer_handbook"}]}` with `developer_handbook/doc.docdoc.json` = `{"title": {"cn": "Developer Handbook"}, "languages": {"cn": "简体中文", "en": "English"}, "renderer": "tree"}`
- **Headings may declare an icon with `<Icon name="..." />`** using Phosphor bold icon names (e.g. `rocket-launch`, `warning-circle`, `database`): wherever it appears inside the heading text, the icon always renders at the very front of the heading; build-time title cleanup strips it from sidebar entries, the search index, and the heading slug
- **Code fence signature is ``` ```language:type#tab ``` **: `language` selects syntax highlighting; `:type` hands the fence to the interface renderer (e.g. `jsonschema:parameters`, keeping its Table ⇄ TypeScript dual-view); `#Tab Label` merges the block into a tab group — adjacent fenced blocks (blank lines only between them) that EACH carry a `#Label` merge into one tabbed code block; a lone labeled block or a run interrupted by any other content stays a plain code block, and `d2` diagram fences never merge into tabs
- **Directory and file names must be English and match one-to-one across languages**: directories and `.md` file names under `cn/` and `en/` must be identical, only the content differs by language, ensuring exact page correspondence when switching languages
- **Directory and file names use kebab-case English slugs**: lowercase letters and hyphens (e.g., `quick-start/`, `example-task.md`), no spaces, underscores, or Chinese characters
- **Every directory must have an `index.md`**: content should only be a short overview plus a TOC macro; do not hand-write a list of sub-pages
- **Choose the TOC macro by chapter type**: use `` to show only direct sub-pages; do not recursively list overly deep levels
- **Use `metadata.docdoc.json` to control sidebar order and renderer (optional)**: directories that need neither can omit this file; doc-doc will sort alphabetically and inherit the sidebar renderer. The file is an **object** with optional keys: `order` (sibling entry order, e.g. `{"order": ["a.md", "b.md"]}`) and `renderer` (`"tree" | "submenu" | "group"`, which overrides the sidebar renderer for this directory's subtree — the deepest configured directory wins per page, falling back to the sub-doc's `renderer` in doc.docdoc.json). Directory names have no extension; file names include the `.md` extension. **Do not list `index.md`** — clicking the directory name in the sidebar navigates to it, so it does not need a separate entry
- **Directories containing only `index.md` are prohibited; use a single file when there are no sub-files, use a directory only when there are**:
  - A topic with no sub-files must use a top-level `.md` file directly (e.g., `deployment.md`); creating an empty wrapper such as `deployment/index.md` is forbidden
  - Only make a directory (with an `index.md` overview page inside) when the topic genuinely needs to be split into multiple sub-files
  - This does not conflict with the "every directory must have an `index.md`" rule - the latter constrains directories only and does not require every topic to become a directory
  - Placeholder chapters (content only "To be added") follow the same rule: use a top-level `.md` file as the placeholder, or do not create the chapter until there are actual sub-pages
  - The following two cases must use a single file instead of a directory:
    1. Only `index.md` exists with no other sub-files
    2. `index.md` and one other file exist, but `index.md` merely links to that file without real body value
  - Criterion: a directory must contain at least one `.md` file or subdirectory besides `index.md`, and `index.md` itself must have independent body value; otherwise using a directory is forbidden
- **Prefer splitting files over creating large single files**: when a `.md` file's content can clearly be divided by sub-topic, prefer splitting it into multiple smaller `.md` files (and promote to a directory when necessary) rather than letting a single file grow too long, which harms readability, maintenance, and navigation. Split granularity target: each file focuses on a single sub-topic
- **Avoid naming conflicts**: at the same level, a directory name and a `.md` file name cannot be identical (e.g., you cannot have both a `quick-start/` directory and a `quick-start.md` file)
- **Use relative paths for links between files**: `[example link](../example/example-1.md)`; doc-doc will convert them to SPA routes automatically
- **Prefer D2 for diagrams**: flowcharts, architecture diagrams, and relationship diagrams should use ` ```d2 ` code blocks (doc-doc renders D2 via the bundled `@terrastruct/d2` WASM package — no external `d2` binary required). Mermaid is still supported; use it only when D2 cannot satisfy the requirement. Screenshots and UI diagrams may be used, but must be accessible (alt text)
- **A glossary `glossary.md` is required**: place `glossary.md` at the document root (next to `docdoc.json` and language directories such as `cn/`, `en/`) to collect project-specific terms, abbreviations, key concepts, and definitions. This file is not intended for end users to browse directly; it is a terminology/translation consistency reference for AI and authors. The glossary must use a table format and include at least the following columns:
  - `English` (required): the original/standard English term
  - `中文` (required): the corresponding Simplified Chinese translation
  - `...`: append other languages actually used in the documentation in order, such as `日本語`, `Français`, etc.

  Example:

  | English      | 中文     | 日本語         |
  | ------------ | -------- | -------------- |
  | Workspace    | 工作区   | ワークスペース |
  | Pull Request | 拉取请求 | プルリクエスト |
- **Keep glossary term mappings up to date**: the same proper noun must map one-to-one across language versions; update it when terms are added, changed, or deprecated
- **Glossaries must stay in sync across languages**: all language versions must keep glossary entries, meanings, and mappings consistent to avoid inconsistency across the multi-language site

## Rules

- **One file per user task; different tasks must be split into different files**: each file focuses on one user goal. Example task A, example task B, example task C, etc. must be kept in separate files; do not mix "how to do example task A" and "how to do example task B" in one file
- **Separate operation instructions from parameter descriptions**: task tutorials (step-by-step how-to) and field/parameter references (what options exist and what they mean) belong in different files. Tutorials emphasize steps; references emphasize explanations. Do not mix them
- **An independent `Configuration Reference` document is required**: the documentation must include a standalone configuration reference page that centrally lists all user-configurable options (name, purpose, default value, whether required), kept in sync with configuration changes
- **Overview first, then details, progressively**: begin each chapter by stating "what this chapter helps you do", then give prerequisites, then move into steps. Overall follow the progression `introduction → getting-started → core-concepts → modules → guides → advanced → editions → faq → support`
- **Do not hand-write "related content" headings**: do not add sections such as "Related content", "Related links", "Related files", "Next steps", or "Further reading" in the body, nor any manually maintained link aggregation sections. Related content is naturally carried by TOC macros and inline hyperlinks, avoiding missed updates when files are added or removed
- **Direct references to related files are forbidden**: do not list links pointing to related files in forms such as "Related docs: XXX"; files may be moved or renamed, causing links to become invalid. When directing readers to related content, use the `?keyword` format to trigger doc-doc's site search, which locates targets by keyword and is more robust than hardcoding file paths
- **Edit results must not include explanatory notes**: when performing edits such as deletions, merges, or replacements, output the final result directly; do not append any explanatory notes (e.g., "Removed XX", "No separate XX chapter", "This was originally XX", etc.)
- **Do not use speculative wording such as "suggest" or "in the future"**: documentation outputs definitive content; phrases such as "suggest in the future...", "later you can...", "may in the future..." that describe changes not confirmed to happen or unverified proposals are forbidden. Describe only currently established facts and currently effective practices
- **No need to restart the docdoc service after editing docs**: restarting the service is not this AGENT's task; verify documentation by checking the `.md` files themselves for content and structure
- **Steps take priority over explanations**: content that can be expressed as numbered steps should not be written as long paragraphs. Each step should include a specific location (menu/button/path), action, and expected result
- **Provide decision support**: when multiple options or applicable scenarios exist, use "who it's for / who it's not for" or comparison tables to help users decide; do not just list features and let users guess
- **Extract common operations into shared files**: operations used by multiple features (e.g., example operation A, example operation B) should be extracted into independent files to avoid duplication
- **Version-related content goes into its own files**: differences between versions/plans should each be independent; do not mix them on the same page
- **Link between files instead of repeating content**: when file A refers to a feature from file B, use a hyperlink to B instead of restating B's content in A
- **UI copy must be accurate**: names of example buttons, menus, and prompts must match the actual product so users can find the corresponding entry

## Documentation Directory Division

> The following directory structure demonstrates the progression order; actual content should be based on project functionality. Chapter numbers and hierarchy must be followed strictly, but sub-item names, counts, and specific business details can be adjusted per project.

The user manual targets end users who need to complete real work; the directory should follow the progression "learn the product first, then get started quickly, and finally find by task scenario". Below is a reference user manual directory; the "Modules" chapter directly reuses the structure you provided, while the other chapters supplement content users typically care about.

1. Introduction
   - Example content 1
   - Example content 2

2. Getting Started
   - Example content 1
   - Example content 2

3. Core Concepts
   - Example content 1
   - Example content 2

4. Modules

   Divide by product feature modules. For each module, explain what users can do, typical usage scenarios, and key entry points.
   - Sub-module A
     - Example content 1
     - Example content 2
   - Sub-module B
     - Example content 1
     - Example content 2

5. Guides
   - Example content 1
   - Example content 2

6. Advanced
   - Example content 1
   - Example content 2

7. Editions
   - Example content 1
   - Example content 2

8. FAQ
   - Example content 1
   - Example content 2

9. Support
   - Example content 1
   - Example content 2

**Ordering recommendation**: overall follow `introduction → getting-started → core-concepts → modules → guides → advanced → editions → faq → support`. Put `support` last so users master usage before getting help.

## Directory Structure Example

```
document/
  docdoc.json
  glossary.md                 # Glossary at the same level as language dirs, collecting terms, abbreviations, and key concepts
  cn/
    index.md
    metadata.docdoc.json  # {"order": ["introduction", "getting-started", "core-concepts", "modules", "guides", "advanced", "editions", "faq", "support"]}
    introduction/
        index.md
        example-1.md
        example-2.md
    getting-started/
        index.md
        example-1.md
        example-2.md
    core-concepts/
        index.md
        example-1.md
        example-2.md
    modules/
        index.md
        example-module-a/
            index.md
            example-1.md
            example-2.md
        example-module-b/
            index.md
            example-1.md
            example-2.md
    guides/
        index.md
        example-1.md
        example-2.md
    advanced/
        index.md
        example-1.md
        example-2.md
    editions/
        index.md
        example-1.md
        example-2.md
    faq/
        index.md
        example-1.md
        example-2.md
    support/
        index.md
        example-1.md
        example-2.md
  en/
    ...                         # Directory and file names identical to cn/
```

## Glossary

@glossary.md

| English | 中文 |
| ------- | ---- |
| Site | 站点 |
| Sub-document | 子文档 |
| Manifest | 站点清单（docdoc.json） |
| Artifact | 构建产物 |
| Registry | 站点注册表 |
| Token | 认证令牌 |
| Bearer Token | Bearer 令牌 |
| ACME | ACME 证书协议 |
| systemd unit | systemd 单元 |
| Tree navigation | 树形导航 |
| Submenu navigation | 逐级菜单导航 |
| Minimap | 页内大纲 |
| Landing page | 落地页 |
| Root prefix | 根前缀 |
| Plain mode | 无清单模式 |
| Keyword search link | `?keyword` 搜索链接 |