feat(docs): publish per-stack Fern products with independent versions

.github/workflows/fern-docs-ci.yml

@@ -36,6 +36,10 @@ jobs:
     steps:
       - name: Checkout repository
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          # check-doc-version-sync resolves stack release tags to commits.
+          fetch-depth: 0
+          fetch-tags: true
 
       - name: Setup Node.js
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
@@ -63,3 +67,10 @@ jobs:
 
       - name: Fern check
         run: fern check
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: tools/go-toolchain/go.mod
+
+      - name: Check generated documentation blocks match the version catalog
+        run: ./tools/ci/check-doc-version-sync

.markdownlintignore

@@ -7,13 +7,15 @@ vendor/
 third_party/
 
 # Frozen versioned documentation. docs/AGENTS.md states that docs/v*/ and
-# docs/cp-*/ must not be edited without an explicit request for a historical
-# docs fix, so linting these trees can only produce findings that must never be
-# acted on.
+# docs/<stack>-<train>/ must not be edited without an explicit request for a
+# historical docs fix, so linting these trees can only produce findings that
+# must never be acted on.
 #
-# The [0-9] keeps docs/version-catalog/, which is not frozen, in scope.
+# The [0-9] keeps docs/version-catalog/, which is not frozen, in scope. The
+# per-stack pattern has no trailing slash on purpose: markdownlint-cli 0.49
+# does not match docs/<stack>-<train>/ files against "docs/*-[0-9]*/".
 docs/v[0-9]*/
-docs/cp-*/
+docs/*-[0-9]*
 
 # Vendored Helm subcharts. Same rationale as vendor/: upstream chart content
 # this repository redistributes rather than authors.
@@ -34,13 +36,13 @@ CLAUDE.md
 # the heading and MD041 can never pass. An inline disable is not an option
 # either: docs/ is rendered as MDX, where an HTML comment is a parse error, and
 # MDX's own {/* */} comment is not a markdownlint directive. MD041 is their only
-# violation. docs/user/ copies are symlinks to the docs/dev/ originals.
+# violation. docs/self-managed/ copies are symlinks to the docs/dev/ originals.
 docs/dev/grpc-load-test-sli-guide.md
 docs/dev/http-load-test-sli-guide.md
 docs/dev/http-load-testing.md
-docs/user/grpc-load-test-sli-guide.md
-docs/user/http-load-test-sli-guide.md
-docs/user/http-load-testing.md
+docs/overview/grpc-load-test-sli-guide.md
+docs/overview/http-load-test-sli-guide.md
+docs/overview/http-load-testing.md
 
 # Generated file. tools/collect-dependencies writes dependencies.md and CI
 # fails if it differs from the generator's output, so it cannot be edited to

CONTRIBUTING.md

@@ -165,19 +165,21 @@ For more information, see the [Developer Certificate of Origin](https://develope
 
 ## Documentation Contributions
 
-Documentation content lives under `docs/`. Fern publishes that content using version-specific navigation files under `fern/versions/`, and `fern/docs.yml` declares the public version list.
+Documentation content lives under `docs/`. Fern publishes one site with four products: Overview plus one product per Helm stack. Each stack product has its own version menu. `fern/docs.yml` declares the products and their versions, and navigation files live under `fern/products/`.
 
 | Path | Audience | Published | Versioning role |
 |---|---|---|---|
-| `docs/user/` | Customers | Yes | Source content for the default `main` docs version. `fern/versions/main.yml` points here and publishes at `/nvcf/`. |
-| `docs/v0.5/` | Customers using release 0.5 | Yes | Frozen content for the `0.5` docs version. `fern/versions/v0.5.yml` points here and publishes at `/nvcf/v0.5/`. |
-| `docs/dev/` | Contributors / internal dev | Only if symlinked | Developer-oriented source pages. These are published only when a symlink from a versioned content tree, usually `docs/user/`, is listed in that version's Fern nav. |
-| `fern/docs.yml` | Docs site | Yes | Declares public versions, display names, slugs, and the nav file for each version. |
-| `fern/versions/*.yml` | Docs site | Yes | Defines navigation and page order for one published version. Page paths are relative to the version file. |
+| `docs/overview/` | Customers | Yes | Unversioned shared content: compatibility matrix, quickstart, manifest, image mirroring, local development, shared images and samples. Publishes at `/nvcf/overview/`. |
+| `docs/self-managed/`, `docs/compute-plane/`, `docs/observability/` | Customers | Yes | Top-of-tree content for one stack, published as that product's `dev` version at `/nvcf/<stack>/dev/`. |
+| `docs/<stack>-<train>/` | Customers on a release train | Yes | Frozen content for one stack train, for example `docs/observability-1.3/`. Publishes at `/nvcf/<stack>/<train>/`. |
+| `docs/v0.5/`, `docs/v0.6.0/`, `docs/v0.6.1/`, `docs/cp-*/` | Customers on legacy releases | Yes | Frozen legacy full-tree content from before the per-stack split, attached to the Self-Managed Stack product. |
+| `docs/dev/` | Contributors / internal dev | Only if symlinked | Developer-oriented source pages. These are published only when a symlink from a product tree is listed in that product's Fern nav. |
+| `fern/docs.yml` | Docs site | Yes | Declares products, their versions, display names, slugs, and the nav file for each version. |
+| `fern/products/overview.yml`, `fern/products/<stack>/*.yml` | Docs site | Yes | Defines navigation and page order for one product version. Page paths are relative to the nav file. |
 
-Use `docs/user/` for changes that should appear in the default `main` docs. Update `docs/v0.5/` only for fixes that must also apply to the 0.5 release docs. When adding, renaming, moving, or removing a published page, update the matching `fern/versions/<version>.yml` file.
+A page belongs to exactly one product. Use the product tree that owns the page for changes that should appear in `dev`. Edit frozen trees only for fixes that must also apply to that released version. When adding, renaming, moving, or removing a published page, update the matching nav file under `fern/products/`. Links to pages in another product must be absolute site paths such as `/nvcf/overview/quickstart`, because Fern resolves relative links inside the rendering product.
 
-All navigation sections use `skip-slug: true`, so each page title becomes a flat URL slug within its published version. Keep page titles unique and descriptive within the version nav. Run `fern check` to validate the docs after any navigation or link change. Preview locally with `fern docs dev` from the `fern/` directory.
+All navigation sections use `skip-slug: true`, so each page title becomes a flat URL slug within its product version. Keep page titles unique and descriptive within each product nav. Run `fern check` to validate the docs after any navigation or link change. Preview locally with `fern docs dev` from the `fern/` directory.
 
 ---
 

README.md

@@ -1,9 +1,9 @@
 <!-- markdownlint-disable-next-line MD041 -->
-![NVCF banner](docs/user/images/nvcf-banner.svg)
+![NVCF banner](docs/overview/images/nvcf-banner.svg)
 
 [![bazel](https://github.com/NVIDIA/nvcf/actions/workflows/bazel.yml/badge.svg?branch=main)](https://github.com/NVIDIA/nvcf/actions/workflows/bazel.yml?query=branch%3Amain)
 
-[Docs](https://docs.nvidia.com/nvcf/overview) | [Roadmap](#roadmap) | [Installation](docs/user/installation.md) | [API Reference](docs/user/api.md) | [Contributing](CONTRIBUTING.md) | [License](#license) | [build.nvidia.com Powered By NVCF](https://build.nvidia.com/)
+[Docs](https://docs.nvidia.com/nvcf/overview) | [Roadmap](#roadmap) | [Installation](docs/self-managed/installation.md) | [API Reference](docs/overview/api.md) | [Contributing](CONTRIBUTING.md) | [License](#license) | [build.nvidia.com Powered By NVCF](https://build.nvidia.com/)
 
 > **Repository move in progress.** This repo is transferring from `NVIDIA/nvcf` to
 > `dsx-ai-factory/nvcf`. Now targeted for **after 2026-09-27** — exact date and
@@ -23,7 +23,7 @@ examples, CLI code, agent skills, and validation tooling.
 
 ## Architecture
 
-![NVCF architecture](docs/user/images/nvcf-high-level-stack.svg)
+![NVCF architecture](docs/overview/images/nvcf-high-level-stack.svg)
 
 NVCF runs as Kubernetes services that manage function lifecycle, invocation
 routing, GPU cluster integration, artifact access, secrets, observability, and
@@ -44,7 +44,7 @@ At a high level:
 The following diagram shows how self-managed NVCF can span regions and GPU
 clusters.
 
-<img src="docs/user/images/nvcf-multi-region-multi-cluster.svg" alt="NVCF multi-region and multi-cluster architecture" width="80%">
+<img src="docs/overview/images/nvcf-multi-region-multi-cluster.svg" alt="NVCF multi-region and multi-cluster architecture" width="80%">
 
 ### Workload types
 
@@ -90,8 +90,8 @@ nvcf-cli function invoke --request-body '{"message": "hello world"}'
 ```
 
 For the full setup, cleanup, and configuration flow, see
-[`docs/user/cli.md`](docs/user/cli.md) and
-[`docs/user/quickstart.md`](docs/user/quickstart.md).
+[`docs/overview/cli.md`](docs/overview/cli.md) and
+[`docs/overview/quickstart.md`](docs/overview/quickstart.md).
 
 ## Repository map
 
@@ -102,7 +102,7 @@ For the full setup, cleanup, and configuration flow, see
 | Compute plane | [`src/compute-plane-services/`](src/compute-plane-services/) | GPU cluster integration, cache services, image credentials, ESS Agent, and telemetry collection. |
 | CLI and libraries | [`src/clis/`](src/clis/), [`src/libraries/`](src/libraries/) | User and developer clients plus shared Go and Python code. |
 | Deployment | [`deploy/`](deploy/), [`migrations/`](migrations/) | Helm charts, stack installation, infrastructure services, and datastore migrations. |
-| Documentation | [`docs/user/`](docs/user/index.md), [`docs/dev/`](docs/dev/), [`fern/`](fern/) | Self-managed user docs, developer docs, and published docs navigation. |
+| Documentation | [`docs/overview/`](docs/overview/index.md), [`docs/self-managed/`](docs/self-managed/), [`docs/compute-plane/`](docs/compute-plane/), [`docs/observability/`](docs/observability/), [`docs/dev/`](docs/dev/), [`fern/`](fern/) | Per-stack user docs, shared overview docs, developer docs, and published docs navigation. |
 | Examples | [`examples/`](examples/) | Local development guides, function samples, and load-test assets. |
 | Tools | [`tools/`](tools/) | Build, docs, dependency, license, and validation utilities. |
 | AI tooling | [`ai-tooling/`](ai-tooling/) | Public agent skills and workflow helpers for NVCF users and developers. |

RELEASE.md

@@ -61,6 +61,42 @@ releases no stack version at all.
   internal publish lanes accept `-rc.N`, so the stack is packaged and published
   without a version landing on its stable line.
 
+The three stacks were level-set to `1.0.0` when this model started. From that
+point each stack advances on its own trains and its own schedule. A
+compute-plane `1.2` says nothing about which self-managed or observability
+train it runs with; the compatibility matrix does, see "Stack compatibility and
+upgrade stops" below.
+
+When a tag is pushed, the `tag` job resolves the publishing stack from the tag
+alone, using the `tag_format` in `tools/ci/github-release-subprojects.json`,
+and attaches that stack's `resolved_inventory_asset` to the GitHub Release.
+Which branch cut the tag does not matter, so release branching did not change
+how inventories reach a release.
+
+### Stack compatibility and upgrade stops
+
+- Only trains N and N-1 of a stack are maintained. A train older than N-1
+  receives no further patches.
+- Patch upgrades within a train are always supported.
+- Upgrading across more than one train is done one train at a time: move to
+  the latest patch of each intermediate train before moving to the next. Each
+  train is an upgrade stop.
+- The compatibility matrix at `docs/overview/compatibility-matrix.md` is the
+  source of truth for which trains of the three stacks run together. It is
+  generated by `tools/docs-version-sync` from the `compatibility:` block in
+  `docs/version-catalog/main.yaml`. A stack change that alters what it can run
+  with must update that block in the same change.
+
+### Stack documentation
+
+Each stack is published as its own Fern product with its own version list, so
+documentation for one stack can be frozen without touching the other two.
+After a train's first release, freeze that stack's docs with:
+
+```sh
+./tools/scripts/cut-docs-version.sh --stack <self-managed|compute-plane|observability> --train X.Y
+```
+
 `nvca` used the same model until the 3.3 line and now releases from `main`
 like every other subproject. Nothing publishes a `-dev.N` any more, and none
 of the ones published under the older form of this model are still in the
@@ -153,7 +189,9 @@ for, or must not carry, the current state of `main`.
 Support window: where a subproject does maintain release branches, only the
 latest minor release train and the one before it (N and N-1) are maintained.
 A release branch older than N-1 is effectively end of life and does not
-receive further backports.
+receive further backports. For the `deploy/stacks/` subprojects the window is
+counted per stack, and each train is also an upgrade stop; see "Stack
+compatibility and upgrade stops".
 
 Mechanism: cherry-pick the commit from `main` onto the `release-*` branch,
 following the same commit and review conventions as `main`. There is no

ai-tooling/dev/skills/nvcf-explore-stack/SKILL.md

@@ -99,5 +99,5 @@ After exploring, suggest the next skill when applicable:
 - `nvcf-self-managed-installation` for installing, upgrading, or tearing down the stack
 - `docs/dev/local-development.md` for k3d / local cluster work
 - `nvcf-self-managed-cli` for `nvcf-cli` usage against an installed stack
-- `docs/AGENTS.md` and `fern/versions/dev.yml` for routing the user to a published docs page
+- `docs/AGENTS.md` and `fern/products/<product>/dev.yml` for routing the user to a published docs page
 - `tools/ci/check-doc-version-sync` for keeping the documentation manifest in sync with the docs version catalog

ai-tooling/user/skills/nvcf-self-managed-installation/references/helmfile-structure.md

@@ -206,7 +206,7 @@ must not be used in production.
 
 The request router uses `power-of-two` when no load-balancer configuration is
 set. Configure other routing methods with the
-[LLM Request Router Load Balancing](https://github.com/NVIDIA/nvcf/blob/main/docs/user/llm-request-router-load-balancing.md)
+[LLM Request Router Load Balancing](https://github.com/NVIDIA/nvcf/blob/main/docs/self-managed/llm-request-router-load-balancing.md)
 guide.
 
 If the sidecar image is mirrored outside the stack's default image registry and

deploy/helm/llm-request-router/README.md

@@ -204,7 +204,7 @@ The chart can pass a Stargate load-balancer config in either of two ways:
 See the
 [Stargate load balancer configuration](../../../src/libraries/rust/stargate/docs/load-balancer-configuration.md)
 for the JSON schema, algorithm behavior, and tuning fields. See
-[LLM Request Router Load Balancing](../../../docs/user/llm-request-router-load-balancing.md)
+[LLM Request Router Load Balancing](../../../docs/self-managed/llm-request-router-load-balancing.md)
 for stack ownership, trusted headers, rollout checks, and troubleshooting.
 
 ## Local Render

deploy/stacks/AGENTS.md

@@ -13,6 +13,11 @@ resource.
 - `nvcf-compute-plane/` owns the NVCF compute-plane stack.
 - `observability/` owns shared observability infrastructure.
 - Each stack owns its own `release-inventory.yaml` and release asset.
+- Each stack releases from its own `release-deploy/stacks/<stack>/vX.Y`
+  branch and advances its trains independently. All three started at `1.0.0`.
+- Each stack has its own documentation tree (`docs/self-managed/`,
+  `docs/compute-plane/`, `docs/observability/`) published as a Fern product
+  with its own version list. Shared pages live in `docs/overview/`.
 - Do not reference another stack's Helmfile state from an inventory config.
 - Keep a dependency in the stack that installs or creates it.
 - Follow the nearest nested `AGENTS.md` when it adds stack-specific guidance.
@@ -27,9 +32,13 @@ For every dependency change:
 4. Add registry and repository overrides for images that customers must mirror.
 5. Record images that do not appear in rendered Kubernetes `image` fields.
 6. Update the artifact classification in `docs/version-catalog/main.yaml`.
-7. Run the stack tests and the inventory and documentation checks described in
+7. If the change raises the minimum train of another stack this stack works
+   with, update the `compatibility:` block in `docs/version-catalog/main.yaml`
+   in the same change (for example `compute-plane: "1.2+"`). It generates
+   `docs/overview/compatibility-matrix.md`.
+8. Run the stack tests and the inventory and documentation checks described in
    [`INVENTORY.md`](INVENTORY.md).
-8. After the stack release publishes its inventory asset, update the catalog
+9. After the stack release publishes its inventory asset, update the catalog
    and generated manifest in a documentation sync change.
 
 A dependency is not fully distributed when the released inventory or generated
@@ -60,7 +69,9 @@ go run -C tools/docs-version-sync . --target main
 git diff --check
 ```
 
-Do not hand-edit generated blocks in `docs/user/manifest.md`. The CI check
+Do not hand-edit generated blocks in `docs/overview/manifest.md`,
+`docs/overview/compatibility-matrix.md`, or any other generated block under
+the product docs trees. The CI check
 against the latest released inventory is warn-only for now. Generated-document
 consistency remains blocking. Treat a release-drift warning as follow-up work
 and keep the local checks clean for a dependency change.