github-samples · GeekTrainer · Sep 16, 2026 · Sep 17, 2026 · Sep 18, 2026 · Sep 18, 2026
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -8,11 +8,12 @@ This repo hosts the **workshop content** for **Copilot Workshops**, published as
 
 - `docs/` — **Source Markdown for all lessons. Edit here.** Browsable directly on github.com; no build required.
   - `README.md` — Workshop landing page (also the site home via `slug: index` frontmatter).
-  - `cli/`, `vscode/`, `cloud/`, `app/` — Per-harness lessons (Copilot CLI / VS Code / Cloud agent / GitHub Copilot app). Each folder's landing page is a `README.md` (routed via a `slug:` matching the folder path). Each harness opens with its own `0-prerequisites.md` 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).
+  - `first-steps/` — Guided introductory workshops. Each workshop has its own folder and `README.md` landing page.
+  - `real-world-development/` — Scenario-based workshops organized by environment (`cli/`, `vscode/`, `cloud/`, and `app/`). Each environment's landing page is a `README.md` routed via a slug matching the full category path. Each workshop opens with its own `0-prerequisites.md` setup lesson.
   - `es-es/`, `ja-jp/`, `ko-kr/`, `pt-br/`, `zh-cn/` — Localized content at the locale-root paths required by Starlight. Translated pages mirror the English path beneath each locale directory; untranslated pages use Starlight's English fallback.
   - `_images/` — Screenshots and diagrams (shared across all locales).
 - `website/` — Optional Astro + Starlight site that publishes `docs/` to GitHub Pages (loader `base: '../docs'`). Only needed to self-host or preview the rendered site.
-  - `astro.config.mjs` — Site config including the manually maintained sidebar and the `locales` block. 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.
+  - `astro.config.mjs` — Site config including the manually maintained sidebar and the `locales` block. 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 workshop (`/<category>/<workshop>/0-prerequisites/`), so the old shared-prereqs URL forwards to the home page.
   - `src/content.config.ts` — Custom content loader (`base: '../docs'`) that excludes underscore-prefixed support directories so `_images/` is not routed as content.
 - `AUTHORING.md` — Author entry point (recipes for adding lessons and images).
 - `CONTRIBUTING.md` — Short pointer to AUTHORING.md + PR/CI rules.
@@ -28,7 +29,7 @@ This repo hosts the **workshop content** for **Copilot Workshops**, published as
 
 ### Reusing prose across paths
 
-When the same prose applies to multiple harnesses (CLI, VS Code, cloud), copy it inline into each per-harness `.md` lesson. There is no import-based shared content system; the host page owns frontmatter, headings, navigation, and body prose.
+When the same prose applies to multiple workshops (CLI, VS Code, cloud), copy it inline into each workshop's `.md` lesson. There is no import-based shared content system; the host page owns frontmatter, headings, navigation, and body prose.
 
 Because inline copies can drift, run the `check-content-alignment` skill after editing duplicated sections. The `.github/workflows/content-alignment.md` agentic workflow performs the same analysis on PRs as a safety net, but do not rely on it as a substitute for updating all affected lessons.
 

diff --git a/.github/instructions/astro.instructions.md b/.github/instructions/astro.instructions.md
@@ -12,7 +12,7 @@ applyTo: 'website/**/*.{astro,mjs,ts,js}'
 - Base path: `/copilot-workshops` (the repo's GitHub Pages slug).
 - Site URL: `https://github-samples.github.io/copilot-workshops/`.
 - **Sidebar: manually maintained** in `astro.config.mjs`. The `sidebar` array drives both the order learners see and which pages appear in navigation. New lessons must be added explicitly.
-- **Content collection** is sourced from the repo-root `docs/` directory via the custom `glob()` loader in `src/content.config.ts` (`base: '../docs'`). That loader excludes underscore-prefixed files and directories so support assets such as `_images/` don't get routed as pages. Folder landing pages are `README.md` files (so they render on github.com) rather than Starlight's default `index.md`; each carries a `slug:` in its frontmatter to reproduce the route it would otherwise get from an index file — `docs/README.md` → `slug: index` (site home `/`), `docs/<harness>/README.md` → `slug: <harness>`, and localized landings use the locale-prefixed slug (`docs/<locale>/README.md` → `slug: <locale>`, `docs/<locale>/<harness>/README.md` → `slug: <locale>/<harness>`).
+- **Content collection** is sourced from the repo-root `docs/` directory via the custom `glob()` loader in `src/content.config.ts` (`base: '../docs'`). That loader excludes underscore-prefixed files and directories so support assets such as `_images/` don't get routed as pages. Folder landing pages are `README.md` files (so they render on github.com) rather than Starlight's default `index.md`; each carries a `slug:` in its frontmatter to reproduce the route it would otherwise get from an index file — `docs/README.md` → `slug: index` (site home `/`), `docs/<category>/README.md` → `slug: <category>`, `docs/<category>/<workshop>/README.md` → `slug: <category>/<workshop>`, and localized landings use the locale-prefixed full path.
 
 ## Don't add app-style components
 

diff --git a/.github/instructions/markdown.instructions.md b/.github/instructions/markdown.instructions.md
@@ -142,7 +142,7 @@ Use Markdown image syntax with paths relative to the Markdown file:
 
 ## Path conventions
 
-- Per-path lessons: `cli/`, `vscode/`, `cloud/`, `app/`. Files are numbered by lesson order: `1-installing.md`, `2-custom-instructions.md`, etc.
+- Workshop lessons live under category and workshop folders, such as `first-steps/copilot-app/` and `real-world-development/cli/`. Files are numbered by lesson order: `1-installing.md`, `2-custom-instructions.md`, etc.
 - Support images live in `_images/` directories and are excluded from routing by `website/src/content.config.ts`.
 
 ## Cross-repo links

diff --git a/.github/skills/localizations/SKILL.md b/.github/skills/localizations/SKILL.md
@@ -17,22 +17,26 @@ The skill takes input content and a list of target locales. It then translates t
 .
 └── docs/                         ← workshop content (source + locale outputs)
     ├── README.md                 ← landing page (source; slug: index)
-    ├── <harness>/                ← English lessons (source)
-    │   ├── README.md             ← harness landing (source; slug: <harness>)
-    │   └── *.md
-    ├── _images/                  ← shared assets (not localized)
-    └── <locale>/                 ← localized output, direct child of docs/
-        ├── README.md             ← locale landing (slug: <locale>)
-        └── <harness>/
-            ├── README.md         ← localized harness landing (slug: <locale>/<harness>)
-            └── *.md
+    ├── <category>/               ← English workshop category
+    │   ├── README.md             ← category landing (source; slug: <category>)
+    │   └── <workshop>/
+    │       ├── README.md         ← workshop landing (source; slug: <category>/<workshop>)
+    │       └── *.md
+    ├── _images/              ← shared assets (not localized)
+    └── <locale>/             ← localized output, direct child of docs/
+        ├── README.md         ← locale landing (slug: <locale>)
+        └── <category>/
+            ├── README.md         ← localized category landing (slug: <locale>/<category>)
+            └── <workshop>/
+                ├── README.md     ← localized workshop landing (slug: <locale>/<category>/<workshop>)
+                └── *.md
 ```
 
 ### Input contents
 
 Here are the contents in scope for localization:
 
-- All English Markdown files under `docs/` **and its subdirectories** — the workshop landing (`docs/README.md`) and the per-harness lessons (`docs/<harness>/**/*.md`).
+- All English Markdown files under `docs/` **and its subdirectories** — the site landing (`docs/README.md`), category landings, and workshop lessons (`docs/<category>/<workshop>/**/*.md`).
 
 Do **not** treat `_images/` (shared assets) or any configured locale-root directory as source input.
 
@@ -66,7 +70,7 @@ The process runs in two passes. First, the content is analyzed to identify key p
 
 Regardless of locale, the following must be preserved exactly and **not** translated:
 
-- YAML frontmatter **keys** (translate values only where appropriate, e.g. a `title`). **Exception — the `slug` key on landing pages (`README.md`):** the site routes each folder landing via its `slug`, so a localized landing must carry a **locale-prefixed** slug rather than the English one. Rewrite it: a locale root (`docs/<locale>/README.md`) uses `slug: <locale>`, and a localized harness landing (`docs/<locale>/<harness>/README.md`) uses `slug: <locale>/<harness>`. Never copy the English `slug: index` / `slug: <harness>` verbatim into a localized file — that would collide with the English route.
+- YAML frontmatter **keys** (translate values only where appropriate, e.g. a `title`). **Exception — the `slug` key on landing pages (`README.md`):** the site routes each folder landing via its `slug`, so a localized landing must carry a **locale-prefixed** slug rather than the English one. Rewrite it: a locale root (`docs/<locale>/README.md`) uses `slug: <locale>`, a localized category landing uses `slug: <locale>/<category>`, and a localized workshop landing uses `slug: <locale>/<category>/<workshop>`. Never copy an English landing slug verbatim into a localized file because it would collide with the English route.
 - Fenced and inline code, including variable, function, and command names.
 - URLs and external link targets.
 - HTML tags, Markdown structure, tables, and admonition markers.
@@ -75,7 +79,7 @@ Translate human-language prose, including comments inside code blocks where they
 
 **Heading anchors follow the localized text.** When a heading is translated, its auto-generated anchor/slug changes with it—this is expected. The requirement is that **same-document anchor links keep resolving**: whenever you translate a heading, update every in-page link that targets it (`](#...)`) to the localized heading's new slug. Do not leave a link pointing at the original English slug once the heading is translated, and do not preserve an English anchor that no longer matches its heading. Anchors that point into **non-localized** files (or external URLs) keep their original target.
 
-**Image and asset paths point to the original assets unless a localized asset exists.** Because localized files live under `docs/<locale>/`, rewrite source-relative paths as needed so they still resolve to the shared asset (for example, an app lesson at `docs/<locale>/app/2-foo.md` uses `../../_images/x.png` to reach `docs/_images/`). Only point at a localized asset when a corresponding translated image actually exists under the locale tree. Either way, the link must resolve to a real file.
+**Image and asset paths point to the original assets unless a localized asset exists.** Because localized files live under `docs/<locale>/`, rewrite source-relative paths as needed so they still resolve to the shared asset (for example, a lesson at `docs/<locale>/real-world-development/app/2-foo.md` uses `../../../_images/x.png` to reach `docs/_images/`). Only point at a localized asset when a corresponding translated image actually exists under the locale tree. Either way, the link must resolve to a real file.
 
 ### Translator agent
 
@@ -97,4 +101,3 @@ The evaluator scores the localized document against the locale's **Evaluator Sco
 - **Don't** treat configured locale-root directories as source input.
 - **Don't** reorder or restructure content; keep headings and their order stable.
 - **Don't** translate code, commands, or identifiers; translate explanatory prose and code comments only.
-
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 website/dist -name index.html | grep -v 404 | sed 's#website/dist#/copilot-workshops#; s#/index.html#/#'
 ```
 
-Validate a **representative sample** that covers every layout and harness: the landing page (`/copilot-workshops/`), 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.
+Validate a **representative sample** that covers every category and workshop: the landing page (`/copilot-workshops/`), a first-steps lesson, and at least one real-world development 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
 

diff --git a/.github/workflows/content-alignment.md b/.github/workflows/content-alignment.md
@@ -50,8 +50,8 @@ Inspect the pull request diff, restricted to `docs/**`. For each changed lesson,
 
 Search the rest of `docs/**` for passages that should stay in sync with each change. Focus on three drift categories:
 
-1. **Formerly-shared copies.** Short callouts and steps that used to be shared partials are now copied verbatim into multiple lessons (for example, the Copilot CLI "Allow all" approval callout, and the "Approve and run workflows" step in `cloud/5-iterating.md` and `vscode/6-iterating.md`). Quote a distinctive phrase from the change and grep for it across all lessons.
-2. **Parallel concepts across harnesses.** The same idea is taught once per harness in `cli/`, `vscode/`, `app/`, and `cloud/`. A conceptual change usually needs the same correction in the sibling lessons of the other harnesses.
+1. **Formerly-shared copies.** Short callouts and steps that used to be shared partials are now copied verbatim into multiple lessons (for example, the Copilot CLI "Allow all" approval callout, and the "Approve and run workflows" step in `real-world-development/cloud/5-iterating.md` and `real-world-development/vscode/6-iterating.md`). Quote a distinctive phrase from the change and grep for it across all lessons.
+2. **Parallel concepts across workshops.** The same idea may be taught in the `cli/`, `vscode/`, `app/`, and `cloud/` workshops under `real-world-development/`. A conceptual change usually needs the same correction in sibling lessons.
 3. **Cross-references and shared facts.** Reference-style links to a renamed/retitled lesson, lesson numbers in prose, the published URL shape, the `github.com/github-samples/tailspin-toys/...` demo-app URL, tool/library names, and shared screenshots.
 
 Exclude the files already changed in this PR from your candidate list.