Update docs UI and acceptance fixtures

Author: osterman

demo/screengrabs/.gitignore

@@ -1 +1,2 @@
 artifacts/*
+.bin/

demo/screengrabs/Makefile

@@ -1,33 +1,66 @@
 INSTALL_PATH ?= ../../website/src/components/Screengrabs
+ATMOS_RELEASE_VERSION ?= $(shell bash scripts/next-release-version.sh 2>/dev/null)
+REPO_ROOT := $(abspath ../..)
+BIN_DIR := .bin
+ATMOS_BIN := $(BIN_DIR)/atmos
+SCREENGRAB_ENV = TERM=xterm-256color COLORTERM=truecolor LANG=en_US.UTF-8 ATMOS_THEME=atmos ATMOS_FORCE_COLOR=true CLICOLOR_FORCE=1 FORCE_COLOR=1 ATMOS_PAGER=false ATMOS_TELEMETRY=false
+.PHONY: all install build-atmos build-all docker-build docker-all
+
 all: build-all install
 
 # Write to website/src/components/Screengrabs/
-install:
+install: validate-artifacts
 	@echo "Installing screengrabs to $(INSTALL_PATH)"
 	@mkdir -p $(INSTALL_PATH)
 	@cp -a artifacts/* $(INSTALL_PATH)
+	@$(MAKE) validate-installed
+
+build-atmos:
+	@test -n "$(ATMOS_RELEASE_VERSION)" || (echo "ERROR: Could not determine ATMOS_RELEASE_VERSION from git tags" && exit 1)
+	@mkdir -p $(BIN_DIR)
+	@echo "Building atmos $(ATMOS_RELEASE_VERSION) for screengrabs..."
+	@cd $(REPO_ROOT) && go build -trimpath -o $(abspath $(ATMOS_BIN)) -ldflags "-s -w -X github.com/cloudposse/atmos/pkg/version.Version=$(ATMOS_RELEASE_VERSION)" .
 
-build-all:
-	@./build-all.sh demo-stacks.txt
+build-all: build-atmos
+	@PATH="$(abspath $(BIN_DIR)):$$PATH" $(SCREENGRAB_ENV) ./build-all.sh demo-stacks.txt
+	@$(MAKE) validate-artifacts
+
+validate-artifacts:
 	@echo "Validating screengrabs..."
 	@! grep -r "atmos: not found" artifacts/ || (echo "ERROR: Found 'atmos: not found' in screengrabs" && exit 1)
 	@! grep -r "COMMAND_EXIT_CODE" artifacts/ || (echo "ERROR: Found 'COMMAND_EXIT_CODE' in screengrabs" && exit 1)
 	@! grep -r "Script started" artifacts/ || (echo "ERROR: Found 'Script started' messages in screengrabs" && exit 1)
 	@! grep -r "Script done" artifacts/ || (echo "ERROR: Found 'Script done' messages in screengrabs" && exit 1)
+	@! grep -r "background-color:" artifacts/ || (echo "ERROR: Found inline background colors in screengrabs" && exit 1)
+	@! grep -r "Atmos test" artifacts/ || (echo "ERROR: Found test-stamped Atmos version in screengrabs" && exit 1)
+	@! grep -r "Update available!.*test" artifacts/ || (echo "ERROR: Found test-stamped update prompt in screengrabs" && exit 1)
 	@echo "✓ All screengrabs validated successfully"
 
+validate-installed:
+	@echo "Validating installed screengrabs..."
+	@! grep -r "background-color:" $(INSTALL_PATH) || (echo "ERROR: Found inline background colors in installed screengrabs" && exit 1)
+	@! grep -r "Atmos test" $(INSTALL_PATH) || (echo "ERROR: Found test-stamped Atmos version in installed screengrabs" && exit 1)
+	@! grep -r "Update available!.*test" $(INSTALL_PATH) || (echo "ERROR: Found test-stamped update prompt in installed screengrabs" && exit 1)
+	@echo "✓ Installed screengrabs validated successfully"
+
 # Generate screengrabs using Docker (cross-platform, recommended)
 docker-build:
-	@echo "Generating screengrabs using Podman (Linux container)..."
+	@echo "Generating screengrabs using Podman (Linux container) with Atmos $(ATMOS_RELEASE_VERSION)..."
 	@podman run --rm -v $$(pwd)/../..:/workspace -w /workspace/demo/screengrabs \
 		--memory=4g \
+		-e TERM=xterm-256color \
+		-e COLORTERM=truecolor \
+		-e LANG=en_US.UTF-8 \
+		-e ATMOS_THEME=atmos \
 		-e ATMOS_TELEMETRY=false \
 		-e ATMOS_FORCE_COLOR=true \
+		-e CLICOLOR_FORCE=1 \
 		-e FORCE_COLOR=1 \
 		ubuntu:22.04 bash -c ' \
 		set -e && \
 		apt-get update -qq && \
-		DEBIAN_FRONTEND=noninteractive apt-get install -y -qq aha make wget tar tree && \
+		DEBIAN_FRONTEND=noninteractive apt-get install -y -qq aha bat make wget tar tree && \
+		ln -sf /usr/bin/batcat /usr/local/bin/bat && \
 		echo "Installing Go 1.26..." && \
 		ARCH=$$(uname -m | sed "s/x86_64/amd64/; s/aarch64/arm64/") && \
 		wget -q https://go.dev/dl/go1.26.0.linux-$$ARCH.tar.gz && \
@@ -36,15 +69,20 @@ docker-build:
 		go version && \
 		echo "Building atmos from source..." && \
 		cd /workspace && \
-		GOMEMLIMIT=3GiB go build -p 2 -o /usr/local/bin/atmos . && \
+		GOMEMLIMIT=3GiB go build -trimpath -p 2 -o /usr/local/bin/atmos -ldflags "-s -w -X github.com/cloudposse/atmos/pkg/version.Version=$(ATMOS_RELEASE_VERSION)" . && \
 		atmos version && \
+		atmos toolchain install hashicorp/terraform && \
+		export PATH="$$(atmos toolchain path hashicorp/terraform):$$PATH" && \
 		cd /workspace/demo/screengrabs && \
-		make build-all && \
+		make build-all ATMOS_RELEASE_VERSION=$(ATMOS_RELEASE_VERSION) && \
 		echo "Validating screengrabs..." && \
 		! grep -r "atmos: not found" artifacts/ && \
 		! grep -r "COMMAND_EXIT_CODE" artifacts/ && \
 		! grep -r "Script started" artifacts/ && \
-		! grep -r "Script done" artifacts/ \
+		! grep -r "Script done" artifacts/ && \
+		! grep -r "background-color:" artifacts/ && \
+		! grep -r "Atmos test" artifacts/ && \
+		! grep -r "Update available!.*test" artifacts/ \
 		'
 	@echo "Screengrabs generated and validated successfully in artifacts/"
 

demo/screengrabs/README.md

@@ -1,21 +1,42 @@
 ## Usage
 
-Add all commands to `commands.txt` (use `#` to disable generation of the command)
+Add all commands to `demo-stacks.txt` (use `#` to disable generation of the command).
 
 Build all colorized HTML snippets of command output by running:
 
 ```shell
-make all
+make build-all
+```
+
+The Makefile builds a local `atmos` binary for the captures and derives `ATMOS_RELEASE_VERSION` from the latest local release/RC tag (for example, `v1.222.0-rc.8` becomes `1.222.0`). Override it only when the next release version is known to be different:
+
+```shell
+make build-all ATMOS_RELEASE_VERSION=1.222.0
 ```
 
-Then install those into `../../website/static/screengrabs' by running
+The capture environment uses `TERM=xterm-256color`, `COLORTERM=truecolor`, `ATMOS_THEME=atmos`, and Atmos's documented force-color path. Do not use `TERM=dumb` or force TTY mode for normal captures; those bypass the curated terminal/color behavior that the screengrabs are meant to show.
+
+Then install those into `../../website/src/components/Screengrabs` by running:
 
 ```shell
 make install
 ```
 
-All the files in `website/static/screengrabs` should be committed.
+You can also build and install in one step:
+
+```shell
+make all
+```
+
+For a reproducible Linux container workflow, run:
+
+```shell
+make docker-all
+```
+
+All generated files in `website/src/components/Screengrabs` should be committed. Do not manually edit checked-in screengrab HTML; regenerate it with the script so postprocessing and validation stay consistent.
 
+For a one-off regeneration, create a temporary manifest named `demo-stacks.txt` with only the commands you want, run `./build-all.sh demo-stacks.txt`, then copy only the resulting artifact from `artifacts/` into `website/src/components/Screengrabs`. The manifest name matters because it controls the example directory used for command execution.
 
 Use these screengrabs then inside of any MDX documentation file, add something like this:
 

demo/screengrabs/build-all.sh

@@ -1,6 +1,9 @@
 #!/bin/bash
 set -e
 export TERM=xterm-256color
+export COLORTERM=truecolor
+export LANG=en_US.UTF-8
+export ATMOS_THEME=atmos
 
 # Check for required dependencies
 MISSING_DEPS=()
@@ -77,6 +80,7 @@ fi
 export ATMOS_FORCE_COLOR=true
 export FORCE_COLOR=1
 export CLICOLOR_FORCE=1
+export ATMOS_TELEMETRY=false
 
 # Ensure that the output is not paginated
 export LESS=-X
@@ -197,7 +201,7 @@ postprocess_html() {
 
 	# Strip all background colors - they cause visibility issues.
 	# aha adds background-color to code blocks which makes text invisible when colors match.
-	sed_inplace 's/background-color:[^;]*;//g' $file
+	sed_inplace -E 's/background-color[[:space:]]*:[[:space:]]*[^;"'\'']*;?//g' $file
 }
 
 manifest=$1

demo/screengrabs/demo-stacks.txt

@@ -9,6 +9,9 @@ atmos ai chat --help
 atmos ai exec --help
 atmos ai sessions --help
 atmos ai skill --help
+atmos ansible --help
+atmos ansible playbook --help
+atmos ansible version --help
 atmos lsp --help
 atmos lsp start --help
 atmos mcp --help

demo/screengrabs/scripts/next-release-version.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+git tag --sort=-v:refname \
+  | sed -nE 's/^v([0-9]+\.[0-9]+\.[0-9]+)(-rc\.[0-9]+)?$/\1/p' \
+  | head -n 1

examples/quick-start-simple/atmos.yaml

@@ -15,6 +15,3 @@ stacks:
   excluded_paths:
     - "**/_defaults.yaml"
   name_template: "{{ .vars.stage }}"
-
-logs:
-  level: Info

tests/fixtures/scenarios/flag-inheritance/atmos.yaml

@@ -47,3 +47,48 @@ commands:
         steps:
           - 'echo "Deploying component: {{ .Arguments.component }}"'
           - 'echo "To stack: {{ .Flags.stack }}"'
+
+  # Test 3: Custom subcommand under the built-in terraform command.
+  - name: terraform
+    description: Execute Terraform commands with custom extensions
+    commands:
+      - name: provision
+        description: This command provisions terraform components
+        arguments:
+          - name: component
+            description: Name of the component
+        flags:
+          - name: stack
+            shorthand: s
+            description: Name of the stack
+            required: true
+        steps:
+          - 'echo "Provisioning component: {{ .Arguments.component }}"'
+          - 'echo "In stack: {{ .Flags.stack }}"'
+
+  # Test 4: Custom command using component_config with --stack.
+  - name: show
+    description: Execute 'show' commands
+    commands:
+      - name: component
+        description: Execute 'show component' command
+        arguments:
+          - name: component
+            description: Name of the component
+        flags:
+          - name: stack
+            shorthand: s
+            description: Name of the stack
+            required: true
+        component_config:
+          component: "{{ .Arguments.component }}"
+          stack: "{{ .Flags.stack }}"
+        env:
+          - key: ATMOS_COMPONENT
+            value: "{{ .Arguments.component }}"
+        steps:
+          - 'echo "Atmos component from argument: {{ .Arguments.component }}"'
+          - 'echo "ATMOS_COMPONENT: $ATMOS_COMPONENT"'
+          - 'echo "Atmos stack: {{ .Flags.stack }}"'
+          - 'echo "Terraform component: {{ .ComponentConfig.component }}"'
+          - 'echo "Stage: {{ .ComponentConfig.vars.stage }}"'