Merge branch 'docker:main' into main

Author: lungayken-ux

.agents/skills/create-lab-guide/SKILL.md

@@ -1,55 +1,44 @@
 ---
 name: create-lab-guide
-description: >
-  Create a guide page for a Labspace. This includes writing the markdown content for the guide, 
-  structuring it according to Docker docs conventions, and ensuring it provides clear instructions 
-  and information about the Labspace. Includes learning about the lab itself, extracting out its
-  learning objectives, and combining all of that into a well-structured guide markdown file.
+description: "Clone a dockersamples Labspace repo, extract learning objectives and module structure from labspace.yaml, and produce a Hugo guide page under content/guides/ with correct frontmatter, labspace-launch shortcode, and Docker docs style compliance. Use when asked to create a lab guide, write a Labspace page, add a Docker lab tutorial, migrate a lab to docs, or document a hands-on lab."
 ---
 
 # Create Lab Guide
 
-You are creating a new guide page for a labspace. The guide should be structured according to Docker docs conventions, 
-with clear sections, learning objectives, and instructions for users to get the most out of the lab.
+Create a guide page for a Docker Labspace: clone the source repo, extract
+structure from `labspace.yaml`, write the Hugo markdown page, and validate.
 
 ## Inputs
 
-The user provides one or more guides to migrate. Resolve these from the inventory below:
-
 - **REPO_NAME**: GitHub repo in the `dockersamples` org (e.g. `labspace-ai-fundamentals`)
 
 ## Step 1: Clone the labspace repo
 
-Clone the guide repo to a temporary directory. This gives you all source files locally — no HTTP calls needed.
-
 ```bash
-git clone --depth 1 https://github.com/dockersamples/{REPO_NAME}.git <tmpdir>/{REPO_NAME}
+TMPDIR=$(mktemp -d)
+git clone --depth 1 https://github.com/dockersamples/{REPO_NAME}.git "$TMPDIR/{REPO_NAME}"
 ```
 
-Where `<tmpdir>` is a temporary directory on your system (e.g. the output of `mktemp -d`).
-
-## Step 2: Learn and extract key information about the lab
-
-The repo structure is:
+## Step 2: Extract key information
 
-- `<tmpdir>/{REPO_NAME}/README.md` — the main README for the lab
-- `<tmpdir>/{REPO_NAME}/labspace/labspace.yaml` — a YAML document outlining details of the lab, including the sections/modules and the path to their content
-- `<tmpdir>/{REPO_NAME}/labspace/*.md` — the content for each section/module (only reference the files specified in `labspace.yaml`)
-- `<tmpdir>/{REPO_NAME}/.github/workflows/` — the GHA workflow that publishes the labspace. It includes the repo URL for the published Compose file, which will be useful for the "launch" command
-- `<tmpdir>/{REPO_NAME}/compose.override.yaml` - lab-specific Compose customizations
+Read these files from the cloned repo:
 
-1. Read `README.md` to understand the purpose of the lab.
-2. Read the `labspace/labspace.yaml` to understand the structure of the lab and its sections/modules.
-3. Read the `labspace/*.md` files to extract the learning objectives, instructions, and any code snippets.
-4. Extract a short description that can be used for the `description` and `summary` fields in the guide markdown.
-5. Determine if a model will be pulled when starting the lab by looking at the `compose.override.yaml` file and looking for the any top-level `model` specifications.
+| File | Purpose |
+|------|---------|
+| `README.md` | Lab purpose and overview |
+| `labspace/labspace.yaml` | Module structure and content paths |
+| `labspace/*.md` | Module content (only files listed in `labspace.yaml`) |
+| `.github/workflows/*.yml` | Published Compose file URL for the launch command |
+| `compose.override.yaml` | Check for top-level `model` specs (triggers `model-download` param) |
 
+Extract:
+1. A short description for the `description` and `summary` frontmatter fields.
+2. Learning objectives from the module content.
+3. Whether a model download is required (`compose.override.yaml` → top-level `model` key).
 
-## Step 2: Write the guide markdown
+## Step 3: Write the guide markdown
 
-The markdown file must be located in the `guides/` directory and have a filename of `lab-{GUIDE_ID}.md`.
-
-Sample markdown structure, including frontmatter and content:
+Place the file at `content/guides/lab-{GUIDE_ID}.md`.
 
 ```markdown
 ---
@@ -60,7 +49,7 @@ description: |
 summary: |
   A short summary of the lab for the guides listing page. 2-3 lines.
 keywords: AI, Docker, Model Runner, agentic apps, lab, labspace
-aliases: # Include if the lab is an AI-related lab
+aliases: # Include only for AI-related labs
   - /labs/docker-for-ai/{REPO_NAME_WITHOUT_LABSPACE_PREFIX}/
 params:
   tags: [ai, labs]
@@ -85,7 +74,6 @@ By the end of this Labspace, you will have completed the following:
 - Objective #1
 - Objective #2
 - Objective #3
-- Objective #4
 
 ## Modules
 
@@ -94,33 +82,35 @@ By the end of this Labspace, you will have completed the following:
 | 1 | Module #1 | Description of module #1 |
 | 2 | Module #2 | Description of module #2 |
 | 3 | Module #3 | Description of module #3 |
-| 4 | Module #4 | Description of module #4 |
-| 5 | Module #5 | Description of module #5 |
-| 6 | Module #6 | Description of module #6 |
 ```
 
-Important notes:
+Conditional rules:
+- All lab guides **must** include `labs` in `params.tags`.
+- AI-related labs: also add `ai` tag and an alias under `/labs/docker-for-ai/`.
+- If a model download is required: add `model-download: true` to the `labspace-launch` shortcode.
+
+## Step 4: Apply Docker docs style rules
+
+Follow STYLE.md and COMPONENTS.md. Key rules:
 
-- The learning objectives should be based on the content of the labspace as a whole.
-- The modules should be based on the sections/modules outlined in `labspace.yaml`.
-- All lab guides _must_ have a tag of `labs`
-- If the lab is AI-related, it should also have a tag of `ai` and aliases for `/labs/docker-for-ai/{REPO_NAME}/`
-- If the lab pulls a model, add a `model-download: true` parameter to the `labspace-launch` shortcode to show a warning about model downloads.
+| Avoid | Use instead |
+|-------|-------------|
+| "we", "let's" | Imperative voice or "you" |
+| "simply", "easily", "just" | Remove the hedge word |
+| "allows you to" / "enables you to" | "lets you" or rephrase |
+| "click" | "select" |
+| Bold for emphasis / product names | Bold only for UI elements |
+| "currently", "new", "recently" | Remove time-relative language |
 
+Use `console` as the language hint for shell blocks with `$` prompts.
+Use contractions ("it's", "you're", "don't").
 
-## Step 3: Apply Docker docs style rules
+## Step 5: Validate
 
-These are mandatory (from STYLE.md and AGENTS.md):
+1. Confirm frontmatter has `title`, `description`, `keywords`, and `params.tags` including `labs`.
+2. Run `npx prettier --write <file>` to format.
+3. Run `docker buildx bake lint vale` and fix any errors.
+4. Re-read the file and verify: correct shortcode syntax, objectives match source content, modules match `labspace.yaml`, no vendored paths edited.
 
-- **No "we"**: "We are going to create" → "Create" or "Start by creating"
-- **No "let us" / "let's"**: → imperative voice or "You can..."
-- **No hedge words**: remove "simply", "easily", "just", "seamlessly"
-- **No meta-commentary**: remove "it's worth noting", "it's important to understand"
-- **No "allows you to" / "enables you to"**: → "lets you" or rephrase
-- **No "click"**: → "select"
-- **No bold for emphasis or product names**: only bold UI elements
-- **No time-relative language**: remove "currently", "new", "recently", "now"
-- **No exclamations**: remove "Voila!!!" etc.
-- Use `console` language hint for interactive shell blocks with `$` prompts
-- Use contractions: "it's", "you're", "don't"
+Do not proceed to commit until validation passes.
 

.agents/skills/write/SKILL.md

@@ -45,7 +45,7 @@ Prettier runs automatically after each edit via the PostToolUse hook.
 Run lint manually after all edits are complete:
 
 ```bash
-${CLAUDE_SKILL_DIR}/scripts/lint.sh <changed-files>
+scripts/lint.sh <changed-files>
 ```
 
 The lint script runs markdownlint and vale on only the files you pass it,

.github/workflows/deploy.yml

@@ -68,7 +68,7 @@ jobs:
       -
         name: Configure AWS Credentials
         if: ${{ env.DOCS_AWS_IAM_ROLE != '' }}
-        uses: aws-actions/configure-aws-credentials@61815dcd50bd041e203e49132bacad1fd04d2708 # v5
+        uses: aws-actions/configure-aws-credentials@d979d5b3a71173a29b74b5b88418bfda9437d885 # v6.1.1
         with:
           role-to-assume: ${{ env.DOCS_AWS_IAM_ROLE }}
           aws-region: ${{ env.DOCS_AWS_REGION }}

.github/workflows/labeler.yml

@@ -5,7 +5,7 @@ concurrency:
   cancel-in-progress: true
 
 on:
-  workflow_dispatch:
+  pull_request_target:
 
 jobs:
   labeler:
@@ -16,4 +16,4 @@ jobs:
     steps:
       -
         name: Run
-        uses: actions/labeler@634933edcd8ababfe52f92936142cc22ac488b1b # v6.0.1
+        uses: actions/labeler@f27b608878404679385c85cfa523b85ccb86e213 # v6.1.0

.github/workflows/nightly-docs-scan.yml

@@ -50,7 +50,7 @@ jobs:
       - name: Configure AWS credentials
         id: aws-credentials
         continue-on-error: true
-        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4
+        uses: aws-actions/configure-aws-credentials@d979d5b3a71173a29b74b5b88418bfda9437d885 # v6.1.1
         with:
           role-to-assume: arn:aws:iam::710015040892:role/docker-agent-action-20260409141318957000000001
           aws-region: us-east-1
@@ -66,7 +66,7 @@ jobs:
           echo "GITHUB_APP_TOKEN=$PAT" >> "$GITHUB_ENV"
 
       - name: Run documentation scan
-        uses: docker/cagent-action@0498757af1c50b084f763d626f571918cf317509 # latest
+        uses: docker/cagent-action@f208610469d69f20983cad64c577949a132caa33 # v1.5.3
         env:
           GH_TOKEN: ${{ env.GITHUB_APP_TOKEN || github.token }}
         with:

.github/workflows/notify-release-notes-pr.yml

@@ -25,7 +25,7 @@ jobs:
           echo "author=$(jq -r .author pr-details.json)" >> "$GITHUB_OUTPUT"
 
       - name: Notify Slack
-        uses: slackapi/slack-github-action@af78098f536edbc4de71162a307590698245be95 # v3.0.1
+        uses: slackapi/slack-github-action@45a88b9581bfab2566dc881e2cd66d334e621e2c # v3.0.3
         with:
           method: chat.postMessage
           token: ${{ secrets.SLACK_BOT_TOKEN }}

.github/workflows/pr-review.yml

@@ -14,7 +14,7 @@ jobs:
     if: |
       github.event_name == 'issue_comment' ||
       github.event.workflow_run.conclusion == 'success'
-    uses: docker/cagent-action/.github/workflows/review-pr.yml@c22076b8856ee12d9b4c4685bb49cf26eb974079 # v1.5.0
+    uses: docker/cagent-action/.github/workflows/review-pr.yml@f208610469d69f20983cad64c577949a132caa33 # v1.5.3
     # Scoped to the job so other jobs in this workflow aren't over-permissioned
     permissions:
       contents: read # Read repository files and PR diffs

.vale.ini

@@ -3,45 +3,34 @@ MinAlertLevel = suggestion
 IgnoredScopes = text.frontmatter, code, tt, b, strong, i, a
 Vocab = Docker
 
-# Disable rules for genered content
-[content/reference/**/**.md]
-Vale.Spelling = NO
-Vale.Terms = NO
+# Generated reference content — disable rules that don't apply
+[content/reference/**]
 Docker.Capitalization = NO
-
-[content/manuals/*/release-notes/*.md]
 Vale.Spelling = NO
 Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.We = NO
 
-[content/manuals/*/release-notes.md]
-Vale.Spelling = NO
-Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.We = NO
-
-[content/contribute/*.md]
-Vale.Spelling = NO
-Vale.Terms = NO
+# Skip release notes and old desktop changelog content entirely
+[{content/manuals/*/release-notes.md,content/manuals/*/release-notes/**,content/manuals/desktop/previous-versions/**}]
+Docker.Avoid = NO
 Docker.Capitalization = NO
 Docker.Exclamation = NO
-
-[content/manuals/desktop/previous-versions/*.md]
+Docker.Forbidden = NO
+Docker.GenericCTA = NO
+Docker.HeadingPunctuation = NO
+Docker.ListComma = NO
+Docker.OxfordComma = NO
+Docker.RecommendedWords = NO
+Docker.Spacing = NO
+Docker.Terms = NO
+Docker.URLFormat = NO
+Docker.Units = NO
+Docker.VersionText = NO
+Docker.We = NO
 Vale.Spelling = NO
+Vale.Repetition = NO
 Vale.Terms = NO
-Docker.Capitalization = NO
-Docker.Exclamation = NO
 
 [*.md]
-BasedOnStyles = Vale, Docker
-# Exclude `{{< ... >}}`, `{{% ... %}}`, [Who]({{< ... >}})
-TokenIgnores = ({{[%<] .* [%>]}}.*?{{[%<] ?/.* [%>]}}), \
-(\[.+\]\({{< .+ >}}\)), \
-[^\S\r\n]({{[%<] \w+ .+ [%>]}})\s, \
-[^\S\r\n]({{[%<](?:/\*) .* (?:\*/)[%>]}})\s, \
-(?sm)({{[%<] .*?\s[%>]}})
-
-# Exclude `{{< myshortcode `This is some <b>HTML</b>, ... >}}`
-BlockIgnores = (?sm)^({{[%<] \w+ [^{]*?\s[%>]}})\n$, \
-(?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}})
+BasedOnStyles = Docker, Vale
+TokenIgnores = ({{[^}]+}}\S*)
+BlockIgnores = (?m)^[ \t]*({{[^}]+}})[ \t]*$, (\[[^\]]*{{[^}]+}}[^\]]*\]\([^)]*\))

AGENTS.md

@@ -80,6 +80,25 @@ introduced, which is permanently true.
 
 - Use lowercase "config" in prose — `vale.Terms` flags a capital-C "Config"
 
+### Updating the vocabulary
+
+If Vale flags a legitimate tech term, product name, or compound identifier
+as a misspelling, add it to `_vale/config/vocabularies/Docker/accept.txt`.
+This is optional — only update when a real new term is missing, not to
+silence individual violations.
+
+- Use the canonical form for case-sensitive product names (`PyTorch`,
+  `GitHub`, `Kubernetes`, `BuildKit`). `Vale.Terms` enforces that exact
+  case across the docs.
+- Use `[Aa]bcd` character-class regex for words that legitimately appear
+  in multiple cases (e.g., sentence-starting capitalization, or a name
+  that's also a generic noun). This covers spelling without enforcing
+  a single canonical form.
+- Avoid broad regex patterns — entries that match many words at once
+  (especially with `(?i)`) suppress other rule checks on every match.
+- Don't add a wrong-cased entry to silence one false positive — it
+  cascades into `Vale.Terms` violations on every correct usage.
+
 ## Alpine.js patterns
 
 Do not combine Alpine's `x-show` with the HTML `hidden` attribute on the
@@ -111,12 +130,17 @@ produces broken HTML — always check COMPONENTS.md for correct syntax.
 
 ```sh
 npx prettier --write <file>        # Format before committing
+scripts/lint.sh <file>...          # Lint specific files (markdownlint + vale)
 docker buildx bake validate        # Run all validation checks
 docker buildx bake lint            # Markdown linting only
 docker buildx bake vale            # Style guide checks only
 docker buildx bake test            # HTML and link checking
 ```
 
+For incremental work, prefer `scripts/lint.sh` over the `bake` targets —
+it runs the same checks on just the files you pass, so the output stays
+scoped to your changes instead of the whole repo.
+
 ### Validation in git worktrees
 
 `docker buildx bake validate` fails in git worktrees because Hugo cannot
@@ -128,9 +152,14 @@ and `validate-vendor` targets run correctly in CI.
 
 1. Make changes
 2. Format with prettier: `npx prettier --write <file>`
-3. Run `docker buildx bake lint vale`
+3. Lint the changed files: `scripts/lint.sh <file>...`
 4. Run a full build with `docker buildx bake` (optional for small changes)
 
+Always lint the specific files you changed before committing. Use
+`scripts/lint.sh` rather than the `bake` targets so the output is scoped
+to your changes — bake runs across the entire repo and the noise makes
+real issues easy to miss.
+
 ## Git hygiene
 
 - **Stage files explicitly.** Never use `git add .` / `git add -A` /

_vale/Docker/Capitalization.yml

@@ -7,4 +7,4 @@ action:
   params:
     - Docker
 tokens:
-  - '[^\[/]docker[^/]'
+  - '[^\[/\-.]docker[^/\-.\w]'