audit-docs git:20261027.1622ddbA

Immutable. This exact content never changes and is served at /api/v1/blob/b6ca52cc867bae5b.

---
name: audit-docs
description: "Audit and write all of Nino's docs - the nino.docs site (English and Chinese pages, changelog, benchmark data), README.md and README.zh.md, docs/ in this repository, CONTRIBUTING.md, the runtimes' READMEs and the public skill skills/nino-serialization - so that every feature is documented in order with its recommended form, its fast form, its costs and pitfalls, every statement matches the code, nothing is said twice, and English and Chinese agree. Use once the code is final (the docs pass), after a user-facing change lands, and before a release. Triggers: docs, README, *.mdx, nino.docs, changelog, page, example, en/zh, llms.txt, the public skill, \"docs out of date\", 文档, 网站, 中文文档, 更新日志, 例子, 文档同步, 写得不对."
metadata:
  internal: true
---

# Docs audit

The site is the separate repository JasonXuDeveloper/Nino.Docs (local clone `/workspace/nino.docs`; read its
AGENTS.md and `WRITING.md` first: page anatomy, tone, numbers, components). This repository holds README.md and
README.zh.md (the landing page on GitHub and NuGet), `docs/` (design, spec, codegen, diagnostics, pitfalls),
CONTRIBUTING.md, `runtimes/*/README.md` and the public skill.

## 1. Inventory: every feature, in order

Build the list from the source, not from the pages:

- every public attribute (`src/Nino.Core/Attributes`), its options and where it may go;
- every public entry point (`NinoSerializer`, `NinoDeserializer`, their overloads: arrays, spans, `IBufferWriter`,
  streams, exact-size and into-existing forms), `NinoSettings` member, pool and registry API;
- every MSBuild property and generator option users set, every NINO diagnostic and code fix;
- every built-in type and collection (BCL, immutable, concurrent, Unity types), each package (`Nino.AspNetCore`,
  `Nino.Immutable`, `Nino.UnityTypes`, Unity, `Nino.Codegen.Tool`) and each runtime's public API;
- every nino-gen option (`src/Nino.Codegen/Options.cs`) and what each language supports.

Then the reading order: the sidebar (`content/docs/v4/meta.json`) goes from what everyone needs (install, first
type, serialize) to what some need (versioning, polymorphism, references, pooling, custom formatters, security) to
integrations and reference. Every inventory item has one owning page and a place in that order; an item without one
is a finding, and so is a page that teaches a feature before the one it builds on.

## 2. Per page (English and Chinese)

1. **Anatomy** (`WRITING.md`, in this order): what it is; when to use it and when not (with what to use instead); how
   to use it, **the recommended form first** (an attribute, a generated path, the simplest overload) with a complete
   example that compiles; a full example where a short program can show the feature alone; **how to use it fast** (the
   overloads and settings that change the cost: exact-size buffers, `IBufferWriter`, reusing instances, pooling,
   `[NinoUtf8]`, raw structs, block copies, untrusted mode's cost), each with its benchmark through a component;
   what it costs (bytes on the wire, time, allocations, what is free when unused); pitfalls (Mistake | What happens |
   Caught by: the NINO rule, the exception); related pages.
2. **True to the code**: every API, attribute, option, default, limit and exception named exists today and behaves as
   written; check a doubtful claim with a throwaway test. Names match the code exactly. No API that is not in the
   source (the site's rule).
3. **Examples compile and are exemplary**: every C# fence compiles against the current source (until a fence checker
   exists, paste the fences of the pages you touch into a scratch project that references `src/`), no NINO warning,
   models a real domain (game state, messages, saves), and uses the recommended form; byte examples match what
   Nino writes now (`wire-format`).
4. **Numbers**: never typed. Runtime numbers only through `BenchValue`, `RuntimeTable`, `ResultsTable`,
   `BenchmarkChart`, `RuntimesTables`, `UnityTables` from the synced data; within 5 % is on par and is written so; the
   docs never call Nino "slower"; v3 means 3.3.13.
5. **Chinese**: the same content and structure as English, written natively (`WRITING.md`, Tone: Chinese), headings
   with the English id (`## 键控成员 [#keyed-members]`), links with the same anchors.

## 3. Across pages and repositories

- **One owner per explanation**: other pages say it in a sentence and link. README, the site, `docs/` and the public
  skill do not repeat each other's long sections; README summarizes and links the site.
- **Copies that must exist agree**: README / README.zh.md, the site's index and comparison pages, the analyzers page
  and `docs/diagnostics.md`, `docs/spec/wire-format.md` and the site's wire-format page, the public skill, the
  runtimes' READMEs and the codegen page.
- **Every feature is everywhere it belongs** (`feature`, part 8): its guide page (both languages), the analyzers page
  for its rules, the platforms page if it is platform-specific, the public skill, README's feature list when users
  choose Nino for it, the changelog.
- **Changelog** (`changelog.mdx` / `.zh.mdx`): one section per v4 release (prereleases included), newest first; user-
  facing items only, "Wire Format" first, then "New", "Performance", fixes; each entry checked against the source,
  linking its issue and its page. Bring it in line with Nino at the start of any docs work (nino.docs AGENTS.md has
  the steps: releases, `git log <tag>..origin/main` with the trailers). A user-facing commit without a trailer
  needs a follow-up commit that carries one.
- **The public skill** (`skills/nino-serialization/SKILL.md`) holds what users' agents need to write correct, fast Nino code: the
  recommended forms, the fast forms, the pitfalls and the diagnostics, matching the pages.
- Stale names: grep the old names of every rename across both repositories; history pages (changelog, migration,
  v3-vs-v4) keep them on purpose.

- The code standard (`audit-code`: DRY, decoupled, clear) applies to these files, and redundancy in them
  (duplicated logic, dead code, two ways to do one job) is part of this audit; the sweep across layers is
  `audit-redundancy`.

## 4. Finish

- nino.docs: `bun run check && bun run build` (links, anchors, icons, types, prerender, llms.txt); commit docs apart
  from code; push to its `main`.
- This repository: links in README and `docs/` resolve; `tools/agents.sh --check` when maps or skills changed.
- Report per page: what was missing, wrong or duplicated, and what you changed; what you left (with the reason).