docs: Add kargo add-on promoter topic

This patch adds an Add-On Promoter topic to demonstrate how Holos pairs
nicely with Kargo for progressive rollouts.

Code examples are automatically tested and used in the doc using go test
and testscripts.

Update the examples using:

    HOLOS_UPDATE_SCRIPTS=1 go test ./doc/md/topics/kargo

.cspell.json

@@ -37,6 +37,7 @@
     "blackbox",
     "buildplan",
     "buildplans",
+    "Buildx",
     "builtinpluginloadingoptions",
     "cachedir",
     "cadvisor",
@@ -84,6 +85,7 @@
     "destinationrules",
     "devel",
     "devicecode",
+    "distroless",
     "dnsmasq",
     "dscacheutil",
     "ecrauthorizationtoken",
@@ -281,6 +283,7 @@
     "serviceentries",
     "serviceentry",
     "servicemonitor",
+    "sigstore",
     "somevalue",
     "SOMEVAR",
     "sortoptions",
@@ -321,6 +324,7 @@
     "udev",
     "uibutton",
     "Unmarshal",
+    "unshallow",
     "unstage",
     "untar",
     "upbound",

.github/workflows/container.yaml

@@ -0,0 +1,143 @@
+name: Container
+
+# Only allow actors with write permission to the repository to trigger this
+# workflow.
+permissions:
+  contents: write
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      git_ref:
+        description: 'Git ref to build (e.g., refs/tags/v1.2.3, refs/heads/main)'
+        required: true
+        type: string
+
+jobs:
+  buildx:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      attestations: write
+      id-token: write
+    steps:
+      - name: Set tag from trigger event
+        id: opts
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "ref=${{ inputs.git_ref }}" >> $GITHUB_OUTPUT
+          else
+            echo "ref=${GITHUB_REF}" >> $GITHUB_OUTPUT
+          fi
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ steps.opts.outputs.ref }}
+      - name: SHA
+        id: sha
+        run: echo "sha=$(/usr/bin/git log -1 --format='%H')" >> $GITHUB_OUTPUT
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+      - name: Fetch tags
+        run: git fetch --prune --unshallow --tags
+      - name: Set Tags
+        id: tags
+        run: |
+          echo "detail=$(/usr/bin/git describe --tags HEAD)" >> $GITHUB_OUTPUT
+          echo "suffix=$(test -n "$(git status --porcelain)" && echo '-dirty' || echo '')" >> $GITHUB_OUTPUT
+          echo "tag=$(/usr/bin/git describe --tags HEAD)$(test -n "$(git status --porcelain)" && echo '-dirty' || echo '')" >> $GITHUB_OUTPUT
+
+      - name: Login to ghcr.io
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: Build and push container images
+        id: build-and-push
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: |
+            ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+            ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}
+      - name: Setup Cosign to sign container images
+        uses: sigstore/cosign-installer@v3.7.0
+      - name: Sign with GitHub OIDC Token
+        env:
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          cosign sign --yes ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST}
+          cosign sign --yes ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST}
+
+      - uses: actions/create-github-app-token@v1
+        id: app-token
+        with:
+          owner: ${{ github.repository_owner }}
+          app-id: ${{ vars.GORELEASER_APP_ID }}
+          private-key: ${{ secrets.GORELEASER_APP_PRIVATE_KEY }}
+      - name: Get GitHub App User ID
+        id: get-user-id
+        run: echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+      - run: |
+          git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'
+          git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'
+      - name: Update holos-run/holos-action
+        env:
+          IMAGE: ghcr.io/holos-run/holos:v0.102.1
+          VERSION: ${{ steps.tags.outputs.tag }}
+          USER_ID: ${{ steps.get-user-id.outputs.user-id }}
+          TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          set -euo pipefail
+          git clone "https://github.com/holos-run/holos-action"
+          cd holos-action
+          git remote set-url origin https://${USER_ID}:${TOKEN}@github.com/holos-run/holos-action
+          docker pull --quiet "${IMAGE}"
+          docker run -v $(pwd):/app --workdir /app --rm "${IMAGE}"  \
+            holos cue export --out yaml action.cue -t "version=${VERSION}" > action.yml
+          git add action.yml
+          git commit -m "ci: update holos to ${VERSION} - https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}" || (echo "No changes to commit"; exit 0)
+          git push origin HEAD:main HEAD:v0 HEAD:v1
+
+      - name: Login to quay.io
+        uses: docker/login-action@v3
+        with:
+          registry: quay.io
+          username: ${{ secrets.QUAY_USER }}
+          password: ${{ secrets.QUAY_TOKEN }}
+      - name: Push to quay.io
+        env:
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          # docker push quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+          docker pull --quiet ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST}
+          docker tag ghcr.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST} \
+                     quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+          docker push quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}
+
+          docker pull --quiet ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST}
+          docker tag ghcr.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST} \
+                     quay.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}
+          docker push quay.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}
+      - name: Sign quay.io image
+        env:
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        run: |
+          cosign sign --yes quay.io/holos-run/holos:${{ steps.tags.outputs.tag }}@${DIGEST}
+          cosign sign --yes quay.io/holos-run/holos:${{ steps.sha.outputs.sha }}${{ steps.tags.outputs.suffix }}@${DIGEST}
+
+    outputs:
+      tag: ${{ steps.tags.outputs.tag }}
+      detail: ${{ steps.tags.outputs.detail }}

.github/workflows/lint.yaml

@@ -1,6 +1,5 @@
 ---
-# https://github.com/golangci/golangci-lint-action?tab=readme-ov-file#how-to-use
-name: Lint
+name: Spelling
 "on":
   push:
     branches:
@@ -8,35 +7,11 @@ name: Lint
       - test
   pull_request:
     types: [opened, synchronize]
-
 permissions:
   contents: read
-
 jobs:
-  lint:
-    name: lint
+  cspell:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: stable
-
-      ## Not needed on ubuntu-latest
-      # - name: Install Packages
-      #   run: sudo apt update && sudo apt -qq -y install git curl zip unzip tar bzip2 make
-
-      - name: Install Tools
-        run: make tools
-
-      - name: Lint
-        # golangci-lint runs in a separate workflow.
-        run: make lint -o golangci-lint
+      - uses: actions/checkout@v4
+      - run: ./hack/cspell

.github/workflows/test.yaml

@@ -28,19 +28,11 @@ jobs:
         with:
           go-version: stable
 
-      - name: Install Packages
-        run: sudo apt update && sudo apt -qq -y install git curl zip unzip tar bzip2 make
-
       - name: Set up Helm
         uses: azure/setup-helm@v4
 
       - name: Set up Kubectl
         uses: azure/setup-kubectl@v4
 
-      - name: Install Tools
-        run: |
-          set -x
-          make tools
-
       - name: Test
         run: ./scripts/test

Dockerfile

@@ -1,8 +1,31 @@
-FROM quay.io/holos-run/debian:bullseye AS final
-USER root
-WORKDIR /app
-ADD bin bin
-RUN chown -R app: /app
-# Kubernetes requires the user to be numeric
-USER 8192
-ENTRYPOINT bin/holos server
+FROM registry.k8s.io/kubectl:v1.31.0 AS kubectl
+# https://github.com/GoogleContainerTools/distroless
+FROM golang:1.23 AS build
+
+WORKDIR /go/src/app
+COPY . .
+
+RUN CGO_ENABLED=0 make install
+RUN CGO_ENABLED=0 go install sigs.k8s.io/kustomize/kustomize/v5
+
+# Install helm to /usr/local/bin/helm
+# https://helm.sh/docs/intro/install/#from-script
+# https://holos.run/docs/v1alpha5/tutorial/setup/#dependencies
+RUN curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 \
+  && chmod 700 get_helm.sh \
+  && DESIRED_VERSION=v3.16.2 ./get_helm.sh \
+  && rm -f get_helm.sh
+
+COPY --from=kubectl /bin/kubectl /usr/local/bin/
+
+# distroless
+FROM gcr.io/distroless/static-debian12 AS final
+COPY --from=build \
+     /go/bin/holos \
+     /go/bin/kustomize \
+     /usr/local/bin/kubectl \
+     /usr/local/bin/helm \
+     /bin/
+
+# Usage: docker run -v $(pwd):/app --workdir /app --rm -it quay.io/holos-run/holos holos render platform
+CMD ["/bin/holos"]

Makefile

@@ -154,6 +154,10 @@ website: ## Build website
 unity: ## https://cuelabs.dev/unity/
 	./scripts/unity
 
+.PHONY: update-docs
+update-docs: ## Update doc examples
+	HOLOS_UPDATE_SCRIPTS=1 go test -v ./doc/md/...
+
 .PHONY: help
 help:  ## Display this help menu.
 	@awk 'BEGIN {FS = ":.*##"; printf "\nUsage:\n  make \033[36m<target>\033[0m\n"} /^[a-zA-Z_0-9-]+:.*?##/ { printf "  \033[36m%-20s\033[0m %s\n", $$1, $$2 } /^##@/ { printf "\n\033[1m%s\033[0m\n", substr($$0, 5) } ' $(MAKEFILE_LIST)

README.md

@@ -119,12 +119,12 @@ here to help.
 
 Holos is licensed under Apache 2.0 as found in the [LICENSE file](LICENSE).
 
-[Holos]: https://holos.run
+[Holos]: https://holos.run/docs/overview/
 [rendered manifests pattern]: https://akuity.io/blog/the-rendered-manifests-pattern
 [CUE]: https://cuelang.org/
 [Discord]: https://discord.gg/JgDVbNpye7
 [GitHub discussions]: https://github.com/holos-run/holos/discussions
 [Why CUE for Configuration]: https://holos.run/blog/why-cue-for-configuration/
-[topics]: https://holos.run/docs/topics/
+[tutorial]: https://holos.run/docs/overview/
 [setup]: https://holos.run/docs/setup/
-[tutorial]: https://holos.run/docs/tutorial/
+[topics]: https://holos.run/docs/topics/

api/author/v1alpha5/definitions.go

@@ -84,6 +84,9 @@ type Helm struct {
 	Chart core.Chart
 	// Values represents data to marshal into a values.yaml for helm.
 	Values core.Values
+	// ValueFiles represents value files for migration from helm value
+	// hierarchies.  Use Values instead.
+	ValueFiles []core.ValueFile `json:",omitempty"`
 	// EnableHooks enables helm hooks when executing the `helm template` command.
 	EnableHooks bool `cue:"true | *false"`
 	// Namespace sets the helm chart namespace flag if provided.

api/core/v1alpha5/types.go

@@ -118,8 +118,12 @@ type Helm struct {
 	// Chart represents a helm chart to manage.
 	Chart Chart `json:"chart" yaml:"chart"`
 	// Values represents values for holos to marshal into values.yaml when
-	// rendering the chart.
+	// rendering the chart.  Values follow ValueFiles when both are provided.
 	Values Values `json:"values" yaml:"values"`
+	// ValueFiles represents hierarchial value files passed in order to the helm
+	// template -f flag.  Useful for migration from an ApplicationSet.  Use Values
+	// instead.  ValueFiles precede Values when both are provided.
+	ValueFiles []ValueFile `json:"valueFiles,omitempty" yaml:"valueFiles,omitempty"`
 	// EnableHooks enables helm hooks when executing the `helm template` command.
 	EnableHooks bool `json:"enableHooks,omitempty" yaml:"enableHooks,omitempty"`
 	// Namespace represents the helm namespace flag
@@ -130,6 +134,17 @@ type Helm struct {
 	KubeVersion string `json:"kubeVersion,omitempty" yaml:"kubeVersion,omitempty"`
 }
 
+// ValueFile represents one Helm value file produced from CUE.
+type ValueFile struct {
+	// Name represents the file name, e.g. "region-values.yaml"
+	Name string `json:"name" yaml:"name"`
+	// Kind is a discriminator.
+	Kind string `json:"kind" yaml:"kind" cue:"\"Values\""`
+	// Values represents values for holos to marshal into the file name specified
+	// by Name when rendering the chart.
+	Values Values `json:"values,omitempty" yaml:"values,omitempty"`
+}
+
 // Values represents [Helm] Chart values generated from CUE.
 type Values map[string]any
 
@@ -263,7 +278,7 @@ type Metadata struct {
 	// Labels represents a resource selector.
 	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
 	// Annotations represents arbitrary non-identifying metadata.  For example
-	// holos uses the `cli.holos.run/description` annotation to log resources in a
+	// holos uses the `app.holos.run/description` annotation to log resources in a
 	// user customized way.
 	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
@@ -320,7 +335,7 @@ type Component struct {
 	// resulting BuildPlan.
 	Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
 	// Annotations represents arbitrary non-identifying metadata.  Use the
-	// `cli.holos.run/description` to customize the log message of each BuildPlan.
+	// `app.holos.run/description` to customize the log message of each BuildPlan.
 	Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
 

doc/md/api/author.md

@@ -86,6 +86,9 @@ type Helm struct {
     Chart core.Chart
     // Values represents data to marshal into a values.yaml for helm.
     Values core.Values
+    // ValueFiles represents value files for migration from helm value
+    // hierarchies.  Use Values instead.
+    ValueFiles []core.ValueFile `json:",omitempty"`
     // EnableHooks enables helm hooks when executing the `helm template` command.
     EnableHooks bool `cue:"true | *false"`
     // Namespace sets the helm chart namespace flag if provided.

doc/md/api/core.md

@@ -43,6 +43,7 @@ Package core contains schemas for a [Platform](<#Platform>) and [BuildPlan](<#Bu
 - [type Resources](<#Resources>)
 - [type Transformer](<#Transformer>)
 - [type Validator](<#Validator>)
+- [type ValueFile](<#ValueFile>)
 - [type Values](<#Values>)
 
 
@@ -188,7 +189,7 @@ type Component struct {
     // resulting BuildPlan.
     Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
     // Annotations represents arbitrary non-identifying metadata.  Use the
-    // `cli.holos.run/description` to customize the log message of each BuildPlan.
+    // `app.holos.run/description` to customize the log message of each BuildPlan.
     Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
 ```
@@ -283,8 +284,12 @@ type Helm struct {
     // Chart represents a helm chart to manage.
     Chart Chart `json:"chart" yaml:"chart"`
     // Values represents values for holos to marshal into values.yaml when
-    // rendering the chart.
+    // rendering the chart.  Values follow ValueFiles when both are provided.
     Values Values `json:"values" yaml:"values"`
+    // ValueFiles represents hierarchial value files passed in order to the helm
+    // template -f flag.  Useful for migration from an ApplicationSet.  Use Values
+    // instead.  ValueFiles precede Values when both are provided.
+    ValueFiles []ValueFile `json:"valueFiles,omitempty" yaml:"valueFiles,omitempty"`
     // EnableHooks enables helm hooks when executing the `helm template` command.
     EnableHooks bool `json:"enableHooks,omitempty" yaml:"enableHooks,omitempty"`
     // Namespace represents the helm namespace flag
@@ -376,7 +381,7 @@ type Metadata struct {
     // Labels represents a resource selector.
     Labels map[string]string `json:"labels,omitempty" yaml:"labels,omitempty"`
     // Annotations represents arbitrary non-identifying metadata.  For example
-    // holos uses the `cli.holos.run/description` annotation to log resources in a
+    // holos uses the `app.holos.run/description` annotation to log resources in a
     // user customized way.
     Annotations map[string]string `json:"annotations,omitempty" yaml:"annotations,omitempty"`
 }
@@ -493,6 +498,23 @@ type Validator struct {
 }
 ```
 
+<a name="ValueFile"></a>
+## type ValueFile {#ValueFile}
+
+ValueFile represents one Helm value file produced from CUE.
+
+```go
+type ValueFile struct {
+    // Name represents the file name, e.g. "region-values.yaml"
+    Name string `json:"name" yaml:"name"`
+    // Kind is a discriminator.
+    Kind string `json:"kind" yaml:"kind" cue:"\"Values\""`
+    // Values represents values for holos to marshal into the file name specified
+    // by Name when rendering the chart.
+    Values Values `json:"values,omitempty" yaml:"values,omitempty"`
+}
+```
+
 <a name="Values"></a>
 ## type Values {#Values}
 

doc/md/topics/kargo.mdx

@@ -1,20 +0,0 @@
----
-description: Kargo
-slug: kargo
-sidebar_position: 110
----
-
-# Kargo
-
-Holos pairs nicely with [Kargo], offering a holistic solution for code
-promotion across stages.
-
-Watch this space for a more detailed write up of the integration being
-developed.
-
-If you're interested in this topic, please thumbs up the [Kargo
-Topic](https://github.com/holos-run/holos/issues/378) issue, or drop into
-[Discord] and let us know about your use case.
-
-[Kargo]: https://kargo.io/
-[Discord]: https://discord.gg/JgDVbNpye7

doc/md/topics/progressive-delivery/.gitignore

@@ -0,0 +1,2 @@
+kargo-demo/
+.tmp/

doc/md/topics/progressive-delivery/_platform-components/examples/01-clone.txtar

@@ -0,0 +1,17 @@
+env GH_USER=holos-run
+# Remove the directory if it already exists
+exec rm -rf kargo-demo
+# Clone your fork of the kargo-demo repository
+exec bash -c 'bash -euo pipefail command.sh 2>&1'
+cmp stdout output.txt
+
+# Get the git commit
+cd kargo-demo
+exec git rev-parse --verify origin/HEAD
+cp stdout $WORK/git.commit
+
+-- command.sh --
+git clone https://github.com/${GH_USER}/kargo-demo.git
+cd kargo-demo
+-- output.txt --
+Cloning into 'kargo-demo'...

doc/md/topics/progressive-delivery/_platform-components/examples/10-cert-manager.txtar

@@ -0,0 +1,37 @@
+env GH_USER=jeffmccune
+cd ../script-01-clone/kargo-demo
+
+## Walk the reader from entrypoint to the deployment pipeline
+# holos render platform entrypoint
+exec bash -c 'cat $(<$WORK/entrypoint.path)'
+cp stdout $WORK/entrypoint.txt
+exec bash -c 'basename $(<$WORK/entrypoint.path)'
+cp stdout $WORK/entrypoint.basename
+
+# platform.stacks location
+exec bash -c 'cat $(<$WORK/stacks.path)'
+cp stdout $WORK/stacks.txt
+exec bash -c 'basename $(<$WORK/stacks.path)'
+cp stdout $WORK/stacks.basename
+
+# certmanager.config location
+exec bash -c 'cat $(<$WORK/config.path)'
+cp stdout $WORK/config.txt
+exec bash -c 'basename $(<$WORK/config.path)'
+cp stdout $WORK/config.basename
+
+# Cert Manager Component.
+exec bash -c 'cat $(<$WORK/component.path)'
+cp stdout $WORK/component.txt
+# Get the path basename for the docs.
+exec bash -c 'basename $(<$WORK/component.path)'
+cp stdout $WORK/component.basename
+
+-- config.path --
+config/certmanager/certmanager.cue
+-- stacks.path --
+config/platform/security.cue
+-- entrypoint.path --
+platform/stacks.cue
+-- component.path --
+stacks/security/components/cert-manager/cert-manager.cue

doc/md/topics/progressive-delivery/_platform-components/examples/20-holos-version.txtar

@@ -0,0 +1,8 @@
+cd ../script-01-clone/kargo-demo
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.102.3

doc/md/topics/progressive-delivery/_platform-components/examples/30-git-url.txtar

@@ -0,0 +1,56 @@
+env GH_USER=jeffmccune
+env HOME=$WORK/.tmp
+cd ../script-01-clone/kargo-demo
+chmod 0755 $WORK/update.sh
+
+# Combine the steps separated in the doc.
+exec cat $WORK/header.sh $WORK/body.txt $WORK/trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+cmp config/platform/organization_$GH_USER.cue $WORK/code.want.cue
+
+# Render the platform
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/output.txt
+
+# Get the diff
+exec bash -c 'bash -euo pipefail $WORK/diff.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/diff.patch
+
+# Set the author
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+
+# Make the commit
+exec bash -c 'bash -euo pipefail $WORK/commit.sh 2>&1'
+stdin stdout
+exec $WORK/update.sh $WORK/commit.txt
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- header.sh --
+cat <<EOF > config/platform/organization_${GH_USER}.cue
+-- body.txt --
+@if(${GH_USER})
+package platform
+
+organization: repoURL: "https://github.com/${GH_USER}/kargo-demo.git"
+-- trailer.sh --
+EOF
+-- code.want.cue --
+@if(jeffmccune)
+package platform
+
+organization: repoURL: "https://github.com/jeffmccune/kargo-demo.git"
+-- command.sh --
+holos render platform -t ${GH_USER}
+-- commit.sh --
+git add .
+git commit -m "Switch to $GH_USER fork"
+-- diff.sh --
+git diff

doc/md/topics/progressive-delivery/_platform-components/script-01-clone/command.sh

@@ -0,0 +1,2 @@
+git clone https://github.com/${GH_USER}/kargo-demo.git
+cd kargo-demo

doc/md/topics/progressive-delivery/_platform-components/script-01-clone/git.commit

@@ -0,0 +1 @@
+238fe0403c99eeea4f4fb764a88b780554048414

doc/md/topics/progressive-delivery/_platform-components/script-01-clone/output.txt

@@ -0,0 +1 @@
+Cloning into 'kargo-demo'...

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.basename

@@ -0,0 +1 @@
+cert-manager.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.path

@@ -0,0 +1 @@
+stacks/security/components/cert-manager/cert-manager.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.txt

@@ -0,0 +1,21 @@
+package holos
+
+import "holos.example/config/certmanager"
+
+// Produce a helm chart build plan.
+holos: Component.BuildPlan
+
+Component: #Helm & {
+	Name:      "cert-manager"
+	Namespace: certmanager.config.namespace
+	Chart:     certmanager.config.chart
+
+	EnableHooks: true
+
+	Values: #Values & {
+		crds: enabled:            true
+		startupapicheck: enabled: false
+		// https://github.com/cert-manager/cert-manager/issues/6716
+		global: leaderElection: namespace: Namespace
+	}
+}

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.basename

@@ -0,0 +1 @@
+certmanager.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.path

@@ -0,0 +1 @@
+config/certmanager/certmanager.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.txt

@@ -0,0 +1,30 @@
+@extern(embed)
+package certmanager
+
+import "github.com/holos-run/holos/api/core/v1alpha5:core"
+
+// Unify data from yaml for Kargo integration.
+_data: _ @embed(file=cert-manager.yaml)
+
+config: #Config & {
+	namespace: "cert-manager"
+	// datafile value must align to the embed file directive above for proper
+	// configuration of Kargo promotion stages.
+	datafile: "./config/certmanager/cert-manager.yaml"
+	chart: {
+		name:    "cert-manager"
+		version: _data.chart.version
+		repository: {
+			name: "jetstack"
+			url:  "https://charts.jetstack.io"
+		}
+	}
+}
+
+#Config: {
+	namespace: string
+	datafile:  string
+	chart: core.#Chart & {
+		version: =~"^v{0,1}[0-9]+\\.[0-9]+\\.[0-9]+$"
+	}
+}

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.basename

@@ -0,0 +1 @@
+stacks.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.path

@@ -0,0 +1 @@
+platform/stacks.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.txt

@@ -0,0 +1,8 @@
+package main
+
+import "holos.example/config/platform"
+
+// Register all stack components with the platform spec.
+for STACK in platform.stacks {
+	Platform: Components: STACK.components
+}

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.basename

@@ -0,0 +1 @@
+security.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.path

@@ -0,0 +1 @@
+config/platform/security.cue

doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.txt

@@ -0,0 +1,46 @@
+package platform
+
+import "holos.example/config/certmanager"
+
+stacks: security: (#StackBuilder & {
+	(#PromoterBuilder & {parameters: {
+		name: "cert-manager"
+		config: {
+			datafile: certmanager.config.datafile
+			chart:    certmanager.config.chart
+		}
+	}}).promoter
+
+	// Manage the external-secrets namespace.
+	stack: namespaces: "external-secrets": _
+
+	parameters: {
+		name: "security"
+		components: {
+			namespaces: {
+				path: "stacks/security/components/namespaces"
+				annotations: description: "configures namespaces for all stacks"
+			}
+			"external-secrets-crds": {
+				path: "stacks/security/components/external-secrets-crds"
+				annotations: description: "external secrets custom resource definitions"
+			}
+			"external-secrets": {
+				path: "stacks/security/components/external-secrets"
+				annotations: description: "external secrets custom resource definitions"
+			}
+			"cert-manager": {
+				path: "stacks/security/components/cert-manager"
+				annotations: description: "cert-manager operator and custom resource definitions"
+				parameters: {
+					kargoProject: "cert-manager"
+					kargoStage:   "main"
+				}
+			}
+			"local-ca": {
+				path: "stacks/security/components/local-ca"
+				annotations: description: "localhost mkcert certificate authority"
+			}
+		}
+	}
+}).stack

doc/md/topics/progressive-delivery/_platform-components/script-20-holos-version/command.sh

@@ -0,0 +1 @@
+holos --version

doc/md/topics/progressive-delivery/_platform-components/script-20-holos-version/output.txt

@@ -0,0 +1 @@
+0.102.3

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/body.txt

@@ -0,0 +1,4 @@
+@if(${GH_USER})
+package platform
+
+organization: repoURL: "https://github.com/${GH_USER}/kargo-demo.git"

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/code.want.cue

@@ -0,0 +1,4 @@
+@if(jeffmccune)
+package platform
+
+organization: repoURL: "https://github.com/jeffmccune/kargo-demo.git"

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/command.sh

@@ -0,0 +1 @@
+holos render platform -t ${GH_USER}

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/commit.sh

@@ -0,0 +1,2 @@
+git add .
+git commit -m "Switch to $GH_USER fork"

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/commit.txt

@@ -0,0 +1,3 @@
+[main b883807] Switch to jeffmccune fork
+ 43 files changed, 70 insertions(+), 66 deletions(-)
+ create mode 100644 config/platform/organization_jeffmccune.cue

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/diff.patch

@@ -0,0 +1,686 @@
+diff --git a/deploy/components/cert-manager-promoter/cert-manager-promoter.gen.yaml b/deploy/components/cert-manager-promoter/cert-manager-promoter.gen.yaml
+index 55a6a49..ab483d5 100644
+--- a/deploy/components/cert-manager-promoter/cert-manager-promoter.gen.yaml
++++ b/deploy/components/cert-manager-promoter/cert-manager-promoter.gen.yaml
+@@ -28,7 +28,7 @@ spec:
+           checkout:
+           - branch: main
+             path: ./src
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - as: update
+         config:
+@@ -51,7 +51,7 @@ spec:
+         uses: git-push
+       - as: pull
+         config:
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+           sourceBranch: ${{ outputs.push.branch }}
+           targetBranch: main
+         uses: git-open-pr
+diff --git a/deploy/components/kargo-promoter/kargo-promoter.gen.yaml b/deploy/components/kargo-promoter/kargo-promoter.gen.yaml
+index 87e4bfd..a2eb91d 100644
+--- a/deploy/components/kargo-promoter/kargo-promoter.gen.yaml
++++ b/deploy/components/kargo-promoter/kargo-promoter.gen.yaml
+@@ -28,7 +28,7 @@ spec:
+           checkout:
+           - branch: main
+             path: ./src
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - as: update
+         config:
+@@ -51,7 +51,7 @@ spec:
+         uses: git-push
+       - as: pull
+         config:
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+           sourceBranch: ${{ outputs.push.branch }}
+           targetBranch: main
+         uses: git-open-pr
+diff --git a/deploy/gitops/app-projects.application.gen.yaml b/deploy/gitops/app-projects.application.gen.yaml
+index a98a52e..a58f7fb 100644
+--- a/deploy/gitops/app-projects.application.gen.yaml
++++ b/deploy/gitops/app-projects.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/app-projects
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/argocd-crds.application.gen.yaml b/deploy/gitops/argocd-crds.application.gen.yaml
+index 6aba002..4ce8835 100644
+--- a/deploy/gitops/argocd-crds.application.gen.yaml
++++ b/deploy/gitops/argocd-crds.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/argocd-crds
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/argocd-secrets.application.gen.yaml b/deploy/gitops/argocd-secrets.application.gen.yaml
+index 245fb00..0a5b79d 100644
+--- a/deploy/gitops/argocd-secrets.application.gen.yaml
++++ b/deploy/gitops/argocd-secrets.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/argocd-secrets
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/argocd.application.gen.yaml b/deploy/gitops/argocd.application.gen.yaml
+index 764a55f..6c4cfad 100644
+--- a/deploy/gitops/argocd.application.gen.yaml
++++ b/deploy/gitops/argocd.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/argocd
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/cert-manager-promoter.application.gen.yaml b/deploy/gitops/cert-manager-promoter.application.gen.yaml
+index c28bb66..a98c0ef 100644
+--- a/deploy/gitops/cert-manager-promoter.application.gen.yaml
++++ b/deploy/gitops/cert-manager-promoter.application.gen.yaml
+@@ -16,5 +16,5 @@ spec:
+     project: security
+     source:
+         path: deploy/components/cert-manager-promoter
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/cert-manager.application.gen.yaml b/deploy/gitops/cert-manager.application.gen.yaml
+index 14e15f0..d6a24d3 100644
+--- a/deploy/gitops/cert-manager.application.gen.yaml
++++ b/deploy/gitops/cert-manager.application.gen.yaml
+@@ -12,5 +12,5 @@ spec:
+     project: security
+     source:
+         path: deploy/components/cert-manager
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/external-secrets-crds.application.gen.yaml b/deploy/gitops/external-secrets-crds.application.gen.yaml
+index 5515a52..c86bbf8 100644
+--- a/deploy/gitops/external-secrets-crds.application.gen.yaml
++++ b/deploy/gitops/external-secrets-crds.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: security
+     source:
+         path: deploy/components/external-secrets-crds
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/external-secrets.application.gen.yaml b/deploy/gitops/external-secrets.application.gen.yaml
+index b1b2434..a1a90d2 100644
+--- a/deploy/gitops/external-secrets.application.gen.yaml
++++ b/deploy/gitops/external-secrets.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: security
+     source:
+         path: deploy/components/external-secrets
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/gateway-api.application.gen.yaml b/deploy/gitops/gateway-api.application.gen.yaml
+index a567685..1209068 100644
+--- a/deploy/gitops/gateway-api.application.gen.yaml
++++ b/deploy/gitops/gateway-api.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/gateway-api
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/httproutes.application.gen.yaml b/deploy/gitops/httproutes.application.gen.yaml
+index 01e7eea..ba17725 100644
+--- a/deploy/gitops/httproutes.application.gen.yaml
++++ b/deploy/gitops/httproutes.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/httproutes
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/istio-base.application.gen.yaml b/deploy/gitops/istio-base.application.gen.yaml
+index 344bba2..32d4f4b 100644
+--- a/deploy/gitops/istio-base.application.gen.yaml
++++ b/deploy/gitops/istio-base.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/istio-base
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/istio-cni.application.gen.yaml b/deploy/gitops/istio-cni.application.gen.yaml
+index 478e7c4..5fdf222 100644
+--- a/deploy/gitops/istio-cni.application.gen.yaml
++++ b/deploy/gitops/istio-cni.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/istio-cni
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/istio-gateway.application.gen.yaml b/deploy/gitops/istio-gateway.application.gen.yaml
+index 9561e06..0267f9b 100644
+--- a/deploy/gitops/istio-gateway.application.gen.yaml
++++ b/deploy/gitops/istio-gateway.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/istio-gateway
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/istio-ztunnel.application.gen.yaml b/deploy/gitops/istio-ztunnel.application.gen.yaml
+index a6da24e..ac21566 100644
+--- a/deploy/gitops/istio-ztunnel.application.gen.yaml
++++ b/deploy/gitops/istio-ztunnel.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/istio-ztunnel
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/istiod.application.gen.yaml b/deploy/gitops/istiod.application.gen.yaml
+index 57d3fdc..a09c8b9 100644
+--- a/deploy/gitops/istiod.application.gen.yaml
++++ b/deploy/gitops/istiod.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: network
+     source:
+         path: deploy/components/istiod
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/kargo-promoter.application.gen.yaml b/deploy/gitops/kargo-promoter.application.gen.yaml
+index 079ee37..f6db555 100644
+--- a/deploy/gitops/kargo-promoter.application.gen.yaml
++++ b/deploy/gitops/kargo-promoter.application.gen.yaml
+@@ -16,5 +16,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/kargo-promoter
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/kargo-secrets.application.gen.yaml b/deploy/gitops/kargo-secrets.application.gen.yaml
+index c1d048b..308560d 100644
+--- a/deploy/gitops/kargo-secrets.application.gen.yaml
++++ b/deploy/gitops/kargo-secrets.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/kargo-secrets
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/kargo.application.gen.yaml b/deploy/gitops/kargo.application.gen.yaml
+index 22408e1..04f92fc 100644
+--- a/deploy/gitops/kargo.application.gen.yaml
++++ b/deploy/gitops/kargo.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/kargo
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/local-ca.application.gen.yaml b/deploy/gitops/local-ca.application.gen.yaml
+index 38901f2..16caa18 100644
+--- a/deploy/gitops/local-ca.application.gen.yaml
++++ b/deploy/gitops/local-ca.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: security
+     source:
+         path: deploy/components/local-ca
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/namespaces.application.gen.yaml b/deploy/gitops/namespaces.application.gen.yaml
+index e35f41c..2fd01a8 100644
+--- a/deploy/gitops/namespaces.application.gen.yaml
++++ b/deploy/gitops/namespaces.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: security
+     source:
+         path: deploy/components/namespaces
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/rollouts-crds.application.gen.yaml b/deploy/gitops/rollouts-crds.application.gen.yaml
+index 221cb50..761a823 100644
+--- a/deploy/gitops/rollouts-crds.application.gen.yaml
++++ b/deploy/gitops/rollouts-crds.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/rollouts-crds
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/gitops/rollouts.application.gen.yaml b/deploy/gitops/rollouts.application.gen.yaml
+index f96f85c..d1fc696 100644
+--- a/deploy/gitops/rollouts.application.gen.yaml
++++ b/deploy/gitops/rollouts.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: argocd
+     source:
+         path: deploy/components/rollouts
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/projects/httpbin/components/kargo-stages/kargo-stages.gen.yaml b/deploy/projects/httpbin/components/kargo-stages/kargo-stages.gen.yaml
+index 815f6a3..bbf1f89 100644
+--- a/deploy/projects/httpbin/components/kargo-stages/kargo-stages.gen.yaml
++++ b/deploy/projects/httpbin/components/kargo-stages/kargo-stages.gen.yaml
+@@ -16,7 +16,7 @@ spec:
+           - branch: project/httpbin/component/dev-httpbin
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -46,7 +46,7 @@ spec:
+           - name: httpbin-dev-httpbin
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -73,7 +73,7 @@ spec:
+           - branch: project/httpbin/component/prod-us-central-httpbin
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -103,7 +103,7 @@ spec:
+           - name: httpbin-prod-us-central-httpbin
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -131,7 +131,7 @@ spec:
+           - branch: project/httpbin/component/prod-us-east-httpbin
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -161,7 +161,7 @@ spec:
+           - name: httpbin-prod-us-east-httpbin
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -189,7 +189,7 @@ spec:
+           - branch: project/httpbin/component/prod-us-west-httpbin
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -219,7 +219,7 @@ spec:
+           - name: httpbin-prod-us-west-httpbin
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -247,7 +247,7 @@ spec:
+           - branch: project/httpbin/component/test-httpbin
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -277,7 +277,7 @@ spec:
+           - name: httpbin-test-httpbin
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -305,7 +305,7 @@ spec:
+           - branch: project/httpbin/component/uat-httpbin
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -335,7 +335,7 @@ spec:
+           - name: httpbin-uat-httpbin
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+diff --git a/deploy/projects/httpbin/gitops/dev-httpbin.application.gen.yaml b/deploy/projects/httpbin/gitops/dev-httpbin.application.gen.yaml
+index 03136e0..8b207ff 100644
+--- a/deploy/projects/httpbin/gitops/dev-httpbin.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/dev-httpbin.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: httpbin
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/httpbin/component/dev-httpbin
+diff --git a/deploy/projects/httpbin/gitops/kargo-project.application.gen.yaml b/deploy/projects/httpbin/gitops/kargo-project.application.gen.yaml
+index 9e666a7..07ebce2 100644
+--- a/deploy/projects/httpbin/gitops/kargo-project.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/kargo-project.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: httpbin
+     source:
+         path: deploy/projects/httpbin/components/kargo-project
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/projects/httpbin/gitops/kargo-stages.application.gen.yaml b/deploy/projects/httpbin/gitops/kargo-stages.application.gen.yaml
+index df82b81..157a1e0 100644
+--- a/deploy/projects/httpbin/gitops/kargo-stages.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/kargo-stages.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: httpbin
+     source:
+         path: deploy/projects/httpbin/components/kargo-stages
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/projects/httpbin/gitops/prod-us-central-httpbin.application.gen.yaml b/deploy/projects/httpbin/gitops/prod-us-central-httpbin.application.gen.yaml
+index d3eb9ee..3e5e8b3 100644
+--- a/deploy/projects/httpbin/gitops/prod-us-central-httpbin.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/prod-us-central-httpbin.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: httpbin
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/httpbin/component/prod-us-central-httpbin
+diff --git a/deploy/projects/httpbin/gitops/prod-us-east-httpbin.application.gen.yaml b/deploy/projects/httpbin/gitops/prod-us-east-httpbin.application.gen.yaml
+index 2d768f4..e43d1f6 100644
+--- a/deploy/projects/httpbin/gitops/prod-us-east-httpbin.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/prod-us-east-httpbin.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: httpbin
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/httpbin/component/prod-us-east-httpbin
+diff --git a/deploy/projects/httpbin/gitops/prod-us-west-httpbin.application.gen.yaml b/deploy/projects/httpbin/gitops/prod-us-west-httpbin.application.gen.yaml
+index 8903303..a7012b0 100644
+--- a/deploy/projects/httpbin/gitops/prod-us-west-httpbin.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/prod-us-west-httpbin.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: httpbin
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/httpbin/component/prod-us-west-httpbin
+diff --git a/deploy/projects/httpbin/gitops/test-httpbin.application.gen.yaml b/deploy/projects/httpbin/gitops/test-httpbin.application.gen.yaml
+index 5426c31..296e3ed 100644
+--- a/deploy/projects/httpbin/gitops/test-httpbin.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/test-httpbin.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: httpbin
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/httpbin/component/test-httpbin
+diff --git a/deploy/projects/httpbin/gitops/uat-httpbin.application.gen.yaml b/deploy/projects/httpbin/gitops/uat-httpbin.application.gen.yaml
+index 717e608..264d1c4 100644
+--- a/deploy/projects/httpbin/gitops/uat-httpbin.application.gen.yaml
++++ b/deploy/projects/httpbin/gitops/uat-httpbin.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: httpbin
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/httpbin/component/uat-httpbin
+diff --git a/deploy/projects/podinfo/components/kargo-stages/kargo-stages.gen.yaml b/deploy/projects/podinfo/components/kargo-stages/kargo-stages.gen.yaml
+index 1107e34..2ebbbd1 100644
+--- a/deploy/projects/podinfo/components/kargo-stages/kargo-stages.gen.yaml
++++ b/deploy/projects/podinfo/components/kargo-stages/kargo-stages.gen.yaml
+@@ -16,7 +16,7 @@ spec:
+           - branch: project/podinfo/component/dev-podinfo
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -46,7 +46,7 @@ spec:
+           - name: podinfo-dev-podinfo
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -73,7 +73,7 @@ spec:
+           - branch: project/podinfo/component/prod-us-central-podinfo
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -103,7 +103,7 @@ spec:
+           - name: podinfo-prod-us-central-podinfo
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -131,7 +131,7 @@ spec:
+           - branch: project/podinfo/component/prod-us-east-podinfo
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -161,7 +161,7 @@ spec:
+           - name: podinfo-prod-us-east-podinfo
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -189,7 +189,7 @@ spec:
+           - branch: project/podinfo/component/prod-us-west-podinfo
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -219,7 +219,7 @@ spec:
+           - name: podinfo-prod-us-west-podinfo
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -247,7 +247,7 @@ spec:
+           - branch: project/podinfo/component/test-podinfo
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -277,7 +277,7 @@ spec:
+           - name: podinfo-test-podinfo
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+@@ -305,7 +305,7 @@ spec:
+           - branch: project/podinfo/component/uat-podinfo
+             create: true
+             path: ./out
+-          repoURL: https://github.com/holos-run/kargo-demo.git
++          repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: git-clone
+       - config:
+           path: ./out
+@@ -335,7 +335,7 @@ spec:
+           - name: podinfo-uat-podinfo
+             sources:
+             - desiredCommitFromStep: commit
+-              repoURL: https://github.com/holos-run/kargo-demo.git
++              repoURL: https://github.com/jeffmccune/kargo-demo.git
+         uses: argocd-update
+   requestedFreight:
+   - origin:
+diff --git a/deploy/projects/podinfo/gitops/dev-podinfo.application.gen.yaml b/deploy/projects/podinfo/gitops/dev-podinfo.application.gen.yaml
+index 9b3108e..9ac4849 100644
+--- a/deploy/projects/podinfo/gitops/dev-podinfo.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/dev-podinfo.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: podinfo
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/podinfo/component/dev-podinfo
+diff --git a/deploy/projects/podinfo/gitops/kargo-project.application.gen.yaml b/deploy/projects/podinfo/gitops/kargo-project.application.gen.yaml
+index 3878efa..ab934d5 100644
+--- a/deploy/projects/podinfo/gitops/kargo-project.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/kargo-project.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: podinfo
+     source:
+         path: deploy/projects/podinfo/components/kargo-project
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/projects/podinfo/gitops/kargo-stages.application.gen.yaml b/deploy/projects/podinfo/gitops/kargo-stages.application.gen.yaml
+index 0d4ade7..1b5eb9f 100644
+--- a/deploy/projects/podinfo/gitops/kargo-stages.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/kargo-stages.application.gen.yaml
+@@ -10,5 +10,5 @@ spec:
+     project: podinfo
+     source:
+         path: deploy/projects/podinfo/components/kargo-stages
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: main
+diff --git a/deploy/projects/podinfo/gitops/prod-us-central-podinfo.application.gen.yaml b/deploy/projects/podinfo/gitops/prod-us-central-podinfo.application.gen.yaml
+index 59b3f98..182a3c9 100644
+--- a/deploy/projects/podinfo/gitops/prod-us-central-podinfo.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/prod-us-central-podinfo.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: podinfo
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/podinfo/component/prod-us-central-podinfo
+diff --git a/deploy/projects/podinfo/gitops/prod-us-east-podinfo.application.gen.yaml b/deploy/projects/podinfo/gitops/prod-us-east-podinfo.application.gen.yaml
+index 0165d40..6101a9b 100644
+--- a/deploy/projects/podinfo/gitops/prod-us-east-podinfo.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/prod-us-east-podinfo.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: podinfo
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/podinfo/component/prod-us-east-podinfo
+diff --git a/deploy/projects/podinfo/gitops/prod-us-west-podinfo.application.gen.yaml b/deploy/projects/podinfo/gitops/prod-us-west-podinfo.application.gen.yaml
+index 3422981..88b7409 100644
+--- a/deploy/projects/podinfo/gitops/prod-us-west-podinfo.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/prod-us-west-podinfo.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: podinfo
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/podinfo/component/prod-us-west-podinfo
+diff --git a/deploy/projects/podinfo/gitops/test-podinfo.application.gen.yaml b/deploy/projects/podinfo/gitops/test-podinfo.application.gen.yaml
+index 7ca895f..c3c32a1 100644
+--- a/deploy/projects/podinfo/gitops/test-podinfo.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/test-podinfo.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: podinfo
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/podinfo/component/test-podinfo
+diff --git a/deploy/projects/podinfo/gitops/uat-podinfo.application.gen.yaml b/deploy/projects/podinfo/gitops/uat-podinfo.application.gen.yaml
+index cb28add..63cf194 100644
+--- a/deploy/projects/podinfo/gitops/uat-podinfo.application.gen.yaml
++++ b/deploy/projects/podinfo/gitops/uat-podinfo.application.gen.yaml
+@@ -14,5 +14,5 @@ spec:
+     project: podinfo
+     source:
+         path: ./
+-        repoURL: https://github.com/holos-run/kargo-demo.git
++        repoURL: https://github.com/jeffmccune/kargo-demo.git
+         targetRevision: project/podinfo/component/uat-podinfo

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/diff.sh

@@ -0,0 +1 @@
+git diff

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/header.sh

@@ -0,0 +1 @@
+cat <<EOF > config/platform/organization_${GH_USER}.cue

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/output.txt

@@ -0,0 +1,47 @@
+rendered kargo-project for project podinfo in 438.04325ms
+rendered kargo-promoter for stack argocd in 440.84075ms
+rendered kargo-secrets for stack argocd in 441.76175ms
+rendered rollouts for stack argocd in 441.989625ms
+rendered kargo-project for project httpbin in 444.166291ms
+rendered kargo-stages for project httpbin in 446.7485ms
+rendered kargo-stages for project podinfo in 446.739792ms
+rendered argocd-secrets for stack argocd in 448.0085ms
+rendered app-projects for stack argocd in 449.610209ms
+rendered gateway-api for stack network in 597.720375ms
+rendered istio-gateway for stack network in 248.44325ms
+rendered rollouts-crds for stack argocd in 885.346417ms
+rendered namespaces for stack security in 478.418ms
+rendered local-ca for stack security in 244.84025ms
+rendered argocd-crds for stack argocd in 991.27875ms
+rendered external-secrets-crds for stack security in 686.799417ms
+rendered istio-cni for stack network in 748.069458ms
+rendered istio-ztunnel for stack network in 762.896542ms
+rendered test-httpbin for project httpbin in 318.5385ms
+rendered cert-manager-promoter for stack security in 481.661833ms
+rendered dev-httpbin for project httpbin in 465.202083ms
+Pulled: ghcr.io/akuity/kargo-charts/kargo:1.1.1
+Digest: sha256:4055c72418db85b85979da2fe12136c0e275709efc2e36a505b158e8234ad443
+rendered kargo for stack argocd in 1.396269208s
+rendered istiod for stack network in 997.264208ms
+rendered external-secrets for stack security in 996.459042ms
+rendered uat-httpbin for project httpbin in 517.124875ms
+rendered prod-us-central-httpbin for project httpbin in 344.330875ms
+rendered prod-us-east-httpbin for project httpbin in 449.991417ms
+rendered prod-us-west-httpbin for project httpbin in 411.234333ms
+rendered argocd for stack argocd in 1.631300708s
+rendered istio-base for stack network in 1.203177s
+rendered cert-manager for stack security in 1.127040208s
+rendered httproutes for stack network in 1.556993875s
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.7.0
+Digest: sha256:104d101017e501c63b3aa71b20d5edd2ca6d5d58cbc57ff8163770110f92b9db
+rendered dev-podinfo for project podinfo in 1.010673334s
+rendered test-podinfo for project podinfo in 945.39075ms
+rendered prod-us-west-podinfo for project podinfo in 897.117125ms
+rendered uat-podinfo for project podinfo in 1.022036209s
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.2
+Digest: sha256:83295d47de6d6ca634ed4b952a7572fc176bcc38854d0c11ca0fa197bc5f1154
+rendered prod-us-central-podinfo for project podinfo in 977.250667ms
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.1
+Digest: sha256:0cc9a8446c95009ef382f5eade883a67c257f77d50f84e78ecef2aac9428d1e5
+rendered prod-us-east-podinfo for project podinfo in 1.071360916s
+rendered platform in 2.467827834s

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/topics/progressive-delivery/_platform-components/tour/tour.txtar

@@ -0,0 +1,8 @@
+cd ../script-setup/kargo-demo
+# Execute the example capture stdout and stderr to one file.
+exec bash -c 'bash -euo pipefail $WORK/tree.sh 2>&1'
+# Copy standard output to a file to embed in the docs.
+cp stdout $WORK/tree.txt
+
+-- tree.sh --
+tree -L3 -d platform stacks config

doc/md/topics/progressive-delivery/docs_test.go

@@ -0,0 +1,87 @@
+package kargo
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/holos-run/holos/cmd"
+	"github.com/rogpeppe/go-internal/testscript"
+
+	cue "cuelang.org/go/cmd/cue/cmd"
+)
+
+func TestMain(m *testing.M) {
+	os.Exit(testscript.RunMain(m, map[string]func() int{
+		"holos": cmd.MakeMain(),
+		"cue":   cue.Main,
+	}))
+}
+
+// Run these with go test -v to see the verbose names
+func TestKargo(t *testing.T) {
+	t.Run("AddOnPromoter", func(t *testing.T) {
+		// Get an ordered list of test script files.
+		dir := "_platform-components"
+		for _, file := range sortedTestScripts(t, filepath.Join(dir, "examples")) {
+			t.Run("examples", func(t *testing.T) {
+				runOneScript(t, dir, file)
+			})
+		}
+	})
+}
+
+func runOneScript(t *testing.T, dir string, file string) {
+	params := testscript.Params{
+		Dir:                 "",
+		Files:               []string{file},
+		RequireExplicitExec: true,
+		RequireUniqueNames:  false,
+		WorkdirRoot:         filepath.Join(testDir(t), dir),
+		UpdateScripts:       os.Getenv("HOLOS_UPDATE_SCRIPTS") != "",
+		Setup: func(env *testscript.Env) error {
+			// Needed for update.sh to determine if we need to update output files.
+			env.Setenv("HOLOS_UPDATE_SCRIPTS", os.Getenv("HOLOS_UPDATE_SCRIPTS"))
+			// Just like cmd/cue/cmd.TestScript, set up separate cache and config dirs per test.
+			env.Setenv("CUE_CACHE_DIR", filepath.Join(env.WorkDir, "tmp/cachedir"))
+			configDir := filepath.Join(env.WorkDir, "tmp/configdir")
+			env.Setenv("CUE_CONFIG_DIR", configDir)
+			return nil
+		},
+	}
+
+	testscript.Run(t, params)
+}
+
+// testDir returns the path of the directory containing the go source file of
+// the caller.
+func testDir(t *testing.T) string {
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("could not get runtime caller")
+	}
+	return filepath.Dir(file)
+}
+
+func sortedTestScripts(t *testing.T, dir string) (files []string) {
+	entries, err := os.ReadDir(dir)
+	if os.IsNotExist(err) {
+		// Continue to helpful error on len(files) == 0 below.
+	} else if err != nil {
+		t.Fatal(err)
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		if strings.HasSuffix(name, ".txtar") || strings.HasSuffix(name, ".txt") {
+			files = append(files, filepath.Join(dir, name))
+		}
+	}
+	if len(files) == 0 {
+		t.Fatalf("no txtar nor txt scripts found in dir %s", dir)
+	}
+	slices.Sort(files)
+	return files
+}

doc/md/topics/progressive-delivery/index.mdx

@@ -0,0 +1,40 @@
+---
+title: Progressive Delivery
+description: Learn how to manage progressive delivery pipelines with Holos.
+sidebar_position: 110
+---
+import DocCardList from '@theme/DocCardList';
+
+# Progressive Delivery
+
+Holos pairs nicely with [Kargo], offering a holistic way to manage the
+configuration of reusable progressive rollout deployment pipelines for Holos
+components.
+
+> Kargo is a next-generation continuous delivery and application lifecycle
+> orchestration platform for Kubernetes. It builds upon GitOps principles and
+> integrates with existing technologies, like Argo CD, to streamline and automate
+> the progressive rollout of changes across the many stages of an application's
+> lifecycle. ([ref](https://github.com/akuity/kargo#:~:text=Kargo%20is%20a%20next%2Dgeneration,stages%20of%20an%20application's%20lifecycle.))
+
+Two main use cases are addressed within this topic.
+
+1. **Platform Components**:  Platform operators want pull requests automatically
+opened when new versions of cluster add-ons are available so they can see
+upcoming changes clearly.
+2. **Workloads**: Product development teams want a well defined deployment
+pipeline to automatically and safely promote new features and bug fixes.  For
+example, from dev to test to staging, then across multiple production regions
+globally.
+
+:::tip
+Holos pairs well with Kargo to progressively deploy changes across multiple
+clusters.  Contact us for personalized [support] for your use case.
+:::
+
+---
+
+<DocCardList />
+
+[Kargo]: https://kargo.io/
+[support]: ../support.mdx

doc/md/topics/progressive-delivery/platform-components.mdx

@@ -0,0 +1,184 @@
+---
+description: Automatic pull requests for platform components.
+sidebar_position: 100
+---
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import ThemedImage from '@theme/ThemedImage';
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+# Platform Components
+
+## Overview
+
+We'll use Holos to configure Kargo to automatically watch for new versions of
+the Istio, cert-manager, and external-secrets cluster platform components.
+We'll learn how to define a reusable technique to mix-in the deployment pipeline
+to any other cluster add-ons, like Kargo and ArgoCD.
+
+<ThemedImage
+  alt="Pull Request summary for an available cert-manager update"
+  sources= {{
+    light: useBaseUrl('/img/kargo/add-on-promoter/kargo-pr-small.light.png'),
+    dark: useBaseUrl('/img/kargo/add-on-promoter/kargo-pr-small.dark.png'),
+  }}
+/>
+
+<ThemedImage
+  alt="Pull Request diff for an available cert-manager update"
+  sources= {{
+    light: useBaseUrl('/img/kargo/add-on-promoter/diff.light.png'),
+    dark: useBaseUrl('/img/kargo/add-on-promoter/diff.dark.png'),
+  }}
+/>
+
+## Setup
+
+First, [fork] the [kargo-demo] repository to your personal account.  Set your
+GitHub user name for use through the rest of this tutorial.
+
+```bash
+export GH_USER=<your username>
+```
+
+Clone your fork.  We'll run the rest of the commands from the root of the
+repository.
+
+import SetupCommand from '!!raw-loader!./_platform-components/script-01-clone/command.sh';
+import SetupOutput from '!!raw-loader!./_platform-components/script-01-clone/output.txt';
+
+<Tabs groupId="setup">
+  <TabItem value="command" label="Command">
+    <CodeBlock language="bash">{SetupCommand}</CodeBlock>
+  </TabItem>
+  <TabItem value="output" label="Output">
+    <CodeBlock language="txt">{SetupOutput}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+## Configuration Tour
+
+Let's review what happens when the `holos render platform` command renders the
+Kargo deployment pipeline configuration for `cert-manager`.
+
+import GitHubLink from '@site/src/components/GitHubLink';
+import GitCommit from '!!raw-loader!./_platform-components/script-01-clone/git.commit';
+
+import CertManagerEntrypointPath from '!!raw-loader!./_platform-components/script-10-cert-manager/entrypoint.path';
+import CertManagerEntrypointBaseName from '!!raw-loader!./_platform-components/script-10-cert-manager/entrypoint.basename';
+import CertManagerEntrypointCode from '!!raw-loader!./_platform-components/script-10-cert-manager/entrypoint.txt';
+
+import CertManagerStacksPath from '!!raw-loader!./_platform-components/script-10-cert-manager/stacks.path';
+import CertManagerStacksBaseName from '!!raw-loader!./_platform-components/script-10-cert-manager/stacks.basename';
+import CertManagerStacksCode from '!!raw-loader!./_platform-components/script-10-cert-manager/stacks.txt';
+
+import CertManagerComponentPath from '!!raw-loader!./_platform-components/script-10-cert-manager/component.path';
+import CertManagerComponentBaseName from '!!raw-loader!./_platform-components/script-10-cert-manager/component.basename';
+import CertManagerComponentCode from '!!raw-loader!./_platform-components/script-10-cert-manager/component.txt';
+
+import CertManagerConfigPath from '!!raw-loader!./_platform-components/script-10-cert-manager/config.path';
+import CertManagerConfigBaseName from '!!raw-loader!./_platform-components/script-10-cert-manager/config.basename';
+import CertManagerConfigCode from '!!raw-loader!./_platform-components/script-10-cert-manager/config.txt';
+
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={CertManagerEntrypointPath}>{CertManagerEntrypointPath}</GitHubLink> is the main entrypoint for the `holos render platform` command.  Each platform stack's components are composed into the Platform spec `holos` uses to render each component.
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={`${CertManagerStacksPath}#L32-L39`}>{CertManagerStacksBaseName}</GitHubLink> in the platform config package is where cert-manager is added to the platform as a holos component.
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={CertManagerComponentPath}>{CertManagerComponentBaseName}</GitHubLink> is the component definition.  The component imports the certmanager config package to get the chart version.
+1. <GitHubLink repo="holos-run/kargo-demo" tree={GitCommit} path={CertManagerConfigPath}>{CertManagerConfigBaseName}</GitHubLink> in the certmanager config package defines configuration imported by multiple components.  This file uses the CUE embed feature to load data from a yaml file in the same directory.  Kargo promotion steps update the cert manager version in this file.
+
+Cert Manager is managed as a Holos Component wrapping the official helm chart.
+See 
+
+<Tabs groupId="render-git-url">
+  <TabItem value="entrypoint" label={CertManagerEntrypointBaseName}>
+    <CodeBlock language="txt">{CertManagerEntrypointPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerEntrypointCode}</CodeBlock>
+  </TabItem>
+  <TabItem value="stacks" label={CertManagerStacksBaseName}>
+    <CodeBlock language="txt">{CertManagerStacksPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerStacksCode}</CodeBlock>
+  </TabItem>
+  <TabItem value="component" label={CertManagerComponentBaseName}>
+    <CodeBlock language="txt">{CertManagerComponentPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerComponentCode}</CodeBlock>
+  </TabItem>
+  <TabItem value="config" label={CertManagerConfigBaseName}>
+    <CodeBlock language="txt">{CertManagerConfigPath}</CodeBlock>
+    <CodeBlock language="cue">{CertManagerConfigCode}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+## Holos Version
+
+Ensure you have a current version of `holos` installed.  This document was
+tested with the following version.
+
+import HolosVersionCommand from '!!raw-loader!./_platform-components/script-20-holos-version/command.sh';
+import HolosVersionOutput from '!!raw-loader!./_platform-components/script-20-holos-version/output.txt';
+
+<CodeBlock language="bash">{HolosVersionCommand}</CodeBlock>
+<CodeBlock language="txt">{HolosVersionOutput}</CodeBlock>
+
+## Configure Git URL
+
+We need to configure gitops tools like ArgoCD and Kargo to use our fork instead
+of the upstream repository when reconciling changes and opening pull requests.
+
+Create the following file to configure your fork url.
+
+import GitURLHeader from '!!raw-loader!./_platform-components/script-30-git-url/header.sh';
+import GitURLBody from '!!raw-loader!./_platform-components/script-30-git-url/body.txt';
+import GitURLTrailer from '!!raw-loader!./_platform-components/script-30-git-url/trailer.sh';
+
+<CodeBlock language="bash">{GitURLHeader}</CodeBlock>
+<CodeBlock language="cue">{GitURLBody}</CodeBlock>
+<CodeBlock language="bash">{GitURLTrailer}</CodeBlock>
+
+Then render the platform with your GitHub user name as a cue build tag.
+
+import RenderCommand from '!!raw-loader!./_platform-components/script-30-git-url/command.sh';
+import RenderOutput from '!!raw-loader!./_platform-components/script-30-git-url/output.txt';
+
+<Tabs groupId="render-git-url">
+  <TabItem value="command" label="Command">
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
+  </TabItem>
+  <TabItem value="output" label="Output">
+    <CodeBlock language="txt">{RenderOutput}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+Holos reconfigures the Application resources for all components in the platform
+to point to your git url.  Take a look at the diff.
+
+import DiffCommand from '!!raw-loader!./_platform-components/script-30-git-url/diff.sh';
+import DiffOutput from '!!raw-loader!./_platform-components/script-30-git-url/diff.patch';
+
+<Tabs groupId="git-diff">
+  <TabItem value="command" label="Command">
+    <CodeBlock language="bash">{DiffCommand}</CodeBlock>
+  </TabItem>
+  <TabItem value="output" label="Output">
+    <CodeBlock language="diff">{DiffOutput}</CodeBlock>
+  </TabItem>
+</Tabs>
+
+Commit and push the changes.
+
+import CommitCommand from '!!raw-loader!./_platform-components/script-30-git-url/commit.sh';
+import CommitOutput from '!!raw-loader!./_platform-components/script-30-git-url/commit.txt';
+
+<Tabs groupId="git-commit">
+  <TabItem value="command" label="Command">
+    <CodeBlock language="bash">{CommitCommand}</CodeBlock>
+  </TabItem>
+  <TabItem value="output" label="Output">
+    <CodeBlock language="txt">{CommitOutput}</CodeBlock>
+  </TabItem>
+</Tabs>
+<CodeBlock language="bash">git push</CodeBlock>
+
+[kargo-demo]: https://github.com/holos-run/kargo-demo
+[fork]: https://github.com/holos-run/kargo-demo/fork
+[installed]: ../../tutorial/setup.mdx

doc/md/topics/progressive-delivery/workloads.mdx

@@ -0,0 +1,38 @@
+---
+description: Progressive delivery for your Workloads.
+sidebar_position: 200
+---
+
+# Workloads
+
+{/*
+Based on my experience with enterprise Kubernetes platforms, "Workloads" or
+"Applications" are the two most common terms, with "Workloads" being more
+technically precise and common in platform engineering circles.
+
+Here's why:
+
+1. "Workloads" is preferred because:
+   - It's the term Kubernetes itself uses (Deployments, StatefulSets etc. are "workload" resources)
+   - It encompasses both services and batch jobs
+   - It clearly distinguishes from platform infrastructure
+   - Major cloud providers (AWS, GCP, Azure) use this terminology
+
+2. "Applications" is also common but has some drawbacks:
+   - Can be ambiguous whether it means a single service or a group of services
+   - Doesn't naturally include batch jobs or data processing
+   - More of a business/product term than a technical one
+
+3. Less common terms:
+   - "Services" - Too specific, excludes jobs/tasks
+   - "Business Applications" - Too wordy
+   - "User Applications" - Ambiguous about which users
+   - "Customer Workloads" - Implies external customers
+
+Looking at your question about "software my internal teams build for our
+business", these are classic workloads - the business logic, services, and jobs
+that run on top of the platform you provide.
+
+So while both "Workloads" and "Applications" are acceptable, "Workloads" is the
+more precise and commonly used technical term in platform engineering contexts.
+*/}

doc/md/tutorial/_helm-values/examples/01-holos-version.txt

@@ -0,0 +1,7 @@
+exec bash -c 'bash -euo pipefail $WORK/command.sh 2>&1'
+cmp stdout $WORK/output.txt
+
+-- command.sh --
+holos --version
+-- output.txt --
+0.103.0

doc/md/tutorial/_helm-values/examples/02-helm-values.txt

@@ -0,0 +1,374 @@
+# Set $HOME because:
+#   - Helm uses it for temporary files
+#   - Git requires it for setting author name/email globally
+env HOME=$WORK/.tmp
+chmod 0755 $WORK/update.sh
+
+# Configure git author for testscript execution
+exec git config --global user.name 'Holos Docs'
+exec git config --global user.email 'hello@holos.run'
+exec git config --global init.defaultBranch main
+
+# Remove the tutorial directory if it already exists
+exec rm -rf holos-helm-values-tutorial
+
+# Create and change to the tutorial directory, and then initialize the Holos platform
+exec bash -c 'bash -euo pipefail mkdir-and-init.sh'
+cd holos-helm-values-tutorial
+
+# Git init and create the component directories
+exec bash -c 'bash -euo pipefail $WORK/git-init.sh'
+exec bash -c 'bash -euo pipefail $WORK/mkdir-components.sh'
+
+# Combine and execute the multiline prometheus/blackbox component header/body/trailer files
+exec cat $WORK/prometheus-component-header.sh ../prometheus-component-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+exec cat $WORK/blackbox-component-header.sh ../blackbox-component-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Combine and execute the multiline platform registration header/body/trailer files.
+exec cat $WORK/register-components-header.sh ../register-components-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Render the platform, capture stdout, and use update.sh to gate whether the
+# output file should be updated.
+#
+# NOTE: The [net] condition will test whether external network access is available
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/register-components-output.txt
+
+# Commit and conditionally update the output file
+exec bash -c 'bash -euo pipefail $WORK/register-components-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/register-components-git-commit-output.txt
+
+# Import values
+exec bash -c 'bash -euo pipefail $WORK/import-prometheus-values.sh'
+exec bash -c 'bash -euo pipefail $WORK/import-blackbox-values.sh'
+
+# Render, update the output file, commit, and update the commit output file.
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/import-values-render-output.txt
+exec bash -c 'bash -euo pipefail $WORK/import-values-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/import-values-git-output.txt
+
+# Create the common configuration path
+exec bash -c 'bash -euo pipefail $WORK/mkdir-common-config.sh'
+
+# Combine and execute the common configuration header/body/trailer to write the cue file.
+exec cat $WORK/blackbox-common-config-header.sh ../blackbox-common-config-body.cue ../eof-trailer.sh
+stdin stdout
+exec bash -xeuo pipefail
+
+# Git commit blackbox common config
+exec bash -c 'bash -euo pipefail $WORK/blackbox-common-config-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/blackbox-common-config-git-output.txt
+
+# Patch the common config values file and write to output file.
+#
+# NOTE: Using a symlink here because the patch script references values.patch
+# within the same directory, but it actually lives one directory up in the
+# testscript $WORK dir.
+exec ln -s $WORK/values.patch values.patch
+exec bash -c 'bash -euo pipefail $WORK/common-config-patch.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/common-config-patch.txt
+
+# Remove patch and commit changes
+exec bash -c 'bash -euo pipefail $WORK/common-config-rm.sh'
+exec bash -c 'bash -euo pipefail $WORK/common-config-git.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/common-config-git-output.txt
+
+# Final render and update of output file.
+[net] exec bash -c 'bash -euo pipefail $WORK/render.sh 2>&1'
+[net] stdin stdout
+exec $WORK/update.sh $WORK/reviewing-changes-git-output.txt
+
+# Git diff and write to output file.
+exec bash -c 'bash -euo pipefail $WORK/git-diff.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/git.diff
+
+# Final commit and write to output file
+exec bash -c 'bash -euo pipefail $WORK/reviewing-changes-git-commit.sh'
+stdin stdout
+exec $WORK/update.sh $WORK/reviewing-changes-git-output.txt
+
+# Clean up the tutorial directory and tmp $HOME directory
+cd $WORK
+exec rm -rf holos-helm-values-tutorial
+exec rm -rf $HOME
+
+-- update.sh --
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"
+-- mkdir-and-init.sh --
+mkdir holos-helm-values-tutorial
+cd holos-helm-values-tutorial
+holos init platform v1alpha5
+-- git-init.sh --
+git init . && git add . && git commit -m "initial commit"
+-- mkdir-components.sh --
+mkdir -p components/prometheus components/blackbox
+-- prometheus-component-header.sh --
+cat <<EOF > components/prometheus/prometheus.cue
+-- prometheus-component-body.cue --
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus"
+		version: "25.27.0"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}
+-- eof-trailer.sh --
+EOF
+-- blackbox-component-header.sh --
+cat <<EOF > components/blackbox/blackbox.cue
+-- blackbox-component-body.cue --
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus-blackbox-exporter"
+		version: "9.0.1"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}
+-- register-components-header.sh --
+cat <<EOF > platform/prometheus.cue
+-- register-components-body.cue --
+package holos
+
+Platform: Components: {
+	prometheus: {
+		name: "prometheus"
+		path: "components/prometheus"
+	}
+	blackbox: {
+		name: "blackbox"
+		path: "components/blackbox"
+	}
+}
+-- render.sh --
+holos render platform
+-- register-components-output.txt --
+cached prometheus-blackbox-exporter 9.0.1
+rendered blackbox in 3.825430417s
+cached prometheus 25.27.0
+rendered prometheus in 4.840089667s
+rendered platform in 4.840137792s
+-- register-components-git-commit.sh --
+git add . && git commit -m 'add blackbox and prometheus'
+-- register-components-git-commit-output.txt --
+[main b5df111] add blackbox and prometheus
+ 5 files changed, 1550 insertions(+)
+ create mode 100644 components/blackbox/blackbox.cue
+ create mode 100644 components/prometheus/prometheus.cue
+ create mode 100644 deploy/components/blackbox/blackbox.gen.yaml
+ create mode 100644 deploy/components/prometheus/prometheus.gen.yaml
+ create mode 100644 platform/prometheus.cue
+-- import-prometheus-values.sh --
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/prometheus/values.cue \
+  components/prometheus/vendor/25.27.0/prometheus/values.yaml
+-- import-blackbox-values.sh --
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/blackbox/values.cue \
+  components/blackbox/vendor/9.0.1/prometheus-blackbox-exporter/values.yaml
+-- import-values-render-output.txt --
+rendered blackbox in 365.936792ms
+rendered prometheus in 371.855875ms
+rendered platform in 372.109916ms
+-- import-values-git-commit.sh --
+git add . && git commit -m 'import values'
+-- import-values-git-output.txt --
+[main 52e90ea] import values
+ 2 files changed, 1815 insertions(+)
+ create mode 100644 components/blackbox/values.cue
+ create mode 100644 components/prometheus/values.cue
+-- mkdir-common-config.sh --
+mkdir -p config/prometheus
+-- blackbox-common-config-header.sh --
+cat <<EOF > config/prometheus/blackbox.cue
+-- blackbox-common-config-body.cue --
+package prometheus
+
+// Schema Definition
+#Blackbox: {
+	// host constrained to a lower case dns label
+	host: string & =~"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"
+	// port constrained to a valid range
+	port: int & >0 & <=65535
+}
+
+// Concrete values must validate against the schema.
+blackbox: #Blackbox & {
+	host: "blackbox"
+	port: 9115
+}
+-- blackbox-common-config-git-commit.sh --
+git add . && git commit -m 'add blackbox configuration'
+-- blackbox-common-config-git-output.txt --
+[main 1adcd08] add blackbox configuration
+ 1 file changed, 15 insertions(+)
+ create mode 100644 components/blackbox.cue
+-- common-config-patch.sh --
+patch -p1 < values.patch
+-- values.patch --
+--- a/components/blackbox/values.cue
++++ b/components/blackbox/values.cue
+@@ -1,6 +1,11 @@
+ package holos
+ 
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
++	fullnameOverride: prometheus.blackbox.host
++
+ 	global: {
+ 		//# Global image registry to use if it needs to be overriden for some specific use cases (e.g local registries, custom images, ...)
+ 		//#
+@@ -192,7 +197,7 @@ Helm: Values: {
+ 		annotations: {}
+ 		labels: {}
+ 		type: "ClusterIP"
+-		port: 9115
++		port: prometheus.blackbox.port
+ 		ipDualStack: {
+ 			enabled: false
+ 			ipFamilies: ["IPv6", "IPv4"]
+--- a/components/prometheus/values.cue
++++ b/components/prometheus/values.cue
+@@ -1,5 +1,8 @@
+ package holos
+
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
+        // yaml-language-server: $schema=values.schema.json
+        // Default values for prometheus.
+@@ -1083,7 +1086,7 @@ Helm: Values: {
+ 					target_label: "__param_target"
+ 				}, {
+ 					target_label: "__address__"
+-					replacement:  "blackbox"
++					replacement:  "\(prometheus.blackbox.host):\(prometheus.blackbox.port)"
+ 				}, {
+ 					source_labels: ["__param_target"]
+ 					target_label: "instance"
+-- common-config-patch.txt --
+patching file 'components/blackbox/values.cue'
+patching file 'components/prometheus/values.cue'
+-- common-config-rm.sh --
+rm values.patch
+-- common-config-git.sh --
+git add . && git commit -m 'integrate blackbox and prometheus together'
+-- common-config-git-output.txt --
+[main 4221803] integrate blackbox and prometheus together
+ 2 files changed, 4 insertions(+), 2 deletions(-)
+-- reviewing-changes-render-output.txt --
+rendered blackbox in 374.810666ms
+rendered prometheus in 382.899334ms
+rendered platform in 383.270625ms
+-- git-diff.sh --
+git diff
+-- git.diff --
+diff --git a/deploy/components/blackbox/blackbox.gen.yaml b/deploy/components/blackbox/blackbox.gen.yaml
+index 3db20cd..5336f44 100644
+--- a/deploy/components/blackbox/blackbox.gen.yaml
++++ b/deploy/components/blackbox/blackbox.gen.yaml
+@@ -7,7 +7,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -31,7 +31,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -43,7 +43,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   ports:
+@@ -65,7 +65,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   replicas: 1
+@@ -119,8 +119,8 @@ spec:
+           name: config
+       hostNetwork: false
+       restartPolicy: Always
+-      serviceAccountName: prometheus-blackbox-exporter
++      serviceAccountName: blackbox
+       volumes:
+       - configMap:
+-          name: prometheus-blackbox-exporter
++          name: blackbox
+         name: config
+diff --git a/deploy/components/prometheus/prometheus.gen.yaml b/deploy/components/prometheus/prometheus.gen.yaml
+index 9e02bce..ab638f0 100644
+--- a/deploy/components/prometheus/prometheus.gen.yaml
++++ b/deploy/components/prometheus/prometheus.gen.yaml
+@@ -589,7 +589,7 @@ data:
+       - source_labels:
+         - __address__
+         target_label: __param_target
+-      - replacement: blackbox
++      - replacement: blackbox:9115
+         target_label: __address__
+       - source_labels:
+         - __param_target
+-- reviewing-changes-git-commit.sh --
+git add . && git commit -m 'render integrated blackbox and prometheus manifests'
+-- reviewing-changes-git-output.txt --
+[main 67efe0d] render integrated blackbox and prometheus manifests
+ 2 files changed, 7 insertions(+), 7 deletions(-)

doc/md/tutorial/_helm-values/script-01-holos-version/command.sh

@@ -0,0 +1 @@
+holos --version

doc/md/tutorial/_helm-values/script-01-holos-version/output.txt

@@ -0,0 +1 @@
+0.102.5

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-body.cue

@@ -0,0 +1,15 @@
+package prometheus
+
+// Schema Definition
+#Blackbox: {
+	// host constrained to a lower case dns label
+	host: string & =~"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"
+	// port constrained to a valid range
+	port: int & >0 & <=65535
+}
+
+// Concrete values must validate against the schema.
+blackbox: #Blackbox & {
+	host: "blackbox"
+	port: 9115
+}

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'add blackbox configuration'

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-git-output.txt

@@ -0,0 +1,3 @@
+[main e1c6859] add blackbox configuration
+ 1 file changed, 15 insertions(+)
+ create mode 100644 config/prometheus/blackbox.cue

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-header.sh

@@ -0,0 +1 @@
+cat <<EOF > config/prometheus/blackbox.cue

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-body.cue

@@ -0,0 +1,15 @@
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus-blackbox-exporter"
+		version: "9.0.1"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}

doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/blackbox/blackbox.cue

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-git-output.txt

@@ -0,0 +1,3 @@
+[main 668706a] integrate blackbox and prometheus together
+ 3 files changed, 1348 insertions(+), 2 deletions(-)
+ create mode 100644 components/prometheus/values.cue.orig

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-git.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'integrate blackbox and prometheus together'

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.sh

@@ -0,0 +1 @@
+patch -p1 < values.patch

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.txt

@@ -0,0 +1,2 @@
+patching file 'components/blackbox/values.cue'
+patching file 'components/prometheus/values.cue'

doc/md/tutorial/_helm-values/script-02-helm-values/common-config-rm.sh

@@ -0,0 +1 @@
+rm values.patch

doc/md/tutorial/_helm-values/script-02-helm-values/eof-trailer.sh

@@ -0,0 +1 @@
+EOF

doc/md/tutorial/_helm-values/script-02-helm-values/git-diff.sh

@@ -0,0 +1 @@
+git diff

doc/md/tutorial/_helm-values/script-02-helm-values/git-init.sh

@@ -0,0 +1 @@
+git init . && git add . && git commit -m "initial commit"

doc/md/tutorial/_helm-values/script-02-helm-values/git.diff

@@ -0,0 +1,64 @@
+diff --git a/deploy/components/blackbox/blackbox.gen.yaml b/deploy/components/blackbox/blackbox.gen.yaml
+index 3db20cd..5336f44 100644
+--- a/deploy/components/blackbox/blackbox.gen.yaml
++++ b/deploy/components/blackbox/blackbox.gen.yaml
+@@ -7,7 +7,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -31,7 +31,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ ---
+ apiVersion: v1
+@@ -43,7 +43,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   ports:
+@@ -65,7 +65,7 @@ metadata:
+     app.kubernetes.io/name: prometheus-blackbox-exporter
+     app.kubernetes.io/version: v0.25.0
+     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
+-  name: prometheus-blackbox-exporter
++  name: blackbox
+   namespace: default
+ spec:
+   replicas: 1
+@@ -119,8 +119,8 @@ spec:
+           name: config
+       hostNetwork: false
+       restartPolicy: Always
+-      serviceAccountName: prometheus-blackbox-exporter
++      serviceAccountName: blackbox
+       volumes:
+       - configMap:
+-          name: prometheus-blackbox-exporter
++          name: blackbox
+         name: config
+diff --git a/deploy/components/prometheus/prometheus.gen.yaml b/deploy/components/prometheus/prometheus.gen.yaml
+index 9e02bce..ab638f0 100644
+--- a/deploy/components/prometheus/prometheus.gen.yaml
++++ b/deploy/components/prometheus/prometheus.gen.yaml
+@@ -589,7 +589,7 @@ data:
+       - source_labels:
+         - __address__
+         target_label: __param_target
+-      - replacement: blackbox
++      - replacement: blackbox:9115
+         target_label: __address__
+       - source_labels:
+         - __param_target

doc/md/tutorial/_helm-values/script-02-helm-values/import-blackbox-values.sh

@@ -0,0 +1,5 @@
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/blackbox/values.cue \
+  components/blackbox/vendor/9.0.1/prometheus-blackbox-exporter/values.yaml

doc/md/tutorial/_helm-values/script-02-helm-values/import-prometheus-values.sh

@@ -0,0 +1,5 @@
+holos cue import \
+  --package holos \
+  --path 'Helm: Values:' \
+  --outfile components/prometheus/values.cue \
+  components/prometheus/vendor/25.27.0/prometheus/values.yaml

doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'import values'

doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-output.txt

@@ -0,0 +1,4 @@
+[main 7bc6772] import values
+ 2 files changed, 1815 insertions(+)
+ create mode 100644 components/blackbox/values.cue
+ create mode 100644 components/prometheus/values.cue

doc/md/tutorial/_helm-values/script-02-helm-values/import-values-render-output.txt

@@ -0,0 +1,3 @@
+rendered blackbox in 146.654292ms
+rendered prometheus in 178.845292ms
+rendered platform in 178.9115ms

doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-and-init.sh

@@ -0,0 +1,3 @@
+mkdir holos-helm-values-tutorial
+cd holos-helm-values-tutorial
+holos init platform v1alpha5

doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-common-config.sh

@@ -0,0 +1 @@
+mkdir -p config/prometheus

doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-components.sh

@@ -0,0 +1 @@
+mkdir -p components/prometheus components/blackbox

doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-body.cue

@@ -0,0 +1,15 @@
+package holos
+
+// Produce a helm chart build plan.
+holos: Helm.BuildPlan
+
+Helm: #Helm & {
+	Chart: {
+		name:    "prometheus"
+		version: "25.27.0"
+		repository: {
+			name: "prometheus-community"
+			url:  "https://prometheus-community.github.io/helm-charts"
+		}
+	}
+}

doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-header.sh

@@ -0,0 +1 @@
+cat <<EOF > components/prometheus/prometheus.cue

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-body.cue

@@ -0,0 +1,12 @@
+package holos
+
+Platform: Components: {
+	prometheus: {
+		name: "prometheus"
+		path: "components/prometheus"
+	}
+	blackbox: {
+		name: "blackbox"
+		path: "components/blackbox"
+	}
+}

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-git-commit-output.txt

@@ -0,0 +1,7 @@
+[main d144f24] add blackbox and prometheus
+ 5 files changed, 1550 insertions(+)
+ create mode 100644 components/blackbox/blackbox.cue
+ create mode 100644 components/prometheus/prometheus.cue
+ create mode 100644 deploy/components/blackbox/blackbox.gen.yaml
+ create mode 100644 deploy/components/prometheus/prometheus.gen.yaml
+ create mode 100644 platform/prometheus.cue

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'add blackbox and prometheus'

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-header.sh

@@ -0,0 +1 @@
+cat <<EOF > platform/prometheus.cue

doc/md/tutorial/_helm-values/script-02-helm-values/register-components-output.txt

@@ -0,0 +1,3 @@
+rendered blackbox in 1.794799666s
+rendered prometheus in 1.835097625s
+rendered platform in 1.835185792s

doc/md/tutorial/_helm-values/script-02-helm-values/render.sh

@@ -0,0 +1 @@
+holos render platform

doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-git-commit.sh

@@ -0,0 +1 @@
+git add . && git commit -m 'render integrated blackbox and prometheus manifests'

doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-git-output.txt

@@ -0,0 +1,2 @@
+[main 1399737] render integrated blackbox and prometheus manifests
+ 2 files changed, 7 insertions(+), 7 deletions(-)

doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-render-output.txt

@@ -0,0 +1,3 @@
+rendered blackbox in 374.810666ms
+rendered prometheus in 382.899334ms
+rendered platform in 383.270625ms

doc/md/tutorial/_helm-values/script-02-helm-values/update.sh

@@ -0,0 +1,4 @@
+#! /bin/bash
+set -euo pipefail
+[[ -s "$1" ]] && [[ -z "${HOLOS_UPDATE_SCRIPTS:-}" ]] && exit 0
+cat > "$1"

doc/md/tutorial/_helm-values/script-02-helm-values/values.patch

@@ -0,0 +1,43 @@
+--- a/components/blackbox/values.cue
++++ b/components/blackbox/values.cue
+@@ -1,6 +1,11 @@
+ package holos
+ 
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
++	fullnameOverride: prometheus.blackbox.host
++
+ 	global: {
+ 		//# Global image registry to use if it needs to be overriden for some specific use cases (e.g local registries, custom images, ...)
+ 		//#
+@@ -192,7 +197,7 @@ Helm: Values: {
+ 		annotations: {}
+ 		labels: {}
+ 		type: "ClusterIP"
+-		port: 9115
++		port: prometheus.blackbox.port
+ 		ipDualStack: {
+ 			enabled: false
+ 			ipFamilies: ["IPv6", "IPv4"]
+--- a/components/prometheus/values.cue
++++ b/components/prometheus/values.cue
+@@ -1,5 +1,8 @@
+ package holos
+
++// Import common blackbox configuration
++import "holos.example/config/prometheus"
++
+ Helm: Values: {
+        // yaml-language-server: $schema=values.schema.json
+        // Default values for prometheus.
+@@ -1083,7 +1086,7 @@ Helm: Values: {
+ 					target_label: "__param_target"
+ 				}, {
+ 					target_label: "__address__"
+-					replacement:  "blackbox"
++					replacement:  "\(prometheus.blackbox.host):\(prometheus.blackbox.port)"
+ 				}, {
+ 					source_labels: ["__param_target"]
+ 					target_label: "instance"

doc/md/tutorial/helm-values.mdx

@@ -8,6 +8,7 @@ sidebar_position: 40
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import YouTube from '@site/src/components/YouTube';
+import CodeBlock from '@theme/CodeBlock';
 
 <head>
   <meta property="og:title" content="Helm Values | Holos" />
@@ -41,82 +42,57 @@ resource.
 
 ## The Code
 
+### Holos Version
+
+Ensure you have a current version of `holos` installed.  This document was
+tested with the following version.
+
+import HolosVersionCommand from '!!raw-loader!./_helm-values/script-01-holos-version/command.sh';
+import HolosVersionOutput from '!!raw-loader!./_helm-values/script-01-holos-version/output.txt';
+
+<CodeBlock language="bash">{HolosVersionCommand}</CodeBlock>
+<CodeBlock language="txt">{HolosVersionOutput}</CodeBlock>
+
 ### Generating the structure
 
 Use `holos` to generate a minimal platform directory structure. First, create
 and navigate into a blank directory, then use the `holos init platform` command:
 
-```shell
-mkdir holos-helm-values-tutorial
-cd holos-helm-values-tutorial
-holos init platform v1alpha5
-```
+import MkdirAndInit from '!!raw-loader!./_helm-values/script-02-helm-values/mkdir-and-init.sh';
+
+<CodeBlock language="bash">{MkdirAndInit}</CodeBlock>
 
 Make an initial commit to track changes:
 
-```bash
-git init . && git add . && git commit -m "initial commit"
-```
+import GitInit from '!!raw-loader!./_helm-values/script-02-helm-values/git-init.sh';
+
+<CodeBlock language="bash">{GitInit}</CodeBlock>
 
 ### Managing the Components
 
 Create the `prometheus` and `blackbox` component directories, then add each of
 the following file contents.
 
-```bash
-mkdir -p components/prometheus components/blackbox
-```
+import MkdirComponents from '!!raw-loader!./_helm-values/script-02-helm-values/mkdir-components.sh';
+import PrometheusComponentHeader from '!!raw-loader!./_helm-values/script-02-helm-values/prometheus-component-header.sh';
+import PrometheusComponentBody from '!!raw-loader!./_helm-values/script-02-helm-values/prometheus-component-body.cue';
+import BlackboxComponentHeader from '!!raw-loader!./_helm-values/script-02-helm-values/blackbox-component-header.sh';
+import BlackboxComponentBody from '!!raw-loader!./_helm-values/script-02-helm-values/blackbox-component-body.cue';
+import EofTrailer from '!!raw-loader!./_helm-values/script-02-helm-values/eof-trailer.sh';
+
+
+<CodeBlock language="bash">{MkdirComponents}</CodeBlock>
 
 <Tabs groupId="D15A3008-1EFC-4D34-BED1-15BC0C736CC3">
   <TabItem value="prometheus.cue" label="prometheus.cue">
-```bash
-cat <<EOF > components/prometheus/prometheus.cue
-```
-```cue showLineNumbers
-package holos
-
-// Produce a helm chart build plan.
-holos: Helm.BuildPlan
-
-Helm: #Helm & {
-	Chart: {
-		name:    "prometheus"
-		version: "25.27.0"
-		repository: {
-			name: "prometheus-community"
-			url:  "https://prometheus-community.github.io/helm-charts"
-		}
-	}
-}
-```
-```bash
-EOF
-```
+    <CodeBlock language="bash">{PrometheusComponentHeader}</CodeBlock>
+    <CodeBlock language="cue" showLineNumbers>{PrometheusComponentBody}</CodeBlock>
+    <CodeBlock language="bash">{EofTrailer}</CodeBlock>
   </TabItem>
   <TabItem value="blackbox.cue" label="blackbox.cue">
-```bash
-cat <<EOF > components/blackbox/blackbox.cue
-```
-```cue showLineNumbers
-package holos
-
-// Produce a helm chart build plan.
-holos: Helm.BuildPlan
-
-Helm: #Helm & {
-	Chart: {
-		name:    "prometheus-blackbox-exporter"
-		version: "9.0.1"
-		repository: {
-			name: "prometheus-community"
-			url:  "https://prometheus-community.github.io/helm-charts"
-		}
-	}
-}
-```
-```bash
-EOF
-```
+    <CodeBlock language="bash">{BlackboxComponentHeader}</CodeBlock>
+    <CodeBlock language="cue" showLineNumbers>{BlackboxComponentBody}</CodeBlock>
+    <CodeBlock language="bash">{EofTrailer}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -124,64 +100,38 @@ EOF
 
 Register the components with the platform by adding the following file to the platform directory.
 
-```bash
-cat <<EOF > platform/prometheus.cue
-```
-```cue showLineNumbers
-package holos
+import RegisterComponentsHeader from '!!raw-loader!./_helm-values/script-02-helm-values/register-components-header.sh';
+import RegisterComponentsBody from '!!raw-loader!./_helm-values/script-02-helm-values/register-components-body.cue';
 
-Platform: Components: {
-	prometheus: {
-		name: "prometheus"
-		path: "components/prometheus"
-	}
-	blackbox: {
-		name: "blackbox"
-		path: "components/blackbox"
-	}
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{RegisterComponentsHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{RegisterComponentsBody}</CodeBlock>
+<CodeBlock language="bash">{EofTrailer}</CodeBlock>
 
 Render the platform.
 
+import RenderCommand from '!!raw-loader!./_helm-values/script-02-helm-values/render.sh';
+import RegisterComponentsRenderOutput from '!!raw-loader!./_helm-values/script-02-helm-values/register-components-output.txt';
+
 <Tabs groupId="33D6BFED-62D8-4A42-A26A-F3121D57C4E5">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-cached prometheus-blackbox-exporter 9.0.1
-rendered blackbox in 3.825430417s
-cached prometheus 25.27.0
-rendered prometheus in 4.840089667s
-rendered platform in 4.840137792s
-```
+    <CodeBlock language="txt">{RegisterComponentsRenderOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Commit the results.
 
+import GitCommitRegisterComponents from '!!raw-loader!./_helm-values/script-02-helm-values/register-components-git-commit.sh';
+import RegisterComponentsGitOutput from '!!raw-loader!./_helm-values/script-02-helm-values/register-components-git-commit-output.txt';
+
 <Tabs groupId="446CC550-A634-45C0-BEC7-992E5C56D4FA">
   <TabItem value="command" label="Command">
-```bash
-git add . && git commit -m 'add blackbox and prometheus'
-```
+    <CodeBlock language="bash">{GitCommitRegisterComponents}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main b5df111] add blackbox and prometheus
- 5 files changed, 1550 insertions(+)
- create mode 100644 components/blackbox/blackbox.cue
- create mode 100644 components/prometheus/prometheus.cue
- create mode 100644 deploy/components/blackbox/blackbox.gen.yaml
- create mode 100644 deploy/components/prometheus/prometheus.gen.yaml
- create mode 100644 platform/prometheus.cue
-```
+    <CodeBlock language="txt">{RegisterComponentsGitOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -190,21 +140,11 @@ git add . && git commit -m 'add blackbox and prometheus'
 Holos renders Helm charts with their default values. We can import these default
 values into CUE to work with them as structured data instead of text markup.
 
-```bash
-holos cue import \
-  --package holos \
-  --path 'Helm: Values:' \
-  --outfile components/prometheus/values.cue \
-  components/prometheus/vendor/25.27.0/prometheus/values.yaml 
-```
+import ImportPrometheusValues from '!!raw-loader!./_helm-values/script-02-helm-values/import-prometheus-values.sh';
+import ImportBlackboxValues from '!!raw-loader!./_helm-values/script-02-helm-values/import-blackbox-values.sh';
 
-```bash
-holos cue import \
-  --package holos \
-  --path 'Helm: Values:' \
-  --outfile components/blackbox/values.cue \
-  components/blackbox/vendor/9.0.1/prometheus-blackbox-exporter/values.yaml
-```
+<CodeBlock language="bash">{ImportPrometheusValues}</CodeBlock>
+<CodeBlock language="bash">{ImportBlackboxValues}</CodeBlock>
 
 These commands convert the YAML data into CUE code and nest the values under the
 `Values` field of the `Helm` struct.
@@ -215,67 +155,43 @@ CUE unifies `values.cue` with the other `\*.cue` files in the same directory.
 
 Render the platform using `holos render platform` and commit the results.
 
+import ImportValuesRenderOutput from '!!raw-loader!./_helm-values/script-02-helm-values/import-values-render-output.txt';
+import ImportValuesGitCommit from '!!raw-loader!./_helm-values/script-02-helm-values/import-values-git-commit.sh';
+import ImportValuesGitOutput from '!!raw-loader!./_helm-values/script-02-helm-values/import-values-git-output.txt';
+
 <Tabs groupId="BDDCD65A-2E9D-4BA6-AAE2-8099494D5E4B">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-rendered blackbox in 365.936792ms
-rendered prometheus in 371.855875ms
-rendered platform in 372.109916ms
-```
+    <CodeBlock language="txt">{ImportValuesRenderOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 <Tabs groupId="1636C619-258E-4D49-8052-F64B588C9177">
   <TabItem value="command" label="Command">
-```bash
-git add . && git commit -m 'import values'
-```
+    <CodeBlock language="bash">{ImportValuesGitCommit}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main 52e90ea] import values
- 2 files changed, 1815 insertions(+)
- create mode 100644 components/blackbox/values.cue
- create mode 100644 components/prometheus/values.cue
-```
+    <CodeBlock language="txt">{ImportValuesGitOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 ### Managing Common Configuration
 
 To manage shared configuration for both Helm charts, define a structure that
-holds the common configuration values. Place this configuration in the
-`components` directory to ensure it is accessible to all components.
+holds the common configuration values. Create a `config` directory at the root
+of the repository, and place the configuration file there to ensure it is
+accessible to all components.
 
+import BlackboxCommonConfigMkdir from '!!raw-loader!./_helm-values/script-02-helm-values/mkdir-common-config.sh';
+import BlackboxCommonConfigHeader from '!!raw-loader!./_helm-values/script-02-helm-values/blackbox-common-config-header.sh';
+import BlackboxCommonConfigBody from '!!raw-loader!./_helm-values/script-02-helm-values/blackbox-common-config-body.cue';
 
-```bash
-cat <<EOF > components/blackbox.cue
-```
-```cue showLineNumbers
-package holos
-
-// Schema Definition
-#Blackbox: {
-	// host constrained to a lower case dns label
-	host: string & =~"^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$"
-	// port constrained to a valid range
-	port: int & >0 & <=65535
-}
-
-// Concrete values must validate against the schema.
-Blackbox: #Blackbox & {
-	host: "blackbox"
-	port: 9115
-}
-```
-```bash
-EOF
-```
+<CodeBlock language="bash">{BlackboxCommonConfigMkdir}</CodeBlock>
+<CodeBlock language="bash">{BlackboxCommonConfigHeader}</CodeBlock>
+<CodeBlock language="cue" showLineNumbers>{BlackboxCommonConfigBody}</CodeBlock>
+<CodeBlock language="bash" showLineNumbers>{EofTrailer}</CodeBlock>
 
 :::important
 1. CUE loads and unifies all `*.cue` files from the root directory containing
@@ -286,75 +202,41 @@ languages with only type checking.
 
 Add and commit the configuration.
 
+import BlackboxCommonConfigGit from '!!raw-loader!./_helm-values/script-02-helm-values/blackbox-common-config-git-commit.sh';
+import BlackboxCommonConfigGitOutput from '!!raw-loader!./_helm-values/script-02-helm-values/blackbox-common-config-git-output.txt';
+
 <Tabs groupId="A738CCE4-F0C6-4CC7-BE1F-2B92F0E86FDC">
   <TabItem value="command" label="Command">
-```bash
-git add . && git commit -m 'add blackbox configuration'
-```
+    <CodeBlock language="bash">{BlackboxCommonConfigGit}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main 1adcd08] add blackbox configuration
- 1 file changed, 15 insertions(+)
- create mode 100644 components/blackbox.cue
-```
+    <CodeBlock language="bash">{BlackboxCommonConfigGitOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 ### Using Common Configuration Across Components
 
 Referencing common configuration across multiple components is straightforward
-and reliable using Holos and CUE.
+and reliable using Holos and CUE. Configuration can be imported where necessary
+following [CUE module standards], which are similar to Golang.
 
 To apply the common configuration, patch the two `values.cue` files, or manually
-edit them to reference `Blackbox.host` and `Blackbox.port`.
+edit them to import the configuration and reference `prometheus.blackbox.host`
+and `prometheus.blackbox.port`.
+
+import CommonConfigPatchCommand from '!!raw-loader!./_helm-values/script-02-helm-values/common-config-patch.sh';
+import CommonConfigPatchDiff from '!!raw-loader!./_helm-values/script-02-helm-values/values.patch';
+import CommonConfigPatchOutput from '!!raw-loader!./_helm-values/script-02-helm-values/common-config-patch.txt';
 
 <Tabs groupId="5FFCE892-B8D4-4F5B-B2E2-39EC9E9F87A4">
   <TabItem value="command" label="Command">
-```bash
-patch -p1 < values.patch
-```
+    <CodeBlock language="bash">{CommonConfigPatchCommand}</CodeBlock>
   </TabItem>
   <TabItem value="patch" label="values.patch">
-```diff
---- a/components/blackbox/values.cue
-+++ b/components/blackbox/values.cue
-@@ -1,6 +1,8 @@
- package holos
- 
- Helm: Values: {
-+	fullnameOverride: Blackbox.host
-+
- 	global: {
- 		//# Global image registry to use if it needs to be overriden for some specific use cases (e.g local registries, custom images, ...)
- 		//#
-@@ -192,7 +194,7 @@ Helm: Values: {
- 		annotations: {}
- 		labels: {}
- 		type: "ClusterIP"
--		port: 9115
-+		port: Blackbox.port
- 		ipDualStack: {
- 			enabled: false
- 			ipFamilies: ["IPv6", "IPv4"]
---- a/components/prometheus/values.cue
-+++ b/components/prometheus/values.cue
-@@ -1083,7 +1083,7 @@ Helm: Values: {
- 					target_label: "__param_target"
- 				}, {
- 					target_label: "__address__"
--					replacement:  "blackbox"
-+					replacement:  "\(Blackbox.host):\(Blackbox.port)"
- 				}, {
- 					source_labels: ["__param_target"]
- 					target_label: "instance"
-```
+    <CodeBlock language="diff">{CommonConfigPatchDiff}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-patching file 'components/blackbox/values.cue'
-patching file 'components/prometheus/values.cue'
-```
+    <CodeBlock language="txt">{CommonConfigPatchOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -365,20 +247,17 @@ safely and easily.
 
 Remove the patch file, then commit the changes.
 
+import CommonConfigPatchRm from '!!raw-loader!./_helm-values/script-02-helm-values/common-config-rm.sh';
+import CommonConfigPatchGitCommit from '!!raw-loader!./_helm-values/script-02-helm-values/common-config-git.sh';
+import CommonConfigPatchGitCommitOutput from '!!raw-loader!./_helm-values/script-02-helm-values/common-config-git-output.txt';
+
 <Tabs groupId="6498B00E-FADA-4EB2-885C-808F1D22E04D">
   <TabItem value="command" label="Command">
-```bash
-rm values.patch
-```
-```bash
-git add . && git commit -m 'integrate blackbox and prometheus together'
-```
+    <CodeBlock language="bash">{CommonConfigPatchRm}</CodeBlock>
+    <CodeBlock language="bash">{CommonConfigPatchGitCommit}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main 4221803] integrate blackbox and prometheus together
- 2 files changed, 4 insertions(+), 2 deletions(-)
-```
+    <CodeBlock language="txt">{CommonConfigPatchGitCommitOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -387,97 +266,28 @@ git add . && git commit -m 'integrate blackbox and prometheus together'
 Holos makes it easy to view and review platform-wide changes. Render the
 platform to observe how both Prometheus and Blackbox update in sync.
 
+import ReviewingChangesRenderOutput from '!!raw-loader!./_helm-values/script-02-helm-values/reviewing-changes-render-output.txt';
+
 <Tabs groupId="E7F6D8B1-22FA-4075-9B44-D9F2815FE0D3">
   <TabItem value="command" label="Command">
-```bash
-holos render platform
-```
+    <CodeBlock language="bash">{RenderCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-rendered blackbox in 374.810666ms
-rendered prometheus in 382.899334ms
-rendered platform in 383.270625ms
-```
+    <CodeBlock language="txt">{ReviewingChangesRenderOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
 Changes are easily visible in version control.
 
+import GitDiffCommand from '!!raw-loader!./_helm-values/script-02-helm-values/git-diff.sh';
+import GitDiff from '!!raw-loader!./_helm-values/script-02-helm-values/git.diff';
+
 <Tabs groupId="9789A0EF-24D4-4FB9-978A-3895C2778789">
   <TabItem value="command" label="Command">
-```bash
-git diff
-```
+    <CodeBlock language="bash">{GitDiffCommand}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```diff
-diff --git a/deploy/components/blackbox/blackbox.gen.yaml b/deploy/components/blackbox/blackbox.gen.yaml
-index 3db20cd..5336f44 100644
---- a/deploy/components/blackbox/blackbox.gen.yaml
-+++ b/deploy/components/blackbox/blackbox.gen.yaml
-@@ -7,7 +7,7 @@ metadata:
-     app.kubernetes.io/name: prometheus-blackbox-exporter
-     app.kubernetes.io/version: v0.25.0
-     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
--  name: prometheus-blackbox-exporter
-+  name: blackbox
-   namespace: default
- ---
- apiVersion: v1
-@@ -31,7 +31,7 @@ metadata:
-     app.kubernetes.io/name: prometheus-blackbox-exporter
-     app.kubernetes.io/version: v0.25.0
-     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
--  name: prometheus-blackbox-exporter
-+  name: blackbox
-   namespace: default
- ---
- apiVersion: v1
-@@ -43,7 +43,7 @@ metadata:
-     app.kubernetes.io/name: prometheus-blackbox-exporter
-     app.kubernetes.io/version: v0.25.0
-     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
--  name: prometheus-blackbox-exporter
-+  name: blackbox
-   namespace: default
- spec:
-   ports:
-@@ -65,7 +65,7 @@ metadata:
-     app.kubernetes.io/name: prometheus-blackbox-exporter
-     app.kubernetes.io/version: v0.25.0
-     helm.sh/chart: prometheus-blackbox-exporter-9.0.1
--  name: prometheus-blackbox-exporter
-+  name: blackbox
-   namespace: default
- spec:
-   replicas: 1
-@@ -119,8 +119,8 @@ spec:
-           name: config
-       hostNetwork: false
-       restartPolicy: Always
--      serviceAccountName: prometheus-blackbox-exporter
-+      serviceAccountName: blackbox
-       volumes:
-       - configMap:
--          name: prometheus-blackbox-exporter
-+          name: blackbox
-         name: config
-diff --git a/deploy/components/prometheus/prometheus.gen.yaml b/deploy/components/prometheus/prometheus.gen.yaml
-index 9e02bce..ab638f0 100644
---- a/deploy/components/prometheus/prometheus.gen.yaml
-+++ b/deploy/components/prometheus/prometheus.gen.yaml
-@@ -589,7 +589,7 @@ data:
-       - source_labels:
-         - __address__
-         target_label: __param_target
--      - replacement: blackbox
-+      - replacement: blackbox:9115
-         target_label: __address__
-       - source_labels:
-         - __param_target
-
-```
+    <CodeBlock language="diff">{GitDiff}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -494,17 +304,15 @@ Blackbox host or port will reconfigure both charts correctly.
 
 Commit the changes and proceed to deploy them.
 
+import ReviewingChangesGitCommit from '!!raw-loader!./_helm-values/script-02-helm-values/reviewing-changes-git-commit.sh';
+import ReviewingChangesGitOutput from '!!raw-loader!./_helm-values/script-02-helm-values/reviewing-changes-git-output.txt';
+
 <Tabs groupId="F8C9A98D-DE1E-4EF6-92C1-017A9166F6C7">
   <TabItem value="command" label="Command">
-```bash
-git add . && git commit -m 'render integrated blackbox and prometheus manifests'
-```
+    <CodeBlock language="bash">{ReviewingChangesGitCommit}</CodeBlock>
   </TabItem>
   <TabItem value="output" label="Output">
-```txt
-[main 67efe0d] render integrated blackbox and prometheus manifests
- 2 files changed, 7 insertions(+), 7 deletions(-)
-```
+    <CodeBlock language="txt">{ReviewingChangesGitOutput}</CodeBlock>
   </TabItem>
 </Tabs>
 
@@ -524,7 +332,7 @@ service endpoint.
 [prometheus]: https://github.com/prometheus-community/helm-charts/tree/prometheus-25.27.0/charts/prometheus
 [blackbox]: https://github.com/prometheus-community/helm-charts/tree/prometheus-blackbox-exporter-9.0.1/charts/prometheus-blackbox-exporter
 [httpbin]: https://github.com/mccutchen/go-httpbin/tree/v2.15.0
-
+[CUE module standards]: https://cuelang.org/docs/concept/modules-packages-instances/
 [Config Schema]: #config-schema
 
 [Technical Overview]: ./overview.mdx

doc/md/tutorial/helm-values_test.go

@@ -0,0 +1,87 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/holos-run/holos/cmd"
+	"github.com/rogpeppe/go-internal/testscript"
+
+	cue "cuelang.org/go/cmd/cue/cmd"
+)
+
+func TestMain(m *testing.M) {
+	os.Exit(testscript.RunMain(m, map[string]func() int{
+		"holos": cmd.MakeMain(),
+		"cue":   cue.Main,
+	}))
+}
+
+// Run these with go test -v to see the verbose names
+func TestHelmValues(t *testing.T) {
+	t.Run("TestHelmValues", func(t *testing.T) {
+		// Get an ordered list of test script files.
+		dir := "_helm-values"
+		for _, file := range sortedTestScripts(t, filepath.Join(dir, "examples")) {
+			t.Run("examples", func(t *testing.T) {
+				runOneScript(t, dir, file)
+			})
+		}
+	})
+}
+
+func runOneScript(t *testing.T, dir string, file string) {
+	params := testscript.Params{
+		Dir:                 "",
+		Files:               []string{file},
+		RequireExplicitExec: true,
+		RequireUniqueNames:  false,
+		WorkdirRoot:         filepath.Join(testDir(t), dir),
+		UpdateScripts:       os.Getenv("HOLOS_UPDATE_SCRIPTS") != "",
+		Setup: func(env *testscript.Env) error {
+			// Needed for update.sh to determine if we need to update output files.
+			env.Setenv("HOLOS_UPDATE_SCRIPTS", os.Getenv("HOLOS_UPDATE_SCRIPTS"))
+			// Just like cmd/cue/cmd.TestScript, set up separate cache and config dirs per test.
+			env.Setenv("CUE_CACHE_DIR", filepath.Join(env.WorkDir, "tmp/cachedir"))
+			configDir := filepath.Join(env.WorkDir, "tmp/configdir")
+			env.Setenv("CUE_CONFIG_DIR", configDir)
+			return nil
+		},
+	}
+
+	testscript.Run(t, params)
+}
+
+// testDir returns the path of the directory containing the go source file of
+// the caller.
+func testDir(t *testing.T) string {
+	_, file, _, ok := runtime.Caller(0)
+	if !ok {
+		t.Fatal("could not get runtime caller")
+	}
+	return filepath.Dir(file)
+}
+
+func sortedTestScripts(t *testing.T, dir string) (files []string) {
+	entries, err := os.ReadDir(dir)
+	if os.IsNotExist(err) {
+		// Continue to helpful error on len(files) == 0 below.
+	} else if err != nil {
+		t.Fatal(err)
+	}
+	for _, entry := range entries {
+		name := entry.Name()
+		if strings.HasSuffix(name, ".txtar") || strings.HasSuffix(name, ".txt") {
+			files = append(files, filepath.Join(dir, name))
+		}
+	}
+	if len(files) == 0 {
+		t.Fatalf("no txtar nor txt scripts found in dir %s", dir)
+	}
+	slices.Sort(files)
+	return files
+}

doc/website/package-lock.json

@@ -15,6 +15,7 @@
         "@mdx-js/react": "^3.0.0",
         "clsx": "^2.0.0",
         "prism-react-renderer": "^2.3.0",
+        "raw-loader": "^4.0.2",
         "react": "^18.0.0",
         "react-dom": "^18.0.0"
       },
@@ -14477,6 +14478,44 @@
         "node": ">= 0.8"
       }
     },
+    "node_modules/raw-loader": {
+      "version": "4.0.2",
+      "resolved": "https://registry.npmjs.org/raw-loader/-/raw-loader-4.0.2.tgz",
+      "integrity": "sha512-ZnScIV3ag9A4wPX/ZayxL/jZH+euYb6FcUinPcgiQW0+UBtEv0O6Q3lGd3cqJ+GHH+rksEv3Pj99oxJ3u3VIKA==",
+      "license": "MIT",
+      "dependencies": {
+        "loader-utils": "^2.0.0",
+        "schema-utils": "^3.0.0"
+      },
+      "engines": {
+        "node": ">= 10.13.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/webpack"
+      },
+      "peerDependencies": {
+        "webpack": "^4.0.0 || ^5.0.0"
+      }
+    },
+    "node_modules/raw-loader/node_modules/schema-utils": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/schema-utils/-/schema-utils-3.3.0.tgz",
+      "integrity": "sha512-pN/yOAvcC+5rQ5nERGuwrjLlYvLTbCibnZ1I7B1LaiAz9BRBlE9GMgE/eqV30P7aJQUf7Ddimy/RsbYO/GrVGg==",
+      "license": "MIT",
+      "dependencies": {
+        "@types/json-schema": "^7.0.8",
+        "ajv": "^6.12.5",
+        "ajv-keywords": "^3.5.2"
+      },
+      "engines": {
+        "node": ">= 10.13.0"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/webpack"
+      }
+    },
     "node_modules/rc": {
       "version": "1.2.8",
       "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",

doc/website/package.json

@@ -22,6 +22,7 @@
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "prism-react-renderer": "^2.3.0",
+    "raw-loader": "^4.0.2",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },

doc/website/src/components/GitHubLink/index.tsx

@@ -0,0 +1,6 @@
+export default function GitHubLink({ repo, tree, path, children }: { repo: string, commit: string, path: string, children: React.ReactNode }) {
+  const href = `https://github.com/${repo}/tree/${tree}/${path}`
+  return (
+    <a href={href} target="_blank" rel="noopener noreferrer">{children}</a>
+  );
+};

doc/website/static/_redirects

@@ -1,13 +1,15 @@
 /docs                /docs/v1alpha5/ 301
 /docs/               /docs/v1alpha5/ 301
-/docs/tutorial       /docs/v1alpha5/tutorial/ 301
-/docs/tutorial/      /docs/v1alpha5/tutorial/ 301
+/docs/tutorial       /docs/v1alpha5/tutorial/overview/ 301
+/docs/tutorial/      /docs/v1alpha5/tutorial/overview/ 301
 /docs/quickstart     /docs/v1alpha5/tutorial/overview/ 301
 /docs/quickstart/    /docs/v1alpha5/tutorial/overview/ 301
 /docs/overview       /docs/v1alpha5/tutorial/overview/ 301
 /docs/overview/      /docs/v1alpha5/tutorial/overview/ 301
-/docs/topics         /docs/v1alpha5/topics/structures/ 301
-/docs/topics/        /docs/v1alpha5/topics/structures/ 301
+/docs/guides         /docs/v1alpha5/tutorial/overview/ 301
+/docs/guides/        /docs/v1alpha5/tutorial/overview/ 301
+/docs/topics         /docs/v1alpha5/topics/ 301
+/docs/topics/        /docs/v1alpha5/topics/ 301
 /docs/setup          /docs/v1alpha5/tutorial/setup/ 301
 /docs/setup/         /docs/v1alpha5/tutorial/setup/ 301
 /docs/local-cluster  /docs/v1alpha5/topics/local-cluster/ 301
@@ -18,3 +20,14 @@
 /docs/kargo/         /docs/v1alpha5/topics/kargo/ 301
 /docs/comparison     /docs/v1alpha5/topics/comparison/ 301
 /docs/comparison/    /docs/v1alpha5/topics/comparison/ 301
+/docs/support        /docs/v1alpha5/tutorial/overview/#getting-help 301
+/docs/support/       /docs/v1alpha5/tutorial/overview/#getting-help 301
+/docs/api/core       /docs/v1alpha5/api/core/ 301
+/docs/api/core/      /docs/v1alpha5/api/core/ 301
+/docs/api/author     /docs/v1alpha5/api/author/ 301
+/docs/api/author/    /docs/v1alpha5/api/author/ 301
+# Redirect to our own take on the pattern once we figure out what to call it.
+# See: https://discord.com/channels/1299051862418395216/1299055980738383882/1327347525354524805
+/blog/the-rendered-manifests-pattern https://akuity.io/blog/the-rendered-manifests-pattern 301
+# without the s which I always forget
+/blog/the-rendered-manifest-pattern  https://akuity.io/blog/the-rendered-manifests-pattern 301