docs: rework workshop flow and refresh authoring tooling

.github/copilot-instructions.md

@@ -12,7 +12,7 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an A
     - `prereqs.mdx` — Shared setup lesson (Exercise 0).
     - `cli/`, `vscode/`, `cloud/` — Per-path lessons (Copilot CLI / VS Code / Cloud agent).
     - `_shared/` — Reusable MDX fragments imported via the `@shared/*` alias (see partials conventions below). Underscore-prefixed dirs are excluded from routing.
-    - `images/` — Screenshots and diagrams.
+    - `_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/`.
 - `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).
@@ -21,7 +21,7 @@ This repo hosts the **workshop content** for *Agents in SDLC*, published as an A
   - `copilot-instructions.md` — This file.
   - `instructions/` — Scoped instruction files (`applyTo` frontmatter targets specific file globs).
   - `agents/` — Custom agents available to Copilot.
-  - `skills/` — Skills available to Copilot.
+  - `skills/` — Skills available to Copilot (see [`skills/README.md`](skills/README.md) for the index of what each one does).
   - `workflows/pages.yml` — Builds and deploys the site.
 
 ## Authoring conventions
@@ -60,41 +60,11 @@ When the same prose applies to multiple paths (CLI, VS Code, cloud), pull the bo
 
 When a partial drops into the middle of an ordered list, the list resumes numbering automatically as long as the partial's items use plain Markdown numerals starting at `1.`. See `exercise-instructions-add-docstring.mdx` for the working pattern.
 
-## Verification before commit
+## Building, previewing, and verifying
 
-Run all of these. Don't commit if any fails.
+The tooling for building, previewing, and verifying the site — dev server, clean build, the page-count invariant, the lychee link check, and the local partial guardrails — lives in the [`build-and-verify-docs`](skills/build-and-verify-docs/SKILL.md) skill. Run that verification sequence before every commit, and don't commit if any step fails.
 
-**Build:**
-
-```bash
-cd docs && rm -rf dist && npm run build
-```
-
-**Link check (offline; catches broken cross-page links):**
-
-```bash
-mkdir -p /tmp/lychee-root && ln -sfn $PWD/docs/dist /tmp/lychee-root/agents-in-sdlc \
-  && lychee --offline --no-progress --root-dir /tmp/lychee-root 'docs/dist/**/*.html'
-```
-
-**Partial lint + sync:**
-
-```bash
-python scripts/lint_partials.py
-python scripts/sync_partial_metadata.py --check
-```
-
-Lychee runs offline and won't catch broken external GitHub URLs. When changing absolute `https://github.com/...` links, click through manually.
-
-## Local development
-
-From repo root:
-
-```bash
-cd docs && npm install && npm run dev
-```
-
-That's it — content lives inside `docs/src/content/docs/` so packages resolve natively. No symlinks required.
+Before opening or updating a PR, also make the **PR-time consistency pass** documented in that skill — a structural-drift sweep (renamed paths, stale skill/instruction references, CI claims, repository-structure trees) that the build and link check can't catch.
 
 ## Commit hygiene
 

.github/instructions/astro.instructions.md

@@ -18,12 +18,6 @@ applyTo: 'docs/**/*.{astro,mjs,ts,js}'
 
 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.
 
-## When changing site config
+## Building and verifying
 
-After modifying `astro.config.mjs` or anything in `docs/src/`:
-
-```bash
-cd docs && rm -rf dist && npm run build
-```
-
-Verify the page count is still **29** unless you intentionally added or removed lessons. A build that produces a different count without an MDX change is a sign of a routing or content-collection misconfiguration — most likely partials being routed as pages (check the loader's exclude pattern).
+After changing `astro.config.mjs` or anything under `docs/src/`, build and verify the site with the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill. Its page-count invariant is the tripwire for the "partials are never routed as pages" rule above: if the build emits more pages than `(routable .mdx files + 1 legacy redirect)`, a `_shared/` partial is leaking into routing — check the underscore-directory exclude in `src/content.config.ts`.

.github/instructions/instructions.instructions.md

@@ -0,0 +1,88 @@
+---
+description: 'How to write and maintain instruction files (`.github/instructions/*.instructions.md`) for this workshop content repo'
+applyTo: '**/*.instructions.md'
+---
+
+# Authoring instruction files
+
+Guidance for creating and maintaining the scoped instruction files that steer Copilot in this repo. This is a **content-only** Astro + Starlight workshop repo, so instruction files govern *Markdown/MDX authoring conventions* — never application code (that lives in `github-samples/tailspin-toys`).
+
+This file covers what is specific to instruction files. For mechanical Markdown formatting (no hard-wrapping, admonition syntax, headings, link style), instruction files also follow [`markdown.instructions.md`](./markdown.instructions.md) — don't restate those rules here.
+
+## Where instruction files live
+
+- Location: `.github/instructions/`.
+- Naming: lowercase with hyphens, ending `.instructions.md` (e.g. `markdown-accessibility.instructions.md`).
+- One concern per file. The existing set: `markdown` (formatting), `markdown-accessibility` (a11y), `partials` (the `_shared/` system), `astro` (the `docs/` site wrapper). Add a new file only for a genuinely new concern; otherwise extend an existing one.
+
+## Required frontmatter
+
+Every instruction file opens with YAML frontmatter:
+
+```yaml
+---
+description: 'One sentence stating the purpose and scope'
+applyTo: '**/*.{md,mdx}'
+---
+```
+
+- **description** — single-quoted, one sentence. This is how an author (and Copilot) tells files apart, so make it specific.
+- **applyTo** — glob(s) selecting the files the instructions bind to. Patterns used in this repo:
+  - `'**/*.{md,mdx}'` — all Markdown and MDX (formatting, accessibility).
+  - `'docs/src/content/docs/_shared/**'` — partials only.
+  - `'docs/**/*.{astro,mjs,ts,js}'` — the site wrapper.
+  - `'**/*.instructions.md'` — this meta-guide.
+
+## Structure
+
+- Start with a single `#` H1 title, then `##` sections. (Instruction files are repository docs, so — unlike lesson MDX — they *do* carry a body H1.)
+- Keep sections short and scannable. Lead with the rule; follow with a tight example only when it removes ambiguity.
+- If two files would cover the same ground, pick one home and have the other point to it. Duplicated guidance drifts.
+
+## Instruction altitude (the Goldilocks zone)
+
+Aim for the smallest rule set that fully defines the outcome. Add a rule after a real failure, not for a hypothetical one. Prefer a high-signal example over an exhaustive decision table.
+
+| Altitude | Failure mode | Result |
+| --- | --- | --- |
+| Over-specified | Brittle if-this-then-that prose | Breaks on any case you didn't list |
+| Under-specified | Assumes shared context | Generic, off-convention output |
+| Right altitude | Heuristics + one example | Stable, generalizes to new content |
+
+## Writing style
+
+- Imperative mood: "Use", "Define", "Avoid" — not "you should" / "it might be good to".
+- Be specific and actionable. Replace vague advice with a concrete instruction plus, where helpful, a `Good`/`Avoid` pair.
+- Use backticks for filenames, paths, and literal syntax; bold for UI labels (per `markdown.instructions.md`).
+
+## Examples
+
+Show the convention, not just describe it. Label the contrast.
+
+**Good** — names the component and shows the call:
+
+```mdx
+Use Starlight's `<Aside>` for callouts in lesson body content:
+
+<Aside type="tip">Run the dev server before editing.</Aside>
+```
+
+**Avoid** — abstract, unactionable:
+
+```markdown
+Callouts should be done properly using the right component.
+```
+
+## Patterns to avoid
+
+- **Hypothetical-rule inflation** — don't encode rules for failures that haven't happened.
+- **Restating other files** — defer mechanical formatting to `markdown.instructions.md`, the partials system to `partials.instructions.md`, and the build/verify process to the [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) skill.
+- **Documenting tooling here** — instruction files describe *what content should look like*; *how to build/verify/preview* belongs in the skill.
+- **Ambiguous terms** — "should", "might", "possibly" leave the outcome undefined.
+- **Copy-paste from upstream docs** — distill and contextualize for this repo instead.
+
+## Maintenance
+
+- When a convention, path, or file is renamed, update the instruction files that mention it (the PR-time consistency pass in [`build-and-verify-docs`](../skills/build-and-verify-docs/SKILL.md) catches this).
+- Keep `applyTo` globs accurate as the project structure evolves.
+- Remove rules that no longer reflect how the repo works rather than letting them accumulate.

.github/instructions/markdown-accessibility.instructions.md

@@ -0,0 +1,99 @@
+---
+description: 'Markdown and MDX accessibility guidelines based on GitHub''s 5 best practices for inclusive documentation'
+applyTo: '**/*.{md,mdx}'
+---
+
+# Markdown Accessibility Review Guidelines
+
+This file is the single home for **accessibility** conventions in this repo. Mechanical Markdown/MDX formatting lives in [`markdown.instructions.md`](./markdown.instructions.md); the accessibility rationale for those conventions lives here.
+
+When writing or reviewing Markdown and MDX files, check for the following accessibility issues based on GitHub's [5 tips for making your GitHub profile page accessible](https://github.blog/developer-skills/github/5-tips-for-making-your-github-profile-page-accessible/) and the Smashing Magazine article [Improving The Accessibility Of Your Markdown](https://www.smashingmagazine.com/2021/09/improving-accessibility-of-markdown/). Flag violations and suggest fixes with clear explanations of the accessibility impact.
+
+## 1. Descriptive Links
+
+- Flag generic link text such as "click here," "here," "this," "read more," "learn more," or "link."
+- Link text must make sense when read out of context, because assistive technology can present links as an isolated list.
+- Weave the link into the prose with descriptive text; never add a sentence whose only job is to point at a link.
+- Flag multiple links on the same page that share identical text but point to different destinations.
+- Bare URLs in prose should be converted to descriptive links.
+
+Bad: `Read my blog post [here](https://example.com)`
+Good: `Read my blog post "[Crafting an accessible resume](https://example.com)"`
+
+## 2. Image Alternative (alt) Text
+
+- Flag images with empty alt text (e.g., `![](path/to/image.png)`) unless they are explicitly decorative. In this repo, Starlight treats alt text as required.
+- Flag alt text that is a filename (e.g., `img_1234.jpg`) or generic placeholder (e.g., `screenshot`, `image`).
+- Alt text should be succinct and descriptive. Include any text visible in the image.
+- Use "screenshot of" where relevant, but do not prefix with "image of" since screen readers announce that automatically.
+- For complex images (charts, infographics), suggest summarizing the data in alt text and providing longer descriptions via `<details>` tags or linked content.
+- When suggesting alt text improvements, present them as recommendations for the author to review. Alt text requires understanding of visual content and context that only the author can properly assess.
+
+## 3. Heading Hierarchy
+
+- Headings must follow a logical hierarchy and never skip levels (e.g., `##` followed by `####` is a violation).
+- Flag bold text (`**text**`) used as a visual substitute for a proper heading.
+- Proper heading structure allows assistive technology users to navigate by section and helps sighted users scan content.
+
+This repo has two repo-specific rules that override the generic "one H1 per document" guidance:
+
+- **Lesson pages have no H1 in the body.** The title comes from MDX frontmatter and Starlight renders it as the H1. Body headings start at `##`.
+- **Partials start at `###`.** A partial under `_shared/` must not contain `##` — the host page owns every H2 (see [`partials.instructions.md`](./partials.instructions.md)). Within a partial, treat `###` as the top level and never skip down from there.
+
+## 4. Plain Language
+
+- Flag unnecessarily complex or jargon-heavy language that could be simplified.
+- Favor short sentences, common words, and active voice.
+- Flag long, dense paragraphs that could be broken into smaller sections or lists.
+- When describing UI navigation, write actions as sequential steps in plain language first (e.g., "open Settings, then select Preferences"). Use generic, stable labels rather than icon names or visual descriptions.
+- A parenthetical visual reference may follow as supplemental context (e.g., "(gear icon > Preferences)"), but never use visual breadcrumb notation or icon names as the sole way to describe a navigation path.
+- When suggesting plain language improvements, present them as recommendations for the author to review. Language decisions require understanding of audience, context, and tone.
+
+### Input-agnostic action verbs
+
+- Use input-agnostic verbs so instructions work for keyboard, screen reader, touch, and mouse users. Prefer **select** over "click", "press", or "tap" when referring to UI elements (buttons, tabs, menu items, links).
+- Reserve "press" for physical keyboard shortcuts (e.g., "press <kbd>Enter</kbd>").
+
+## 5. Lists and Emoji Usage
+
+### Lists
+
+- Flag emoji or special characters used as bullet points instead of proper markdown list syntax (`-`, `*`, `+`, or `1.`).
+- Flag sequential items in plain text that should be structured as a proper list.
+- Proper list markup allows screen readers to announce list context (e.g., "item 1 of 3").
+
+### Emoji
+
+- Flag multiple consecutive emoji, which are disruptive to screen reader users since each emoji name is read aloud in full (e.g., "rocket" "sparkles" "fire").
+- Flag emoji used to convey meaning that is not also communicated in text.
+- Emoji should be used sparingly and thoughtfully.
+
+## 6. Multimedia
+
+- Provide captions for videos and transcripts for recorded audio.
+- Do not auto-play audio and video.
+- It's recommended that animated images and other animations are paused on page load.
+
+## 7. Other
+
+- Links: Avoid opening links in a new tab or window.
+- Bold and Italics: Screen readers often don't announce bold or italic emphasis, so critical information should not rely on this styling alone.
+- Tables: Use tables for data only. Do not use tables for page layout. Avoid nested tables. Avoid complex tables as they are difficult to represent in an accessible format in standard Markdown.
+
+## Review Priority
+
+When multiple issues exist, prioritize in this order:
+
+1. Missing or empty alt text on images
+2. Skipped heading levels or heading hierarchy issues
+3. Non-descriptive link text
+4. Emoji used as bullet points or list markers
+5. Plain language improvements
+6. Multimedia
+7. Other
+
+## Review Tone
+
+- Explain the accessibility impact of each issue, specifying which users are affected (e.g., screen reader users, people with cognitive disabilities, non-native speakers).
+- Do not remove personality or voice from the writing. Accessibility and engaging content are not mutually exclusive.
+- Keep suggestions actionable and specific.

.github/instructions/markdown.instructions.md

@@ -70,9 +70,9 @@ Follow the [GitHub Docs style guide][github-style]. In short:
 
 Rule of thumb: if the reader is going to select it, it's bold; if they're going to type it, read it in the filesystem, or see it in code, it's backticks.
 
-## Accessibility: action verbs
+## Accessibility
 
-Use input-agnostic verbs so instructions work for keyboard, screen reader, touch, and mouse users. Prefer **select** over "click", "press", or "tap" when referring to UI elements (buttons, tabs, menu items, links). Reserve "press" for physical keyboard shortcuts (e.g., "press <kbd>Enter</kbd>").
+Accessibility conventions — descriptive link text, alt text, heading hierarchy, plain language, input-agnostic action verbs (**select** not "click") — live in [`markdown-accessibility.instructions.md`](./markdown-accessibility.instructions.md).
 
 ## Keyboard shortcuts
 
@@ -88,8 +88,7 @@ Mac modifiers: spell out **Command**, **Option**, **Control** — don't use ⌘,
 
 - Use reference-style links. Define refs at the bottom of the file (or the bottom of the partial that owns them).
 - Strip locale codes (`/en/`, `/en-us/`, etc.) from URLs so readers land in their own locale.
-- Never use "click here", "here", "learn more", "read more", or "this link" as link text. Weave the link into the prose with descriptive text.
-- Never add a sentence whose only job is to point at a link.
+- For descriptive link text (no "click here"; no link-only sentences), see [`markdown-accessibility.instructions.md`](./markdown-accessibility.instructions.md).
 
 ## MDX-only conventions
 
@@ -126,10 +125,10 @@ When the same callout repeats across lessons, extract it to a `callout-*.mdx` pa
 Use the `@shared/` alias (not relative paths):
 
 ```mdx
-import CalloutStartCopilotCli from '@shared/callout-start-copilot-cli.mdx';
+import CalloutStartCopilotCliAllowAll from '@shared/callout-start-copilot-cli-allow-all.mdx';
 import ExerciseAddDocstring from '@shared/exercise-instructions-add-docstring.mdx';
 
-<CalloutStartCopilotCli />
+<CalloutStartCopilotCliAllowAll />
 
 <ExerciseAddDocstring />
 ```
@@ -147,15 +146,15 @@ When dropping an exercise partial into a numbered list, write the partial's item
 Use Markdown image syntax with paths relative to the MDX file:
 
 ```mdx
-![Alt text describing the image](../images/some-screenshot.png)
+![Alt text describing the image](../_images/some-screenshot.png)
 ```
 
-For shared lesson pages under `shared/<topic>/`, image paths are typically `../../images/...`.
+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.
 
 ### Path conventions
 
 - Per-path lessons: `cli/`, `vscode/`, `cloud/`. Files numbered by lesson order: `1-installing.mdx`, `2-custom-instructions.mdx`, etc.
-- Shared content: `shared/<topic>/<lesson>.mdx`. Per-path stubs redirect to the shared page and include a "Return to your path" footer.
+- 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