• Add atmos list aliases subcommand for viewing CLI command aliases
• Add query normalization and simplified syntax for atmos list components
• Support installing multiple tools in a single atmos toolchain install command
• Add markdown rendering extensions (admonitions, badges, highlights, linkify, muted)
• Fix inline code spacing in markdown rendering
• Add terraform output format improvements
• Update roadmap component with demo links support
• Various documentation updates across CLI commands

why

• These improvements enhance the CLI user experience with better list filtering and multi-tool installation
• The markdown extensions enable richer terminal output formatting
• Documentation updates ensure consistency across command reference pages
• These changes were developed alongside the vhs-demo-videos feature but are independent core improvements

references

• Extracted from osterman/vhs-demo-videos branch (excluding demo infrastructure: tools/director/, pkg/ffmpeg/, pkg/vhs/, demos/)

Summary by CodeRabbit

• New Features

  • Added atmos list aliases to show built-in + configured aliases.
  • atmos toolchain install accepts multiple tools in one command.
  • List commands can page output when enabled; Terraform output gains a table format.
  • Rich Markdown rendering: admonitions, badges, highlights, muted text.
  • Demo video embeds added across CLI docs.

• Improvements

  • List/vendor tables show Tags; stacks expose extracted vars for templates.
  • Better terminal color/profile and optional force-color handling.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Added SidebarScrollHandler component to automatically scroll the sidebar to show the active menu item
• Component triggers on route changes and waits for sidebar DOM updates before scrolling
• Uses smooth animation to center the active link in the sidebar viewport

why

When navigating to design patterns or other sections that share sidebars with references, Docusaurus's autoCollapseCategories feature expands/collapses categories. Previously, the active item would end up off-screen. This fix ensures the active menu item is always visible and centered in the sidebar.

references

Fixes the sidebar navigation issue where design pattern pages weren't scrolled into focus when the sidebar changed.

Summary by CodeRabbit

• New Features
  • The sidebar now automatically scrolls to highlight the active navigation link when navigating between pages, improving visibility of your current location in the documentation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Adds comprehensive support for atmos terraform generate files with auto-generation enabled during component execution for all provisioners (terraform, helmfile, packer).

What Changed

Core Features

• Auto-generate files BEFORE path validation when auto_generate_files is enabled, allowing components to be JIT (Just-In-Time) created from stack configuration
• Interactive prompting for component and stack selection (like terraform backend command)
• Idempotent file generation - compares existing content before writing to avoid unnecessary updates
• Deterministic output - uses sorted map keys to ensure reproducible file generation across runs
• Enhanced UI - shows individual files changed plus a summary line with counts

Files Modified

• pkg/terraform/generate/file_generator.go - Core idempotent generation logic with sorted keys and summary output
• pkg/terraform/generate/generate.go - Directory creation before file generation
• cmd/terraform/generate/files.go - Interactive prompting for component/stack selection
• internal/exec/terraform.go - Auto-generation during terraform execution
• internal/exec/helmfile.go - Auto-generation during helmfile execution
• internal/exec/packer.go - Auto-generation during packer execution
• pkg/schema/schema.go - Config support for helmfile and packer auto-generation
• examples/generate-files/ - Complete working example with terraform configurations

Test Plan

1. Test interactive prompting without arguments:

   atmos -C examples/generate-files terraform generate files
   # Should prompt for component, then stack

2. Test with component argument only:

   atmos -C examples/generate-files terraform generate files demo
   # Should prompt for stack only

3. Test with all arguments (no prompting):

   atmos -C examples/generate-files terraform generate files demo -s dev
   # Should generate without prompting

4. Test idempotency (run twice):

   atmos -C examples/generate-files terraform generate files demo -s dev
   atmos -C examples/generate-files terraform generate files demo -s dev
   # Second run should show "unchanged" files

5. Test auto-generation during terraform plan:

   cd examples/generate-files
   atmos terraform plan demo -s dev
   # Should auto-generate files before validation

6. Test helmfile and packer:

   atmos -C examples/generate-files helmfile diff demo -s dev
   atmos -C examples/generate-files packer build demo -s dev
   # Both should auto-generate files if needed

7. Run test suite:

   make testacc

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Interactive prompts (with shell completion) to select component and stack when generating files; JIT auto-generation for Terraform, Helmfile, and Packer before validation; deterministic HCL/.tfvars output and per-file create/update/skip summaries.

• Documentation

  • New blog post, CLI docs, working example, and embedded demos for file-generation workflows.

• Tests

  • Broadly expanded tests covering generation, .tfvars, labeled blocks, formatting, templates, and edge cases.

• Chores

  • Added example project, README, and ignore/config files for the generate-files demo.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Removed non-existent CLI flags (--sentry-enabled, --terminal-width, --markdown-style) from the blog post examples. Fixed incorrect config keys (width → max_width). Now accurately shows the real problem: scattered environment variables across CI/CD systems.

why

The examples were showing CLI flags that don't exist in Atmos, which could mislead users. These settings are configuration-only via atmos.yaml or profiles, not CLI flags. The corrected examples now focus on the actual pain point that Profiles solve.

references

Follows investigation of hallucinated flags in documentation examples.

Summary by CodeRabbit

• Documentation
  • Updated blog post to reflect environment variable-based configuration approach instead of CLI flags.
  • Expanded content on profile benefits including version control and composability.
  • Updated configuration examples and terminology throughout.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Made --stack flag optional for atmos terraform source list and atmos list sources commands
• Added optional [component] positional argument to filter by component name or folder
• Added dynamic Folder column that appears only when component folder differs from instance name
• Added Type column to atmos list sources for multi-type visibility

why

• Improves UX by allowing users to list sources across all stacks without specifying --stack
• Follows Atmos naming conventions with optional positional arguments for filtering
• Better visibility when dealing with derived components using metadata.component

references

Implements enhancements outlined in the source provisioner PRD for comprehensive source listing capabilities.

Summary by CodeRabbit

• New Features

  • Added unified atmos list sources to list component sources across Terraform, Helmfile, and Packer with optional component/stack filtering and multiple output formats.

• Documentation

  • Expanded docs and examples for the new command and per-type variants; added blog post and roadmap entry.

• Improvements

  • Dynamic output columns and improved user-facing messages; enhanced error context extraction and inline markdown formatting.

• Tests

  • Comprehensive tests added for listing, extraction, filtering, sorting, rendering, and error scenarios.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Created unified pkg/env/ package for environment variable formatting (env, dotenv, bash, github formats)
• Created pkg/github/actions/env/ package with GitHub Actions environment file helpers
• Added --format=github support for atmos terraform output that writes to $GITHUB_OUTPUT
• Eliminated code duplication between cmd/env and pkg/terraform/output by refactoring to use pkg/env
• All output formats now consistently sort keys alphabetically for deterministic output

why

• Reduces code maintenance burden by consolidating format logic into a single package
• Enables GitHub Actions workflows to directly consume terraform outputs
• Supports multiline values via heredoc syntax for GitHub Actions compatibility
• Provides flexible options pattern for key transformation (uppercase, flatten with separator)

references

Part of environment variable formatting consolidation effort.

Summary by CodeRabbit

• New Features

  • Added --format=github to export Terraform outputs to GitHub Actions ($GITHUB_OUTPUT or custom file)
  • Unified environment-variable formatting across formats (env, dotenv, bash, github) with options for uppercase keys, flattening, and export-prefix control

• Documentation

  • Added docs and examples for GitHub Actions integration and sharing outputs between workflow steps

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Support multiple tools in a single atmos toolchain add command
• Default version to latest when omitted (e.g., atmos toolchain add terraform)
• Fixed help examples to use @ syntax (tool@version) instead of incorrect space-separated syntax
• Updated CLI documentation and removed phantom --file flag references
• Added comprehensive tests for multi-package and latest-version-default behavior

why

The help text was showing incorrect space-separated syntax (<tool-name> <version>) which didn't match the actual command behavior that uses @ syntax (tool@version). Users also couldn't add multiple tools efficiently. This fix aligns the UX with other similar CLIs and improves productivity for users managing toolchains.

references

Related to improving the toolchain command usability and fixing the discrepancy between documented and actual command syntax.

Summary by CodeRabbit

• New Features

  • Add accepts multiple tool[@Version] args (version defaults to latest); new --tool-versions flag. Env supports a new github format and --output/-o (auto-uses GITHUB_PATH); path acts as an env alias for PATH emission.

• Bug Fixes

  • Clearer, actionable errors and hints for missing tools and unknown commands.
  • More resilient release fetching with retries and backoff.
  • Improved ANSI-aware formatting/whitespace handling for CLI output.

• Documentation

  • CLI docs and blog updated with GitHub Actions PATH examples and usage.

• Tests

  • Expanded unit tests across toolchain commands, env/path emitters, formatting, and ANSI trimming.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Enable locals to access .settings, .vars, and .env sections from the same YAML file during template resolution
• Add template context (settings, vars, env) to the locals resolver so locals can reference these sections
• Only add context to template processing when locals are present (preserving existing behavior for files without locals)
• Merge section-specific settings/vars/env with global values (not replace) so global keys are preserved
• Add YAML functions support in locals (!env, !exec, !store, !terraform.state, !terraform.output)
• Update documentation with error handling, common pitfalls, workarounds for optional values, and YAML functions
• Add examples/locals example demonstrating the feature
• Add Locals Design Patterns documentation
• Add blog posts announcing the enhancements

why

• The PRD for file-scoped locals explicitly shows examples of locals accessing .vars from the same file
• YAML functions in locals enable powerful patterns like fetching values from terraform state or environment variables
• This enables useful patterns like:

  settings:
    substage: dev
  locals:
    domain: '{{ .settings.substage }}.example.com'

• Cross-file access (from imported files) remains unsupported by design - locals are file-scoped
• Clear error messages help users understand when template references fail

YAML Functions in Locals

Locals support all Atmos YAML functions for dynamic value resolution:

Example:

locals:
  # Fetch from environment variable
  api_endpoint: !env API_ENDPOINT
  
  # Combine with Go templates
  api_url: "https://{{ .locals.api_endpoint }}/api/v1"

components:
  terraform:
    myapp:
      vars:
        api_url: "{{ .locals.api_url }}"

Blog Posts

1. Locals Context Access (2026-01-19-locals-context-access-and-design-patterns.mdx)

   • Enhancement allowing locals to access settings/vars/env from same file
   • File-scoped context explanation

2. YAML Functions in Locals (2026-01-20-locals-yaml-functions.mdx)

   • Support for !env, !exec, !store, !terraform.state, !terraform.output in locals
   • Examples and use cases

Error Handling Behavior

When a template reference cannot be resolved, Atmos produces a hard error with a clear message rather than silently returning an empty string or passing through the literal template syntax:

Workarounds for optional values:

locals:
  # Using 'with' for conditional access
  safe_region: '{{ with .settings }}{{ .region }}{{ else }}us-west-2{{ end }}'
  
  # Using index with default
  domain: '{{ index .settings "region" | default "us-west-2" }}.example.com'

Example

A new examples/locals example demonstrates the feature:

cd examples/locals

# See how locals are resolved
atmos describe component myapp -s dev

# View all resolved locals
atmos describe locals myapp -s dev

Output:

vars:
  environment: development
  full_name: acme-development-dev
  name: acme
  tags:
    Environment: development
    ManagedBy: Atmos
    Namespace: acme
    Team: platform

Summary of Changes

Code Changes:

• pkg/locals/resolver.go:
  • Added templateContext field and WithTemplateContext method to pass settings/vars/env during resolution
  • Added YamlFunctionProcessor callback type and WithYamlFunctionProcessor method for YAML function support
  • Updated resolveString to detect and process YAML functions (strings starting with !)
• internal/exec/stack_processor_locals.go:
  • Build and pass template context with settings/vars/env from the stack config
  • Added localsResolveOptions struct and createYamlFunctionProcessor for YAML function processing
  • Fixed buildSectionTemplateContext to merge section values with global values (not replace)
  • Added mergeStringAnyMaps helper for shallow merging
• internal/exec/stack_processor_utils.go:
  • Extract settings/vars/env from raw YAML and add to context only when locals are present
  • Updated to use Atmos YAML unmarshaling for proper custom tag handling
• errors/errors.go: Added ErrLocalsYamlFunctionFailed sentinel error

Test Changes:

• Added new integration tests: TestLocalsSettingsAccessSameFile, TestLocalsSettingsAccessDescribeStacks, TestLocalsSettingsAccessNotCrossFile
• Added test fixture tests/fixtures/scenarios/locals-settings-access/ demonstrating same-file access
• Added test fixture tests/fixtures/scenarios/locals-settings-cross-file/ demonstrating cross-file access error
• Added advanced tests: TestLocalsNestedSettingsAccess, TestLocalsEnvironmentVariableAccess, TestLocalsHelmfileSectionLocals
• Added test fixture tests/fixtures/scenarios/locals-advanced/ for nested values and helmfile section locals
• Converted context-access unit tests to table-driven format (TestExtractLocalsFromRawYAML_ContextAccess)
• Added unit tests for merge behavior (TestMergeStringAnyMaps, TestBuildSectionTemplateContext_MergesBehavior)
• Added TestLocalsWithYamlFunctionsEnv for YAML functions in locals
• Added test fixture tests/fixtures/scenarios/locals-yaml-functions/ for YAML function testing

Documentation Changes:

• Added "Accessing Other Sections" section explaining what template context is available
• Added "Processing Order" section explaining why cross-file access doesn't work
• Added "Component-Level Locals" section with inheritance from base components
• Added "Scope Merging for Settings and Vars" section explaining merge behavior
• Added "Debugging Locals" section with troubleshooting guidance
• Added "YAML Functions in Locals" section with examples for !env, !exec, !store, !terraform.state, !terraform.output
• Added "Error Handling" section with:
  • Unresolved template reference behavior (produces error, not empty string)
  • Common error scenarios table
  • Handling optional values with Go template conditionals
  • Cross-file access error explanation and solutions
• Updated "Locals vs Vars" comparison table with "Cross-File Access" row
• Added best practice for using vars for cross-file sharing

Blog Posts Added:

• website/blog/2026-01-19-locals-context-access-and-design-patterns.mdx
• website/blog/2026-01-20-locals-yaml-functions.mdx

Example Added:

• examples/locals/ - Minimal example demonstrating locals feature:
  • Basic locals and dependency resolution
  • Accessing settings/vars from same file
  • Building computed values (name_prefix, full_name, tags)
  • File-scoped isolation between dev and prod stacks

Dependency Updates:

• Updated google.golang.org/api from retracted v0.258.0 to v0.260.0

Summary by CodeRabbit

• New Features

  • Locals now access .settings, .vars, and .env from the same file during resolution
  • YAML function support in locals (e.g., !env, !exec, !store, !terraform.state, !terraform.output)

• Documentation

  • Major docs and blog updates with processing diagrams, examples, guidance, and warnings

• Tests

  • Extensive new tests and fixtures covering locals scope, YAML functions, env access, cross-file cases, and edge conditions

• Examples

  • New examples demonstrating locals usage and try-it workflows

• Chores

  • Multiple dependency patch bumps and NOTICE license URL updates

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Stacks with explicit name field now correctly bypass name_template and name_pattern validation
• Previously, stacks with explicit names that lacked template/pattern-required vars were silently skipped
• Added regression test to prevent future regressions
• Added example demonstrating imperative stack naming

why

The processStackContextPrefix function was processing name_template or name_pattern before checking if the stack had an explicit name field. According to the stack name identity spec, explicit names take absolute precedence and should skip template/pattern processing entirely.

how

Updated processStackContextPrefix to accept stackManifestName parameter and skip validation when an explicit name is present. This ensures the correct precedence order is enforced during component discovery in ProcessStacks.

references

• Relates to stack name identity specification (docs/prd/stack-name-identity.md)
• Test fixture: tests/fixtures/scenarios/stack-name-pattern-missing-vars/
• Example: examples/stack-names/

Summary by CodeRabbit

• New Features

  • Added a stack-names example workspace demonstrating explicit stack naming with precedence over filename-based names
  • Included example Terraform mock component and .gitignore for the example

• Bug Fixes

  • Pattern validation failures now gracefully fall back to filename-based stack names instead of aborting
  • Improved CLI error hints when an invalid stack name is provided

• Documentation

  • Added docs and an embedded "Stack Names" example describing naming rules and usage

• Tests

  • Added tests and snapshots covering explicit naming, pattern-fallback behavior, and CLI outputs (including telemetry notice)

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Fixed atmos describe affected to correctly detect component file changes (Terraform, Helmfile, Packer)
• Added gitRepoRoot parameter to path resolution logic to properly resolve relative paths from git diff
• Fixed detection of components using source for vendoring (components without explicit component field)
• A regression in previous Atmos releases caused changes to component files to not be detected in certain scenarios

why

Issue 1: Git repo root path resolution

• Git diff returns file paths relative to the git repository root
• The previous implementation used filepath.Abs() which resolves paths against the current working directory
• When Atmos was run from a subdirectory (e.g., atmos -C examples/demo-stacks), paths would not match, causing component changes to go undetected

Issue 2: Vendored components with source

• Components using source for just-in-time vendoring were not being detected
• The affected detection required an explicit component field to determine which folder to monitor
• Now defaults to using the component name (YAML key) when no explicit component field is specified

changes

Path resolution fix

• newChangedFilesIndex() now accepts gitRepoRoot parameter
• Relative paths from git diff are resolved against the git repo root, not the current working directory

Source component detection fix

• Added GetComponentFolder() helper in stack_utils.go to consolidate component folder resolution logic
• Modified BuildComponentPath() to accept optional fallback parameter
• processTerraformComponentsIndexed(), processHelmfileComponentsIndexed(), processPackerComponentsIndexed() now use GetComponentFolder() which defaults to component name when component field is missing
• This ensures components with source vendoring are properly tracked

test coverage

All three scenarios are covered by unit tests:

Resolution flow

1. metadata.component: mock → Stack processing sets componentSection["component"] = "mock" → GetComponentFolder uses that value
2. source only → No component field → GetComponentFolder falls back to componentName (YAML key)
3. source + workdir → Same as 2 (see note below)

Why provision.workdir doesn't affect folder resolution

For describe affected, the workdir configuration doesn't change how component folders are resolved because:

1. Workdir is runtime-only: The .workdir/ directory is created at runtime when you run atmos terraform plan/apply. It's a temporary copy of the component files.

2. Workdir is not tracked in git: The .workdir/ directory is in .gitignore. Changes to files in .workdir/ don't appear in git diff.

3. describe affected compares git branches: It looks at what files changed between commits/branches. Since workdir files aren't tracked, the detection happens on the source files:

   • For local components: components/terraform/<component>/
   • For vendored components with source: components/terraform/<component-name>/ (where files are vendored)

Source of truth (tracked in git)     →    Workdir (runtime, not tracked)
components/terraform/vpc-remote/     →    .workdir/terraform/dev-vpc-remote/
         ↑                                           ↑
   describe affected                          terraform runs here
   detects changes HERE

When you modify vendored component files in components/terraform/vpc-remote-workdir/, describe affected detects that change. The fact that at runtime those files get copied to .workdir/ doesn't matter for change detection.

references

• Closes #1978
• Vendoring Documentation
• Source Configuration
• Just-in-Time Vendoring

Summary by CodeRabbit

• Bug Fixes
  • Corrected affected-component detection when running from a repo root or subdirectory (e.g., using -C), improving path resolution.
  • Properly detect vendored (source-based) components and component folder/file changes across Terraform, Helmfile, and Packer.
• Documentation
  • Added blog posts explaining the improved detection, vendoring behavior, and cross-platform path-handling guidance.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

• Fixed critical bug where terraform commands with --all, --affected, --query, or --components flags would incorrectly prompt for component selection, then error
• Root cause was applyOptionsToInfo being called after resolveAndPromptForArgs, preventing prompting logic from detecting multi-component flags
• Added regression tests to prevent similar bugs in future

why

The --all flag must be applied to the info struct BEFORE checking whether to show interactive prompts. Otherwise, the prompting logic cannot determine that multi-component flags are set and incorrectly prompts for a component, which then conflicts with the multi-component flag validation.

references

closes #1945

Summary by CodeRabbit

• New Features

  • Interactive prompts now respect CLI multi-component options earlier, preventing prompts when those flags are present.

• Bug Fixes

  • Clear success messages when no components are affected or no query matches.
  • Dry-run now reports results and cleanly skips execution while indicating success.

• Tests

  • Expanded coverage for multi-component flags, prompt-skipping, dry-run behavior, no-match cases, and related edge conditions.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting @dependabot rebase.