Fix toolchain set, markdown text loss, and mise/aqua migration doc bugs

.claude/skills/changelog/SKILL.md

@@ -84,6 +84,28 @@ problem or technique first, the way someone outside the project would recognize
 
 Structure the body `## The Problem` / `## The Fix` / `## How to Use It` / `## Get Involved`.
 
+### Rule 1a — Open on the real reason, at the scope it actually applies to
+
+Find the actual motivating reason for the change (PR description, linked issue, commit messages) before
+writing the intro, and open on *that* — not a plausible-sounding scenario constructed to fit it, and not
+narrowed to the one path you happened to notice it through when the real gap is broader. Both are the same
+mistake: substituting a specific, contrived framing for the real, general one.
+
+- **Correct** — `2026-07-13-atmos-stack-schema-command.mdx`: "Editors, CI pipelines, and offline
+  environments that want to validate stack manifests locally have had one option: fetch the JSON Schema
+  from `atmos.tools`... and hope it matches." A real, checkable limitation, not an anecdote.
+- **Violation (invented)** — `2026-08-06-toolchain-lockfile-default.mdx` opened with a fabricated "a
+  teammate's laptop and CI don't quite match" vignette, when the real reason (stated correctly two
+  paragraphs later) was simpler: the fix already existed but was undocumented, so nobody enabled it.
+- **Violation (over-narrowed)** — `2026-08-05-taskfile-convergence.mdx` opens "If you've ever tried to move
+  a `Taskfile.yml` over to Atmos, you've hit the gap..." — framing a general task-runner deficiency (no
+  dependency ordering, no incremental builds — table-stakes features nearly every task runner has) as if it
+  only matters to people migrating from one specific competitor. The real problem, stated correctly under
+  `## The Problem`, is category-general: Atmos was missing it as a task runner, full stop.
+
+If you can't find the real reason, ask rather than invent one — and state it at the scope it actually
+applies to.
+
 ## Rule 2 — Never open prose with a backtick
 
 Prose (a sentence, paragraph, or the post intro) must start with a word, not an inline code span or fence.
@@ -130,6 +152,8 @@ implementation structure — describe behavior only in CLI/config/output terms.
 ## Pre-publish checklist
 
 - [ ] Intro opens on the problem, not the feature, and doesn't open with a backtick
+- [ ] The opening problem is the real, specific reason this change happened (checked against the PR
+      description/issue/commits) — not a generic scenario invented to justify it
 - [ ] Body follows Problem → Fix → How to Use It → Get Involved (no `## What Changed` opener)
 - [ ] Tag(s) exist in `website/blog/tags.yml`
 - [ ] Author exists in `website/blog/authors.yml` (added in this PR if new)

.github/actions/go-mod-download-retry/action.yml

@@ -0,0 +1,38 @@
+name: Go Mod Download With Retry
+description: >
+  Runs `go mod download`, retrying on transient proxy.golang.org failures. A
+  request that gets reset mid-stream (e.g. "stream error: stream ID <n>;
+  INTERNAL_ERROR; received from peer") is not retried by `go mod download`
+  itself, and GOPROXY's `|direct` fallback only helps when the proxy is
+  unreachable outright, not a mid-stream reset. Makes up to three attempts
+  with a cooldown between each, matching the convention already used for
+  artifact downloads (.github/actions/download-artifact-retry) and
+  magefiles/build.go's runGoModDownload. See
+  docs/fixes/2026-08-25-build-atmos-go-mod-download-retry.md.
+
+inputs:
+  backoff-seconds:
+    description: 'Seconds to wait before each retry'
+    required: false
+    default: '15'
+
+runs:
+  using: composite
+  steps:
+    - name: go mod download (with retry)
+      shell: bash
+      env:
+        BACKOFF_SECONDS: ${{ inputs.backoff-seconds }}
+      run: |
+        set -euo pipefail
+        attempt=1
+        max_attempts=3
+        until go mod download; do
+          if [ "$attempt" -ge "$max_attempts" ]; then
+            echo "go mod download failed after $max_attempts attempts" >&2
+            exit 1
+          fi
+          echo "go mod download failed (attempt $attempt/$max_attempts), retrying in ${BACKOFF_SECONDS}s..." >&2
+          sleep "$BACKOFF_SECONDS"
+          attempt=$((attempt + 1))
+        done

.github/workflows/test.yml

@@ -238,8 +238,20 @@ jobs:
     # cache save (tar + zstd) runs after that and is much slower on Windows,
     # so a flat 20m job budget can expire mid-save even though the test
     # itself already passed (see the Acceptance tests step's timeout comment
-    # below for the same Windows-is-slower pattern).
-    timeout-minutes: ${{ matrix.flavor.target == 'windows' && 30 || 20 }}
+    # below for the same Windows-is-slower pattern). 30m (raised from 20 in
+    # #2959) was still not enough: GitHub Job ID 99475416637 hit it at
+    # 30m27s even though every step had genuinely completed or nearly
+    # completed -- "Get dependencies" (normally ~5s) took ~5m, the test step
+    # itself (normally ~1m, well under its own 15m budget) took ~10.5m, and
+    # "Post Set up Go" (normally near-instant) took ~10.5m before finishing
+    # successfully; only the next step, "Post Cache Atmos toolchain"
+    # (normally ~42s), was still running when the job clock ran out. That
+    # uniform ~10x slowdown across three unrelated operations (dependency
+    # download, test execution, cache save) is the signature of a
+    # degraded/throttled runner that day, not a code regression -- see
+    # docs/fixes/2026-08-31-terraform-registry-cache-windows-runner-degradation.md.
+    # Raised to 45m for real headroom above that worst case.
+    timeout-minutes: ${{ matrix.flavor.target == 'windows' && 45 || 20 }}
     runs-on: ${{ matrix.flavor.os }}
     steps:
       - name: Harden Runner

.github/workflows/website-deploy-prod.yml

@@ -65,6 +65,13 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      # `go run .` below has no prior module cache warm-up, so a single
+      # mid-stream proxy.golang.org reset (e.g. "stream error: ...
+      # INTERNAL_ERROR; received from peer") aborts it outright -- see
+      # docs/fixes/2026-08-25-build-atmos-go-mod-download-retry.md.
+      - name: Download Go modules (with retry)
+        uses: ./.github/actions/go-mod-download-retry
+
       - name: Generate atmos-manifest schema
         # website/static/schemas/atmos/atmos-manifest/ is gitignored (see .gitignore) — it is
         # never hand-maintained or committed, only generated here from the embedded schema

.github/workflows/website-preview-build.yml

@@ -51,6 +51,13 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      # `go run .` below has no prior module cache warm-up, so a single
+      # mid-stream proxy.golang.org reset (e.g. "stream error: ...
+      # INTERNAL_ERROR; received from peer") aborts it outright -- see
+      # docs/fixes/2026-08-25-build-atmos-go-mod-download-retry.md.
+      - name: Download Go modules (with retry)
+        uses: ./.github/actions/go-mod-download-retry
+
       - name: Generate atmos-manifest schema
         # website/static/schemas/atmos/atmos-manifest/ is gitignored (see .gitignore) — it is
         # never hand-maintained or committed, only generated here from the embedded schema

.gitignore

@@ -144,9 +144,9 @@ TEST_QUALITY_*.md
 /lintroller
 /.lintroller
 tools/lintroller/.lintroller
+tools/gomodcheck/.gomodcheck
 .golangci/lintroller/lintroller
 /custom-gcl
-tools/gomodcheck/.gomodcheck
 
 # golangci-lint per-worktree cache + lock isolation (see
 # magefiles/mage_lint_golangci_run.go). The cache is large (100MB+); .golangci-tmp

agent-skills/AGENTS.md

@@ -141,7 +141,7 @@ When a task involves Atmos, activate the matching skill for detailed guidance.
 | AWS ECR: registry login, ECR auth integrations, Docker credential writes                                          | `atmos-aws-ecr`         | `agent-skills/skills/atmos-aws-ecr/SKILL.md`         |
 | AWS compliance: Security Hub standards, compliance reports, CIS AWS, PCI DSS, SOC2, HIPAA, NIST                   | `atmos-aws-compliance`  | `agent-skills/skills/atmos-aws-compliance/SKILL.md`  |
 | AWS security: analyze findings, map to components/stacks, structured remediation                                  | `atmos-aws-security`    | `agent-skills/skills/atmos-aws-security/SKILL.md`    |
-| Migrating to Atmos from native Terraform/OpenTofu, Terraform Workspaces, or Terramate: layout, workspace mapping, remote-state bridge, generate_hcl/script decomposition | `atmos-migration`       | `agent-skills/skills/atmos-migration/SKILL.md`       |
+| Migrating to Atmos from native Terraform/OpenTofu, Terraform Workspaces, or Terramate (layout, workspace mapping, remote-state bridge, generate_hcl/script decomposition), or migrating CLI tool-version management from mise or Aqua CLI to the Atmos toolchain | `atmos-migration`       | `agent-skills/skills/atmos-migration/SKILL.md`       |
 | Atmos Modernization: replace deprecated patterns with current Atmos naming, CI, Pro, auth, secrets, and dependencies | `atmos-modernization`   | `agent-skills/skills/atmos-modernization/SKILL.md`   |
 
 ## Common Patterns

agent-skills/skills/atmos-migration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: atmos-migration
-description: "Migrating to Atmos from existing IaC: techniques, tactics, and design patterns for native Terraform, Terraform Workspaces, and Terramate — minimum-disruption paths, file-layout options, workspace mapping, tag/generate_hcl/script decomposition, and the remote-state bridge for progressive migration"
+description: "Migrating to Atmos from existing IaC: techniques, tactics, and design patterns for native Terraform, Terraform Workspaces, and Terramate — minimum-disruption paths, file-layout options, workspace mapping, tag/generate_hcl/script decomposition, and the remote-state bridge for progressive migration; also covers migrating CLI tool-version management from mise or Aqua CLI to the Atmos toolchain"
 metadata:
   copyright: Copyright Cloud Posse, LLC 2026
   version: "1.0.0"
@@ -11,6 +11,8 @@ references:
   - references/remote-state-bridge.md
   - references/from-terramate.md
   - references/from-component-updater.md
+  - references/from-mise.md
+  - references/from-aqua.md
 ---
 
 # Migrating to Atmos
@@ -22,6 +24,10 @@ Atmos is designed to **adopt an existing repo without forcing a reorganization**
 `components/terraform/` layout is a recommendation, not a requirement. Lead with the minimum
 change that delivers value, then escalate only as the user's needs grow.
 
+This skill also covers migrating CLI tool-version management from mise or Aqua CLI to the Atmos
+toolchain -- see [from-mise.md](references/from-mise.md) and
+[from-aqua.md](references/from-aqua.md) in the routing table below.
+
 For full prose tutorials aimed at end users, link to:
 
 - [Migrating from Native Terraform](https://atmos.tools/migration/native-terraform)
@@ -80,6 +86,8 @@ different reference:
 | `.tm.hcl` files, `stack.tm.hcl`, `generate_hcl` blocks (Terramate project) | [from-terramate.md](references/from-terramate.md) |
 | Need to read outputs from un-migrated TF (legacy or another repo)    | [remote-state-bridge.md](references/remote-state-bridge.md) |
 | `cloudposse/github-action-atmos-component-updater`                   | [from-component-updater.md](references/from-component-updater.md) |
+| mise config (`mise.toml`, `.mise.toml`, `.mise/config.toml`, `.tool-versions`) for tool versions | [from-mise.md](references/from-mise.md) |
+| `aqua.yaml` (Aqua CLI) for tool versions                             | [from-aqua.md](references/from-aqua.md) |
 
 The remote-state-bridge pattern is what makes **progressive, component-by-component migration**
 possible. Without it, a team is forced into a big-bang cutover. Cover it any time the user has
@@ -196,3 +204,7 @@ Things to push back on if a user (or another agent) proposes them during migrati
 - [References/from-terramate.md](references/from-terramate.md) -- construct-by-construct mapping
   from Terramate (`stack.tm.hcl`, globals, `generate_hcl`, `script{}`, tags/labels) to Atmos,
   including the one remaining known gap (`.tmtriggers`)
+- [References/from-mise.md](references/from-mise.md) -- migrating tool versions, tasks, and env
+  vars from mise to the Atmos toolchain
+- [References/from-aqua.md](references/from-aqua.md) -- migrating tool versions from Aqua CLI's
+  `aqua.yaml` to the Atmos toolchain