From 43a48b3a311c6cceed8634f55cbd344a565875c0 Mon Sep 17 00:00:00 2001 From: Christopher Harrison Date: Tue, 30 Jun 2026 12:38:50 -0700 Subject: [PATCH] docs: add GitHub Copilot App harness and restructure harnesses Add a new GitHub Copilot App learning path (9 lessons, Ex 0-8) that mirrors the Copilot CLI flow while introducing app-specific features: sessions from issues, Plan/Autopilot modes, Playwright MCP manual testing, the agent skill for running tests, Agent Merge, and canvases. Restructure all harnesses to use per-harness prerequisites (each opens with its own 0-prerequisites lesson) and rename CLI/VS Code lessons so numbering matches the new flow. Replace the shared prereqs page with a redirect, refresh shared partials and landing pages, and align the Playwright MCP exercise across paths. Update authoring docs, skills, and instruction files to match, and prune unused images. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/copilot-instructions.md | 13 +- .github/instructions/astro.instructions.md | 2 +- .github/instructions/markdown.instructions.md | 4 +- .github/skills/build-and-verify-docs/SKILL.md | 2 +- .../skills/validate-site-playwright/SKILL.md | 4 +- AUTHORING.md | 20 +- README.md | 6 +- docs/README.md | 1 + docs/astro.config.mjs | 42 +++-- docs/package-lock.json | 9 +- docs/package.json | 2 +- .../docs/_images/app-0-create-repository.png | Bin 0 -> 302207 bytes .../docs/_images/app-0-use-template.png | Bin 0 -> 48811 bytes .../docs/_images/app-2-review-panel.png | Bin 0 -> 45105 bytes .../docs/_images/app-2-start-session.png | Bin 0 -> 89917 bytes .../content/docs/_images/app-4-plan-mode.png | Bin 0 -> 51483 bytes .../docs/_images/app-agent-merge-merge.png | Bin 0 -> 100512 bytes .../docs/_images/app-automation-dialog.png | Bin 0 -> 32695 bytes .../docs/_images/app-enable-agent-merge.png | Bin 0 -> 96309 bytes .../_images/app-new-session-from-issue.png | Bin 0 -> 19456 bytes .../docs/_images/app-open-terminal.png | Bin 0 -> 32627 bytes .../docs/_images/app-select-changes.png | Bin 0 -> 39404 bytes .../docs/_images/cli-4-mcp-add-playwright.png | Bin 0 -> 34048 bytes .../docs/_images/ex1-create-issue-allow.png | Bin 51258 -> 0 bytes .../docs/_images/ex1-create-issue-dialog.png | Bin 113896 -> 0 bytes .../docs/_images/ex1-create-issue-review.png | Bin 320429 -> 0 bytes .../docs/_images/ex1-extensions-updates.png | Bin 108740 -> 0 bytes .../_images/ex1-github-issues-created.png | Bin 150699 -> 0 bytes .../docs/_images/ex1-mcp-auth-popup.png | Bin 48796 -> 0 bytes .../docs/_images/ex1-mcp-authorize-vscode.png | Bin 280966 -> 0 bytes .../docs/_images/ex1-mcp-select-account.png | Bin 91099 -> 0 bytes .../content/docs/_images/ex1-select-model.png | Bin 174249 -> 0 bytes .../docs/_images/ex1-start-mcp-server.png | Bin 48365 -> 0 bytes .../_images/ex2-add-instructions-file.png | Bin 108454 -> 0 bytes .../ex2-copilot-instructions-references.png | Bin 68561 -> 0 bytes .../_images/ex2-generate-instructions.png | Bin 116151 -> 0 bytes .../docs/_images/ex2-select-chat-mode.png | Bin 51334 -> 0 bytes .../docs/_images/ex2-select-edit-mode.png | Bin 51464 -> 0 bytes .../_images/ex2-source-control-changes.png | Bin 118532 -> 0 bytes .../_images/ex3-mcp-playwright-config.png | Bin 0 -> 37052 bytes .../_images/ex6-steer-coding-agent-task.png | Bin 184871 -> 0 bytes .../_images/shared-add-instructions-file.png | Bin 76312 -> 0 bytes .../callout-start-copilot-cli-allow-all.mdx | 2 +- .../docs/_shared/callout-student-plan.mdx | 9 + .../callout-template-seeds-backlog.mdx | 9 + .../_shared/exercise-create-codespace.mdx | 29 +++ .../_shared/exercise-create-template-repo.mdx | 15 ++ .../exercise-explore-instructions-files.mdx | 12 +- .../exercise-instructions-add-docstring.mdx | 10 +- .../_shared/section-agent-skills-overview.mdx | 6 +- .../_shared/section-instructions-overview.mdx | 8 +- .../_shared/section-iterating-recap-cloud.mdx | 6 +- .../section-iterating-recap-vscode.mdx | 2 +- .../_shared/section-playwright-mcp-test.mdx | 30 +++ .../_shared/section-tech-debt-scenarios.mdx | 6 +- docs/src/content/docs/app/0-prerequisites.mdx | 82 ++++++++ .../docs/app/1-install-copilot-app.mdx | 97 ++++++++++ .../content/docs/app/2-add-star-rating.mdx | 131 +++++++++++++ .../docs/app/3-custom-instructions.mdx | 156 +++++++++++++++ .../content/docs/app/4-build-filtering.mdx | 177 ++++++++++++++++++ .../src/content/docs/app/5-mcp-playwright.mdx | 83 ++++++++ docs/src/content/docs/app/6-agent-merge.mdx | 64 +++++++ docs/src/content/docs/app/7-canvases.mdx | 124 ++++++++++++ docs/src/content/docs/app/8-review.mdx | 83 ++++++++ docs/src/content/docs/app/index.mdx | 54 ++++++ docs/src/content/docs/cli/0-prerequisites.mdx | 42 +++++ .../docs/cli/1-install-copilot-cli.mdx | 6 +- ...ructions.mdx => 2-custom-instructions.mdx} | 69 ++++--- docs/src/content/docs/cli/2-mcp.mdx | 102 ---------- ...erating-code.mdx => 3-generating-code.mdx} | 18 +- docs/src/content/docs/cli/4-mcp.mdx | 117 ++++++++++++ docs/src/content/docs/cli/5-agent-skills.mdx | 6 +- .../src/content/docs/cli/7-slash-commands.mdx | 10 +- docs/src/content/docs/cli/8-review.mdx | 2 +- docs/src/content/docs/cli/index.mdx | 27 +-- .../content/docs/cloud/0-prerequisites.mdx | 39 ++++ .../docs/cloud/1-custom-instructions.mdx | 10 +- docs/src/content/docs/cloud/2-cloud-agent.mdx | 56 +++--- docs/src/content/docs/cloud/5-iterating.mdx | 36 ++-- docs/src/content/docs/cloud/index.mdx | 19 +- docs/src/content/docs/index.mdx | 82 ++------ docs/src/content/docs/prereqs.mdx | 96 ---------- .../content/docs/vscode/0-prerequisites.mdx | 63 +++++++ ...ructions.mdx => 1-custom-instructions.mdx} | 79 ++++---- docs/src/content/docs/vscode/1-mcp.mdx | 175 ----------------- .../{3-agent-mode.mdx => 2-agent-mode.mdx} | 72 +++---- docs/src/content/docs/vscode/3-mcp.mdx | 146 +++++++++++++++ .../content/docs/vscode/4-custom-agents.mdx | 6 +- .../content/docs/vscode/5-managing-agents.mdx | 2 +- docs/src/content/docs/vscode/6-iterating.mdx | 16 +- docs/src/content/docs/vscode/index.mdx | 28 +-- docs/src/pages/shared/0-prereqs.astro | 30 +++ .../_shared/callout-student-plan.mdx.d.ts | 9 + .../callout-template-seeds-backlog.mdx.d.ts | 9 + .../exercise-create-codespace.mdx.d.ts | 8 + .../exercise-create-template-repo.mdx.d.ts | 8 + ...ercise-instructions-add-docstring.mdx.d.ts | 4 +- .../section-iterating-recap-cloud.mdx.d.ts | 3 +- .../section-playwright-mcp-test.mdx.d.ts | 8 + .../section-tech-debt-scenarios.mdx.d.ts | 2 +- 100 files changed, 1951 insertions(+), 754 deletions(-) create mode 100644 docs/src/content/docs/_images/app-0-create-repository.png create mode 100644 docs/src/content/docs/_images/app-0-use-template.png create mode 100644 docs/src/content/docs/_images/app-2-review-panel.png create mode 100644 docs/src/content/docs/_images/app-2-start-session.png create mode 100644 docs/src/content/docs/_images/app-4-plan-mode.png create mode 100644 docs/src/content/docs/_images/app-agent-merge-merge.png create mode 100644 docs/src/content/docs/_images/app-automation-dialog.png create mode 100644 docs/src/content/docs/_images/app-enable-agent-merge.png create mode 100644 docs/src/content/docs/_images/app-new-session-from-issue.png create mode 100644 docs/src/content/docs/_images/app-open-terminal.png create mode 100644 docs/src/content/docs/_images/app-select-changes.png create mode 100644 docs/src/content/docs/_images/cli-4-mcp-add-playwright.png delete mode 100644 docs/src/content/docs/_images/ex1-create-issue-allow.png delete mode 100644 docs/src/content/docs/_images/ex1-create-issue-dialog.png delete mode 100644 docs/src/content/docs/_images/ex1-create-issue-review.png delete mode 100644 docs/src/content/docs/_images/ex1-extensions-updates.png delete mode 100644 docs/src/content/docs/_images/ex1-github-issues-created.png delete mode 100644 docs/src/content/docs/_images/ex1-mcp-auth-popup.png delete mode 100644 docs/src/content/docs/_images/ex1-mcp-authorize-vscode.png delete mode 100644 docs/src/content/docs/_images/ex1-mcp-select-account.png delete mode 100644 docs/src/content/docs/_images/ex1-select-model.png delete mode 100644 docs/src/content/docs/_images/ex1-start-mcp-server.png delete mode 100644 docs/src/content/docs/_images/ex2-add-instructions-file.png delete mode 100644 docs/src/content/docs/_images/ex2-copilot-instructions-references.png delete mode 100644 docs/src/content/docs/_images/ex2-generate-instructions.png delete mode 100644 docs/src/content/docs/_images/ex2-select-chat-mode.png delete mode 100644 docs/src/content/docs/_images/ex2-select-edit-mode.png delete mode 100644 docs/src/content/docs/_images/ex2-source-control-changes.png create mode 100644 docs/src/content/docs/_images/ex3-mcp-playwright-config.png delete mode 100644 docs/src/content/docs/_images/ex6-steer-coding-agent-task.png delete mode 100644 docs/src/content/docs/_images/shared-add-instructions-file.png create mode 100644 docs/src/content/docs/_shared/callout-student-plan.mdx create mode 100644 docs/src/content/docs/_shared/callout-template-seeds-backlog.mdx create mode 100644 docs/src/content/docs/_shared/exercise-create-codespace.mdx create mode 100644 docs/src/content/docs/_shared/exercise-create-template-repo.mdx create mode 100644 docs/src/content/docs/_shared/section-playwright-mcp-test.mdx create mode 100644 docs/src/content/docs/app/0-prerequisites.mdx create mode 100644 docs/src/content/docs/app/1-install-copilot-app.mdx create mode 100644 docs/src/content/docs/app/2-add-star-rating.mdx create mode 100644 docs/src/content/docs/app/3-custom-instructions.mdx create mode 100644 docs/src/content/docs/app/4-build-filtering.mdx create mode 100644 docs/src/content/docs/app/5-mcp-playwright.mdx create mode 100644 docs/src/content/docs/app/6-agent-merge.mdx create mode 100644 docs/src/content/docs/app/7-canvases.mdx create mode 100644 docs/src/content/docs/app/8-review.mdx create mode 100644 docs/src/content/docs/app/index.mdx create mode 100644 docs/src/content/docs/cli/0-prerequisites.mdx rename docs/src/content/docs/cli/{3-custom-instructions.mdx => 2-custom-instructions.mdx} (64%) delete mode 100644 docs/src/content/docs/cli/2-mcp.mdx rename docs/src/content/docs/cli/{4-generating-code.mdx => 3-generating-code.mdx} (78%) create mode 100644 docs/src/content/docs/cli/4-mcp.mdx create mode 100644 docs/src/content/docs/cloud/0-prerequisites.mdx delete mode 100644 docs/src/content/docs/prereqs.mdx create mode 100644 docs/src/content/docs/vscode/0-prerequisites.mdx rename docs/src/content/docs/vscode/{2-custom-instructions.mdx => 1-custom-instructions.mdx} (65%) delete mode 100644 docs/src/content/docs/vscode/1-mcp.mdx rename docs/src/content/docs/vscode/{3-agent-mode.mdx => 2-agent-mode.mdx} (72%) create mode 100644 docs/src/content/docs/vscode/3-mcp.mdx create mode 100644 docs/src/pages/shared/0-prereqs.astro create mode 100644 docs/src/types/_shared/callout-student-plan.mdx.d.ts create mode 100644 docs/src/types/_shared/callout-template-seeds-backlog.mdx.d.ts create mode 100644 docs/src/types/_shared/exercise-create-codespace.mdx.d.ts create mode 100644 docs/src/types/_shared/exercise-create-template-repo.mdx.d.ts create mode 100644 docs/src/types/_shared/section-playwright-mcp-test.mdx.d.ts diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 6967f376..dfef81ed 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -2,18 +2,17 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an Astro + Starlight site at . The demo application learners build during the workshop lives in a separate repository: . -**This is a content-only repo.** Do not add Python, Flask, Svelte, Tailwind, or other application code here. Application changes belong in `tailspin-toys`. +**This is a content-only repo.** Do not add the demo app's application code (Astro SSR endpoints, the Drizzle data layer, UI components, Tailwind styles, or tests) here. Application changes belong in `tailspin-toys`. ## Repository structure - `docs/` — Astro + Starlight site that publishes the workshop to GitHub Pages. - `src/content/docs/` — **Source MDX for all lessons. Edit here.** - `index.mdx` — Workshop landing page. - - `prereqs.mdx` — Shared setup lesson (Exercise 0). - - `cli/`, `vscode/`, `cloud/` — Per-path lessons (Copilot CLI / VS Code / Cloud agent). + - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each harness opens with its own `0-prerequisites.mdx` setup lesson; the CLI and VS Code harnesses set up a codespace, while the app and cloud harnesses cover the setup their flow needs (for the app, installing Node.js locally and creating the project from the template). - `_shared/` — Reusable MDX fragments imported via the `@shared/*` alias (see partials conventions below). Underscore-prefixed dirs are excluded from routing. - `_images/` — Screenshots and diagrams. - - `astro.config.mjs` — Site config including the manually maintained sidebar and a redirect from the legacy `/shared/0-prereqs/` URL to `/prereqs/`. + - `astro.config.mjs` — Site config including the manually maintained sidebar. The legacy `/shared/0-prereqs/` → home (`/`) redirect is a full-HTML redirect page at `src/pages/shared/0-prereqs.astro` (not an `astro.config.mjs` `redirects` entry, which would emit a stub with no `` element that Pagefind can't index). Prerequisites are now per-harness (`//0-prerequisites/`), so the old shared-prereqs URL forwards to the home page. - `scripts/` — Author tooling for the partials system (`lint_partials.py`, `sync_partial_metadata.py`, `_partials_lib.py`). - `AUTHORING.md` — Author entry point (recipes for adding lessons, partials, images). - `CONTRIBUTING.md` — Short pointer to AUTHORING.md + PR/CI rules. @@ -48,7 +47,7 @@ Don't extract a partial unless it's used in 2+ places (or the same place across ### Reusing a lesson across paths -When the same prose applies to multiple paths (CLI, VS Code, cloud), pull the body into a `section-…` partial under `_shared/` and `import` it from each per-path lesson. The host page owns frontmatter, H2s, and prev/next nav; the partial owns the reusable prose. +When the same prose applies to multiple harnesses (CLI, VS Code, cloud), pull the body into a `section-…` partial under `_shared/` and `import` it from each per-harness lesson. The host page owns frontmatter, H2s, and prev/next nav; the partial owns the reusable prose. ### Linking @@ -76,7 +75,7 @@ Before opening or updating a PR, also make the **PR-time consistency pass** docu ## Things NOT to do here -- Don't add Python, Flask, SQLAlchemy, Svelte, Astro components, Tailwind classes, or any other application code. That belongs in `github-samples/tailspin-toys`. -- Don't author against `client/` or `server/` paths — they were removed when the app was extracted. +- Don't add the demo app's application code — Astro SSR endpoints, the Drizzle data layer, `.astro` UI components, Tailwind classes, or Vitest/Playwright tests. That belongs in `github-samples/tailspin-toys`. +- Don't author against application source paths — the demo app is a single Astro project that lives in `tailspin-toys`, not here. - Don't generate summary markdown files at the end of a task. - Don't add `mkdocs.yml` or other parallel docs tooling — Astro + Starlight is the site. diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md index 5f57c60f..bedd1025 100644 --- a/.github/instructions/astro.instructions.md +++ b/.github/instructions/astro.instructions.md @@ -16,7 +16,7 @@ applyTo: 'docs/**/*.{astro,mjs,ts,js}' ## Don't add app-style components -This is a docs wrapper. Don't add interactive Svelte islands, Tailwind utility-class styling layers, custom routing, or other application-style code. Anything beyond Starlight defaults should be justified. +This is a docs wrapper. Don't add interactive framework islands (Svelte, React, etc.), Tailwind utility-class styling layers, custom routing, or other application-style code. Anything beyond Starlight defaults should be justified. ## Building and verifying diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md index 515bff82..f5193b60 100644 --- a/.github/instructions/markdown.instructions.md +++ b/.github/instructions/markdown.instructions.md @@ -149,11 +149,11 @@ Use Markdown image syntax with paths relative to the MDX file: ![Alt text describing the image](../_images/some-screenshot.png) ``` -For an image referenced from a `_shared/` partial, use the same `../_images/...` relative path — `_shared/` sits one level under `docs/src/content/docs/`, just like `cli/`, `vscode/`, and `cloud/`, so the path resolves identically for the partial and its consumer pages. +For an image referenced from a `_shared/` partial, use the same `../_images/...` relative path — `_shared/` sits one level under `docs/src/content/docs/`, just like `cli/`, `vscode/`, `cloud/`, and `app/`, so the path resolves identically for the partial and its consumer pages. ### Path conventions -- Per-path lessons: `cli/`, `vscode/`, `cloud/`. Files numbered by lesson order: `1-installing.mdx`, `2-custom-instructions.mdx`, etc. +- Per-path lessons: `cli/`, `vscode/`, `cloud/`, `app/`. Files numbered by lesson order: `1-installing.mdx`, `2-custom-instructions.mdx`, etc. - Shared content: reusable fragments live in `_shared/` (e.g. `section-mcp-overview.mdx`) and are imported into lesson pages via the `@shared/` alias. They are body-only partials inlined at build time, not standalone routed pages — see [`partials.instructions.md`](./partials.instructions.md). ### Cross-repo links diff --git a/.github/skills/build-and-verify-docs/SKILL.md b/.github/skills/build-and-verify-docs/SKILL.md index 707db55a..1da8fe7f 100644 --- a/.github/skills/build-and-verify-docs/SKILL.md +++ b/.github/skills/build-and-verify-docs/SKILL.md @@ -45,7 +45,7 @@ cd docs && rm -rf dist && npm run build ### 2. Page-count invariant -The built page count should equal the number of routable `.mdx` files — everything under `docs/src/content/docs/` **except** `_shared/` — plus the one legacy redirect (`/shared/0-prereqs/`). You never hard-code the number; you confirm the relationship: +The built page count should equal the number of routable `.mdx` files — everything under `docs/src/content/docs/` **except** `_shared/` — plus the one legacy redirect (`/shared/0-prereqs/`, authored as a full-HTML redirect page at `docs/src/pages/shared/0-prereqs.astro`). You never hard-code the number; you confirm the relationship: ```bash # routable .mdx (expected pages, minus the redirect) diff --git a/.github/skills/validate-site-playwright/SKILL.md b/.github/skills/validate-site-playwright/SKILL.md index e04c3be2..b901add7 100644 --- a/.github/skills/validate-site-playwright/SKILL.md +++ b/.github/skills/validate-site-playwright/SKILL.md @@ -39,7 +39,7 @@ Don't hard-code URLs. The built `dist/` is the source of truth for what routes e find docs/dist -name index.html | grep -v 404 | sed 's#docs/dist#/agents-in-sdlc#; s#/index.html#/#' ``` -Validate a **representative sample** that covers every layout and path: the landing page (`/agents-in-sdlc/`), `prereqs/`, and at least one lesson from each of `cli/`, `vscode/`, and `cloud/`. For a release pass or a change that touches shared layout/components, validate **all** routes. +Validate a **representative sample** that covers every layout and harness: the landing page (`/agents-in-sdlc/`), a per-harness prerequisites page (e.g. `cli/0-prerequisites/`), and at least one lesson from each of `cli/`, `vscode/`, `cloud/`, and `app/`. For a release pass or a change that touches shared layout/components, validate **all** routes. ## 3. Validate each route @@ -49,7 +49,7 @@ For each chosen route, use the Playwright MCP tools: 2. **Confirm it rendered** — `browser_snapshot` and check the page has its heading/title and real content (not an error page or raw, unrendered MDX). 3. **Check the console** — `browser_console_messages` with `level: "error"`. There should be **zero** errors. Hydration warnings and 404s for assets surface here. - *Known benign exception:* the legacy redirect route `/agents-in-sdlc/shared/0-prereqs/` is a bare meta-refresh stub (it immediately forwards to `/prereqs/`) and declares no favicon, so the browser auto-requests `/favicon.ico` and logs a single `404 (Not Found)`. That one favicon 404 **on the redirect stub only** is expected. Validate that route by confirming it lands on `/prereqs/`, not by console cleanliness. A favicon 404 on any *real* page is a genuine finding (real pages link `favicon.svg`). + *Known benign exception:* the legacy redirect route `/agents-in-sdlc/shared/0-prereqs/` is a minimal full-HTML redirect page (it immediately forwards to the home page `/agents-in-sdlc/` via a meta refresh) and declares no favicon, so the browser auto-requests `/favicon.ico` and logs a single `404 (Not Found)`. That one favicon 404 **on the redirect page only** is expected. Validate that route by confirming it lands on the home page, not by console cleanliness. A favicon 404 on any *real* page is a genuine finding (real pages link `favicon.svg`). 4. **Find broken images** — `browser_evaluate` with an async function that **force-loads lazy images first**, then flags only the ones that truly fail. Starlight/Astro mark below-the-fold images `loading="lazy"`, so a naive `naturalWidth === 0` check reports false positives for images that simply haven't scrolled into view yet: ```js diff --git a/AUTHORING.md b/AUTHORING.md index 1a0a65ae..3774be30 100644 --- a/AUTHORING.md +++ b/AUTHORING.md @@ -13,10 +13,10 @@ agents-in-sdlc/ ├── docs/ │ └── src/content/docs/ ← MDX source. EDIT HERE. │ ├── index.mdx ← Workshop landing page -│ ├── prereqs.mdx ← Shared setup (Exercise 0) -│ ├── cli/ ← Copilot CLI lessons -│ ├── vscode/ ← VS Code lessons -│ ├── cloud/ ← Cloud agent lessons +│ ├── cli/ ← Copilot CLI lessons (0-prerequisites.mdx + numbered exercises) +│ ├── vscode/ ← VS Code lessons (0-prerequisites.mdx + numbered exercises) +│ ├── cloud/ ← Cloud agent lessons (0-prerequisites.mdx + numbered exercises) +│ ├── app/ ← GitHub Copilot app lessons (setup folded into Exercise 1) │ ├── _shared/ ← Reusable MDX fragments (callout-/section-/exercise-) │ └── _images/ ← Screenshots and diagrams └── .github/ @@ -29,7 +29,7 @@ agents-in-sdlc/ ### Add a new lesson -1. **Pick a path and number.** Lessons live under `docs/src/content/docs/{cli,vscode,cloud}/N-name.mdx`. `N` is the next available integer in that path; the number drives the URL slug (`/cli/4-generating-code/`). +1. **Pick a path and number.** Lessons live under `docs/src/content/docs/{cli,vscode,app,cloud}/N-name.mdx`. `N` is the next available integer in that path; the number drives the URL slug (`/cli/3-generating-code/`). 2. **Create the file** with frontmatter: ```mdx --- @@ -44,8 +44,8 @@ agents-in-sdlc/ 3. **Write the body.** Use Markdown plus optional MDX `