From cfb07f490bbbb267f28999f134f0917ba4849581 Mon Sep 17 00:00:00 2001 From: Kyle Felter Date: Tue, 14 Jul 2026 13:04:37 -0500 Subject: [PATCH 1/5] docs: Add documentation review guidance --- AGENTS.md | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a15aff20ea..51dd5be74d 100644 --- a/AGENTS.md +++ b/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,55 @@ 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 + +- Write for the intended reader and task. Put the primary workflow before + background material, define unfamiliar terms on first use, and state + prerequisites and constraints before the steps that depend on them. +- Verify documented names, commands, flags, values, defaults, ranges, + interactions, fallbacks, exceptions, errors, unsupported paths, outputs, + side effects, and required order against the current code, schema, generated + reference, or real command output. Check every affected page and source + description for the same facts. +- Use official product and component terminology consistently. Keep + capitalization and punctuation consistent within repeated labels, and + distinguish similar services, states, and protocols explicitly. Describe + present behavior precisely; avoid vague, promotional, and time-relative + wording. Keep draft or experimental labels aligned with the actual state. + Do not leave review-history notes in user documentation, mention future + behavior only with a descriptive link to tracked work, and ask the owner + rather than presenting an unresolved policy question as fact. +- Make command examples realistic, safe, and internally consistent. Use values + that satisfy the documented formats, reuse identifiers throughout a task, + split long commands across lines, keep flag order consistent, tag every code + fence with a language, and show only verified output. +- Use ordered lists only when sequence matters, and use `1.` for every ordered + item so edits do not require renumbering. Use paragraphs or unordered lists + when order does not matter. +- Use descriptive link text and stable repository-relative or canonical + targets. Include enough context for each link to stand alone, verify anchors + after heading changes, and do not use a bare issue number. Link to the + authoritative release page instead of hardcoding a version unless the + procedure depends on that exact version. +- Treat generated reference pages as outputs: update their source descriptions + and regenerate them instead of editing generated files alone. Verify the + generated reference and hand-written documentation agree. +- Treat user-visible log messages, metric HELP text, and code doc comments as + documentation. Name the exact entity, state or condition, scope, direction + or protocol, and label dimension; verify the implementation before rewriting + the description. +- In Fern pages, use headings for hierarchy and components for their documented + semantics, not only for visual styling. Inspect the page in its actual target + renderer for navigation, layout, wrapping, links, and readability. +- Before requesting documentation review, run + `rumdl check --config docs/.rumdl.toml `. For + Fern-published pages, run `fern check` and inspect the PR preview. If the + preview is unavailable, run `fern docs dev` and inspect the pages locally. + Lint success does not replace rendered inspection. + ## 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 From 1fc3ab33701e1d6d58e86ca50d0d2fd1de8a2c3a Mon Sep 17 00:00:00 2001 From: Kyle Felter Date: Tue, 14 Jul 2026 13:32:31 -0500 Subject: [PATCH 2/5] docs: Sharpen documentation review gates --- AGENTS.md | 105 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 62 insertions(+), 43 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 51dd5be74d..6b98e5f588 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -209,49 +209,68 @@ lives in [`docs/observability/instrumentation.md`](docs/observability/instrument ## Documentation review -- Write for the intended reader and task. Put the primary workflow before - background material, define unfamiliar terms on first use, and state - prerequisites and constraints before the steps that depend on them. -- Verify documented names, commands, flags, values, defaults, ranges, - interactions, fallbacks, exceptions, errors, unsupported paths, outputs, - side effects, and required order against the current code, schema, generated - reference, or real command output. Check every affected page and source - description for the same facts. -- Use official product and component terminology consistently. Keep - capitalization and punctuation consistent within repeated labels, and - distinguish similar services, states, and protocols explicitly. Describe - present behavior precisely; avoid vague, promotional, and time-relative - wording. Keep draft or experimental labels aligned with the actual state. - Do not leave review-history notes in user documentation, mention future - behavior only with a descriptive link to tracked work, and ask the owner - rather than presenting an unresolved policy question as fact. -- Make command examples realistic, safe, and internally consistent. Use values - that satisfy the documented formats, reuse identifiers throughout a task, - split long commands across lines, keep flag order consistent, tag every code - fence with a language, and show only verified output. -- Use ordered lists only when sequence matters, and use `1.` for every ordered - item so edits do not require renumbering. Use paragraphs or unordered lists - when order does not matter. -- Use descriptive link text and stable repository-relative or canonical - targets. Include enough context for each link to stand alone, verify anchors - after heading changes, and do not use a bare issue number. Link to the - authoritative release page instead of hardcoding a version unless the - procedure depends on that exact version. -- Treat generated reference pages as outputs: update their source descriptions - and regenerate them instead of editing generated files alone. Verify the - generated reference and hand-written documentation agree. -- Treat user-visible log messages, metric HELP text, and code doc comments as - documentation. Name the exact entity, state or condition, scope, direction - or protocol, and label dimension; verify the implementation before rewriting - the description. -- In Fern pages, use headings for hierarchy and components for their documented - semantics, not only for visual styling. Inspect the page in its actual target - renderer for navigation, layout, wrapping, links, and readability. -- Before requesting documentation review, run - `rumdl check --config docs/.rumdl.toml `. For - Fern-published pages, run `fern check` and inspect the PR preview. If the - preview is unavailable, run `fern docs dev` and inspect the pages locally. - Lint success does not replace rendered inspection. +These are release gates, not style guidance. Apply every gate touched by the +change before requesting review. + +- **Interface contract gate:** For every documented command, flag, environment + variable, config key, API field, mode, or state, verify 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; and 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 interface gate:** Never edit a generated reference alone. + 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 -- --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` alone. +- **Workflow parity gate:** 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 gate:** 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 alone. +- **Cross-surface drift gate:** Search every changed literal or behavior with + `rg -n --fixed-strings '' 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; + `rest-api/CHANGELOG.md` is legacy history whose published entry order must be + preserved. +- **Temporary claim and version gate:** 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. +- **Renderer gate:** Run + `rumdl check --config docs/.rumdl.toml ` 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 From 75638661471767436ef8c3b2cb05c3233ddbf2c2 Mon Sep 17 00:00:00 2001 From: Kyle Felter Date: Tue, 14 Jul 2026 13:36:42 -0500 Subject: [PATCH 3/5] docs: Restructure documentation review gates --- AGENTS.md | 142 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 83 insertions(+), 59 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6b98e5f588..482cdba85e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -212,65 +212,89 @@ lives in [`docs/observability/instrumentation.md`](docs/observability/instrument These are release gates, not style guidance. Apply every gate touched by the change before requesting review. -- **Interface contract gate:** For every documented command, flag, environment - variable, config key, API field, mode, or state, verify 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; and 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 interface gate:** Never edit a generated reference alone. - 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 -- --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` alone. -- **Workflow parity gate:** 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 gate:** 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 alone. -- **Cross-surface drift gate:** Search every changed literal or behavior with - `rg -n --fixed-strings '' 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; - `rest-api/CHANGELOG.md` is legacy history whose published entry order must be - preserved. -- **Temporary claim and version gate:** 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. -- **Renderer gate:** Run - `rumdl check --config docs/.rumdl.toml ` 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. +- **Interface contract gate:** 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 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; and 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 interface gate:** Change the source, regenerate every output, and prove they stay in sync. + + - Never edit a generated reference alone. + - 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 -- --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` alone. + +- **Workflow parity gate:** 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 gate:** 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 alone. + +- **Cross-surface drift gate:** Change a fact everywhere it appears or make one page canonical and link the rest. + + - Search every changed literal or behavior with + `rg -n --fixed-strings '' 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; + `rest-api/CHANGELOG.md` is legacy history whose published entry order must + be preserved. + +- **Temporary claim and version gate:** 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. + +- **Renderer gate:** Review each artifact in the renderer its readers actually use. + + - Run `rumdl check --config docs/.rumdl.toml ` 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 From 5b6de1665ea1ec8d6eba329c617f53ab8962b351 Mon Sep 17 00:00:00 2001 From: Kyle Felter Date: Tue, 14 Jul 2026 13:46:13 -0500 Subject: [PATCH 4/5] docs: Remove gate terminology from review rules --- AGENTS.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 482cdba85e..1732dbe404 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -209,10 +209,10 @@ lives in [`docs/observability/instrumentation.md`](docs/observability/instrument ## Documentation review -These are release gates, not style guidance. Apply every gate touched by the -change before requesting review. +These are documentation checks, not style guidance. Apply every relevant +check before requesting review. -- **Interface contract gate:** Document the complete contract, not just the name or happy path. +- **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 from code, schema, or exercised output: exact @@ -226,7 +226,7 @@ change before requesting review. - If any answer is unknown, stop and ask the owner; another documentation page is not evidence. -- **Generated interface gate:** Change the source, regenerate every output, and prove they stay in sync. +- **Generated interfaces:** Change the source, regenerate every output, and prove they stay in sync. - Never edit a generated reference alone. - For `nico-admin-cli`, change the Clap declarations under @@ -241,7 +241,7 @@ change before requesting review. `make openapi-breaking`; do not edit `rest-api/sdk/standard/` or `rest-api/docs/index.html` alone. -- **Workflow parity gate:** Make the documentation match the workflow that actually runs. +- **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 @@ -252,7 +252,7 @@ change before requesting review. handler. Narrative, Mermaid, and transition tables must contain the same states and edges, including persisted resume state. -- **Metric catalogue gate:** A metric is not documented until its HELP text, emitted series, and generated catalogue agree. +- **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. @@ -263,7 +263,7 @@ change before requesting review. `test_integration` so catalogue generation includes their exposed name, type, and description. Do not patch the generated table alone. -- **Cross-surface drift gate:** Change a fact everywhere it appears or make one page canonical and link the rest. +- **Cross-surface drift:** Change a fact everywhere it appears or make one page canonical and link the rest. - Search every changed literal or behavior with `rg -n --fixed-strings '' README.md crates/ rest-api/ docs/ book/ helm/ helm-prereqs/ deploy/`; @@ -275,7 +275,7 @@ change before requesting review. `rest-api/CHANGELOG.md` is legacy history whose published entry order must be preserved. -- **Temporary claim and version gate:** Tie temporary claims and pinned versions to a real support boundary. +- **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 @@ -285,7 +285,7 @@ change before requesting review. maximum, or pinned compatibility boundary; otherwise link the authoritative release page. -- **Renderer gate:** Review each artifact in the renderer its readers actually use. +- **Rendered output:** Review each artifact in the renderer its readers actually use. - Run `rumdl check --config docs/.rumdl.toml ` and fail on every finding. From 53f7a0d4e34eb3372238c0273fad156db5c65897 Mon Sep 17 00:00:00 2001 From: Kyle Felter Date: Tue, 14 Jul 2026 16:15:04 -0500 Subject: [PATCH 5/5] docs: Address documentation review feedback --- AGENTS.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1732dbe404..54dfd2362e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -214,13 +214,15 @@ 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 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; and observable output, side effects, errors, and unsupported - paths. + - 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 @@ -228,7 +230,7 @@ check before requesting review. - **Generated interfaces:** Change the source, regenerate every output, and prove they stay in sync. - - Never edit a generated reference alone. + - 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 -- --help`, then run @@ -239,7 +241,7 @@ check before requesting review. 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` alone. + `rest-api/docs/index.html`. - **Workflow parity:** Make the documentation match the workflow that actually runs. @@ -261,9 +263,9 @@ check before requesting review. 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 alone. + 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 the rest. +- **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 '' README.md crates/ rest-api/ docs/ book/ helm/ helm-prereqs/ deploy/`; @@ -272,8 +274,8 @@ check before requesting review. - 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; - `rest-api/CHANGELOG.md` is legacy history whose published entry order must - be preserved. + 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.