docs: rewrite Overview section and add landing page by andreliuNV · Pull Request #1190 · NVIDIA/infra-controller

andreliuNV · 2026-04-28T05:46:32Z

Summary

Landing page (docs/index.md): persona-based entry points for operators, integrators, and evaluators — replaces the stale Introduction page
Overview section (5 pages): complete rewrite covering What is NICo, Key Capabilities, Operational Principles, Day 0/1/2 Lifecycle, and Scope and Boundaries
What is NICo (what-is-nico.md): architecture overview with NICo Components (green boxes) and Prerequisite Components (white boxes) matching the architecture diagram; "Why NICo exists" framing sourced from VDR and Code Yellow docs
Scope and Boundaries (renamed from "What NICo Does Not Cover"): two-column tables showing NICo vs platform/operator responsibilities at each boundary
Nav fixes: explicit slugs to prevent Fern from mangling NICo in URLs (e.g. what-is-ni-co → what-is-nico)

Context

Part of the NICo Docs Code Yellow (FORGE-8168). Follows the IA recommendation from CDEVS-2173 for the Overview section structure and landing page.

Test plan

Preview with fern docs dev — verify all nav links resolve, no broken internal links
Verify Overview sidebar matches: Home → What is NICo? → Key Capabilities → Operational Principles → Day 0/1/2 Lifecycle → Scope and Boundaries
Verify landing page persona table links resolve to correct pages
Verify URL slugs use what-is-nico and scope-and-boundaries (not what-is-ni-co)
Review component descriptions in architecture overview against the architecture diagram

🤖 Generated with Claude Code

copy-pr-bot · 2026-04-28T05:46:36Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

andreliuNV · 2026-04-28T06:01:50Z

related RFE to update the diagram: #1192 (not critical path)

ajf · 2026-04-28T19:34:16Z

@andreliuNV your commits aren't signed

ajf

lgtm after commits get signed

andreliuNV · 2026-04-28T19:52:56Z

commits are signed now

github-actions · 2026-04-30T03:34:22Z

🌿 Preview your docs: https://nvidia-preview-pull-request-1190.docs.buildwithfern.com/infra-controller

benhuntley · 2026-04-30T23:28:54Z

"Bootstrap the org (required one-time call)" — GET /v2/org/ncx/carbide/service-account/current
This is a read/verification call, not a bootstrap — no org creation or write operation is performed.
"carbide-ntp ... perPodAnnotations" (Step 3h VIP assignment table)
carbide-ntp is not a subchart in helm/charts/ and has no entry in helm/Chart.yaml; these values are silently ignored by Helm.

Rewrites the entire Overview section of the NICo documentation and adds a new landing page, following the IA recommendation from CDEVS-2173. Overview section (5 pages): - What is NICo? — intro, "Why NICo exists" (sourced from VDR/Code Yellow), architecture overview with NICo Components and Prerequisite Components matching the architecture diagram, "Where NICo fits" stack diagram - Key Capabilities — hardware readiness, DPU lifecycle, multi-tenancy, trust/attestation, firmware control, deployment flexibility, GB200 rack-scale - Operational Principles — 5 foundational design principles - Day 0/1/2 Lifecycle — three operational phases - Scope and Boundaries — two-column tables showing NICo vs platform responsibilities (renamed from "What NICo Does Not Cover") Landing page (index.md): - Persona-based entry points: Deploy & Operate, Integrate, Evaluate - Quick links to HCL, release notes, FAQs, GitHub repos Other changes: - Replace "NCX Infra Controller" with "NVIDIA Infra Controller" in prose - Replace "GB200/GB300-class AI infrastructure" with "AI factory-scale infrastructure" - Fix /admin UI protocol: HTTP → HTTPS - Fix database name: forgedb → forge_system_carbide - Remove Route Server from NICo Components (not a NICo-deployed service) - Remove hand-wavey/marketing language across all overview pages - Remove duplicative content between overview pages - Add explicit URL slugs to prevent Fern slug mangling (what-is-ni-co) - Replace stale Introduction page (README.md) with new landing page Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Andrew Liu <andreliu@nvidia.com>

andreliuNV · 2026-05-04T05:53:59Z

@benhuntley issues addressed across both #1190 and #1227

andreliuNV · 2026-05-04T05:56:22Z

/ok to test 4d019dc

andreliuNV · 2026-05-04T05:56:59Z

@Coco-Ben please review

…d reference installation (#1227) ## Summary Adds the Getting Started section to the NICo documentation, covering the full deployment path from prerequisites through first host discovery. - **Prerequisites** (4 pages): Hardware, Network, Software, BMC/OOB — consolidated from site-reference-arch.md, site-setup.md, and networking_requirements.md - **Building NICo Containers**: repositioned in nav before Quick Start - **Quick Start Guide**: 7-step deployment walkthrough (build → K8s → configure → deploy → verify → OOB → first host) with site configuration pulled from helm-prereqs/README.md - **Reference Installation**: manual phase-by-phase installation from SETUP_PHASES.md, plus PKI architecture, PostgreSQL architecture, and troubleshooting - **Provisioning (Day 0 Operations)**: new section with Ingesting Hosts, Host Validation, SKU Validation - **helm-prereqs/README.md**: slimmed to lightweight pointer to docs site - Old pages removed where fully superseded (site-reference-arch, site-setup, networking_requirements, expected_machine_update, bootstrap) - TLS/SPIFFE page moved from kubernetes/ to development/ - CLI naming standardized: admin-cli (gRPC) vs carbide-cli (REST) with distinction table ## Context Part of NICo Docs Code Yellow (FORGE-8168). Follows the IA recommendation from CDEVS-2173 for the Getting Started section structure. Builds on the Overview section work in PR #1190. ## Test plan - [ ] Preview with `fern docs dev` — verify all nav links resolve - [ ] Walk through Quick Start Guide steps 1-7 for completeness - [ ] Verify prerequisite pages cover all content from removed old pages - [ ] Verify Reference Installation troubleshooting section is complete - [ ] Check landing page persona table links resolve to new page paths - [ ] Verify helm-prereqs/README.md links point to published docs URLs 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Peter Gambrill <pgambrill@nvidia.com> Signed-off-by: Andrew Liu <andreliu@nvidia.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Peter Gambrill <pgambrill@nvidia.com>

## Summary - **Landing page** (`docs/index.md`): persona-based entry points for operators, integrators, and evaluators — replaces the stale Introduction page - **Overview section** (5 pages): complete rewrite covering What is NICo, Key Capabilities, Operational Principles, Day 0/1/2 Lifecycle, and Scope and Boundaries - **What is NICo** (`what-is-nico.md`): architecture overview with NICo Components (green boxes) and Prerequisite Components (white boxes) matching the architecture diagram; "Why NICo exists" framing sourced from VDR and Code Yellow docs - **Scope and Boundaries** (renamed from "What NICo Does Not Cover"): two-column tables showing NICo vs platform/operator responsibilities at each boundary - **Nav fixes**: explicit slugs to prevent Fern from mangling NICo in URLs (e.g. `what-is-ni-co` → `what-is-nico`) ## Context Part of the NICo Docs Code Yellow (FORGE-8168). Follows the IA recommendation from CDEVS-2173 for the Overview section structure and landing page. ## Test plan - [ ] Preview with `fern docs dev` — verify all nav links resolve, no broken internal links - [ ] Verify Overview sidebar matches: Home → What is NICo? → Key Capabilities → Operational Principles → Day 0/1/2 Lifecycle → Scope and Boundaries - [ ] Verify landing page persona table links resolve to correct pages - [ ] Verify URL slugs use `what-is-nico` and `scope-and-boundaries` (not `what-is-ni-co`) - [ ] Review component descriptions in architecture overview against the architecture diagram 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Andrew Liu <andreliu@nvidia.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…d reference installation (NVIDIA#1227) ## Summary Adds the Getting Started section to the NICo documentation, covering the full deployment path from prerequisites through first host discovery. - **Prerequisites** (4 pages): Hardware, Network, Software, BMC/OOB — consolidated from site-reference-arch.md, site-setup.md, and networking_requirements.md - **Building NICo Containers**: repositioned in nav before Quick Start - **Quick Start Guide**: 7-step deployment walkthrough (build → K8s → configure → deploy → verify → OOB → first host) with site configuration pulled from helm-prereqs/README.md - **Reference Installation**: manual phase-by-phase installation from SETUP_PHASES.md, plus PKI architecture, PostgreSQL architecture, and troubleshooting - **Provisioning (Day 0 Operations)**: new section with Ingesting Hosts, Host Validation, SKU Validation - **helm-prereqs/README.md**: slimmed to lightweight pointer to docs site - Old pages removed where fully superseded (site-reference-arch, site-setup, networking_requirements, expected_machine_update, bootstrap) - TLS/SPIFFE page moved from kubernetes/ to development/ - CLI naming standardized: admin-cli (gRPC) vs carbide-cli (REST) with distinction table ## Context Part of NICo Docs Code Yellow (FORGE-8168). Follows the IA recommendation from CDEVS-2173 for the Getting Started section structure. Builds on the Overview section work in PR NVIDIA#1190. ## Test plan - [ ] Preview with `fern docs dev` — verify all nav links resolve - [ ] Walk through Quick Start Guide steps 1-7 for completeness - [ ] Verify prerequisite pages cover all content from removed old pages - [ ] Verify Reference Installation troubleshooting section is complete - [ ] Check landing page persona table links resolve to new page paths - [ ] Verify helm-prereqs/README.md links point to published docs URLs 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Signed-off-by: Peter Gambrill <pgambrill@nvidia.com> Signed-off-by: Andrew Liu <andreliu@nvidia.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Co-authored-by: Peter Gambrill <pgambrill@nvidia.com>

andreliuNV requested a review from a team as a code owner April 28, 2026 05:46

andreliuNV force-pushed the docs-overview-rewrite branch from 3b080c9 to 36f02cc Compare April 28, 2026 05:49

andreliuNV mentioned this pull request Apr 28, 2026

docs: update architecture diagram with missing elements from legacy diagram #1192

Open

ajf approved these changes Apr 28, 2026

View reviewed changes

andreliuNV force-pushed the docs-overview-rewrite branch 2 times, most recently from ebe55b5 to 010dd0d Compare April 28, 2026 19:52

andreliuNV mentioned this pull request Apr 29, 2026

docs: add Getting Started section with prerequisites, quick start, and reference installation #1227

Merged

6 tasks

andreliuNV force-pushed the docs-overview-rewrite branch from 010dd0d to b7211b7 Compare April 29, 2026 20:22

andreliuNV requested a review from Coco-Ben as a code owner April 29, 2026 20:22

andreliuNV force-pushed the docs-overview-rewrite branch 2 times, most recently from 1230446 to 284c8bf Compare April 30, 2026 03:33

vigviswa mentioned this pull request Apr 30, 2026

docs: end-to-end installation guide and prerequisite gap fixes #512

Closed

8 tasks

andreliuNV force-pushed the docs-overview-rewrite branch from 284c8bf to 7789860 Compare May 4, 2026 05:47

andreliuNV force-pushed the docs-overview-rewrite branch from 7789860 to 4d019dc Compare May 4, 2026 05:48

docs: correct overview accuracy details

1cdd19f

Coco-Ben approved these changes May 5, 2026

View reviewed changes

Coco-Ben merged commit efd92fb into NVIDIA:main May 5, 2026
45 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: rewrite Overview section and add landing page#1190

docs: rewrite Overview section and add landing page#1190
Coco-Ben merged 2 commits into
NVIDIA:mainfrom
andreliuNV:docs-overview-rewrite

andreliuNV commented Apr 28, 2026

Uh oh!

copy-pr-bot Bot commented Apr 28, 2026

Uh oh!

andreliuNV commented Apr 28, 2026

Uh oh!

ajf commented Apr 28, 2026

Uh oh!

ajf left a comment

Uh oh!

andreliuNV commented Apr 28, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

benhuntley commented Apr 30, 2026

Uh oh!

andreliuNV commented May 4, 2026

Uh oh!

andreliuNV commented May 4, 2026

Uh oh!

andreliuNV commented May 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

andreliuNV commented Apr 28, 2026

Summary

Context

Test plan

Uh oh!

copy-pr-bot Bot commented Apr 28, 2026

Uh oh!

andreliuNV commented Apr 28, 2026

Uh oh!

ajf commented Apr 28, 2026

Uh oh!

ajf left a comment

Choose a reason for hiding this comment

Uh oh!

andreliuNV commented Apr 28, 2026

Uh oh!

github-actions Bot commented Apr 30, 2026

Uh oh!

benhuntley commented Apr 30, 2026

Uh oh!

andreliuNV commented May 4, 2026

Uh oh!

andreliuNV commented May 4, 2026

Uh oh!

andreliuNV commented May 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants