developer_handbook 模板

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.

## Project Architecture

This project documentation is built on the **doc-doc document server**. The documentation source is a Markdown directory tree of arbitrary depth: each directory maps to a collapsible chapter in the sidebar, and each `.md` file maps to a page. Multi-language support is included.

## 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., `installation/`, `linux-install.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**: `reference/` chapters use `` to show all levels recursively; other chapters use `` to show only direct sub-pages
- **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 an `install/` directory and an `install.md` file)
- **`reference/` is reserved for Reference chapters**: used to describe code entities in detail; the directory name must be `reference/`. Type tag badges must be used in headings: prefix tags go before the title (e.g., `#class# ExampleClass`, `#method# ExampleMethod`), and suffix tags go after the title (e.g., `#property# ExampleProperty #description#`). Built-in tags: `class`, `interface`, `enum`, `const`, `property`, `method`, `parameter`, `static`, `namespace` (alias: `ns`). Custom tags are also supported and rendered in a neutral style
- **Use `[ParentName]` to indicate inheritance**: e.g., `#class# ExampleChild[ExampleParent]` means ExampleChild inherits from ExampleParent. Do not use this notation in non-inheritance scenarios
- **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
- **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

- **API reference documentation is forbidden**: the developer handbook does not carry API reference documentation (HTTP endpoint paths and parameters, NATS subjects and payloads, response formats, etc.) - that is the responsibility of the separate `api_references` template. The developer handbook's `reference/` chapter only contains code entity definitions (Class / Interface / Enum, etc.); API endpoint and NATS interface descriptions are forbidden. When an API needs to be referenced, use `?keyword` to trigger site search pointing to the standalone API reference documentation instead
- **Execution order follows the root AGENTS.md**: the project workflow (planning -> nitrogen scaffolding -> documentation -> code -> testing) is defined in the Execution Workflow section of the workspace root AGENTS.md and is not restated here; in particular, documentation that plans code organization is written only after the corresponding subproject exists, per that workflow, and is produced according to the conventions in that subproject's AGENTS.md
- **Stack-specific code conventions are not restated in the handbook**: the handbook does not embed NestJS / Next.js or other stack-specific module and route rules; module and route documentation is produced according to the corresponding subproject's AGENTS.md
- **Separate Guides from Reference**: operation guides (how to do a task) and code entity reference (Class / Interface / Enum definitions) belong in different files. Guides teach steps; references list definitions. Do not mix them
- **An independent `Configuration Reference` document is required**: the `reference/` chapter must include a standalone configuration reference page that centrally lists all configuration items (name, purpose, default value, whether required, corresponding environment variable name), kept in sync with configuration changes
- **One file per topic; different topics must be split into different files**: each file focuses on a single piece of knowledge. Installation, configuration, usage, FAQ, and other distinct types of content must be kept in separate files; do not mix "how to install" and "how to use" in one file
- **Overview first, then details, progressively**: begin each chapter with an overview (what it is, why it matters), then expand into details (how to do it). Overall follow the progression `introduction -> getting-started -> architecture -> deployment -> modules -> reference`
- **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
- **Do not mention infrastructure deployment**: infrastructure (e.g., databases, Redis, K3s itself, etc.) is out of scope for an application; in normal cases existing infrastructure is used directly. Documentation covers only the deployment of the application/business services and does not address infrastructure provisioning or operations
- **Provide decision support**: when multiple options or applicable scenarios exist, use "when to use / when not to use" or comparison tables to help users decide; do not just list features and let users guess
- **Extract common functionality into shared files**: functionality shared by multiple sub-modules should be extracted into independent files to avoid duplication
- **Version-related content goes into its own files**: differences between versions 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 concept from file B, use a hyperlink to B instead of restating B's content in A
- **`reference/` non-code entry ordering rule**: **non-code** entries in the reference chapter (e.g., database schema entries distinguished by source system tags such as `#CRDB#` / `#VL#`) are sorted by **TAG first, then alphabetical, then related** - first group by Tag Badge, within the same tag sort alphabetically by name, and entries with subordinate relationships immediately follow their parent. Example order:
  ```
  #tag 1# abc
  #tag 1# xyz
  #tag 2# def
  #tag 2# def_2
  #tag 2# defg
  ```
  > This ordering rule **applies only to non-code entries**; code entries (`#class#`, `#interface#`, `#enum#`, `#const#`, `#method#`, etc.) are not subject to it and are sorted alphabetically by name.
- **Database schema entry tag combination rule**: database table/view entries are recommended to use a combination of two tag types; both tags can coexist:
  - **Source-system tags**: `#CRDB#` / `#VL#`
  - **Type tags**: `#Table#` / `#View#`
  - **Ordering rule**: the source-system tag comes first, the type tag second, e.g.:
    - `#CRDB# #Table# users`
    - `#CRDB# #View# user_summary`
    - `#VL# #Table# audit_logs`

## 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 developer handbook targets technicians who need to understand, extend, or maintain the system; the directory should follow the progression "overview first, concepts before reference". Below is a reference developer handbook directory; the "Modules" chapter directly reuses the structure you provided, while the other chapters supplement content developers typically care about.

1. Introduction
   - Example content 1
   - Example content 2

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

3. Architecture

   Covers both the overall system architecture and core concepts (domain models, key abstractions, design principles, etc.); there is no separate "Core Concepts" chapter.
   - Example content 1
   - Example content 2

4. Deployment

   Focus only on deploying the application/business services themselves.
   - Example content 1
   - Example content 2

5. Modules

   Each module's responsibilities, name, and key technologies used (e.g., queues, caches, event buses) without expanding on specific choices, which belong in "Architecture". This chapter is written according to the conventions in the corresponding subproject's AGENTS.md.
   - Sub-module A
     - Example content 1
     - Example content 2
   - Sub-module B
     - Example content 1
     - Example content 2

6. Reference

    Each Entity in the actual code gets its own file. Sub-titles within a file may describe its members; constants, methods, properties, etc. inside a Class or Interface do not need separate files.
    - #class# ExampleClass
    - #interface# ExampleInterface
    - #enum# ExampleEnum
    - #ns# #class# ExampleNamespaceClass
    - #ns# #interface# ExampleNamespaceInterface

    Sub-element tags (used only for members inside a file, not standalone files): `#const#`, `#property#`, `#method#`, `#parameter#`, `#static#`. When a Class/Interface itself contains sub-files (e.g., sub-types or sub-namespaces), also mark it with `#ns#` (or `#namespace#`) to indicate it is a container.

**Ordering recommendation**: overall follow `introduction -> getting-started -> architecture -> deployment -> modules -> reference`. Put `reference` last so users understand the big picture before looking up specific code entities.

## 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", "architecture", "deployment", "modules", "reference"]}
    introduction/
        index.md
        example-1.md
        example-2.md
    getting-started/
        index.md
        example-1.md
        example-2.md
    architecture/
        index.md
        example-1.md
        example-2.md
    deployment/
        metadata.docdoc.json  # {"order": ["example-1.md", "example-2.md"]}
        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
    reference/
        index.md
        example-class.md
        example-interface.md
        example-enum.md
        example-namespace-class/
            index.md
            example-subclass.md
        example-namespace-interface/
            index.md
            example-subinterface.md
  en/
    ...                         # Directory and file names identical to cn/
```

## Glossary

@glossary.md

| English | 中文 |
| ------- | ---- |
| docdoc | docdoc |
| Workspace | 工作区 |
| Site | 站点 |
| Artifact | 产物 |
| DataDir | 数据目录 |
| Registry | 站点注册表 |
| Chrome | 页面外观框架 |
| Sidebar | 侧边栏 |
| Minimap | 小地图 |
| rootPrefix | 根前缀 |
| Build Pipeline | 构建管线 |
| Baked at Build Time | 构建期烘焙 |
| Bearer Token | Bearer 令牌 |
| ACME | 自动化证书管理环境 |
| HTTP-01 Challenge | HTTP-01 质询 |
| systemd Unit | systemd 单元 |
| Watch Mode | 监听模式 |