feat(docs): publish workshop site + dedup + content partials

Builds out the workshop-content/ directory as a publishable MkDocs site
and removes long-standing duplication across the three learning paths.

Site infrastructure (Phase A1)
  - mkdocs.yml at repo root with Material theme, dark/light toggle,
    nav tabs, search, code-copy, edit links, and PyMdown Snippets
    configured against partials/.
  - requirements-docs.txt pinning mkdocs-material, pymdown-extensions,
    and mkdocs-callouts (renders > [!NOTE]/[!IMPORTANT]/[!TIP] blocks
    as Material admonitions).
  - .github/workflows/pages.yml builds with mkdocs --strict on PRs
    (validation only) and on push to main (build + deploy via
    actions/deploy-pages). Explicit per-job permissions; pages
    concurrency group; pinned actions.
  - site/ and .venv-docs/ added to .gitignore.

Content partials (Phase A2 — Tier 1)
  Five reusable snippets at repo-root partials/, replacing verbatim
  duplicates across paths via --8<-- includes:
    - sections/coding-agent-intro.md     (vscode/4 + cloud/2)
    - sections/iterating-recap.md        (vscode/7 + cloud/5)
    - sections/security-coding-agent.md  (vscode/7 + cloud/5)
    - scenarios/tech-debt.md             (vscode/4 + cloud/2)
    - scenarios/accessibility.md         (cli/6 + shared/coding-agent/custom-agents)
  Partials follow inline-links-only / no-images / no-H1 rules
  documented in partials/README.md.

Path-publishing fixes
  - Converted 3 outbound links pointing to .github/instructions/*.md
    to absolute github.com URLs (would otherwise break --strict).
  - Escaped <branch-name> placeholders in iterating files so they
    render as code spans, not stray HTML tags.
  - Escaping shared/1 link refs to absolute URLs preserves both raw
    GitHub readability and Pages strict build.

Prior dedup + cleanup (also pending on this branch, included here)
  - shared/coding-agent/{custom-agents,managing-agents}.md as
    canonical bodies for the cross-path coding-agent flows.
  - Wrappers in vscode/{5,6} and cloud/{3,4} reduced to skeletons
    pointing to the shared module.
  - Multiple polish passes from earlier session work
    (cli warm-up, hands-on demos, /delegate optional section, etc.).

Local validation: mkdocs build --strict passes with zero errors;
all 5 partials resolve correctly in rendered output; GitHub alerts
render as Material admonitions.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: GeekTrainer

.github/workflows/pages.yml

@@ -0,0 +1,74 @@
+name: Build and deploy workshop site
+
+# Builds the MkDocs site. Deploys to GitHub Pages on pushes to main.
+# Pull requests run a build-only validation pass.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'workshop-content/**'
+      - 'partials/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '.github/workflows/pages.yml'
+  pull_request:
+    paths:
+      - 'workshop-content/**'
+      - 'partials/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+# Single in-flight deploy per branch; do not cancel an active deploy mid-flight.
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build site (mkdocs --strict)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+          cache: 'pip'
+          cache-dependency-path: requirements-docs.txt
+
+      - name: Install MkDocs and extensions
+        run: pip install -r requirements-docs.txt
+
+      - name: Build site (strict)
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -68,4 +68,9 @@ msbuild.err
 msbuild.wrn
 
 # SQLite
-*.db
+*.db
+# MkDocs build output
+site/
+
+# MkDocs docs venv (local docs builds)
+.venv-docs/

mkdocs.yml

@@ -0,0 +1,86 @@
+site_name: Agents in the SDLC Workshop
+site_description: A hands-on workshop exploring GitHub Copilot agents across VS Code, the Copilot CLI, and the Copilot coding agent.
+site_url: https://github-samples.github.io/agents-in-sdlc/
+repo_url: https://github.com/github-samples/agents-in-sdlc
+edit_uri: edit/main/workshop-content/
+docs_dir: workshop-content
+
+theme:
+  name: material
+  palette:
+    - scheme: default
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - scheme: slate
+      primary: indigo
+      accent: indigo
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.indexes
+    - navigation.top
+    - content.code.copy
+    - content.action.edit
+    - search.highlight
+    - search.suggest
+  icon:
+    repo: fontawesome/brands/github
+
+markdown_extensions:
+  - admonition
+  - attr_list
+  - md_in_html
+  - tables
+  - toc:
+      permalink: true
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.snippets:
+      base_path:
+        - partials
+      check_paths: true
+
+plugins:
+  - search
+  - callouts
+
+# Files inside docs_dir that should not be published as standalone pages.
+# (Currently empty; partials live OUTSIDE docs_dir at repo root /partials.)
+not_in_nav: |
+  /shared/coding-agent/*.md
+
+nav:
+  - Home: README.md
+  - Prerequisites: shared/0-prereqs.md
+  - Custom instructions: shared/1-custom-instructions.md
+  - VS Code path:
+      - Overview: vscode/README.md
+      - 2. MCP with VS Code: vscode/2-mcp.md
+      - 3. Agent mode: vscode/3-agent-mode.md
+      - 4. Coding agent: vscode/4-coding-agent.md
+      - 5. Custom agents: vscode/5-custom-agents.md
+      - 6. Managing agents: vscode/6-managing-agents.md
+      - 7. Iterating: vscode/7-iterating.md
+  - Copilot CLI path:
+      - Overview: cli/README.md
+      - 2. Install Copilot CLI: cli/2-install-copilot-cli.md
+      - 3. MCP with CLI: cli/3-mcp.md
+      - 4. Generating code: cli/4-generating-code.md
+      - 5. Agent skills: cli/5-agent-skills.md
+      - 6. Custom agents: cli/6-custom-agents.md
+      - 7. Slash commands: cli/7-slash-commands.md
+      - 8. Review: cli/8-review.md
+  - Cloud agent path:
+      - Overview: cloud/README.md
+      - 2. Coding agent: cloud/2-coding-agent.md
+      - 3. Custom agents: cloud/3-custom-agents.md
+      - 4. Managing agents: cloud/4-managing-agents.md
+      - 5. Iterating: cloud/5-iterating.md

partials/README.md

@@ -0,0 +1,30 @@
+# Reusable Markdown partials for the workshop site
+
+This directory holds reusable content fragments included into the published workshop site
+(`https://github-samples.github.io/agents-in-sdlc/`) via the
+[PyMdown Snippets](https://facelessuser.github.io/pymdown-extensions/extensions/snippets/) extension.
+
+Snippets are referenced from pages in `workshop-content/` using:
+
+```markdown
+--8<-- "sections/coding-agent-intro.md"
+```
+
+The `base_path` for snippet resolution is configured to this folder in `mkdocs.yml`.
+
+## Rules for partials
+
+- **Inline links only** — do NOT use reference-style links (`[text][ref]` plus `[ref]: url`). Reference
+  definitions become document-global once the snippet is included and can collide with the host page.
+- **No image references** — keep images in the consuming page outside the include. Snippets are
+  inserted before Markdown conversion and have no stable source path.
+- **No H1** — partials drop into the middle of a page; use H2 (`##`) at most.
+- **One concept per partial** — easier to reuse, easier to update.
+
+## Layout
+
+```
+partials/
+  scenarios/   # Repeatable scenario blocks (Tailspin-specific framing)
+  sections/    # Multi-paragraph sections that recur verbatim across paths
+```

partials/scenarios/.gitkeep

@@ -0,0 +1,5 @@
+## Scenario
+
+Tailspin Toys is committed to ensuring their crowdfunding platform is accessible to all users, regardless of their visual abilities or preferences. Recent user feedback has highlighted that some users find the current dark theme difficult to read due to insufficient contrast between text and background colors. To address this accessibility concern, the design team has requested the implementation of a high-contrast mode that users can toggle on and off.
+
+Because accessibility is critical, you want to ensure this is implemented as quickly as possible. You're going to utilize a custom agent to generate the functionality.

partials/scenarios/accessibility.md

@@ -0,0 +1,7 @@
+## Scenarios
+
+Tailspin Toys has some tech debt they'd like to address. The contractors initially hired to create the first version of the site left the documentation in an unideal state - and by that you'll notice it's completely lacking. As a first step, they'd like to see docstrings or the equivalent added to all functions in the application.
+
+Additionally, the design team is ready to get to work on building the UX for managing games. They don't need a full implementation yet, but they at least need some endpoints they can use for testing. Specifically, they need endpoints for the games API which will allow them to create, update and delete games. This is currently a blocker, but there are other issues which are of higher priority at the moment.
+
+These are both examples of tasks which can quickly find themselves deprioritized, and are great to assign to Copilot coding agent. Copilot coding agent can then work on them asynchronously, allowing the developer to focus on other tasks, then return to review Copilot's work and ensure everything is as expected.

partials/scenarios/tech-debt.md

@@ -0,0 +1,3 @@
+## Introducing GitHub Copilot coding agent
+
+[GitHub Copilot coding agent](https://docs.github.com/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot#overview-of-copilot-coding-agent) can perform tasks in the background, much in the same way a human developer would. And, just like with working with a human developer, this can be done in multiple ways, including [assigning a GitHub issue to Copilot](https://docs.github.com/copilot/using-github-copilot/coding-agent/using-copilot-to-work-on-an-issue). Once assigned, Copilot will create a draft pull request to track its progress, setup an environment, and begin working on the task. You can dig into Copilot's session while it's still in flight or after its completed. Once its ready for you to review the proposed solution, it'll tag you in the pull request!

partials/sections/.gitkeep

@@ -0,0 +1,5 @@
+Throughout this lab you've assigned several issues to GitHub Copilot coding agent. You asked it to add documentation to your code, generate endpoints for the design team to iterate on, and implement accessibility features including high-contrast and light mode toggles. Let's explore the code changes it suggested and, if necessary, provide feedback to Copilot to improve its work.
+
+## Scenario
+
+As has been highlighted numerous times, the fundamentals of software design and DevOps do not change with the addition of generative AI. We always want to review the code generated, and work through our normal DevOps process. With that in mind, let's review the suggestions from GitHub Copilot for creating the documentation, new endpoints, and accessibility features before we turn on review for the rest of our team.