api_references 模板

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. This template strictly governs the writing of "API Reference" documentation — one file per API (HTTP endpoint or NATS request-reply interface), directories organized by resource, and a fixed heading structure within each file.

## 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., `user/`, `get-by-id.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
- **TOC macro is always ``**: show only direct sub-pages; do not recurse into deeper 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 `user/` directory and a `user.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
- **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 API per `.md` file**: each HTTP endpoint or NATS request-reply interface gets its own file; different APIs must be kept in separate files; do not describe multiple APIs in one file
- **One DTO / Interface per `.md` file**: each DTO / Interface gets its own file; do not pack multiple DTOs into one file
- **Organize directories by resource; every distinct resource route is its own directory group, even with a single endpoint**: the resource of an HTTP route is its path minus version prefixes, trailing `:param` segments, and endpoint-specific sub-actions: `/api/v1/sites`, `/api/v1/sites/by-name/:name` share `sites/`; `/api/v1/document` and `/api/v1/tree` are two resources and get `document/` and `tree/`. NATS request-reply interfaces use the first segment of the subject, e.g., subject `user.by-id` goes under `user/`; HTTP routes and NATS subjects of the same resource share that resource directory. Endpoints of different resources never sit as sibling pages in one directory
- **Routes versioned under `/api/v<N>` aggregate into one parent group** (this aggregation applies only to the `/api/v<N>` version-prefix scenario; other shared prefixes do not create parent groups): all `/api/v1/...` resources live as per-resource subdirectories inside one aggregation directory named after the kebab-case prefix (`api-v1/`), whose `index.md` title is the real prefix path `# /api/v1`; the resource directories inside title with the resource name only (`# document`, `# sites`) and are ordered alphabetically or via `metadata.docdoc.json`. Endpoint pages never live directly in the aggregation directory
- **API titles and group directory titles use the real path as-is, never descriptive text, never translated**: every API page's title Uri and every group directory's `index.md` title keep the real route path as-is in **all** language versions. Resource directories use the route path (e.g., `# /user`); resource directories nested under a `/api/v<N>` aggregation group use the resource name only (e.g., `# document` under `# /api/v1`); the group holding server-root endpoints uses the real path `# /`; non-path groups (e.g., DTO collections) use the directory name verbatim (e.g., `# types`). Descriptive words such as `misc` must not appear as titles, and no language translates them (no "用户", "杂项", "类型", "首页"). The `index.md` overview body may describe the resource in the target language
- **Interfaces that belong to no resource root go under `misc/`**: endpoints mounted at the server root (e.g., `/health`, `/metrics`, wildcard site content) or NATS subjects that cannot be assigned to a specific resource go under the `misc/` directory, whose `index.md` title is the real path `# /`
- **Interface pages and path-titled groups are sorted by route path at build time**: within each directory, pages carrying an interface marker are ordered automatically by their real route path (HTTP: the `@base`-joined full path; NATS: the subject), and group directories whose `index.md` title is a route path (starting with `/`) are ordered by that path — static path segments come before `:param` segments, and identical paths are ordered by method GET → POST → PUT → PATCH → DELETE. `metadata.docdoc.json` does not order these entries; it only orders non-path entries (shared files, `types/` directories, group directories without path titles)
- **Every resource directory must have an `index.md`**: content is a resource overview + ``; do not hand-write an API list
- **Shared files live directly under the language root, and only four exist**:
  - `code.md`: shared error code table, centrally listing all error codes common to every API (e.g., generic validation errors, generic auth errors); individual API documents do not repeat these shared codes
  - `request.md`: shared HTTP request conventions, describing Base URL, common headers, authentication scheme, request format notes, and other request conventions common to all HTTP APIs
  - `response.md`: unified HTTP response format description, centrally explaining each field of the response wrapper `{id, code, messages, result}`; each HTTP API document's `### Body` (response group) describes only the `result` part and does not repeat the wrapper
  - `nats.md`: shared NATS request-reply conventions, centrally describing subject naming, connection / authentication notes, the request-reply message envelope, timeout semantics, and other conventions common to all NATS interfaces; individual NATS interface documents do not repeat them
- **DTO files are placed under a `types/` subdirectory inside the API resource directory**: e.g., `user/types/page-user-dto.md`, one file per DTO. Order within the directory is controlled by `metadata.docdoc.json`
- **If a DTO is shared across multiple resource directories, treat it as a potential API design issue**: prompt the user to review whether the API partitioning is reasonable; do not create a shared DTO directory
- **Error codes are documented only in dedicated sections**: each endpoint page's `### HTTP Code` / `### Response Code` and the shared `code.md` are the only places that explain or annotate error codes; field descriptions (e.g., `Authorization` in a headers fence) and other sections must not repeat error codes or their HTTP status mappings
- **No extra directories or documents beyond the above structure**: do not add introduction, getting-started, guides, or other chapters; the API reference contains only the API tree + the three shared files
- **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

## Title and Tag Rules

- **Every API document starts with an interface marker as its first non-empty line**: HTTP documents use `<!--HTTP ACTION Path-->`, NATS request-reply documents use `<!--NATS Subject-->` (action / subject may be omitted for inference from the title), and Type Object documents use `<!--TYPE TypeName-->` (the name selects the Type Object renderer and names the `jsonschema:type` fence's TS view). An optional `@base=` declares the Try it panel's Base URL: an absolute URL is used as-is, a `/`-prefixed path is joined onto the site origin. The marker path's relative basis: leading `/` means server-root-relative; no leading `/` means site-root-relative. The marker is stripped at build time and drives the interface renderer (parameter fence tables + Try it panel). Examples: `<!--HTTP POST /api/v1/sites-->`, `<!--HTTP GET /health-->`, `<!--HTTP GET api/v1/document-->`, `<!--NATS user.by-id-->`, `<!--TYPE SiteDTO-->`
- **The Action / protocol must be an all-uppercase Tag placed before the title**: HTTP actions use `#GET#`, `#POST#`, `#PUT#`, `#DELETE#`, `#PATCH#`; NATS request-reply interfaces use `#NATS#`. The method tag is colored by method (GET green, POST blue, PUT amber, PATCH purple, DELETE red, NATS teal); no source change required
- **API document title format**: the title line `# #ACTION# Uri` contains only the method tag and the path, e.g., `# #GET# /users`, `# #POST# /user`, `# #GET# /user/by-id/:id`; NATS interfaces use `# #NATS# Subject`, e.g., `# #NATS# user.by-id`
- **Single-line description**: a `#### Single-line description` level-4 heading directly under the title line, e.g., `#### List users paginated`; the build merges it into the page title (second line of the two-line title) and the sidebar entry's second line
- **DTO document title format**: `# #Interface# DTOName` (or `#class#`, depending on the actual type), e.g., `# #Interface# PageUserDTO`
- **The Uri in the title is the actual full path of the API**: including path parameter placeholders such as `/user/by-id/:id`; do not omit path parameters
- **Use the actual route path for the Uri**: it must match the route registered in code; do not use a document-style pseudo path. The same applies to NATS subjects: the Subject must match the subject registered in code

## Heading Structure of a Single HTTP API Document

A single HTTP API document is fixed to the following structure. Sections with no corresponding content are omitted entirely; do not keep empty headings or write "None". The one exception is `### HTTP Code`: every API document must contain it, presenting at minimum the success status.

1. **Interface marker** — first non-empty line, format per "Title and Tag Rules" above, e.g., `<!--HTTP POST /api/v1/sites-->`
2. **`# #ACTION# Uri`** — title line, format per "Title and Tag Rules" above
3. **`#### Single-line description`** — level-4 heading directly under the title line, merged at build time into the second line of the two-line title
4. **Intro paragraph** — one or more short paragraphs directly under the single-line description, no heading; carries the description that would otherwise sit in an overview section
5. **`## Request`** — request group, containing only the sub-sections below; omitted entirely when the request has no headers, parameters, or body

   1. **`### Headers`** — request headers this API requires, **including authentication and content type**: the `Authorization` field (Bearer Token, etc.) is declared here so the Try it panel renders it as an input; for methods with a request body, the `Content-Type` field is declared here as well (with `default`, e.g., `application/json`, `multipart/form-data`) — never as a "Request format" note on `### Body`. Use a ` ```jsonschema:headers ` fence; the fence renders in place as the header table (columns: Name / Data Type / Required / Description) and feeds the panel

      ```jsonschema:headers
      {
        "type": "object",
        "properties": {
          "Authorization": {
            "type": "string",
            "description": "Bearer Token auth, format `Bearer <token>`"
          },
          "Content-Type": {
            "type": "string",
            "description": "Request body content type",
            "default": "application/json"
          }
        },
        "required": ["Authorization", "Content-Type"]
      }
      ```

   2. **`### URL Parameters`** — URL path parameters (e.g., `:id`), as a hand-written table with columns: Name | Data Type | Description. Path placeholders in the marker path (`:name` style) are parsed automatically; the Try it panel generates a required input field for each and fills the placeholder on send

      | Name | Data Type | Description           |
      | ---- | --------- | --------------------- |
      | id   | string    | Unique user identifier|

   3. **`### Query Parameters`** — URL query string parameters, as a ` ```jsonschema:query ` fence; the fence renders in place as the parameter table and feeds the panel (serialized into the query string for any method)

   4. **`### Body`** — request body, as a ` ```jsonschema:parameters ` fence; the fence renders in place as the parameter table and feeds the panel (serialized as the JSON request body, or as a multipart form when a property declares `"format": "binary"`). The content type is declared as the `Content-Type` field of the `### Headers` fence; do not write a "Request format" note line in this section

      ```jsonschema:parameters
      {
        "type": "object",
        "properties": {
          "name": { "type": "string", "description": "User name" }
        },
        "required": ["name"]
      }
      ```

6. **`## Response`** — response group, containing only the sub-sections below

   1. **`### Headers`** — response headers the endpoint sets (e.g., `Content-Type` / `Cache-Control` on static hosting), as a hand-written table with columns: Name | Data Type | Description. Omitted when the endpoint sets no noteworthy response headers

      | Name         | Data Type | Description                                  |
      | ------------ | --------- | -------------------------------------------- |
      | Content-Type | string    | Mapped from the served file's extension name |

   2. **`### Body`** — response body. In principle the API response format is unified as `{id: string, code: number, messages: string[], result: xxx}`; the wrapper is centralized in `response.md`, and this section describes only `result`. Fields are presented only via the in-place Table / TypeScript dual view — prose descriptions are not allowed:
      - **If `result` corresponds to a known DTO**: write a standalone paragraph holding only `{#ref: DTOName}`; it renders inline as the Table ⇄ TypeScript dual-view block of that type, with the block head linking to the type page; do not expand fields here. A `null` result states `result type: null`
      - **If there is no standalone DTO and the response is an inline expanded object** (including raw endpoints without the wrapper): declare it as a ` ```jsonschema:response ` fence; the fence renders in place as a field table with a switchable TypeScript type view and does not feed the Try it panel. Do not hand-write field tables in this section
      - **Raw non-JSON bodies** (file streams, plain text): present the body as a single field of the ` ```jsonschema:response ` fence (e.g., `"format": "binary"` for a file stream). Header semantics such as `Content-Type` must not appear in this section; they belong to `### Headers` of the response group

   3. **`### HTTP Code`** — mandatory in every API document, presenting the HTTP status codes in table format: `HTTP Status | Meaning | Notes`. Must present the success row (`200`), followed by only the statuses of errors **unique** to this API. HTTP statuses of codes centralized in `code.md` (generic validation, generic auth, etc.) must not be repeated

      | HTTP Status | Meaning | Notes |
      | ----------- | ------- | ----- |
      | 200         | Success | Returns the created user |
      | 404         | User not found | The user with the given id was not found |
      | 409         | User disabled | The user account has been disabled by an administrator |

   4. **`### Response Code`** — required for APIs using the unified wrapper; omitted by raw endpoints (no envelope `code` exists). The unified response structure is centralized in `response.md` and must not be repeated here; this section holds a one-line intro linking to `response.md` (e.g., `响应为统一响应包装（见 [响应格式](../response.md)），其中 \`code\` 字段：`), followed by the envelope `code` table (columns `code | Meaning | Notes`): must present the success row (`0`), followed by only the codes **unique** to this API. Codes already centralized in `code.md` (generic validation `1001`, generic auth `1002`, etc.) must not be repeated. Do not link to `code.md` from this section

      | code | Meaning        | Notes                                     |
      | ---- | -------------- | ----------------------------------------- |
      | 0    | Success        | Returns the created user                  |
      | 4001 | User not found | The user with the given id was not found  |
      | 4002 | User disabled  | The user account has been disabled by an administrator |

7. **`## Examples`** — request / response example pairs; placement, pairing and value rules per "Examples and Remarks Sections"
8. **`## Remarks`** — side effects, idempotency, and other behavior notes; rules per "Examples and Remarks Sections"

## Heading Structure of a NATS Interface Document

A NATS request-reply interface document follows the same section discipline: it **must contain, and may only contain**, the sections below. Sections with no corresponding content are omitted entirely; do not keep empty headings or write "None".

1. **Interface marker** — first non-empty line, format per "Title and Tag Rules" above, e.g., `<!--NATS user.by-id-->`
2. **`# #NATS# Subject`** — title line, format per "Title and Tag Rules"
3. **`#### Single-line description`** — level-4 heading directly under the title line, merged at build time into the second line of the two-line title
4. **Intro paragraph** — one or more short paragraphs directly under the single-line description, no heading
5. **`## Request Payload`** — request message. The first line states the message format (e.g., JSON), followed by a ` ```jsonschema:parameters ` fence; the fence renders in place as the parameter table and feeds the Try it payload builder

   Request format: JSON

   ```jsonschema:parameters
   {
     "type": "object",
     "properties": {
       "id": { "type": "string", "description": "User identifier" }
     },
     "required": ["id"]
   }
   ```

6. **`## Response Payload`** — reply message, following the shared NATS message envelope centralized in `nats.md`; this section describes only the payload. If the payload corresponds to a known DTO, state only the type name and link to that DTO file, e.g., `payload type: [UserDTO](./types/user-dto.md)`; if there is no standalone DTO and the payload is an inline expanded object, expand it as a hand-written table with the same columns as query parameters
7. **`## Response Code`** — mandatory in every interface document, presenting at minimum the success code of the reply envelope; list only the error codes **unique** to this interface, codes centralized in `code.md` are not repeated. NATS request-reply carries no HTTP status codes, so there is no `## HTTP Code` section and the table uses columns `code | Meaning | Notes`
8. **`## Examples`** — request payload / reply payload example pairs; rules per "Examples and Remarks Sections"
9. **`## Remarks`** — behavior notes; rules per "Examples and Remarks Sections"

## DTO Document Structure

A DTO / Interface document (Type Object) has the following structure; keep it minimal and do not add extra sub-headings:

1. **Interface marker** — first non-empty line `<!--TYPE DTOName-->`, e.g., `<!--TYPE SiteDTO-->`; the name must match the title's DTOName. This marker selects the Type Object renderer
2. **`# #Interface# DTOName`** (or `#class#`, depending on the actual type) — title
3. A short description (one or two sentences explaining the DTO's purpose)
4. A ` ```jsonschema:type ` fence declaring all fields; it renders in place as a field table with a switchable TypeScript type view — the TS type name is the `<!--TYPE -->` marker's name. Do not hand-write field tables in this section. A representative instance is declared via the fence's `x-example` key (see "Schema Fence Views"), so every type reference block across the site gains the Example view

   ```jsonschema:type
   {
     "type": "object",
     "properties": {
       "id": { "type": "string", "description": "Unique user identifier" },
       "name": { "type": "string", "description": "User name" }
     },
     "required": ["id", "name"]
   }
   ```

5. **`{references}`** — last, a standalone paragraph holding only this directive; the build replaces it with the list of API pages that reference this type via `{#ref: DTOName}` (method badge + path links, with the single-line description on the second line). It renders nothing when the type has no referrers, so the directive is included unconditionally

## Schema Fence Views

Every ` ```jsonschema:* ` fence (`parameters` / `headers` / `query` / `response` / `type`) renders in place as a switchable multi-view block; `{#ref: Name}` inline type blocks share the same views:

- **View set**: Table (default) ⇄ TypeScript ⇄ Example. The Example view exists only when the fence declares example data; without a declaration the block stays Table ⇄ TypeScript dual-view
- **Example data is declared as a top-level `"x-example"` key in the fence JSON**: the value is one complete sample payload object conforming to the schema, with realistic business values (a real-looking site name, a reachable-looking URL), never placeholder junk such as `"xxx"` or `"foo"`. File fields (`"format": "binary"`) cannot be JSON-serialized and are omitted from `x-example`. Every parameter-carrying fence (`parameters` / `headers` / `query`) declares `x-example` without exception; `response` / `type` fences declare it whenever the payload is a JSON object with at least one serializable field (skipped only for all-binary or empty-object payloads)
- **`x-example` never leaks outside the Example view**: it is stripped from the Table / TypeScript views and never enters the Try it panel data
- **Do not add an Example column to parameter tables**: example data always goes through the Example view, not table columns
- **Requiredness is presented positively**: fence tables use the column `Name | Data Type | Required | Description`, where `Required` is `Yes` / `No` (the legacy `Optional` column with inverted `No` / `Yes` is forbidden)

## Examples and Remarks Sections

- **`## Examples`** — placed after the entire response group (HTTP: after `### Response Code`; NATS: after `## Response Code`), followed by `## Remarks`. It holds request / response example **pairs** as code blocks: HTTP pages show one raw request line + head + body in a ```http block, answered by the full response envelope in a ```json block (wrapped APIs always include `{id, code, messages, result}` in full, consistent with `response.md`); NATS pages show one request payload ```json block answered by one reply payload ```json block. Example values must mirror the corresponding fence's `x-example` data. Omit the section for endpoints with no meaningful value (e.g. an empty object response)
- **Omit `## Examples` for raw self-describing bodies**: when a `jsonschema:response` fence already declares `x-example`, the Example view plays the example role and no redundant `## Examples` section is written
- **`## Remarks`** — last section of the page; carries only behavior that field tables cannot express: side effects, idempotency, synchronous / asynchronous semantics, recovery notes. Never duplicates content already present in the intro paragraph or in field descriptions; omitted entirely when nothing noteworthy exists

## Type Object References

- **`{#ref: DTOName}`**: in an API document, a standalone paragraph holding only this directive renders that type inline as a Table ⇄ TypeScript dual-view block; the block head shows the type name and links to the type page. Unknown names render an inline error note. Use it in `### Body` of the response group for a known DTO, replacing hand-written `result type:` lines. It does not feed the Try it panel — request bodies that must feed the panel keep their ` ```jsonschema:parameters ` fence
- **`{references}`**: a Type Object document directive (see "DTO Document Structure"); it aggregates referrers at build time, similar to a TOC macro

## 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": ["code.md", "request.md", "response.md", "nats.md", "user", "misc"]}
      code.md                 # Shared error code table
      request.md              # Shared HTTP request conventions
      response.md             # Unified HTTP response format description
      nats.md                 # Shared NATS request-reply conventions
      user/
          index.md            # H1: /user
          metadata.docdoc.json  # {"order": ["types", "page.md", "get-by-id.md", "by-id.md"]}  (types/ subdir first)
          types/
              index.md        # H1: types
              page-user-dto.md    # #Interface# PageUserDTO
              user-dto.md         # #Interface# UserDTO
          page.md             # #GET# /users - List users paginated
          get-by-id.md        # #GET# /user/by-id/:id - Get user by ID
          by-id.md            # #NATS# user.by-id - Get user by ID
      misc/
          index.md            # H1: / (real path, not descriptive text)
          metadata.docdoc.json  # {"order": ["health.md", "metrics.md"]}
          health.md           # #GET# /health
          metrics.md          # #GET# /metrics
  en/
    ...                         # Directory and file names identical to cn/
```

## Glossary

@glossary.md

| English | 中文 |
| ------- | ---- |
| Site | 站点 |
| Artifact | 产物 |
| DataDir | 数据目录 |
| Registry | 站点注册表 |
| Site Root | 站点根 |
| Bearer Token | Bearer 令牌 |
| Reserved Name | 保留名 |
| Path Prefix Routing | 路径前缀路由 |
| ACME | 自动化证书管理环境 |
| HTTP-01 Challenge | HTTP-01 质询 |
| TOC | 目录树 |
| Search Index | 全文搜索索引 |
| Cache-Control | 缓存控制头 |
| Multipart | 多部分表单上传 |