From 537d7c2be616ba3dee9a478d8fb05f7bbdf8840c Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust Date: Mon, 24 Aug 2026 16:48:45 -0700 Subject: [PATCH 1/3] feat: update QUICK_START guide with installation steps --- docs/guides/QUICK_START.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/guides/QUICK_START.mdx b/docs/guides/QUICK_START.mdx index f6abf09d..3cf83911 100644 --- a/docs/guides/QUICK_START.mdx +++ b/docs/guides/QUICK_START.mdx @@ -41,8 +41,11 @@ git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.g cd sample-autonomous-cloud-coding-agents # Trust mise config and install tools +curl https://mise.run | sh +eval "$(mise activate bash)" mise trust mise install +npm install -g aws-cdk # Enable Yarn via Corepack corepack enable From d2f84665b495c4bd3a09b46fdd338743d0082693 Mon Sep 17 00:00:00 2001 From: Scott Schreckengaust Date: Thu, 3 Sep 2026 16:16:32 -0700 Subject: [PATCH 2/3] Update installation command for mise tool --- docs/guides/QUICK_START.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/QUICK_START.mdx b/docs/guides/QUICK_START.mdx index 3cf83911..6fa3a346 100644 --- a/docs/guides/QUICK_START.mdx +++ b/docs/guides/QUICK_START.mdx @@ -41,7 +41,7 @@ git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.g cd sample-autonomous-cloud-coding-agents # Trust mise config and install tools -curl https://mise.run | sh +command -v mise >/dev/null || curl https://mise.run | sh eval "$(mise activate bash)" mise trust mise install From be2c20a813ba4221413ef0f70841d4e05c9c2c27 Mon Sep 17 00:00:00 2001 From: scottschreckengaust <345885+scottschreckengaust@users.noreply.github.com> Date: Thu, 3 Sep 2026 23:27:43 +0000 Subject: [PATCH 3/3] docs(quickstart): drop global aws-cdk install; fix docs-sync .mdx blind spot MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses both review comments on #780. `npm install -g aws-cdk` is not needed. `cdk/package.json` pins `aws-cdk: ^2` as a devDependency and every documented command reaches it through `mise //cdk:*`, which runs `npx cdk` against the workspace binary — Step 3 uses `mise //cdk:bootstrap` and `mise //cdk:deploy`, never a bare `cdk`. A global install can drift from the pinned version and shadow it on PATH, so the line is removed from Step 1 and the stale Prerequisites bullet (which contradicted the note directly below it) now says so explicitly. The `command -v mise` guard and `mise activate` lines are kept as reviewed. Also fixes the gate that let the mirror drift reach CI: the `docs-sync` hook filtered on `^docs/(design|guides)/.*\.md$`, and the `$` after `\.md` means `.mdx` never matched. QUICK_START.mdx is the only `.mdx` guide of 12, and it is exactly the file the hook could not see, so editing it skipped mirror regeneration locally and could only fail CI's "Files were changed during build" check. `sync-starlight.mjs` already knew how to mirror it; only the trigger was blind. The same `\.md$` bug in the trailing-whitespace / end-of-file-fixer excludes is fixed too — latent today (the mirror is clean) but it would pit those fixers against the generator. Starlight mirror regenerated and verified idempotent. Refs #780 --- .pre-commit-config.yaml | 14 +++++++++++--- docs/guides/QUICK_START.mdx | 3 +-- .../content/docs/getting-started/Quick-start.mdx | 4 +++- 3 files changed, 15 insertions(+), 6 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0b2f7a7c..42fa2707 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -11,9 +11,12 @@ repos: hooks: - id: trailing-whitespace # Skip generated trees and paths often checked in read-only (0444); mutating hooks must not touch them. - exclude: (cdk/cdk\.out/|node_modules/|^docs/src/content/docs/.*\.md$|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$|\.(snap|lock)$) + # `\.mdx?$` covers the .mdx mirrors too (Quick-start.mdx) — with a bare + # `\.md$` these fixers could reformat a generated file, which the next + # sync-starlight.mjs run then reverts, i.e. permanent CI self-mutation. + exclude: (cdk/cdk\.out/|node_modules/|^docs/src/content/docs/.*\.mdx?$|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$|\.(snap|lock)$) - id: end-of-file-fixer - exclude: (cdk/cdk\.out/|node_modules/|^docs/src/content/docs/.*\.md$|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$) + exclude: (cdk/cdk\.out/|node_modules/|^docs/src/content/docs/.*\.mdx?$|(^|/)LICENSE$|(^|/)\.gitattributes$|(^|/)\.npmignore$|(^|/)\.gitignore$|^cli/header\.js$|^docs/astro\.config\.mjs$|^docs/tsconfig\.json$|^docs/src/content\.config\.ts$) - id: check-merge-conflict - id: check-yaml exclude: ^(cdk/cdk\.out/|cdk\.out/|node_modules/|agent/\.venv/) @@ -59,7 +62,12 @@ repos: entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && node scripts/sync-starlight.mjs && git add src/content/docs/' language: system pass_filenames: false - files: ^(docs/(design|guides)/.*\.md$|CONTRIBUTING\.md$) + # `.mdx?$`, not `.md$`: QUICK_START.mdx is an .mdx source that + # sync-starlight.mjs mirrors to getting-started/Quick-start.mdx, but the + # `$` after `\.md` meant this hook never selected it — so edits to it + # skipped mirror regeneration locally and could only fail in CI's + # "Files were changed during build" check (PR #780). + files: ^(docs/(design|guides)/.*\.mdx?$|CONTRIBUTING\.md$) stages: [pre-commit] - id: docs-astro-check diff --git a/docs/guides/QUICK_START.mdx b/docs/guides/QUICK_START.mdx index 6fa3a346..9eed85b1 100644 --- a/docs/guides/QUICK_START.mdx +++ b/docs/guides/QUICK_START.mdx @@ -19,7 +19,7 @@ Install these before you begin: - **Docker** - for building the agent container image. On an **x86_64** host you also need QEMU/binfmt to build the arm64 (Graviton) image — see the caution in Step 3. - **Node.js** v20 or later (Node 24 is the supported maximum — see CI matrix) - **mise** - task runner ([install guide](https://mise.jdx.dev/getting-started.html)) -- **AWS CDK CLI** - `npm install -g aws-cdk` (after mise is active) +- **AWS CDK CLI** — **no global install needed.** Step 1's `mise run install` provisions the version pinned in `cdk/package.json` into the `cdk/` workspace, and every command in this guide reaches it through `mise //cdk:*` (which runs `npx cdk`). A global `npm install -g aws-cdk` can drift from the pinned version and shadow it on `PATH`. - **GitHub account** — You need a [GitHub profile](https://github.com/join) to fork the sample repository and create a **fine-grained personal access token (PAT)** the agent uses to push branches and open pull requests. A free github.com account is sufficient. :::note[mise provisions Node, Yarn, and the CDK CLI for you] @@ -45,7 +45,6 @@ command -v mise >/dev/null || curl https://mise.run | sh eval "$(mise activate bash)" mise trust mise install -npm install -g aws-cdk # Enable Yarn via Corepack corepack enable diff --git a/docs/src/content/docs/getting-started/Quick-start.mdx b/docs/src/content/docs/getting-started/Quick-start.mdx index bd14eaf4..112a46d6 100644 --- a/docs/src/content/docs/getting-started/Quick-start.mdx +++ b/docs/src/content/docs/getting-started/Quick-start.mdx @@ -19,7 +19,7 @@ Install these before you begin: - **Docker** - for building the agent container image. On an **x86_64** host you also need QEMU/binfmt to build the arm64 (Graviton) image — see the caution in Step 3. - **Node.js** v20 or later (Node 24 is the supported maximum — see CI matrix) - **mise** - task runner ([install guide](https://mise.jdx.dev/getting-started.html)) -- **AWS CDK CLI** - `npm install -g aws-cdk` (after mise is active) +- **AWS CDK CLI** — **no global install needed.** Step 1's `mise run install` provisions the version pinned in `cdk/package.json` into the `cdk/` workspace, and every command in this guide reaches it through `mise //cdk:*` (which runs `npx cdk`). A global `npm install -g aws-cdk` can drift from the pinned version and shadow it on `PATH`. - **GitHub account** — You need a [GitHub profile](https://github.com/join) to fork the sample repository and create a **fine-grained personal access token (PAT)** the agent uses to push branches and open pull requests. A free github.com account is sufficient. :::note[mise provisions Node, Yarn, and the CDK CLI for you] @@ -41,6 +41,8 @@ git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.g cd sample-autonomous-cloud-coding-agents # Trust mise config and install tools +command -v mise >/dev/null || curl https://mise.run | sh +eval "$(mise activate bash)" mise trust mise install