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
docs: make update-docs for version 0.103.0
2026-03-19 16:54:58 +00:00 · 2025-01-13 09:56:07 -08:00 · 2025-01-12 14:26:27 -08:00 · 2025-01-12 14:25:44 -08:00 · 2025-01-12 14:22:58 -08:00 · 2025-01-12 14:09:45 -08:00
176 changed files with 12182 additions and 787 deletions
--- a/.cspell.json
+++ b/.cspell.json
@@ -29,6 +29,7 @@
    "authpolicy",
    "authproxy",
    "authroutes",
+    "autoload",
    "automount",
    "automounting",
    "autoscaler",
@@ -36,6 +37,7 @@
    "blackbox",
    "buildplan",
    "buildplans",
+    "Buildx",
    "builtinpluginloadingoptions",
    "cachedir",
    "cadvisor",
@@ -44,6 +46,7 @@
    "certificaterequest",
    "certificaterequests",
    "certificatesigningrequests",
+    "chartmuseum",
    "clientset",
    "clsx",
    "clusterexternalsecret",
@@ -58,6 +61,7 @@
    "Cmds",
    "CNCF",
    "CODEOWNERS",
+    "compinit",
    "componentconfig",
    "configdir",
    "configmap",
@@ -71,6 +75,7 @@
    "creds",
    "crossplane",
    "crunchydata",
+    "ctxt",
    "cuecontext",
    "cuelang",
    "customresourcedefinition",
@@ -80,6 +85,7 @@
    "destinationrules",
    "devel",
    "devicecode",
+    "distroless",
    "dnsmasq",
    "dscacheutil",
    "ecrauthorizationtoken",
@@ -98,6 +104,7 @@
    "fieldmaskpb",
    "fieldspec",
    "flushcache",
+    "fluxcd",
    "fullname",
    "gatewayclass",
    "gatewayclasses",
@@ -151,6 +158,7 @@
    "jetstack",
    "jiralert",
    "Jsonnet",
+    "Kargo",
    "kfbh",
    "killall",
    "kubeadm",
@@ -188,6 +196,7 @@
    "mutatingwebhookconfigurations",
    "mvdan",
    "mxcl",
+    "mychart",
    "myhostname",
    "myRegistrKeySecretName",
    "mysecret",
@@ -274,6 +283,7 @@
    "serviceentries",
    "serviceentry",
    "servicemonitor",
+    "sigstore",
    "somevalue",
    "SOMEVAR",
    "sortoptions",
@@ -314,6 +324,7 @@
    "udev",
    "uibutton",
    "Unmarshal",
+    "unshallow",
    "unstage",
    "untar",
    "upbound",
--- a/.github/workflows/container.yaml
+++ b/.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 }}
--- a/.github/workflows/lint.yaml
+++ b/.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
--- a/.github/workflows/test.yaml
+++ b/.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
--- a/39
+++ b/39
@@ -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"]
--- a/4
+++ b/4
@@ -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)
--- a/README.md
+++ b/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/
--- a/api/author/v1alpha5/definitions.go
+++ b/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.
--- a/api/core/v1alpha5/types.go
+++ b/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

@@ -146,9 +161,26 @@ type Chart struct {
 }

 // Repository represents a [Helm] [Chart] repository.
+//
+// The Auth field is useful to configure http basic authentication to the Helm
+// repository.  Holos gets the username and password from the environment
+// variables represented by the Auth field.
 type Repository struct {
 	Name string `json:"name" yaml:"name"`
 	URL  string `json:"url" yaml:"url"`
+	Auth Auth   `json:"auth,omitempty" yaml:"auth,omitempty"`
+}
+
+// Auth represents environment variable names containing auth credentials.
+type Auth struct {
+	Username AuthSource `json:"username" yaml:"username"`
+	Password AuthSource `json:"password" yaml:"password"`
+}
+
+// AuthSource represents a source for the value of an [Auth] field.
+type AuthSource struct {
+	Value   string `json:"value,omitempty" yaml:"value,omitempty"`
+	FromEnv string `json:"fromEnv,omitempty" yaml:"fromEnv,omitempty"`
 }

 // Transformer combines multiple inputs from prior [Generator] or [Transformer]
@@ -246,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"`
 }
@@ -286,6 +318,10 @@ type Component struct {
 	// Path represents the path of the component relative to the platform root.
 	// Injected as the tag variable "holos_component_path".
 	Path string `json:"path" yaml:"path"`
+	// Instances represents additional cue instance paths to unify with Path.
+	// Useful to unify data files into a component BuildPlan.  Added in holos
+	// 0.101.7.
+	Instances []Instance `json:"instances,omitempty" yaml:"instances,omitempty"`
 	// WriteTo represents the holos render component --write-to flag.  If empty,
 	// the default value for the --write-to flag is used.
 	WriteTo string `json:"writeTo,omitempty" yaml:"writeTo,omitempty"`
@@ -299,6 +335,30 @@ 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"`
 }
+
+// Instance represents a data instance to unify with the configuration.
+//
+// Useful to unify json and yaml files with cue configuration files for
+// integration with other tools.  For example, executing holos render platform
+// from a pull request workflow after [Kargo] executes the [yaml update] and
+// [git wait for pr] promotion steps.
+//
+// [Kargo]: https://docs.kargo.io/
+// [yaml update]: https://docs.kargo.io/references/promotion-steps#yaml-update
+// [git wait for pr]: https://docs.kargo.io/references/promotion-steps#git-wait-for-pr
+type Instance struct {
+	// Kind is a discriminator.
+	Kind string `json:"kind" yaml:"kind" cue:"\"ExtractYAML\""`
+	// Ignored unless kind is ExtractYAML.
+	ExtractYAML ExtractYAML `json:"extractYAML,omitempty" yaml:"extractYAML,omitempty"`
+}
+
+// ExtractYAML represents a cue data instance encoded as yaml or json. If Path
+// refers to a directory all files in the directory are extracted
+// non-recursively.  Otherwise, path must refer to a file.
+type ExtractYAML struct {
+	Path string `json:"path" yaml:"path"`
+}
--- a/cmd/cmd.go
+++ b/cmd/cmd.go
@@ -0,0 +1,63 @@
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"os"
+	"runtime/pprof"
+	"runtime/trace"
+
+	"github.com/holos-run/holos/internal/cli"
+	"github.com/holos-run/holos/internal/holos"
+)
+
+// MakeMain makes a main function for the cli or tests.
+func MakeMain(options ...holos.Option) func() int {
+	return func() (exitCode int) {
+		cfg := holos.New(options...)
+		slog.SetDefault(cfg.Logger())
+		ctx := context.Background()
+
+		if format := os.Getenv("HOLOS_CPU_PROFILE"); format != "" {
+			f, _ := os.Create(fmt.Sprintf(format, os.Getppid(), os.Getpid()))
+			err := pprof.StartCPUProfile(f)
+			defer func() {
+				pprof.StopCPUProfile()
+				f.Close()
+			}()
+			if err != nil {
+				return cli.HandleError(ctx, err, cfg)
+			}
+		}
+		defer memProfile(ctx, cfg)
+
+		if format := os.Getenv("HOLOS_TRACE"); format != "" {
+			f, _ := os.Create(fmt.Sprintf(format, os.Getppid(), os.Getpid()))
+			err := trace.Start(f)
+			defer func() {
+				trace.Stop()
+				f.Close()
+			}()
+			if err != nil {
+				return cli.HandleError(ctx, err, cfg)
+			}
+		}
+
+		feature := &holos.EnvFlagger{}
+		if err := cli.New(cfg, feature).ExecuteContext(ctx); err != nil {
+			return cli.HandleError(ctx, err, cfg)
+		}
+		return 0
+	}
+}
+
+func memProfile(ctx context.Context, cfg *holos.Config) {
+	if format := os.Getenv("HOLOS_MEM_PROFILE"); format != "" {
+		f, _ := os.Create(fmt.Sprintf(format, os.Getppid(), os.Getpid()))
+		defer f.Close()
+		if err := pprof.WriteHeapProfile(f); err != nil {
+			_ = cli.HandleError(ctx, err, cfg)
+		}
+	}
+}
--- a/cmd/holos/main.go
+++ b/cmd/holos/main.go
@@ -3,9 +3,9 @@ package main
 import (
 	"os"

-	"github.com/holos-run/holos/internal/cli"
+	"github.com/holos-run/holos/cmd"
 )

 func main() {
-	os.Exit(cli.MakeMain()())
+	os.Exit(cmd.MakeMain()())
 }
--- a/cmd/holos/main_test.go
+++ b/cmd/holos/main_test.go
@@ -6,13 +6,13 @@ import (
 	"testing"

 	cue "cuelang.org/go/cmd/cue/cmd"
-	"github.com/holos-run/holos/internal/cli"
+	"github.com/holos-run/holos/cmd"
 	"github.com/rogpeppe/go-internal/testscript"
 )

 func TestMain(m *testing.M) {
 	os.Exit(testscript.RunMain(m, map[string]func() int{
-		"holos": cli.MakeMain(),
+		"holos": cmd.MakeMain(),
 		"cue":   cue.Main,
 	}))
 }
--- a/cmd/holos/tests/v1alpha5/issues/helm-pull-errors.txt
+++ b/cmd/holos/tests/v1alpha5/issues/helm-pull-errors.txt
@@ -1,38 +0,0 @@
-# https://github.com/holos-run/holos/issues/332
-env HOME=$WORK
-# Mock with a stub helm command
-env PATH=$WORK/bin:$PATH
-chmod 755 bin/helm
-# Initialize the platform
-exec holos init platform v1alpha5 --force
-# when helm update returns an error
-! exec holos render platform
-# holos should log the helm error to stderr
-stderr 'Error: chart "podinfo" matching 0.0.0 not found in podinfo index'
-- bin/helm --
-#! /bin/bash
-echo 'Error: chart "podinfo" matching 0.0.0 not found in podinfo index' >&2
-exit 2
-- platform/podinfo.cue --
-package holos
-
-Platform: Components: podinfo: {
-	name: "podinfo"
-	path: "components/podinfo"
-}
-- components/podinfo/podinfo.cue --
-package holos
-
-// Produce a helm chart build plan.
-holos: HelmChart.BuildPlan
-
-HelmChart: #Helm & {
-	Name: "podinfo"
-	Chart: {
-		version: "0.0.0"
-		repository: {
-			name: "podinfo"
-			url:  "https://stefanprodan.github.io/podinfo"
-		}
-	}
-}
--- a/doc/md/api/author.md
+++ b/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.
--- a/doc/md/api/core.md
+++ b/doc/md/api/core.md
@@ -15,17 +15,21 @@ Package core contains schemas for a [Platform](<#Platform>) and [BuildPlan](<#Bu
 ## Index

 - [type Artifact](<#Artifact>)
+- [type Auth](<#Auth>)
+- [type AuthSource](<#AuthSource>)
 - [type BuildPlan](<#BuildPlan>)
 - [type BuildPlanSpec](<#BuildPlanSpec>)
 - [type Chart](<#Chart>)
 - [type Command](<#Command>)
 - [type Component](<#Component>)
+- [type ExtractYAML](<#ExtractYAML>)
 - [type File](<#File>)
 - [type FileContent](<#FileContent>)
 - [type FileContentMap](<#FileContentMap>)
 - [type FilePath](<#FilePath>)
 - [type Generator](<#Generator>)
 - [type Helm](<#Helm>)
+- [type Instance](<#Instance>)
 - [type InternalLabel](<#InternalLabel>)
 - [type Join](<#Join>)
 - [type Kind](<#Kind>)
@@ -39,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>)


@@ -65,6 +70,30 @@ type Artifact struct {
 }
 ```

+<a name="Auth"></a>
+## type Auth {#Auth}
+
+Auth represents environment variable names containing auth credentials.
+
+```go
+type Auth struct {
+    Username AuthSource `json:"username" yaml:"username"`
+    Password AuthSource `json:"password" yaml:"password"`
+}
+```
+
+<a name="AuthSource"></a>
+## type AuthSource {#AuthSource}
+
+AuthSource represents a source for the value of an [Auth](<#Auth>) field.
+
+```go
+type AuthSource struct {
+    Value   string `json:"value,omitempty" yaml:"value,omitempty"`
+    FromEnv string `json:"fromEnv,omitempty" yaml:"fromEnv,omitempty"`
+}
+```
+
 <a name="BuildPlan"></a>
 ## type BuildPlan {#BuildPlan}

@@ -143,6 +172,10 @@ type Component struct {
    // Path represents the path of the component relative to the platform root.
    // Injected as the tag variable "holos_component_path".
    Path string `json:"path" yaml:"path"`
+    // Instances represents additional cue instance paths to unify with Path.
+    // Useful to unify data files into a component BuildPlan.  Added in holos
+    // 0.101.7.
+    Instances []Instance `json:"instances,omitempty" yaml:"instances,omitempty"`
    // WriteTo represents the holos render component --write-to flag.  If empty,
    // the default value for the --write-to flag is used.
    WriteTo string `json:"writeTo,omitempty" yaml:"writeTo,omitempty"`
@@ -156,11 +189,22 @@ 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"`
 }
 ```

+<a name="ExtractYAML"></a>
+## type ExtractYAML {#ExtractYAML}
+
+ExtractYAML represents a cue data instance encoded as yaml or json. If Path refers to a directory all files in the directory are extracted non\-recursively. Otherwise, path must refer to a file.
+
+```go
+type ExtractYAML struct {
+    Path string `json:"path" yaml:"path"`
+}
+```
+
 <a name="File"></a>
 ## type File {#File}

@@ -240,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
@@ -253,6 +301,22 @@ type Helm struct {
 }
 ```

+<a name="Instance"></a>
+## type Instance {#Instance}
+
+Instance represents a data instance to unify with the configuration.
+
+Useful to unify json and yaml files with cue configuration files for integration with other tools. For example, executing holos render platform from a pull request workflow after [Kargo](<https://docs.kargo.io/>) executes the [yaml update](<https://docs.kargo.io/references/promotion-steps#yaml-update>) and [git wait for pr](<https://docs.kargo.io/references/promotion-steps#git-wait-for-pr>) promotion steps.
+
+```go
+type Instance struct {
+    // Kind is a discriminator.
+    Kind string `json:"kind" yaml:"kind" cue:"\"ExtractYAML\""`
+    // Ignored unless kind is ExtractYAML.
+    ExtractYAML ExtractYAML `json:"extractYAML,omitempty" yaml:"extractYAML,omitempty"`
+}
+```
+
 <a name="InternalLabel"></a>
 ## type InternalLabel {#InternalLabel}

@@ -317,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"`
 }
@@ -365,10 +429,13 @@ type PlatformSpec struct {

 Repository represents a [Helm](<#Helm>) [Chart](<#Chart>) repository.

+The Auth field is useful to configure http basic authentication to the Helm repository. Holos gets the username and password from the environment variables represented by the Auth field.
+
 ```go
 type Repository struct {
    Name string `json:"name" yaml:"name"`
    URL  string `json:"url" yaml:"url"`
+    Auth Auth   `json:"auth,omitempty" yaml:"auth,omitempty"`
 }
 ```

@@ -431,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}

--- a/doc/md/topics/comparison.mdx
+++ b/doc/md/topics/comparison.mdx
@@ -0,0 +1,57 @@
+---
+description: Holos compared to other tools
+sidebar_label: Comparison
+slug: comparison
+sidebar_position: 40
+---
+
+{/* cspell:ignore Prodan, rollouts */}
+
+# Holos compared to other tools
+
+## Timoni
+
+Holos and Timoni both aim to solve similar problems but approach them at
+different levels of the stack.
+
+Timoni focuses on managing applications by evaluating [CUE] stored in OCI
+containers. Its creator, Stephan Prodan, envisions a controller that applies the
+resulting manifests. In this process, Timoni defers to [Flux] for managing Helm
+charts within the cluster.
+
+In contrast, Holos implements the [Rendered Manifests Pattern] and takes a
+different approach, particularly in how it handles [Helm] charts. Like
+[ArgoCD], Holos renders Helm charts into manifests using the `helm template`
+command in its rendering pipeline. Holos differs from Timoni in several important
+ways:
+
+1. **Separation of Responsibilities:**  Holos stops short of applying
+rendered manifests to a cluster, leaving that task to existing tools like
+[ArgoCD], [Flux], or even basic `kubectl apply` commands.
+
+2. **Ecosystem Integration:**  By focusing solely on rendering Kubernetes
+manifests, Holos creates space for other tools to handle deployment and
+management. For instance, Holos integrates seamlessly with [Kargo] for
+progressive rollouts, as [Kargo] operates between Holos and the Kubernetes API.
+This approach ensures that you're not locked into any specific tool and can
+choose the best solution for each task.
+
+3. **Platform Integration:** Holos focuses on integrating multiple Components
+into a larger Platform. In Holos terminology, a Component refers to a wrapper
+for [Helm] charts, [Kustomize] bases, or raw YAML files, integrated into the
+rendering pipeline through [CUE].  A Platform represents the full combination of
+these components.
+
+4. **Explicit Rendering Pipeline:** Holos emphasizes flexibility in its
+rendering pipeline. The system allows any tool that generates Kubernetes
+manifests to be wrapped in a Generator, which can then feed into existing
+transformers like [Kustomize]. This explicit separation makes Holos highly
+adaptable for different workflows.
+
+[Kargo]: https://kargo.io/
+[Flux]: https://fluxcd.io
+[Helm]: https://helm.sh
+[ArgoCD]: https://argoproj.github.io/cd/
+[Kustomize]: https://kustomize.io/
+[CUE]: https://cuelang.org/
+[Rendered Manifests Pattern]: https://akuity.io/blog/the-rendered-manifests-pattern
--- a/doc/md/topics/gitops/flux-kustomization.mdx
+++ b/doc/md/topics/gitops/flux-kustomization.mdx
@@ -0,0 +1,218 @@
+---
+slug: flux-kustomization
+title: Flux Kustomization
+description: Configuring a Kustomization for each Component.
+sidebar_position: 120
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CommonComponent from '../../common/example-component.mdx';
+import CommonComponentIntegrate from '../../common/example-component-integrate.mdx';
+
+# Flux Kustomization
+
+## Overview
+
+This topic covers how to mix in a Flux Kustomization to all components.  We'll
+use the `Artifacts` field of [ComponentConfig] defined by the author schema.
+
+## The Code
+
+### Generating the structure
+
+Use `holos` to generate a minimal platform directory structure.  Start by
+creating a blank directory to hold the platform configuration.
+
+```shell
+mkdir holos-flux-kustomization && cd holos-flux-kustomization
+```
+
+```shell
+holos init platform v1alpha5
+```
+
+### Creating an example Component
+
+<CommonComponent />
+<CommonComponentIntegrate />
+
+## Adding Flux Kustomizations
+
+Configure Holos to render a [Kustomization] by defining an [Artifact] for it in
+every BuildPlan holos produces.  We're unifying our custom configuration with
+the existing `#ComponentConfig` defined in `schema.cue`.
+
+```bash
+cat <<EOF >flux-kustomization.cue
+```
+```cue showLineNumbers
+package holos
+
+import (
+	"path"
+	flux "kustomize.toolkit.fluxcd.io/kustomization/v1"
+)
+
+#ComponentConfig: {
+	Name:          _
+	OutputBaseDir: _
+
+	let ArtifactPath = path.Join([OutputBaseDir, "gitops", "\(Name).kustomization.gen.yaml"], path.Unix)
+	let ResourcesPath = path.Join(["deploy", OutputBaseDir, "components", Name], path.Unix)
+
+	Artifacts: "\(Name)-kustomization": {
+		artifact: ArtifactPath
+		generators: [{
+			kind:   "Resources"
+			output: artifact
+			resources: Kustomization: (Name): flux.#Kustomization & {
+				metadata: name:      Name
+				metadata: namespace: "default"
+				spec: {
+					interval: "5m"
+					timeout:  "1m"
+					prune:    true
+					path:     ResourcesPath
+					sourceRef: {
+						kind: "GitRepository"
+						name: "webapp"
+					}
+				}
+			}
+		}]
+	}
+}
+```
+```bash
+EOF
+```
+
+## Inspecting the BuildPlan
+
+Our customized `#ComponentConfig` results in the following `BuildPlan`.
+
+:::note
+The second artifact around line 40 contains the configured `Kustomization`
+resource.
+:::
+
+<Tabs groupId="55075C71-02E8-4222-88C0-2D52C82D18FC">
+  <TabItem value="command" label="Command">
+```bash
+holos cue export --expression holos --out=yaml ./components/podinfo
+```
+  </TabItem>
+  <TabItem value="output" label="Output">
+```yaml showLineNumbers
+kind: BuildPlan
+apiVersion: v1alpha5
+metadata:
+  name: podinfo
+spec:
+  artifacts:
+    - artifact: components/podinfo/podinfo.gen.yaml
+      generators:
+        - kind: Helm
+          output: helm.gen.yaml
+          helm:
+            chart:
+              name: podinfo
+              version: 6.6.2
+              release: podinfo
+              repository:
+                name: podinfo
+                url: https://stefanprodan.github.io/podinfo
+            values:
+              ui:
+                message: Hello World
+            enableHooks: false
+        - kind: Resources
+          output: resources.gen.yaml
+          resources: {}
+      validators: []
+      transformers:
+        - kind: Kustomize
+          inputs:
+            - helm.gen.yaml
+            - resources.gen.yaml
+          output: components/podinfo/podinfo.gen.yaml
+          kustomize:
+            kustomization:
+              resources:
+                - helm.gen.yaml
+                - resources.gen.yaml
+              kind: Kustomization
+              apiVersion: kustomize.config.k8s.io/v1beta1
+    - artifact: gitops/podinfo.kustomization.gen.yaml
+      generators:
+        - kind: Resources
+          output: gitops/podinfo.kustomization.gen.yaml
+          resources:
+            Kustomization:
+              podinfo:
+                apiVersion: kustomize.toolkit.fluxcd.io/v1
+                kind: Kustomization
+                metadata:
+                  name: podinfo
+                  namespace: default
+                spec:
+                  interval: 5m
+                  path: deploy/components/podinfo
+                  prune: true
+                  sourceRef:
+                    kind: GitRepository
+                    name: webapp
+                  timeout: 1m
+```
+  </TabItem>
+</Tabs>
+
+## Rendering manifests
+
+<Tabs groupId="E150C802-7162-4FBF-82A7-77D9ADAEE847">
+  <TabItem value="command" label="Command">
+```bash
+holos render platform
+```
+  </TabItem>
+  <TabItem value="output" label="Output">
+```
+rendered podinfo in 140.341417ms
+rendered platform in 140.441333ms
+```
+  </TabItem>
+</Tabs>
+
+## Reviewing the Kustomization
+
+The Artifact we added to `#ComponentConfig` will produce a Flux Kustomization
+resource for every component in the platform.  The output in this example is
+located at:
+
+```txt
+deploy/gitops/podinfo.kustomization.gen.yaml
+```
+```yaml showLineNumbers
+apiVersion: kustomize.toolkit.fluxcd.io/v1
+kind: Kustomization
+metadata:
+    name: podinfo
+    namespace: default
+spec:
+    interval: 5m
+    path: deploy/components/podinfo
+    prune: true
+    sourceRef:
+        kind: GitRepository
+        name: webapp
+    timeout: 1m
+```
+
+[podinfo]: https://github.com/stefanprodan/podinfo
+[CUE Module]: https://cuelang.org/docs/reference/modules/
+[CUE Tags]: https://cuelang.org/docs/howto/inject-value-into-evaluation-using-tag-attribute/
+[Kustomization]: https://fluxcd.io/flux/components/kustomize/kustomizations/
+[Platform]: ../../api/author.md#Platform
+[ComponentConfig]: ../../api/author.md#ComponentConfig
+[Artifact]: ../../api/core.md#Artifact
--- a/doc/md/topics/oci-helm-charts.mdx
+++ b/doc/md/topics/oci-helm-charts.mdx
@@ -0,0 +1,65 @@
+---
+description: OCI Helm Charts
+slug: oci-helm-charts
+sidebar_position: 710
+---
+
+# OCI Helm Charts
+
+Holos supports OCI Helm charts.  Use the following example to get started.
+
+```bash
+mkdir -p oci-helm && cd oci-helm
+holos init platform v1alpha5
+```
+
+```bash
+mkdir -p components/podinfo-oci
+cat <<EOF > components/podinfo-oci/podinfo-oci.cue
+```
+```cue showLineNumbers
+package holos
+
+holos: Component.BuildPlan
+
+Component: #Helm & {
+	Chart: {
+		name:    "oci://ghcr.io/stefanprodan/charts/podinfo"
+		release: "podinfo"
+		version: "6.6.2"
+	}
+}
+```
+```bash
+EOF
+```
+
+Register the component with the platform.
+
+```bash
+cat <<EOF >platform/podinfo-oci.cue
+```
+```cue showLineNumbers
+package holos
+
+Platform: Components: podinfo: {
+	name: "podinfo-oci"
+	path: "components/podinfo-oci"
+}
+```
+```bash
+EOF
+```
+
+The OCI chart is cached in the vendor directory and rendered.
+
+```bash
+holos render platform
+```
+
+```txt
+Pulled: ghcr.io/stefanprodan/charts/podinfo:6.6.2
+Digest: sha256:83295d47de6d6ca634ed4b952a7572fc176bcc38854d0c11ca0fa197bc5f1154
+rendered podinfo-oci in 7.21581325s
+rendered platform in 7.216199167s
+```
--- a/doc/md/topics/private-helm.mdx
+++ b/doc/md/topics/private-helm.mdx
@@ -0,0 +1,183 @@
+---
+description: Private Helm Repositories
+slug: private-helm
+sidebar_position: 700
+---
+
+# Private Helm
+
+Holos supports private Helm repositories accessed with http basic authentication
+since `v0.101.4`.  Use the following command to update your author and core
+schemas to support this configuration.
+
+```bash
+holos init platform v1alpha5 --force
+```
+
+## Configuration
+
+Holos uses the Helm SDK and defers to it for authentication to private
+repositories.  Each Helm Generator supports providing http basic authentication
+credentials from environment variables.
+
+For example, the following BuildPlan causes `holos` to get the admin username
+password from the `HOLOS_TEST_PASS` environment variable.
+
+```bash
+mkdir -p projects/holos/components/private-chart
+cat <<EOF > projects/holos/components/private-chart/private-chart.cue
+```
+```cue showLineNumbers
+package holos
+
+holos: Component.BuildPlan
+
+// Test holos can access a private repository with basic auth.
+// https://github.com/holos-run/holos/issues/370
+Component: #Helm & {
+	Chart: {
+		name:    "mychart"
+		version: "0.1.0"
+		repository: {
+			name: "holos-test"
+			url:  "https://charts.holos.localhost"
+			// auth: username: fromEnv:   "HOLOS_TEST_USER"
+			auth: username: value:   "admin"
+			auth: password: fromEnv: "HOLOS_TEST_PASS"
+		}
+	}
+}
+```
+```bash
+EOF
+```
+
+## Verification
+
+Verify `holos` can access a private Helm repository by setting [ChartMuseum] up
+on a [Local Cluster].  We'll use https with basic auth to authenticate to the
+chart repository.
+
+Using the [bank of holos] repository, deploy chart museum:
+
+```bash
+holos render platform -t ChartMuseum
+```
+
+Apply the manifests:
+
+```bash
+kubectl apply --server-side=true -f deploy/clusters/workload/projects/holos/components/chart-museum
+kubectl apply --server-side=true -f deploy/clusters/workload/projects/network/components/httproutes
+```
+
+Get the admin password:
+
+```bash
+kubectl get secret -n holos chartmuseum-auth -o json \
+  | jq --exit-status -r '.data.password | @base64d'
+```
+
+Add a local repo:
+
+```bash
+helm repo add holos-test https://charts.holos.localhost --username admin
+```
+```txt
+Password:
+"holos-test" has been added to your repositories
+```
+
+:::note
+Helm by default stores this password in `~/Library/Preferences/helm/repositories.yaml`
+:::
+
+Create a chart:
+
+```bash
+helm create mychart
+```
+```txt
+Creating mychart
+```
+
+Package it up.
+
+```bash
+helm package mychart
+```
+```txt
+Successfully packaged chart and saved it to: mychart-0.1.0.tgz
+```
+
+Publish it.
+
+```bash
+curl --user "admin:$(pbpaste)" --data-binary "@mychart-0.1.0.tgz" https://charts.holos.localhost/api/charts
+```
+```json
+{"saved":true}
+```
+
+Remove all cached charts:
+
+```bash
+find . -name vendor | xargs rm -rf
+```
+
+Render the chart:
+
+```bash
+cat <<EOF > test-private-repo.cue
+```
+```cue showLineNumbers
+@if(TestPrivateRepo)
+package holos
+
+// Test holos can access a private repository with basic auth.
+// https://github.com/holos-run/holos/issues/370
+Projects: holos: #ProjectBuilder & {
+        team: "holos-authors"
+
+        namespaces: holos:            _
+        _components: "private-chart": _
+}
+```
+```bash
+EOF
+```
+
+```
+time holos render platform -t TestPrivateRepo
+```
+
+Check the chart was pulled and cached:
+
+```shell
+tree ./projects/holos/components/private-chart/vendor
+```
+```txt
+./projects/holos/components/private-chart/vendor
+└── 0.1.0
+    ├── mychart
+    │   ├── Chart.yaml
+    │   ├── mychart-0.1.0.tgz
+    │   ├── templates
+    │   │   ├── NOTES.txt
+    │   │   ├── _helpers.tpl
+    │   │   ├── deployment.yaml
+    │   │   ├── hpa.yaml
+    │   │   ├── ingress.yaml
+    │   │   ├── service.yaml
+    │   │   ├── serviceaccount.yaml
+    │   │   └── tests
+    │   │       └── test-connection.yaml
+    │   └── values.yaml
+    └── mychart-0.1.0.tgz
+
+6 directories, 11 files
+```
+
+[Local Cluster]: ./local-cluster.mdx
+[ChartMuseum]: https://chartmuseum.com/docs/
+[bank of holos]: https://github.com/holos-run/bank-of-holos
--- a/doc/md/topics/progressive-delivery/.gitignore
+++ b/doc/md/topics/progressive-delivery/.gitignore
@@ -0,0 +1,2 @@
+kargo-demo/
+.tmp/
--- a/doc/md/topics/progressive-delivery/_platform-components/examples/01-clone.txtar
+++ b/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'...
--- a/doc/md/topics/progressive-delivery/_platform-components/examples/10-cert-manager.txtar
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/examples/20-holos-version.txtar
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/examples/30-git-url.txtar
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/script-01-clone/command.sh
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/script-01-clone/git.commit
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-01-clone/git.commit
@@ -0,0 +1 @@
+238fe0403c99eeea4f4fb764a88b780554048414
--- a/doc/md/topics/progressive-delivery/_platform-components/script-01-clone/output.txt
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-01-clone/output.txt
@@ -0,0 +1 @@
+Cloning into 'kargo-demo'...
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.basename
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.basename
@@ -0,0 +1 @@
+cert-manager.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.path
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.path
@@ -0,0 +1 @@
+stacks/security/components/cert-manager/cert-manager.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/component.txt
+++ b/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
+	}
+}
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.basename
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.basename
@@ -0,0 +1 @@
+certmanager.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.path
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.path
@@ -0,0 +1 @@
+config/certmanager/certmanager.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/config.txt
+++ b/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]+$"
+	}
+}
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.basename
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.basename
@@ -0,0 +1 @@
+stacks.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.path
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.path
@@ -0,0 +1 @@
+platform/stacks.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/entrypoint.txt
+++ b/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
+}
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.basename
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.basename
@@ -0,0 +1 @@
+security.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.path
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.path
@@ -0,0 +1 @@
+config/platform/security.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-10-cert-manager/stacks.txt
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/script-20-holos-version/command.sh
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-20-holos-version/command.sh
@@ -0,0 +1 @@
+holos --version
--- a/doc/md/topics/progressive-delivery/_platform-components/script-20-holos-version/output.txt
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-20-holos-version/output.txt
@@ -0,0 +1 @@
+0.102.3
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/body.txt
+++ b/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"
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/code.want.cue
+++ b/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"
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/command.sh
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/command.sh
@@ -0,0 +1 @@
+holos render platform -t ${GH_USER}
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/commit.sh
+++ b/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"
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/commit.txt
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/diff.patch
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/diff.sh
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/diff.sh
@@ -0,0 +1 @@
+git diff
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/header.sh
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/header.sh
@@ -0,0 +1 @@
+cat <<EOF > config/platform/organization_${GH_USER}.cue
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/output.txt
+++ b/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
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/trailer.sh
+++ b/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/trailer.sh
@@ -0,0 +1 @@
+EOF
--- a/doc/md/topics/progressive-delivery/_platform-components/script-30-git-url/update.sh
+++ b/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"
--- a/doc/md/topics/progressive-delivery/_platform-components/tour/tour.txtar
+++ b/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
--- a/doc/md/topics/progressive-delivery/docs_test.go
+++ b/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
+}
--- a/doc/md/topics/progressive-delivery/index.mdx
+++ b/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
--- a/doc/md/topics/progressive-delivery/platform-components.mdx
+++ b/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
--- a/doc/md/topics/progressive-delivery/workloads.mdx
+++ b/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.
+*/}
--- a/doc/md/topics/structures/environments.mdx
+++ b/doc/md/topics/structures/environments.mdx
@@ -45,7 +45,40 @@ holos init platform v1alpha5

 ### Using an example Component

-<CommonComponent />
+Create a directory for the example `podinfo` component we'll use to render
+platform manifests.
+
+```bash
+mkdir -p components/podinfo
+```
+
+Create the CUE configuration for the example `podinfo` component.
+
+```bash
+cat <<EOF >components/podinfo/podinfo.cue
+```
+```cue showLineNumbers
+package holos
+
+holos: Component.BuildPlan
+
+Component: #Helm & {
+	Chart: {
+		name:    "podinfo"
+		version: "6.6.2"
+		repository: {
+			name: "podinfo"
+			url:  "https://stefanprodan.github.io/podinfo"
+		}
+	}
+	Values: ui: {
+		message: string | *"Hello World" @tag(message, type=string)
+	}
+}
+```
+```bash
+EOF
+```

 We'll integrate the component with the platform after we define the
 configuration structures.
@@ -277,6 +310,9 @@ let ProdPodinfo = {
 	parameters: EnvironmentName:       "prod-\(_city)"
 }
 ```
+```
+EOF
+```

 ### Using the environment

--- a/doc/md/topics/support.mdx
+++ b/doc/md/topics/support.mdx
--- a/doc/md/tutorial/_helm-values/examples/01-holos-version.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/examples/02-helm-values.txt
+++ b/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(-)
--- a/doc/md/tutorial/_helm-values/script-01-holos-version/command.sh
+++ b/doc/md/tutorial/_helm-values/script-01-holos-version/command.sh
@@ -0,0 +1 @@
+holos --version
--- a/doc/md/tutorial/_helm-values/script-01-holos-version/output.txt
+++ b/doc/md/tutorial/_helm-values/script-01-holos-version/output.txt
@@ -0,0 +1 @@
+0.102.5
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-body.cue
+++ b/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
+}
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-git-commit.sh
+++ b/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'
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-git-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-header.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-common-config-header.sh
@@ -0,0 +1 @@
+cat <<EOF > config/prometheus/blackbox.cue
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-body.cue
+++ b/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"
+		}
+	}
+}
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-header.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/blackbox-component-header.sh
@@ -0,0 +1 @@
+cat <<EOF > components/blackbox/blackbox.cue
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-git-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-git.sh
+++ b/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'
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.sh
@@ -0,0 +1 @@
+patch -p1 < values.patch
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-patch.txt
+++ b/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'
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-rm.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/common-config-rm.sh
@@ -0,0 +1 @@
+rm values.patch
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/eof-trailer.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/eof-trailer.sh
@@ -0,0 +1 @@
+EOF
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/git-diff.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/git-diff.sh
@@ -0,0 +1 @@
+git diff
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/git-init.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/git-init.sh
@@ -0,0 +1 @@
+git init . && git add . && git commit -m "initial commit"
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/git.diff
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/import-blackbox-values.sh
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/import-prometheus-values.sh
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-commit.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-commit.sh
@@ -0,0 +1 @@
+git add . && git commit -m 'import values'
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/import-values-git-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/import-values-render-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-and-init.sh
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-common-config.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-common-config.sh
@@ -0,0 +1 @@
+mkdir -p config/prometheus
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-components.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/mkdir-components.sh
@@ -0,0 +1 @@
+mkdir -p components/prometheus components/blackbox
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-body.cue
+++ b/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"
+		}
+	}
+}
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-header.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/prometheus-component-header.sh
@@ -0,0 +1 @@
+cat <<EOF > components/prometheus/prometheus.cue
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/register-components-body.cue
+++ b/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"
+	}
+}
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/register-components-git-commit-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/register-components-git-commit.sh
+++ b/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'
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/register-components-header.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/register-components-header.sh
@@ -0,0 +1 @@
+cat <<EOF > platform/prometheus.cue
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/register-components-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/render.sh
+++ b/doc/md/tutorial/_helm-values/script-02-helm-values/render.sh
@@ -0,0 +1 @@
+holos render platform
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-git-commit.sh
+++ b/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'
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-git-output.txt
+++ b/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(-)
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/reviewing-changes-render-output.txt
+++ b/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
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/update.sh
+++ b/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"
--- a/doc/md/tutorial/_helm-values/script-02-helm-values/values.patch
+++ b/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"
--- a/doc/md/tutorial/helm-values.mdx
+++ b/doc/md/tutorial/helm-values.mdx
@@ -7,6 +7,8 @@ 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" />
@@ -28,84 +30,69 @@ In this tutorial, we'll manage the [prometheus] and [blackbox] Helm charts. By
 default, the upstream `values.yaml` files are misconfigured, causing Prometheus
 to connect to Blackbox at the wrong host and port.

+## The Video
+
+The video below enhances this tutorial by offering greater detail on the issue
+of poorly integrated Helm charts and the solution we've provided. If you're
+looking for a deeper explanation of the code being presented, this video is a great
+resource.
+
+{/* cspell:disable-next-line */}
+<YouTube id="PSdceGlhHGo"/>
+
 ## 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>

@@ -113,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>

@@ -179,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.
@@ -204,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
@@ -275,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>

@@ -354,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>

@@ -376,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>

@@ -483,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>

@@ -513,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
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Jeff McCune	700c6975f1	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	2025-01-13 09:56:07 -08:00
Jeff McCune	e9d1240d63	docs: make update-docs for version 0.103.0	2025-01-12 14:26:27 -08:00
Gary Larizza	03fa4eaaa2	docs: Helm Values test updates * Convert all files with.period.separators to hyphen-separators. * Rename and markdown_test.go to be specific to Helm Values. * Move helm-values_test.go to be in the same directory as the Helm Values doc. * Move Blackbox common configuration CUE file to `config/prometheus` so it can be imported as necessary. * Use explicit import statements for Blackbox common config in `blackbox` and `prometheus` components. Closes: #399	2025-01-12 14:25:44 -08:00
Jeff McCune	e363f3a597	docs: add make update-docs task We need to run this prior to tagging a release otherwise the tests fail for the new version string.	2025-01-12 14:22:58 -08:00
Jeff McCune	8b49ed93be	docs: release version 0.103.0	2025-01-12 14:09:45 -08:00
Jeff McCune	d2be9fe278	helm: add valueFiles for migration from an ApplicationSet Without this patch migrating from [helm hierarchies] to Holos requires the user to unify the value hierarchy. This is a problem because helm hierarchies are difficult to unify because it's not clear if or why a value is used in the final results. This makes it difficult to identify how to resolve conflicts. This patch adds `valueFiles` field to the Helm component kind. This field is intended to provide a direct migration path from the ApplicationSet.spec.template.spec.sources.helm.valueFiles field. With this patch, users can directly migrate the values files to CUE using `@embed`, then directly migrate the valueFiles field to reference the values from within CUE. Note we actively discourage the use of Helm value hierarchies. The feature is intended as a temporary migration tool. We encourage the use of CUE unification instead. After migration, the valueFiles field should be refactored to the values field as one unified structure in CUE. The valueFiles field makes this second order migration easier becuase we can inspect and verify the complete rendered output, allowing us to determine if a value is actually used in the final configuration or is overridden. [helm hierarchies]: https://medium.com/containers-101/using-helm-hierarchies-in-multi-source-argo-cd-applications-for-promoting-to-different-gitops-133c3bc93678	2025-01-12 13:30:29 -08:00
Jeff McCune	6ec341bbb1	docs: redirect /docs/api/core	2025-01-10 15:02:12 -08:00
Jeff McCune	13a4305b78	docs: add redirect for /blog/rendered-manifest-pattern (manifest instead of manifests)	2025-01-10 14:50:26 -08:00
Jeff McCune	0cfce3a823	docs: redirect rendered manifests pattern for now Need a URL we can redirect when we publish our own variation on the pattern with a link back to Akuity.	2025-01-10 10:55:06 -08:00
Jeff McCune	61d7539e1c	docs: fix /docs/guides/ redirect	2025-01-09 16:03:50 -08:00
Jeff McCune	bf84724137	docs: add redirects for github.com/holos-run readme	2025-01-09 15:11:04 -08:00
Jeff McCune	9f0de7555c	init: change to holos.example default cue module Match the cue mod init behavior of a module named `cue.example`.	2025-01-09 13:57:26 -08:00
Gary Larizza	650636f944	Merge pull request #393 from holos-run/gl/update-helm-docs Update Helm Values Tutorial to use testscript	2025-01-09 12:01:09 -08:00
Gary Larizza	b28c110694	Update Helm Values tutorial to use testscript PROBLEM: The Helm Values tutorial contains a fair bit of code/scripts, and we need a way to test the steps we recommend to make sure nothing breaks or slips out of date. SOLUTION: * Use `testscript` as a way to automate the execution of the steps in the doc and verify that none of the steps produce errors. * Update the MDX file to directly reference the files embedded into the testscript. OUTCOME: * We have an automated way to perform the steps in the Helm Values document. * We have unit tests that will fail should any of the commands being executed in the doc fail. * The doc's MDX file directly references the files within the testscript, so we only need to modify the MDX file to update wording.	2025-01-09 11:53:53 -08:00
Gary Larizza	5bb3e90b38	Install raw-loader module We use this module within our markdown tutorials (like the Helm Values tutorial) to load in files generated by testscript.	2025-01-09 11:53:13 -08:00
Jeff McCune	6a60b613ff	render: fix selectors (#394 ) Without this patch selectors don't work as expected. This patch fixes selectors such that each --selector flag value configures one selector containing multiple positive or negative label matchers. Result: Render build plans for cluster dev or cluster test. Note the use of two flags indicating logical OR. holos render platform --selector cluster=test --selector cluster=dev rendered external-secrets for cluster test in 299.897542ms rendered external-secrets for cluster dev in 299.9225ms rendered external-secrets-crds for cluster test in 667.6075ms rendered external-secrets-crds for cluster dev in 708.126541ms rendered platform in 708.795625ms Render build plans for prod clusters that are not customer facing. Note the use of one selector with comma separated labels. holos render platform --selector "tier=prod,scope!=customer"	2025-01-08 21:09:00 -08:00
Jeff McCune	5862725bab	builder: deprecate ExtractYAML, use cue embed instead Easier to place the data, better supported in the ecosystem.	2025-01-02 18:53:10 -08:00
Jeff McCune	8660826b05	builder: protect LoadInstance with a mutex CUE is not safe for concurrent access so we protect the main LoadInstance function with a mutex lock.	2025-01-02 17:32:53 -08:00
Jeff McCune	449df91e33	docs: app.holos.run/description not cli The core component documentation on the annotation used to configure the display line for each rendered component was incorrect.	2025-01-02 08:36:37 -08:00
Jeff McCune	ac59173b30	ci: update holos-run/holos-action version (try 3) Fix the use of digests when pulling and pushing images. Pull the image from ghcr.io before pushing it to quay.io	2024-12-23 10:33:45 -08:00
Jeff McCune	fb75e560fc	ci: update holos-run/holos-action version (try 2) When new container image versions are built, automatically update the holos-run/holos-action to use the new version. Users of the action automatically update by default as a result.	2024-12-23 09:52:09 -08:00
Jeff McCune	69a064e3ea	ci: update holos-run/holos-action version When new container image versions are built, automatically update the holos-run/holos-action to use the new version. Users of the action automatically update by default as a result.	2024-12-23 07:23:36 -08:00
Jeff McCune	71b72807bb	ci: tag v0.102.1 for container images We need a released tag to reference in workflows that use the container image to render the platform configuration. This is the first image, subsequent git tags will also build and publish container images.	2024-12-21 08:08:51 -08:00
Jeff McCune	0e4ecf9d13	ci: fix error in containers.yaml	2024-12-21 07:33:31 -08:00
Jeff McCune	ec2fdadd44	ci: build container from any ref Too hard to try and build back in time, so let's just get it working then build containers going forward for tags.	2024-12-21 07:31:09 -08:00
Jeff McCune	38b082095f	ci: drop linux/arm/v7 support There aren't kubectl images to build against.	2024-12-21 07:14:21 -08:00
Jeff McCune	f9346ea7c0	ci: use Dockerfile from main when building tags Problem: We can't build old tags because the wrong Dockerfile is used from the old tag. Solution: Save the Dockerfile from main and use it to build the tag. This create a dirty working directory but that's OK.	2024-12-21 07:11:29 -08:00
Jeff McCune	0f7010288a	ci: build distroless container image for holos Push it to ghcr and quay. * sign images with cosign and oidc id token * add kustomize v5.5.0 to tools for distroless image Usage: docker run -v $(pwd):/app -w /app --rm -it ghcr.io/holos-run/holos:v0.101.8 holos render platform	2024-12-21 06:58:57 -08:00
Jeff McCune	386fb89cc6	ci: replace lint workflow with cspell The lint workflow was slow and we don't often change buf or angular these days so they're not necessary. The remaining valuable task is cspell, which we can speed up with a dedicated step.	2024-12-20 13:52:54 -08:00
Jeff McCune	c5401d6b02	ci: speed up tests by killing steps	2024-12-20 11:57:05 -08:00
Jeff McCune	f215405643	docs: fix links in readme	2024-12-20 07:28:04 -08:00
Jeff McCune	2c79982bd3	cue: enable @embed for loading yaml (#385 ) mpvl suggests @embed is a more ideal solution than our implementation of core.Component.Instances for the use case of unifying YAML data updated by Kargo Stage resources. See the issue for a link to the discussion.	2024-12-20 07:14:01 -08:00
Jeff McCune	e5e4de3073	cue: update to 0.11.1 go get cuelang.org/go/cmd/cue@latest go: downloading cuelang.org/go v0.11.1 go: upgraded cuelang.org/go v0.11.0 => v0.11.1	2024-12-20 07:09:39 -08:00
Jeff McCune	ec462f5f0b	docs: redirect /docs/support	2024-12-19 22:13:04 -08:00
Jeff McCune	0e95a2812e	cmd: expose MakeMain() for testing I'd like to add the kargo-demo repository to Unity to test evalv3, but can't get a handle on the main function to wire up to testscript. This patch fixes the problem by moving the MakeMain function to a public package so the kargo-demo go module can import and call it using the go mod tools technique.	2024-12-19 15:19:46 -08:00
Jeff McCune	54efe3e24a	core: pass --extract-yaml flag from platform to component (#376 ) Previously holos render platform was not setting the --extract-yaml file when calling holos render component, causing data file instances defined in the Platform spec to be discarded. This patch passes the value along using the flag.	2024-12-19 08:39:55 -08:00
Jeff McCune	f693f049f4	core: refactor --instance to --extract-yaml (#376 ) Extract YAML is more clear and aligns with the schema docs for the Component Instance field which has an extractYAML kind. This also leaves the door open for additional kinds of data extractors which are almost certainly going to be needed.	2024-12-19 08:34:05 -08:00
Jeff McCune	85238710ac	core: unify data files into config (#376 ) Previously there isn't a good way to unify json and yaml files with the cue configuration. This is a problem for use cases where data can be generated idempotentialy prior to rendering the platform configuration. The first use case is to explore unifying configuration with decrypted sops values, which isn't typical since Holos is designed to handle secrets with ExternalSecret resources, but does fit into the use case of executing a command to produce data idempotently, then make the data available to the platform configuration. Other use cases this feature is intended to support are the prior experiment where we fetch top level platform configuration from an rpc service, and the future goal of integrating with data provided by Terraform.	2024-12-19 08:34:05 -08:00
Jeff McCune	3ec62d272e	v1alpha5: update kargo crds to 1.1.1	2024-12-19 08:34:04 -08:00
Jeff McCune	49afb44fd4	docs: redirect /docs/comparison/	2024-12-18 14:37:36 -08:00
Gary Larizza	a023f135ab	Add a Comparisons page PROBLEM: We've noticed that Holos almost immediately gets compared to Timoni, and we frequently get asked for specifics in how they're similar/different. SOLUTION: * Add a `Comparison` page. * Include a section that compares Holos to Timoni OUTCOME: Fewer questions about how Holos compares to Timoni because people are able to find that answer themselves on our docs page.	2024-12-18 14:33:52 -08:00
Jeff McCune	c6a3a5d689	docs: redirect /docs/kargo/	2024-12-17 06:30:20 -08:00
Jeff McCune	3f1eed3f06	platform: add kargo.akuity.io custom resource definitions Needed for Kargo integration. Imported with timoni from v1.0.3 Kargo CRD's.	2024-12-16 13:19:39 -08:00
Jeff McCune	7fb7df1441	docs: make the linter happy	2024-12-16 11:04:35 -05:00
Jeff McCune	a798111d4d	docs: add oci helm charts example Question came up in chat, there isn't a good example and it's a pain to piece together from the reference docs.	2024-12-16 10:56:50 -05:00
Jeff McCune	3ddb823341	docs: add note about compinit Andy ran into issues enabling completion without first figuring out how to initialize the completion system.	2024-12-16 08:15:45 -05:00
Jeff McCune	70d48592c4	docs: fix environments topic It didn't work, failed with: ❯ holos show buildplans --selector app.holos.run/city=ams could not run: Component.Name: 2 errors in empty disjunction: (and 2 more errors) at internal/builder/instance.go:66 Component.Name: 2 errors in empty disjunction: Component.Name: conflicting values "no-name" and "podinfo-ams": /Users/jeff/Holos/foo/holos-environments-tutorial/components/podinfo/podinfo.cue:6:12 /Users/jeff/Holos/foo/holos-environments-tutorial/schema.cue:6:13 /Users/jeff/Holos/foo/holos-environments-tutorial/schema.cue:35:2 /Users/jeff/Holos/foo/holos-environments-tutorial/tags.cue:13:19 Component.Name: conflicting values "podinfo" and "podinfo-ams": /Users/jeff/Holos/foo/holos-environments-tutorial/components/podinfo/podinfo.cue:6:12 /Users/jeff/Holos/foo/holos-environments-tutorial/components/podinfo/podinfo.cue:7:8 /Users/jeff/Holos/foo/holos-environments-tutorial/schema.cue:6:13 /Users/jeff/Holos/foo/holos-environments-tutorial/schema.cue:35:2 This was likely because the podinfo component was used in different ways in different topics. Don't use the shared component to fix the problem.	2024-12-13 09:20:52 -05:00
Jeff McCune	006f08df93	docs: add kargo place holder (#378 )	2024-12-11 09:58:54 -08:00
Jeff McCune	39e2db5d37	docs: remove related content from youtube embed Except stuff in our own channel.	2024-12-08 19:43:12 -08:00
Jeff McCune	ceb293fd8a	docs: fix typescript className not class check error	2024-12-08 19:36:36 -08:00
Jeff McCune	188ff95015	docs: enable youtube fullscreen Without this patch the fullscreen button is disabled.	2024-12-08 19:33:06 -08:00
Jeff McCune	5f658e0ba0	docs: add flux kustomization example (#374 ) Almost identical to the ArgoCD Application example.	2024-12-08 19:20:12 -08:00
Jeff McCune	18b2850d3c	platform: import flux custom resources kustomize build https://github.com/fluxcd/flux2/manifests/crds\?ref=v2.4.0 \ timoni mod vendor crds -f-	2024-12-08 19:03:18 -08:00
Jeff McCune	366a7fe93d	docs: private helm repos need updated schemas (#370 ) Document the need to run holos init platform v1alpha5 --force to use the private helm repository feature.	2024-12-08 17:13:56 -08:00
Jeff McCune	f71d6d5bd9	helm: support private helm repositories (#370 ) Previously holos unconditionally executed helm repo add which failed for private repositories requiring basic authentication. This patch addresses the problem by using the Helm SDK to pull and cache charts without adding them as repositories. New fields for the core.Helm type allow basic auth credentials to be read from environment variables. Multiple repositories are supported by using different env vars for different repositories.	2024-12-06 15:38:46 -08:00
Gary Larizza	4529673e93	Embed YouTube Video (#369 ) PROBLEM: We've created a YouTube video walking people through Holos and the Helm Values tutorial, but now we need to embed it on the site for visitors to watch. SOLUTION: * Create a `YouTube` MDX plugin * Use that plugin on Overview and Helm Values * Tune the video size/attributes using CSS OUTCOME: The Helm Values YouTube video is embedded on our site for visitors to watch.	2024-12-06 15:33:03 -08:00
Jeff McCune	16a6447926	helm: support oci images in chart name Without this patch we do not support installing Kargo from an OCI helm chart. We want to support: ``` Component: #Helm & { Name: "kargo" Namespace: Kargo.Namespace Chart: { name: "oci://ghcr.io/akuity/kargo-charts/kargo" version: "1.0.3" release: Name } EnableHooks: true Values: Kargo.Values } ``` This patch fixes the problem by using the base name for filesystem cache operations.	2024-12-03 12:15:06 -08:00
Jeff McCune	111a5944ff	cue: bump to 0.11.0 go get cuelang.org/go/cmd/cue@latest	2024-12-02 12:37:19 -08:00
Jeff McCune	ff1446dc93	docs: redirect /docs/guides/helm/ This shows up in the Unity tests I'm working on with mvdan and goes to a blank page without the redirect in place. --- FAIL: TestGuides_v1alpha5 (0.00s) --- FAIL: TestGuides_v1alpha5/helm (0.60s) testscript.go:584: # Helm Guide https://holos.run/docs/guides/helm/	2024-12-02 09:05:13 -08:00
				`@@ -0,0 +1 @@`
				`stacks/security/components/cert-manager/cert-manager.cue`
				`@@ -0,0 +1 @@`
				`cat <<EOF > config/platform/organization_${GH_USER}.cue`
				`@@ -0,0 +1 @@`
				`git add . && git commit -m 'add blackbox configuration'`
				`@@ -0,0 +1 @@`
				`cat <<EOF > components/blackbox/blackbox.cue`
				`@@ -0,0 +1 @@`
				`git add . && git commit -m 'integrate blackbox and prometheus together'`
				`@@ -0,0 +1 @@`
				`git init . && git add . && git commit -m "initial commit"`
				`@@ -0,0 +1 @@`
				`mkdir -p components/prometheus components/blackbox`
				`@@ -0,0 +1 @@`
				`cat <<EOF > components/prometheus/prometheus.cue`
				`@@ -0,0 +1 @@`
				`git add . && git commit -m 'render integrated blackbox and prometheus manifests'`