git:20261027.bf64f38 to git:20261027.1622ddb

2 added, 2 removed. Audit A to A.

---

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 - 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\", 文档, 网站, 中文文档, 更新日志, 例子, 文档同步, 写得不对."

+ 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/SKILL.md`) holds what users' agents need to write correct, fast Nino code: the

+ - **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).