Skip to content

Documentation Maintenance ​

Project N.E.K.O. documentation is part of the product contract. Keep it close to the code it explains, state what kind of document it is, and avoid copying volatile facts into multiple pages.

Documentation layers ​

LayerPurposeLocation
User and developer guidesSupported setup and common workflowsguide/, config/, deployment/, frontend/, plugins/
Architecture and API referenceCurrent code-backed contractsarchitecture/, modules/, api/
Contributor rulesRepository-wide development and validation rulescontributing/
Project recordsDesign decisions, benchmark snapshots, and SDK change notesdesign/, benchmarks/, changelog/
Component-owned docsDetailed documentation maintained with one componentFor example plugin/plugins/mcp_adapter/docs/

The Project Records section is evidence and context, not a substitute for current code, tests, or accepted issues.

Canonical-source rule ​

Choose one canonical page for each fact:

  • behavior and public contracts belong in the owning guide, architecture page, or API page;
  • repository process belongs in contributing/;
  • implementation rationale and dated measurements belong in project records;
  • component-specific workflows belong beside that component;
  • active future work belongs in accepted issues or the maintained project board.

Link to the canonical page instead of copying command lists, provider tables, version claims, or roadmap promises. A translated page mirrors the canonical meaning; it does not become an independent specification.

Status language ​

Every plan or record must make its authority clear near the beginning:

  • Current contract — behavior that current code and tests enforce.
  • Implemented design record — rationale for shipped behavior; later code may supersede details.
  • Proposal — not approved or implemented merely because the file exists.
  • Historical snapshot — dated evidence that must not be read as current behavior.
  • Deprecated — retained only for migration or archaeology.

Avoid vague labels such as “phase 2 soon” or “future version” without an owner and authoritative tracking link.

Languages ​

The documentation site has English, Simplified Chinese, and Japanese navigation. Not every project record is translated. The locale switcher falls back to the locale home when a matching page does not exist.

When changing a mirrored guide:

  1. update all existing mirrors in the same change;
  2. preserve code identifiers, paths, placeholders, and warning meaning;
  3. do not invent a translated page solely to hide missing coverage;
  4. note intentional language-only records in the nearest index.

The runtime UI's eight-locale rule is separate and remains mandatory for user-visible locale keys.

The root README.MD is the English repository README. docs/README_zh-CN.md, docs/README_ja.md, and docs/README_ru.md are its translations, and docs/README_en.md only redirects old links to the root README. Update all translations in the same change as the root README. They are intentionally excluded from the VitePress build and should not be used as site navigation pages.

  • Use site-root links such as /plugins/quick-start for VitePress pages.
  • For repository files outside the documentation site, use a full GitHub blob URL; do not use relative-up (../) links.
  • Keep established routes stable. If a move is necessary, add a redirect or compatibility page and update inbound references.
  • Do not link generated files, local worktrees, temporary reports, private logs, or unmerged PR branches as permanent documentation.

Review checklist ​

Before submitting documentation changes:

  1. confirm the described behavior against current code and tests;
  2. remove secrets, raw user content, machine-specific paths, and temporary evidence;
  3. check all existing language mirrors;
  4. run the documentation build from docs/ with npm ci and npm run build;
  5. run relevant code checks when the documentation changes a public contract or example;
  6. ensure the PR is focused and does not stack unrelated documentation work.