github-samples · GeekTrainer · Jun 30, 2026
diff --git 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 <https://github-samples.github.io/agents-in-sdlc/>. The demo application learners build during the workshop lives in a separate repository: <https://github.com/github-samples/tailspin-toys>.
 
-**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 `<html>` element that Pagefind can't index). Prerequisites are now per-harness (`/<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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 `<Aside>` admonitions. See **Style essentials** below.
 4. **Add prev/next navigation.** Define `[previous-lesson]` and `[next-lesson]` reference links at the bottom of the page, pointing at the adjacent lessons in the same path:
    ```markdown
-   [previous-lesson]: ../3-custom-instructions/
-   [next-lesson]: ../5-agent-skills/
+   [previous-lesson]: ../2-custom-instructions/
+   [next-lesson]: ../4-mcp/
    ```
    Then surface them in the body using **the same style as the other lessons in your path** — don't mix styles within a path:
    - **Woven into prose** (common in the CLI path): end the lesson with a sentence like ``the next step is to [create the PR][next-lesson]``.
@@ -108,7 +108,7 @@ See [`.github/instructions/partials.instructions.md`](./.github/instructions/par
 
 ### Add an image
 
-1. **Drop the file** in `docs/src/content/docs/_images/` (or a path-scoped `cli/_images/` etc. when the image is path-specific). Use lowercase-with-hyphens filenames; prefix with `shared-` if the image is referenced from multiple paths.
+1. **Drop the file** in `docs/src/content/docs/_images/` (or a path-scoped `cli/_images/` etc. when the image is path-specific). Use lowercase-with-hyphens filenames; prefix with `shared-` if the image is referenced from multiple harnesses.
 2. **Reference it** with a relative path from the consuming MDX page:
    ```mdx
    ![Description of the screenshot](../_images/my-screenshot.png)
@@ -118,14 +118,14 @@ See [`.github/instructions/partials.instructions.md`](./.github/instructions/par
 
 ### Edit an existing lesson
 
-1. **Find the file** under `docs/src/content/docs/` (use the published URL as a hint — `/cli/4-generating-code/` lives at `cli/4-generating-code.mdx`).
+1. **Find the file** under `docs/src/content/docs/` (use the published URL as a hint — `/cli/3-generating-code/` lives at `cli/3-generating-code.mdx`).
 2. **Edit the MDX.** Same conventions apply — see **Style essentials** below.
 3. **Preview** with `npm run dev` in `docs/`.
 4. **Commit, PR, merge.**
 
 ### Reuse a lesson across paths
 
-When the same lesson 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 page. The host page owns the frontmatter, the H2s, and the prev/next nav; the partial owns the reusable prose.
+When the same lesson 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 page. The host page owns the frontmatter, the H2s, and the prev/next nav; the partial owns the reusable prose.
 
 ## Building and verifying
 

diff --git a/README.md b/README.md
@@ -5,7 +5,7 @@ Workshop content for **Agents in SDLC**, a guided exploration of GitHub Copilot'
 The published site lives at **<https://github-samples.github.io/agents-in-sdlc/>**.
 
 > [!NOTE]
-> The demo application learners build through during the workshop — Tailspin Toys, a Flask + Astro/Svelte crowdfunding site — lives in a separate repository: **<https://github.com/github-samples/tailspin-toys>**. This repo holds only the *content*: lesson MDX, partials, images, and the Astro + Starlight site that publishes them.
+> The demo application learners build through during the workshop — Tailspin Toys, a pure-Astro crowdfunding site (SSR, API endpoints, and a Drizzle data layer) — lives in a separate repository: **<https://github.com/github-samples/tailspin-toys>**. This repo holds only the *content*: lesson MDX, partials, images, and the Astro + Starlight site that publishes them.
 
 ## Start the workshop
 
@@ -22,10 +22,10 @@ For PR/CI rules, see **[CONTRIBUTING.md](./CONTRIBUTING.md)**.
 - **`docs/`** — Astro + Starlight site that publishes the workshop to GitHub Pages.
   - `src/content/docs/` — **Lesson source (MDX). 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 codespace-based harness opens with its own `0-prerequisites.mdx` setup lesson.
     - `_shared/` — Reusable MDX fragments (`callout-*`, `section-*`, `exercise-*` prefixes), imported via the `@shared/*` alias.
     - `_images/` — Screenshots and diagrams.
+  - `src/pages/shared/0-prereqs.astro` — Full-HTML redirect forwarding the legacy `/shared/0-prereqs/` URL to the home page.
 - **`AUTHORING.md`** — Author entry point (recipes for adding/editing content).
 - **`CONTRIBUTING.md`** — PR flow + CI requirements.
 - **`.github/`**

diff --git a/docs/README.md b/docs/README.md
@@ -20,6 +20,7 @@ npm run preview  # preview the production build
 - `astro.config.mjs` — Site URL, base path, sidebar (manually maintained).
 - `src/content.config.ts` — Content collection loader. Excludes `_shared/**` from routing so partials aren't published as pages.
 - `src/components/` — Site-shell components (`.astro`). Lesson content does **not** live here.
+- `src/pages/` — Standalone Astro routes outside the content collection. Currently just `shared/0-prereqs.astro`, the full-HTML redirect that forwards the legacy `/shared/0-prereqs/` URL to the home page (prerequisites are now per-harness at `/<harness>/0-prerequisites/`).
 
 ## Deployment