docs: Add documentation review guidance

AGENTS.md

@@ -25,7 +25,7 @@ bare-metal lifecycle to fast-track building next-generation AI Cloud offerings.
 
 ## Repository Structure
 
-```
+```text
 infra-controller/
 ├── crates/              # Rust crate implementations. To discover all crates
 │                        # and their purpose, run `ls crates/` or see the
@@ -54,7 +54,8 @@ infra-controller/
 
 ## Technology Stack
 
-### gRPC API and components:
+### gRPC API and components
+
 - **Language:** Rust (edition 2024, toolchain pinned in `rust-toolchain.toml`)
 - **Async runtime:** Tokio
 - **gRPC framework:** Tonic (with TLS via Rustls/aws_lc_rs)
@@ -65,6 +66,7 @@ infra-controller/
 - **API definitions:** Protocol Buffers (protobuf)
 
 ### REST API and components
+
 - **Language (REST API):** Golang 1.26.x
 
 ## Build, Test, and Lint Commands
@@ -205,9 +207,100 @@ counters, unit-suffixed histograms) and the name in the attribute is the
 exposed name, verbatim. Existing metric names never change. The full standard
 lives in [`docs/observability/instrumentation.md`](docs/observability/instrumentation.md).
 
+## Documentation review
+
+These are documentation checks, not style guidance. Apply every relevant
+check before requesting review.
+
+- **Interface contracts:** Document the complete contract, not just the name or happy path.
+
+  - For every documented command, flag, environment variable, config key, API field, mode, or state, verify the following from code, schema, or exercised output:
+    - exact spelling and case
+    - required or optional condition
+    - default
+    - accepted values, units, formats, and bounds
+    - mutual exclusions and interactions
+    - global versus subcommand position and required order
+    - omission or fallback behavior
+    - observable output, side effects, errors, and unsupported paths
+  - Exercise each changed example at the PR revision on an authorized local or
+    test target and compare it with real `--help` output.
+  - If any answer is unknown, stop and ask the owner; another documentation page
+    is not evidence.
+
+- **Generated interfaces:** Change the source, regenerate every output, and prove they stay in sync.
+
+  - Never edit a generated reference.
+  - For `nico-admin-cli`, change the Clap declarations under
+    `crates/admin-cli/src/`, verify the affected command with
+    `cargo run -q -p nico-admin-cli -- <command-path> --help`, then run
+    `cargo make gen-cli-docs` and `cargo make check-cli-docs`. See
+    `crates/admin-cli/AGENTS.md` for the generated and hand-authored boundaries.
+  - For REST, use `rest-api/openapi/spec.yaml` for the contract and inspect the
+    handler or model for conditional behavior the schema cannot express. When
+    the spec changes, run `make rest-api/lint-openapi`,
+    `make rest-api/generate-sdk`, `make rest-api/publish-openapi`, and
+    `make openapi-breaking`; do not edit `rest-api/sdk/standard/` or
+    `rest-api/docs/index.html`.
+
+- **Workflow parity:** Make the documentation match the workflow that actually runs.
+
+  - For setup documentation, `helm-prereqs/setup.sh` is the source of truth for
+    phases, skip flags, environment requirements, and component order. Run
+    `bash -n helm-prereqs/setup.sh` and cross-check `helm-prereqs/README.md` and
+    `docs/getting-started/quick-start.md`.
+  - For state-machine documentation, trace every success, skip, retry, poll,
+    restart, deletion, maintenance, and error transition to its enum and
+    handler. Narrative, Mermaid, and transition tables must contain the same
+    states and edges, including persisted resume state.
+
+- **Metric catalogue:** A metric is not documented until its HELP text, emitted series, and generated catalogue agree.
+
+  - Treat metric HELP text and `docs/observability/core_metrics.md` as generated
+    API documentation.
+  - Verify what causes the observation, its counter/gauge/histogram type, the
+    exact entity and condition measured, direction or protocol, and every label
+    dimension.
+  - New metrics need non-empty `describe` text and must be exercised by
+    `test_integration` so catalogue generation includes their exposed name,
+    type, and description. Do not patch the generated table.
+
+- **Cross-surface drift:** Change a fact everywhere it appears or make one page canonical and link to the canonical page from the others.
+
+  - Search every changed literal or behavior with
+    `rg -n --fixed-strings '<literal>' README.md crates/ rest-api/ docs/ book/ helm/ helm-prereqs/ deploy/`;
+    reconcile every conflicting hit or establish one canonical explanation and
+    link the others to it.
+  - New or moved public pages must be present in `docs/index.yml`, and changed
+    public paths need redirects in `fern/docs.yml`.
+  - `docs/release-notes.md` owns current unified releases;
+    do not modify `rest-api/CHANGELOG.md`, as it is legacy history whose
+    published entry order must be preserved.
+
+- **Temporary claims and versions:** Tie temporary claims and pinned versions to a real support boundary.
+
+  - Search changed prose for `currently`, `today`, `for now`, `temporarily`, and
+    `draft`. Each match must name a release, deliberate support boundary, or
+    full tracking URL; a bare issue number or review-history note is
+    insufficient.
+  - Hard-code a tool or dependency version only when it is a tested minimum,
+    maximum, or pinned compatibility boundary; otherwise link the authoritative
+    release page.
+
+- **Rendered output:** Review each artifact in the renderer its readers actually use.
+
+  - Run `rumdl check --config docs/.rumdl.toml <changed-markdown-files>` and fail
+    on every finding.
+  - For Fern-published pages, run `fern check` and inspect the PR preview; if it
+    is unavailable, use `(cd fern && fern docs dev)`.
+  - Inspect generated `nico-admin-cli` pages in GitHub's renderer and OpenAPI
+    output with `make rest-api/preview-openapi`. Check navigation, anchors, wide
+    tables, Mermaid layout, and component rendering in the actual target; lint
+    success is not rendered verification.
+
 ## Further Reading
 
 - [`README.md`](README.md) — Project overview and getting started
 - [`STYLE_GUIDE.md`](STYLE_GUIDE.md) — Detailed Rust coding conventions
 - [`CONTRIBUTING.md`](CONTRIBUTING.md) — Contribution workflow and DCO process
-- [`book/src/README.md`](book/src/README.md) — Architecture and operational guides
+- [`docs/architecture/overview.md`](docs/architecture/overview.md) — Architecture overview