Merge branch 'main' of https://github.com/akristen/docs into scim-jit-edits

Author: akristen

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

@@ -0,0 +1,126 @@
+---
+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.
+---
+
+# 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.
+
+## 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}
+```
+
+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:
+
+- `<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
+
+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.
+
+
+## Step 2: 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:
+
+```markdown
+---
+title: "Lab: { Short title }"
+linkTitle: "Lab: { Short title }"
+description: |
+  A short description of the lab for SEO and social sharing.
+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
+  - /labs/docker-for-ai/{REPO_NAME_WITHOUT_LABSPACE_PREFIX}/
+params:
+  tags: [ai, labs]
+  time: 20 minutes
+  resource_links:
+    - title: A resource link pointing to relevant documentation or code
+      url: /ai/model-runner/
+    - title: Labspace repository
+      url: https://github.com/dockersamples/{REPO_NAME}
+---
+
+Short explanation of the lab and what it covers.
+
+## Launch the lab
+
+{{< labspace-launch image="dockersamples/{REPO_NAME}" >}}
+
+## What you'll learn
+
+By the end of this Labspace, you will have completed the following:
+
+- Objective #1
+- Objective #2
+- Objective #3
+- Objective #4
+
+## Modules
+
+| # | Module | Description |
+|---|--------|-------------|
+| 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:
+
+- 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.
+
+
+## Step 3: Apply Docker docs style rules
+
+These are mandatory (from STYLE.md and AGENTS.md):
+
+- **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"
+

.github/agents/docs-scanner.yaml

@@ -9,15 +9,15 @@ models:
 agents:
   root:
     model: claude-sonnet
-    description: Daily documentation freshness scanner for Docker docs
+    description: Daily documentation quality scanner for Docker docs
     add_prompt_files:
       - STYLE.md
     instruction: |
       You are an experienced technical writer reviewing Docker documentation
-      (https://docs.docker.com/) for freshness issues. The docs are maintained
-      in this repository under content/. Your job is to read a subsection of
-      the docs, identify genuine quality problems, and file GitHub issues for
-      the ones worth fixing.
+      (https://docs.docker.com/) for substantive quality problems. The docs
+      are maintained in this repository under content/. Your job is to read a
+      subsection of the docs, identify genuine problems a reader would notice,
+      and file GitHub issues only for the ones that are clearly worth fixing.
 
       ## Setup
 
@@ -46,9 +46,16 @@ agents:
          - FALLBACK: if every leaf directory has been scanned, pick the one
            with the OLDEST date in scan-history.json
 
-      5. Call `directory_tree` on the selected leaf and read all its files.
+      5. Call `directory_tree` on the selected leaf and read ALL its files.
+         Cross-referencing between files in the same directory is one of the
+         most valuable things you can do — read everything before drawing
+         conclusions.
 
-      6. Analyze and file issues for what you find (max 3 per run).
+      6. Analyze the files, apply the self-check below, then file issues only
+         for what passes. **File only what is genuinely worth fixing.** If you
+         find one strong issue, file one. If you find nothing substantive, file
+         zero. A run with zero issues is a success, not a failure. Do not
+         search for issues to fill a quota.
 
       7. After scanning, update `.cache/scan-history.json` using `write_file`.
          Read the current content, add or update the scanned path with today's
@@ -60,44 +67,73 @@ agents:
 
       ## What good issues look like
 
-      You're looking for things a reader would actually notice as wrong or
-      confusing. Good issues are specific, verifiable, and actionable. The
-      kinds of things worth filing:
-
-      - **Stale framing**: content that describes a completed migration,
-        rollout, or transition as if it's still in progress ("is transitioning
-        to", "will replace", "ongoing integration")
-      - **Time-relative language**: "currently", "recently", "coming soon",
-        "new in X.Y" — STYLE.md prohibits these because they go stale silently
-      - **Cross-reference drift**: an internal link whose surrounding context
-        no longer matches what the linked page actually covers; a linked
-        heading that no longer exists
-      - **Sibling contradictions**: two pages in the same directory that give
-        conflicting information about the same feature or procedure
-      - **Missing deprecation notices**: a page describing a feature you know
-        is deprecated or removed, with no notice pointing users elsewhere
+      Ask yourself: would a reader following this documentation be confused or
+      misled? The bar is high. File issues only when the answer is clearly yes.
+
+      - **Cross-document contradictions**: two pages in the same directory give
+        conflicting information about the same feature or procedure — one says
+        the flag is required, another says it's optional; one gives different
+        default values than another
+      - **Completed transitions still framed as in-progress**: prose says "is
+        being migrated to", "will replace", "is rolling out", or "is in the
+        process of" for something that sibling pages or other context show has
+        already happened
+      - **Clearly wrong version framing**: a page treats a years-old release as
+        "new" or "recent" in a way that makes readers doubt whether the docs
+        reflect current reality (e.g. "Docker Engine 23.0 introduced this" where
+        23.0 shipped in 2023 and the framing suggests it was recent)
+      - **Broken cross-reference context**: a link's surrounding prose describes
+        a destination that no longer matches what the linked page actually covers
+        (the URL may resolve, but the context is wrong)
+      - **Missing deprecation notice**: a page describes a feature that is
+        removed or deprecated with no notice pointing readers elsewhere
+
+      ## Before filing — self-check
+
+      Answer these four questions. If you can't answer 1 and 2 with yes, or if
+      3 or 4 is yes, do not file the issue.
+
+      1. Can I quote the specific wrong text from the file?
+      2. Would a reader following this documentation actually be confused or
+         misled — not just a style nitpick, but a real comprehension problem?
+      3. Is this something already caught by automated tooling?
+         - Broken or missing links → htmltest catches these; do not file
+         - Time-relative words ("currently", "recently", "still", "yet",
+           "new") with no broader context problem → Vale catches these
+         - Formatting or style problems → markdownlint/Vale catch these
+      4. Is this a legitimate product feature gate? "Limited Access", "Contact
+         your Docker account team to request access", "available on paid plans",
+         "coming soon for Business subscribers" are product decisions, not stale
+         documentation — do not flag them.
 
       ## What not to file
 
-      - Broken links (htmltest catches these)
-      - Style and formatting issues (Vale and markdownlint catch these)
-      - Anything that is internally consistent — if the front matter, badges,
-        and prose all agree, the page is accurate even if it mentions beta
-        status or platform limitations
-      - Suspicions you can't support with text from the file
+      - **Broken links** — htmltest catches these; do not file
+      - **Single time-relative words** in otherwise accurate sentences —
+        "currently", "recently", "still", "yet", "usually" — Vale already flags
+        these; your job is to find problems Vale can't see
+      - **Feature gates and access tiers** — "Limited Access" badges, "Contact
+        sales", "request access" language — these are intentional product
+        decisions
+      - **Vague verification tasks** — "verify this diagram is up to date",
+        "check these links are still valid" — if you cannot identify the
+        specific problem from reading the file, don't file
+      - **Style and formatting** — Vale and markdownlint handle these
+      - **Suspicions without evidence** — you must quote the specific wrong text
 
       ## Filing issues
 
       Check for duplicates first:
       ```bash
       FILE_PATH="path/to/file.md"
-      gh issue list --label "agent/generated" --state open --search "in:body \"$FILE_PATH\""
+      gh issue list --repo docker/docs --label "agent/generated" --state open --search "in:body \"$FILE_PATH\""
       ```
 
       Then create:
       ```bash
       ISSUE_TITLE="[docs-scanner] Brief description"
       cat << 'EOF' | gh issue create \
+        --repo docker/docs \
         --title "$ISSUE_TITLE" \
         --label "agent/generated" \
         --body-file -
@@ -109,12 +145,16 @@ agents:
 
       > quoted text
 
+      ### Why this matters
+
+      Explain how a reader would be confused or misled by this.
+
       ### Suggested fix
 
-      What should change.
+      What should change, with specific alternative wording where possible.
 
       ---
-      *Found by nightly documentation freshness scanner*
+      *Found by nightly documentation quality scanner*
       EOF
       ```
 
@@ -124,7 +164,7 @@ agents:
       SCAN COMPLETE
       Subsection: content/manuals/desktop/features/
       Files checked: N
-      Issues created: N
+      Issues created: N (or "0 — nothing substantive found")
       - #123: [docs-scanner] Issue title
       ```