docs-gen

docs-gen Library Doc Build and Push

This skill serves only library repositories and does three things: build library docs to standard; after library code changes, determine and sync affected docs; push the whole library's docs to the central service to build a full-text index. To search internal library docs, use the docs-search skill; it is not covered in this skill.

库维护者 ──push-docs.mjs（HTTP PUT）──▶ docs-server（SQLite FTS5）◀──docs-search── 使用者的 AI

Core Principles

The readers of the docs are AI, not humans. After a user's AI finds the docs, it treats them as a spec and follows them directly; where things are written unclearly, it will fill in gaps using training knowledge of open-source libraries and produce incorrect code. Docs have only two quality metrics:

Precise instructions: the type, default value, required status, and value range of every parameter, the return and errors of every method, and the differences from the open-source library — all are definite facts, with no "usually", "recommended", or "possibly".
Sufficient examples: every core scenario has a self-contained, directly runnable example; guides and scenario solutions give end-to-end ## 完整示例。

The doc-writing approach must match the server's current implementation: the server recalls with high weight by title / keywords / aliases / doc path, and returns only by ## slices; when AI retrieves one chapter, it cannot see other chapters. For the mechanism and countermeasures, see references/server-behavior.md。

Reference files (read on demand, do not read all at once)

File	When to read
references/server-behavior.md	Before writing frontmatter / keywords, splitting chapters, and deciding doc granularity: how the server tokenizes, weights, degrades, slices, and validates, and the doc-writing approach corresponding to each mechanism
references/doc-standards.md	When writing or modifying any doc: hard frontmatter rules, doc types and chapter vocabulary, writing rules, example rules, self-check checklist
`references/templates/<类型>.md`	When creating a new doc, read only one file for the corresponding type:`overview`（index.md）、`api-reference`、`guide`、`recipe`、`troubleshooting`、`migration`
references/golden-sample.md	Read once before writing docs for the first time: a fully written API reference example, used to compare against your own output
references/change-sync.md	After library code changes: determine the scope of changes, decide by the decision table whether docs are affected, locate affected documents and chapters, and output a sync report

Library Maintainer Workflow

1. Detect configuration and environment variables (always the first step)

Do this step first upon entering this skill; afterward, whether building, syncing changes, or pushing, do not judge again. Detection method:

Read the repository root .pe.jsonc, and confirm non-sensitive configuration is complete:
- docs_server_url: doc service address, e.g. "http://docs.internal:8080"(a trailing slash is automatically removed by the script)
- docs_push_lib_name: library slug: only lowercase letters, numbers, and hyphens (^[a-z0-9-]+$), using the slug form of the package name
Read the repository root .env and the current shell environment, and confirm sensitive configuration is complete:
- DOCS_TOKEN: push token, consistent with the server's DOCS_PUSH_TOKEN , ask the service administrator for it

Complete: go directly to step 2.
Missing: guide the user to fill it in:
1. Use the question tool to ask the user item by item for the missing values; do not fabricate the token, service address, or library slug.
2. Write non-sensitive configuration to the repository root .pe.jsonc(If it already exists, supplement or update the corresponding fields; this file must be committed to git). Example:
```
{
  "docs_server_url": "http://docs.internal:8080",
  "docs_push_lib_name": "your-lib"
}
```
3. Write sensitive configuration to the repository root .env(if it already exists, only add missing lines, do not overwrite existing values). Format:DOCS_TOKEN=value，= Do not leave spaces on either side.
4. Confirm that .gitignore already contains .env; if not, append it. The token is sensitive information and must never be committed to the repository.

Copying the script is strictly prohibited: this skill has a built-in push script, and command execution must always point to the absolute path of this skill's built-in script. It is strictly prohibited to create scripts/push-docs.mjs or any other script copies in the target repository root directory or subdirectories!

2. Build documentation

Place documentation in agent-docs/(the script parameter can specify another directory). Execute in order:

Collect facts: APIs, signatures, default values, constraints, and error messages must be taken only from public exports, type declarations, source code, tests, examples, README, and CHANGELOG; it is forbidden to fill them in using training data or the usage of similar open-source libraries. Confirm facts that cannot be obtained with the user; do not write "possibly".
Plan the documentation set: according to doc-standards.md "File Organization" and "Document Types and Section Vocabulary", list a plan table (path / type / exports covered), including index.md. When creating documentation for the first time, give the plan table to the user for confirmation before writing; when updating existing documentation, only modify the affected sections.
Write each document: determine the type according to doc-standards.md "Document Types and Section Vocabulary", and read only references/templates/ the corresponding skeleton under it; frontmatter, section names, writing rules, and example rules follow doc-standards.md.
Self-check each document: go through the doc-standards.md "Self-check List". Fix anything that does not pass on the spot; do not leave it until after pushing.

If an existing document does not meet the standards (missing frontmatter fields, section names not in the vocabulary, examples are fragments), rewrite that document according to the standards; do not make partial patches.

3. Execute push

Execution timing:

The user explicitly requests to push/sync documentation: execute directly
After substantive changes to the documentation (adding/modifying/deleting .md): proactively ask the user whether to sync and push
After fixing a push failure: re-push as soon as the fix is complete
For important releases or the first documentation build: use --verify to push, and report the "retrievable verification" results as well

Command (commands are always executed in the user repository root directory, that is, where .pe.jsonc and .env are located; write the script path as an absolute path pointing to this skill's built-in script; use Node's built-in --env-file parameter to load .env, universally across platforms; prohibit set -a && source and other POSIX-specific prefixes):

node --env-file=.env <本技能绝对路径>/scripts/push-docs.mjs            # 推送（目录默认 agent-docs/）
node --env-file=.env <本技能绝对路径>/scripts/push-docs.mjs --verify   # 推送后逐篇按 title 搜索验证可检索
node --env-file=.env <本技能绝对路径>/scripts/push-docs.mjs --clear    # 下架整库（服务端删除该库全部文档与索引）

Node ≥ 24 already has built-in --env-file；.env and .pe.jsonc must already exist (guaranteed by step 1).

Behavior notes:

Full-library overwrite: each push fully replaces all documents in that library on the server; old server-side documents will be deleted
Atomicity: if any document fails validation, the entire batch is not written to the library; when local validation fails (frontmatter issues), no request is sent, and all issues in all files are listed at once
--verify After pushing, search each document by title; if any document cannot be found, exit non-zero — this allows immediate detection of successful pushes with abnormal indexing, and important releases should use push with verification
--clear For permanent removal of a library: the server deletes the library,libraries it no longer appears in the list; if you only want to clear and re-push,do notuse it, just push normally (a full-library overwrite will also delete documents that have been removed locally)
Successfully output 推送成功：库 <slug> 共 <N> 篇文档, report the number of articles to the user

On failure, handle according to the error; do not blindly retry:

Error (script stderr)	Cause	Handling
`找不到配置文件：.pe.jsonc` / `配置文件 … 缺少必填字段：…`	`.pe.jsonc` missing or missing items	Go back to step 1 to fill in `.pe.jsonc`
`缺少必填环境变量：DOCS_TOKEN`	`.env` not loaded or missing `DOCS_TOKEN`	Go back to step 1 to fill in `.env`, confirm the command includes `--env-file=.env`
`无法读取文档目录：…` / `文档目录 … 下没有任何 .md 文件`	Directory parameter is wrong or the directory is empty	Check the directory parameter; confirm that you want to remove the entire library before using `--clear`
`本地校验失败（未发出请求），共 N 处`	One or more frontmatter entries do not conform to the server's strict validation (BOM, trailing spaces on separator lines, duplicate keys, unquoted `:` or `#`in values, unclosed quotes, title missing/empty/non-string)	Fix the corresponding file for each item listed, and push again after all are fixed
`请求推送接口失败：fetch failed（…）`	Service address unreachable (the specific reason is in parentheses)	Check `.pe.jsonc` in `docs_server_url` and the network, and confirm with the administrator
`请求超时`	No response from the server	Stop retrying, report to the administrator
`HTTP 401` `unauthorized`	token and server `DOCS_PUSH_TOKEN` do not match	Verify the token with the administrator; do not guess
`HTTP 400` `invalid_slug`	`docs_push_lib_name` does not match `^[a-z0-9-]+$`	Change `.pe.jsonc` the slug in
`HTTP 400` `invalid_frontmatter`	Server-side strict YAML error that local validation missed; the message contains the path of the document with the error	Fix only the article indicated by the message, referring to "Push Validation" in server-behavior.md
`验证失败，以下 N 篇推送后搜不到`	`--verify` server-side tokenization or indexing exception in mode	Relay the original error text to the administrator; do not re-push
`HTTP 404`（`--clear` when) `library_not_found`	The library does not exist in the first place	No action needed, just confirm with the user
`HTTP 500` `internal`	Server-side library write failed	Relay the original error text to the administrator

monorepo multiple packages: when there are multiple packages in one repository, you can configure different configuration files (such as --config=.pe.ui.jsonc) and different document directories, and execute node --env-file=.env <本技能绝对路径>/scripts/push-docs.mjs --config=.pe.ui.jsonc <该包文档目录>per package; the document directories of each package do not nest within each other, and pushes do not affect each other.

Optional: integrate CI (GitHub Actions) to automatically sync documents with the main branch:

- run: node <本技能绝对路径>/scripts/push-docs.mjs
  env:
    DOCS_TOKEN: ${{ secrets.DOCS_TOKEN }}

Change synchronization (after library code changes)

If the library code changes, the documentation must keep up. Trigger conditions (execute if any one is met, without waiting for the user to ask):

Library code was just changed in this session (including changes requested by the user); execute before wrapping up
The user says the library was changed / released / refactored, or requests "sync the docs" or "are the docs out of date"
The user provides a commit range, tag, or PR

Steps (for the decision table, commands, and report format, see references/change-sync.md）：

Determine scope: user-specified scope > changes in this session > uncommitted changes in the working tree > agent-docs/ source code changes since the last commit
Assess impact: read each diff body against the decision table; only changes reachable from public exports affect the documentation. Internal implementations, tests, CI, and dependency upgrades never affect it
Locate：agent-docs/index.md ## 模块速查 Check the article corresponding to the export name;rg use the identifier or the original error message to find all articles that reference it
Update: only modify the affected sections; after modification, run the articles through the doc-standards.md self-check checklist; when adding or removing articles, sync the index.md quick-reference table
Report: output a change-sync report; even if no item is affected, still report and state the reason; for anything that cannot be determined, mark it as "pending confirmation" and ask the user. If there are substantive changes, proceed to "3. Push execution"

agent-docs/ If it does not exist, skip this section and go to "2. Build documentation".

Checklist

Step 1 configuration and environment variable detection has been executed:.pe.jsonc（docs_server_url、docs_push_lib_name) and .env（DOCS_TOKEN) are complete,.env has been added to .gitignore
Always directly call the skill's built-in script; no push-docs.mjs copy was created in the target repository
All facts come from source code / type declarations / tests / CHANGELOG, with no guesses
Every article has passed the doc-standards.md self-check checklist: the four frontmatter fields, section vocabulary, the five elements of parameters, self-contained examples, and difference annotations
Guides and scenario solutions have ## 完整示例; API reference ## 典型示例 2~3
After library code changes: the impact scope has been determined per change-sync.md and a sync report has been output; affected articles have been updated
After a successful push, report the number of articles pushed to the user;--verify mode, also report the searchable verification results

Anti-patterns

Creating copies of scripts such as scripts/push-docs.mjs in the target repository root directory (the skill's built-in scripts must always be executed directly)
Writing sensitive configuration DOCS_TOKEN into .pe.jsonc, code, examples, or committing it to the repository (sensitive information may only be placed in .env）
Writing non-sensitive configuration docs_server_url or docs_push_lib_name into .env(non-sensitive configuration must be placed in .pe.jsonc and committed to the repository)
Using training data or the usage of similar open-source libraries to fill in this library's API
Writing examples as fragments:// ...、// 同上, omitting imports, using undefined variables
Cross-references between sections ("see Quick Start") — not visible when AI reads only one section
Inventing section names (## Props、## 用法) instead of using the vocabulary
Vague words: usually, recommended, possibly, etc.
Fabricating or guessing DOCS_TOKEN, service addresses, library slugs
Retrying blindly after a failed push without reading the error
Committing .env
without user confirmation
Documents stuffed with internal implementation details and sensitive information
Cramming the entire library API into one large document, or creating a separate file for a tiny function agent-docs/is not checked; judging "no impact" just by looking at file names without reading the diff; skipping changes that cannot be determined without asking
Expanding retrieval installation or query steps within this skill (retrieval is left to docs-search）