fix: Audit and fix broken links in README

.atmos.d/README.md

@@ -15,4 +15,4 @@ The `dev.yaml` file defines development workflow commands that help maintain cod
 
 We use Atmos custom commands for our development workflow as a form of "dogfooding" - using our own tool to manage our development process. This ensures we experience the same workflows our users do and helps us identify areas for improvement.
 
-For more information on custom commands, see the [Atmos Custom Commands documentation](https://atmos.tools/core-concepts/custom-commands/).
+For more information on custom commands, see the [Atmos Custom Commands documentation](https://atmos.tools/cli/configuration/commands).

.github/workflows/link-check.yml

@@ -0,0 +1,33 @@
+name: Link Check
+
+on:
+  pull_request:
+    paths:
+      - '**.md'
+      - '!website/**'
+      - 'lychee.toml'
+  push:
+    branches: [main]
+    paths:
+      - '**.md'
+      - '!website/**'
+      - 'lychee.toml'
+  workflow_dispatch:
+
+jobs:
+  link-check:
+    name: Check Markdown Links
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Check links with lychee
+        uses: lycheeverse/lychee-action@v2
+        with:
+          args: --config lychee.toml --root-dir ${{ github.workspace }} '**/*.md'
+          fail: true
+          jobSummary: true
+          token: ${{ secrets.GITHUB_TOKEN }}

CLAUDE.md

@@ -310,7 +310,7 @@ Reply to threads: Use `gh api graphql` with `addPullRequestReviewThreadReply`
 - Use definition lists `<dl>` instead of tables for arguments and flags
 - Follow Docusaurus conventions from existing files
 - File location: `website/docs/cli/commands/<command>/<subcommand>.mdx`
-- Link to core concepts using `/core-concepts/` paths
+- Link to documentation using current URL paths (e.g., `/stacks`, `/components`, `/cli/configuration`)
 - Include purpose note and help screengrab
 - Use consistent section ordering: Usage → Examples → Arguments → Flags
 

Makefile

@@ -119,4 +119,9 @@ generate-mocks:
 	@go generate ./pkg/http/...
 	@echo "Mocks regenerated successfully"
 
-.PHONY: readme lint lintroller gomodcheck build version build-linux build-windows build-macos deps version-linux version-windows version-macos testacc testacc-cover testacc-coverage test-short test-short-cover generate-mocks
+# Check markdown links (requires lychee: brew install lychee)
+link-check:
+	@command -v lychee >/dev/null 2>&1 || { echo "Install lychee: brew install lychee"; exit 1; }
+	lychee --config lychee.toml --root-dir "$(CURDIR)" '**/*.md'
+
+.PHONY: readme lint lintroller gomodcheck build version build-linux build-windows build-macos deps version-linux version-windows version-macos testacc testacc-cover testacc-coverage test-short test-short-cover generate-mocks link-check

README.md

@@ -29,7 +29,7 @@
 
 Atmos is a framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains.
 
-## Use Atmos to break your architecture into reusable [Components](https://atmos.tools/core-concepts/components) that you implement using [Terraform "root modules"](https://atmos.tools/core-concepts/components/terraform). Then tie everything together using [Stack](https://atmos.tools/core-concepts/stacks) configurations defined in YAML.
+## Use Atmos to break your architecture into reusable [Components](https://atmos.tools/components) that you implement using [Terraform "root modules"](https://atmos.tools/components/terraform). Then tie everything together using [Stack](https://atmos.tools/stacks) configurations defined in YAML.
 
 Atmos can change how you think about the Terraform code you write to build your infrastructure. Atmos is a framework that simplifies complex cloud architectures and DevOps workflows into intuitive CLI commands.
 Its strength in managing DRY configurations at scale for Terraform and is supported by robust design patterns, comprehensive documentation, and a passionate community, making it a versatile tool for both startups and enterprises.
@@ -82,11 +82,11 @@ indispensable asset for managing complex infrastructures with confidence.
 
 - [**Terminal UI**](https://atmos.tools/cli) Polished interface for easier interaction with Terraform, workflows, and commands.
 - [**Native Terraform Support:**](https://atmos.tools/cli/commands/terraform/usage) Orchestration, backend generation, varfile generation, ensuring compatibility with vanilla Terraform.
-- [**Stacks:**](https://atmos.tools/core-concepts/stacks) Powerful abstraction layer defined in YAML for orchestrating and deploying components.
-- [**Components:**](https://atmos.tools/core-concepts/components) A generic abstraction for deployable units, such as Terraform "root" modules.
-- [**Vendoring:**](https://atmos.tools/core-concepts/vendor) Pulls dependencies from remote sources, supporting immutable infrastructure practices.
-- [**Custom Commands:**](https://atmos.tools/core-concepts/custom-commands) Extends Atmos's functionality, allowing integration of any command with stack configurations.
-- [**Workflow Orchestration:**](https://atmos.tools/core-concepts/workflows) Comprehensive support for managing the lifecycle of cloud infrastructure from initiation to maintenance.
+- [**Stacks:**](https://atmos.tools/stacks) Powerful abstraction layer defined in YAML for orchestrating and deploying components.
+- [**Components:**](https://atmos.tools/components) A generic abstraction for deployable units, such as Terraform "root" modules.
+- [**Vendoring:**](https://atmos.tools/vendor) Pulls dependencies from remote sources, supporting immutable infrastructure practices.
+- [**Custom Commands:**](https://atmos.tools/cli/configuration/commands) Extends Atmos's functionality, allowing integration of any command with stack configurations.
+- [**Workflow Orchestration:**](https://atmos.tools/workflows) Comprehensive support for managing the lifecycle of cloud infrastructure from initiation to maintenance.
 
 See [all features of Atmos](https://atmos.tools/features).
 
@@ -103,12 +103,12 @@ strength in the cloud infrastructure and DevOps domains:
   Simply define a baseline tenant configuration once, and then seamlessly onboard new tenants by reusing this baseline through pure
   configuration, bypassing the need for further code development.
 - **Efficient Multi-Region Deployments:** Atmos facilitates streamlined multi-region deployments by enabling businesses to define baseline
-  configurations with [stacks](https://atmos.tools/core-concepts/stacks/) and extend them across regions with DRY principles through
-  [imports](https://atmos.tools/core-concepts/stacks/imports) and [inheritance](https://atmos.tools/core-concepts/stacks/inheritance).
+  configurations with [stacks](https://atmos.tools/stacks) and extend them across regions with DRY principles through
+  [imports](https://atmos.tools/stacks/imports) and [inheritance](https://atmos.tools/howto/inheritance).
 - **Compliant Infrastructure for Regulated Industries:** Atmos empowers DevOps and SecOps teams to create vetted configurations that comply
   with SOC2, HIPAA, HITRUST, PCI, and other regulatory standards. These configurations can then be efficiently shared and reused across the
-  organization via [service catalogs](https://atmos.tools/core-concepts/stacks/catalogs), [component libraries](https://atmos.tools/core-concepts/components/library),
-  [vendoring](https://atmos.tools/core-concepts/vendor), and [OPA policies](https://atmos.tools/core-concepts/validate/opa),
+  organization via [service catalogs](https://atmos.tools/howto/catalogs), [component libraries](https://atmos.tools/components),
+  [vendoring](https://atmos.tools/vendor), and [OPA policies](https://atmos.tools/validation/opa),
   simplifying the process of achieving and maintaining rigorous compliance.
 - **Empowering Teams with Self-Service Infrastructure:** Allows teams to manage their infrastructure needs independently, using
   predefined templates and policies.

README.yaml

@@ -41,7 +41,7 @@ screenshots:
 description: |-
   Atmos is a framework for orchestrating and operating infrastructure workflows across multiple cloud and DevOps toolchains.
 
-  ## Use Atmos to break your architecture into reusable [Components](https://atmos.tools/core-concepts/components) that you implement using [Terraform "root modules"](https://atmos.tools/core-concepts/components/terraform). Then tie everything together using [Stack](https://atmos.tools/core-concepts/stacks) configurations defined in YAML.
+  ## Use Atmos to break your architecture into reusable [Components](https://atmos.tools/components) that you implement using [Terraform "root modules"](https://atmos.tools/components/terraform). Then tie everything together using [Stack](https://atmos.tools/stacks) configurations defined in YAML.
 
   Atmos can change how you think about the Terraform code you write to build your infrastructure. Atmos is a framework that simplifies complex cloud architectures and DevOps workflows into intuitive CLI commands.
   Its strength in managing DRY configurations at scale for Terraform and is supported by robust design patterns, comprehensive documentation, and a passionate community, making it a versatile tool for both startups and enterprises.
@@ -86,11 +86,11 @@ introduction: |-
 
   - [**Terminal UI**](https://atmos.tools/cli) Polished interface for easier interaction with Terraform, workflows, and commands.
   - [**Native Terraform Support:**](https://atmos.tools/cli/commands/terraform/usage) Orchestration, backend generation, varfile generation, ensuring compatibility with vanilla Terraform.
-  - [**Stacks:**](https://atmos.tools/core-concepts/stacks) Powerful abstraction layer defined in YAML for orchestrating and deploying components.
-  - [**Components:**](https://atmos.tools/core-concepts/components) A generic abstraction for deployable units, such as Terraform "root" modules.
-  - [**Vendoring:**](https://atmos.tools/core-concepts/vendor) Pulls dependencies from remote sources, supporting immutable infrastructure practices.
-  - [**Custom Commands:**](https://atmos.tools/core-concepts/custom-commands) Extends Atmos's functionality, allowing integration of any command with stack configurations.
-  - [**Workflow Orchestration:**](https://atmos.tools/core-concepts/workflows) Comprehensive support for managing the lifecycle of cloud infrastructure from initiation to maintenance.
+  - [**Stacks:**](https://atmos.tools/stacks) Powerful abstraction layer defined in YAML for orchestrating and deploying components.
+  - [**Components:**](https://atmos.tools/components) A generic abstraction for deployable units, such as Terraform "root" modules.
+  - [**Vendoring:**](https://atmos.tools/vendor) Pulls dependencies from remote sources, supporting immutable infrastructure practices.
+  - [**Custom Commands:**](https://atmos.tools/cli/configuration/commands) Extends Atmos's functionality, allowing integration of any command with stack configurations.
+  - [**Workflow Orchestration:**](https://atmos.tools/workflows) Comprehensive support for managing the lifecycle of cloud infrastructure from initiation to maintenance.
 
   See [all features of Atmos](https://atmos.tools/features).
 
@@ -107,12 +107,12 @@ introduction: |-
     Simply define a baseline tenant configuration once, and then seamlessly onboard new tenants by reusing this baseline through pure
     configuration, bypassing the need for further code development.
   - **Efficient Multi-Region Deployments:** Atmos facilitates streamlined multi-region deployments by enabling businesses to define baseline
-    configurations with [stacks](https://atmos.tools/core-concepts/stacks/) and extend them across regions with DRY principles through
-    [imports](https://atmos.tools/core-concepts/stacks/imports) and [inheritance](https://atmos.tools/core-concepts/stacks/inheritance).
+    configurations with [stacks](https://atmos.tools/stacks) and extend them across regions with DRY principles through
+    [imports](https://atmos.tools/stacks/imports) and [inheritance](https://atmos.tools/howto/inheritance).
   - **Compliant Infrastructure for Regulated Industries:** Atmos empowers DevOps and SecOps teams to create vetted configurations that comply
     with SOC2, HIPAA, HITRUST, PCI, and other regulatory standards. These configurations can then be efficiently shared and reused across the
-    organization via [service catalogs](https://atmos.tools/core-concepts/stacks/catalogs), [component libraries](https://atmos.tools/core-concepts/components/library),
-    [vendoring](https://atmos.tools/core-concepts/vendor), and [OPA policies](https://atmos.tools/core-concepts/validate/opa),
+    organization via [service catalogs](https://atmos.tools/howto/catalogs), [component libraries](https://atmos.tools/components),
+    [vendoring](https://atmos.tools/vendor), and [OPA policies](https://atmos.tools/validation/opa),
     simplifying the process of achieving and maintaining rigorous compliance.
   - **Empowering Teams with Self-Service Infrastructure:** Allows teams to manage their infrastructure needs independently, using
     predefined templates and policies.

cmd/markdown/getting_started.md

@@ -4,8 +4,8 @@ To configure and start using Atmos, refer to the following documents:
 
 **Atmos CLI Configuration:** <https://atmos.tools/cli/configuration>
 
-**Atmos Components:** <https://atmos.tools/core-concepts/components>
+**Atmos Components:** <https://atmos.tools/components>
 
-**Atmos Stacks:** <https://atmos.tools/core-concepts/stacks>
+**Atmos Stacks:** <https://atmos.tools/stacks>
 
 **Quick Start:** <https://atmos.tools/quick-start>

docs/circular-dependency-detection.md

@@ -236,4 +236,4 @@ See `internal/exec/yaml_func_circular_deps_test.go` for comprehensive test examp
 
 - [PRD: Circular Dependency Detection](prd/circular-dependency-detection.md)
 - [Error Handling Strategy](prd/error-handling-strategy.md)
-- [Testing Strategy](prd/testing-strategy.md)
+- [Testability Refactoring Strategy](prd/testability-refactoring-strategy.md)

docs/developing-atmos-commands.md

@@ -976,4 +976,4 @@ See these commands for reference implementations:
 - [Flag Handler Documentation](../.claude/agents/flag-handler.md) - **Complete flag handler guide**
 - [Command Registry Pattern PRD](prd/command-registry-pattern.md)
 - [Cobra Documentation](https://github.com/spf13/cobra)
-- [Atmos Custom Commands](/core-concepts/custom-commands)
+- [Atmos Custom Commands](https://atmos.tools/cli/configuration/commands)

docs/development.md

@@ -23,7 +23,7 @@ This guide covers the development workflow for contributing to Atmos.
 
 ## Development Workflow
 
-We use Atmos custom commands for development (dogfooding our own tool). This ensures we experience the same workflows our users do. See [Atmos Custom Commands](https://atmos.tools/core-concepts/custom-commands/) for more details.
+We use Atmos custom commands for development (dogfooding our own tool). This ensures we experience the same workflows our users do. See [Atmos Custom Commands](https://atmos.tools/cli/configuration/commands) for more details.
 
 ### Available Commands
 

docs/logging.md

@@ -486,6 +486,6 @@ logs:
 
 ## Structured and Semantic Logging
 
-Structured logs record events as key/value pairs so machines and humans can parse them. Semantic logging standardizes those keys so logs can be understood across tools and teams. Atmos uses the [Charm Logger](https://charm.sh/blog/the-charm-logger/) for this purpose.
+Structured logs record events as key/value pairs so machines and humans can parse them. Semantic logging standardizes those keys so logs can be understood across tools and teams. Atmos uses the [Charm Logger](https://charm.land/blog/the-charm-logger/) for this purpose.
 
 See [structured-logging.md](structured-logging.md) for detailed guidance and examples.

docs/markdown-styles.md

@@ -118,7 +118,7 @@ All standard GFM syntax is also supported:
 - **Bold**: `**text**`
 - *Italic*: `*text*`
 - `Inline code`: `` `code` ``
-- [Links](url): `[text](url)`
+- [Links](https://example.com): `[text](url)`
 - Headings: `# H1`, `## H2`, etc.
 - Lists: `- item` or `1. item`
 - Blockquotes: `> text`

docs/prd/atmos-error-implementation-plan.md

@@ -446,7 +446,7 @@ docs/
   errors.md              # Developer how-to guide (NEW)
 
   prd/
-    atmos-error-handling.md              # Architecture PRD (NEW)
+    error-handling.md              # Architecture PRD (NEW)
     atmos-error-implementation-plan.md   # This file
     error-handling-strategy.md           # Updated
 

docs/prd/atmos-profiles.md

@@ -1815,4 +1815,4 @@ atmos profile validate ci
 - [XDG Base Directory Specification PRD](./xdg-base-directory-specification.md) - XDG support for user-global profiles
 - [Atmos Configuration Documentation](https://atmos.tools/cli/configuration)
 - [Viper Configuration Library](https://github.com/spf13/viper)
-- [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)
+- [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir/basedir-spec-latest.html)

docs/prd/auth-architecture-linter-rules.md

@@ -209,5 +209,5 @@ import (
 
 - Command Registry Pattern: `docs/prd/command-registry-pattern.md`
 - Error Handling Linter Rules: `docs/prd/error-handling-linter-rules.md`
-- Testing Strategy: `docs/prd/testing-strategy.md`
+- Testing Strategy: `docs/prd/testability-refactoring-strategy.md`
 - Interface-Driven Design: `CLAUDE.md` - "Architectural Patterns"

docs/prd/auth-context-multi-identity.md

@@ -1129,7 +1129,7 @@ func processTagStore(
 ## References
 
 - [Original Issue Report](#problem-statement)
-- [Atmos Auth PRD](../pkg/auth/docs/PRD/PRD-Atmos-Auth.md)
+- [Atmos Auth PRD](../../pkg/auth/docs/PRD/PRD-Atmos-Auth.md)
 - [AWS SDK Go v2 Configuration](https://aws.github.io/aws-sdk-go-v2/docs/configuring-sdk/)
 - [Error Handling Strategy](error-handling-strategy.md)
 

docs/prd/auth-file-isolation-pattern.md

@@ -517,7 +517,7 @@ When implementing this pattern for an existing provider that uses non-XDG paths:
 3. **Provider-specific PRDs**:
    - [AWS Authentication File Isolation](./aws-auth-file-isolation.md)
    - [Azure Authentication File Isolation](./azure-auth-file-isolation.md)
-4. **[XDG Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html)** - Official standard
+4. **[XDG Specification](https://specifications.freedesktop.org/basedir/basedir-spec-latest.html)** - Official standard
 
 ## Success Metrics
 

docs/prd/auth-list-command.md

@@ -1087,7 +1087,7 @@ func validateMermaidStructure(mermaid string) error
 - Atmos Authentication Documentation: https://atmos.tools/cli/commands/auth/
 - CLAUDE.md: ../../CLAUDE.md - Atmos coding conventions
 - Error Handling Strategy: ./error-handling-strategy.md
-- Testing Strategy: ./testing-strategy.md
+- Testing Strategy: ./testability-refactoring-strategy.md
 - Charmbracelet Bubbles Table: https://github.com/charmbracelet/bubbles/tree/master/table
 - Charmbracelet Lipgloss: https://github.com/charmbracelet/lipgloss
 - Graphviz DOT Language: https://graphviz.org/doc/info/lang.html
@@ -1414,8 +1414,7 @@ atmos auth list --format graphviz > auth-graph.dot
 ### Next Steps
 
 - See full documentation: https://atmos.tools/cli/commands/auth/list
-- Configure authentication: https://atmos.tools/cli/commands/auth/
-- Learn about authentication providers: https://atmos.tools/core-concepts/auth-providers
+- Configure authentication: https://atmos.tools/cli/commands/auth/login
 
 ---
 

docs/prd/auth-logout.md

@@ -782,8 +782,8 @@ func (p *GCPProvider) Logout(ctx context.Context) error
 
 ## 12. References
 
-- [PRD: Atmos Auth](pkg/auth/docs/prd/PRD-Atmos-Auth.md)
-- [Atmos Error Handling Strategy](docs/prd/error-handling-strategy.md)
-- [Atmos Testing Strategy](docs/prd/testing-strategy.md)
+- [PRD: Atmos Auth](../../pkg/auth/docs/PRD/PRD-Atmos-Auth.md)
+- [Atmos Error Handling Strategy](./error-handling-strategy.md)
+- [Atmos Testability Refactoring Strategy](./testability-refactoring-strategy.md)
 - [Charmbracelet Huh Documentation](https://github.com/charmbracelet/huh)
 - [Charmbracelet Lipgloss Documentation](https://github.com/charmbracelet/lipgloss)