docs(self-managed): document upstream supporting images

[sbaum1994]

TL;DR

Document how self-managed deployments can pull supporting images directly
from upstream registries. Point the NATS configuration reloader and
alpine-k8s manifest entries to their public Docker Hub distributions in both
dev docs and the 0.6.1-rc snapshot.

Additional Details (optional for docs, build, test, refactor, ci, chore, style, and revert PRs)

The artifact manifest previously listed both supporting images under the NVCF
Early Access registry even though they can be consumed directly from their
public upstream repositories.

This change:

• adds upstream image override examples for the NATS configuration reloader
  and the three alpine-k8s consumers in the self-managed stack
• identifies docker.io/natsio/nats-server-config-reloader:0.23.0 and
  docker.io/alpine/k8s:1.36.1 as their distributions
• updates the dev version catalog so generated manifest content stays
  synchronized
• applies the same manifest changes to the 0.6.1-rc documentation snapshot

No third-party dependency versions changed. License review and NOTICE updates
are not required for this documentation-only change.

For the Reviewer

Review the upstream override examples and generated manifest distribution
paths for both supporting images.

For QA (optional for docs, build, test, refactor, ci, chore, style, and revert PRs)

QA is not needed. Validation performed:

• go test -C tools/docs-version-sync ./...
• generated dev manifest check using tools/docs-version-sync
• exact comparison of dev and 0.6.1-rc manifests
• ./tools/ci/check-docs
• git diff --check

The remote catalog refresh remains advisory because the migrated repository no
longer contains the root marker expected by the sync command. Local generated
content and Fern validation passed.

Issues

Closes #370

Checklist

• I am familiar with the Contributing Guidelines.
• I have signed off my commits for Developer Certificate of Origin (DCO) compliance.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

Summary by CodeRabbit

• Documentation

  • Added guidance for configuring supported upstream container images from Docker Hub.
  • Updated artifact inventories with upstream Alpine Kubernetes and NATS reloader image references.
  • Documented registry access, authentication, image versions, and configuration limitations.

• Tests

  • Added single-cluster validation covering upstream image overrides through rendering and deployment.
  • Added coverage for multi-line configuration block substitutions and restoration.
  • Improved live-test setup and topology cleanup verification.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The version catalog maps Alpine Kubernetes and NATS artifacts to Docker Hub registries. Manifests document upstream image overrides, and BDD coverage adds block substitution plus a single-cluster Helmfile workflow that renders, installs, and verifies the upstream images.

Changes

Upstream image documentation and validation

Layer / File(s)	Summary
Map and document upstream images docs/version-catalog/main.yaml, docs/user/manifest.md, docs/v0.6.1-rc/manifest.md	Adds Docker Hub registry mappings and Alpine metadata, documents override configuration, and updates Alpine Kubernetes and NATS image distributions.
Add block substitution support tests/bdd/dsl/*, tests/bdd/steps/*, tests/bdd/PLAN.md	Adds exact multi-line block replacement with validation, interpolation, ledger snapshots, and tests.
Wire the upstream-image BDD workflow tests/bdd/features/*, tests/bdd/godog_test.go, tests/bdd/README.md, tests/bdd/PLAN_DESTRUCTIVE_CLEANUP.md	Adds fixture wiring, live execution, targeted Helmfile installs, runtime image verification, prerequisites, and cleanup-mode documentation.
Record design and live-run decisions docs/superpowers/specs/*, docs/superpowers/issues/*	Documents the workflow design, verification boundaries, failure behavior, and implementation issues addressed during live runs.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant BDDFeature
  participant ScenarioContext
  participant Helmfile
  participant Kubernetes
  BDDFeature->>ScenarioContext: substitute upstream image blocks
  ScenarioContext->>Helmfile: render and install selected releases
  Helmfile->>Kubernetes: deploy workloads
  Kubernetes-->>BDDFeature: return image references

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The BDD DSL/helper, feature, design, and test additions are broader than the linked documentation request.	Split the validation harness and design/spec updates into a separate PR, keeping this one focused on the documentation and manifest changes.
Docstring Coverage	⚠️ Warning	Docstring coverage is 55.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The docs(self-managed) Conventional Commit matches the primarily documentation-focused change set.
Linked Issues check	✅ Passed	The docs now point the NATS reloader manifest to Docker Hub and include override, connectivity, and pull-secret guidance.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/nats-upstream-config-reloader

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-docs-nats-upstream-config-reloader.docs.buildwithfern.com/nvcf

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/user/manifest.md`:
- Around line 76-78: Update the documentation around global.imagePullSecrets to
explain that it references existing Kubernetes Secret names rather than
embedding registry credentials, require the Secret to exist in each workload
namespace, and show the expected list shape such as [{name:
"my-registry-secret"}].

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 593b40b1-bc11-43fe-a2cd-19f3ef360d73

📥 Commits

Reviewing files that changed from the base of the PR and between ea8ca3e and d0f5741.

📒 Files selected for processing (2)

• docs/user/manifest.md
• docs/version-catalog/main.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/version-catalog/main.yaml

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/superpowers/issues/2026-07-22-single-cluster-upstream-images.md`:
- Around line 146-151: Update the workflow summary to explicitly mention that
the feature installs the `name=nats-auth-callout-service` selector, alongside
the existing dependency, `ess-api`, and `api` prerequisites. Keep the
description consistent with BDD-UPSTREAM-014 and preserve the existing scope of
the single-cluster Helmfile bring-up.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: f8c1cb57-6363-450d-bcac-437bb885f412

📥 Commits

Reviewing files that changed from the base of the PR and between dd9237e and 4cb3c42.

📒 Files selected for processing (13)

• docs/superpowers/issues/2026-07-22-single-cluster-upstream-images.md
• docs/superpowers/specs/2026-07-22-single-cluster-upstream-images-design.md
• docs/user/manifest.md
• docs/v0.6.1-rc/manifest.md
• tests/bdd/PLAN.md
• tests/bdd/PLAN_DESTRUCTIVE_CLEANUP.md
• tests/bdd/README.md
• tests/bdd/dsl/yamledit.go
• tests/bdd/dsl/yamledit_test.go
• tests/bdd/features/single-cluster-helmfile-upstream-images.feature
• tests/bdd/godog_test.go
• tests/bdd/steps/file_steps.go
• tests/bdd/steps/steps_test.go

🚧 Files skipped from review as they are similar to previous changes (2)

• docs/user/manifest.md
• docs/v0.6.1-rc/manifest.md