githubnext · pelikhan · Jul 19, 2026 · Jul 19, 2026
diff --git a/.github/workflows/guidelines.md b/.github/workflows/guidelines.md
@@ -224,3 +224,78 @@ TOC generation rules (script-friendly):
    - Side quest: `NN-SQMM`
 
 This keeps IDs lexically sortable, preserves the choose-your-adventure branch model, and cleanly groups optional side quests under their parent step.
+
+## Workshop page frontmatter schema
+
+Every Markdown file in `workshop/` (except `README.md`) carries a YAML frontmatter block that describes the user journey and adventure category of the page. Tools and tables of contents use these fields to filter pages by learner profile.
+
+### Frontmatter format
+
+```yaml
+---
+journey: <value>
+adventure: <value>
+---
+```
+
+Place this block as the **very first content** in the file, before the `#` heading.
+
+### `journey` — learner path
+
+Describes which learner profile the page targets.
+
+| Value | Meaning |
+|-------|---------|
+| `all` | Applicable to every learner regardless of environment |
+| `ui` | GitHub web UI path only (no terminal required) |
+| `terminal` | Any terminal user — Codespace or local |
+| `codespace` | Codespace-specific instructions (subset of `terminal`) |
+| `local` | Local terminal-specific instructions (subset of `terminal`) |
+| `copilot` | GitHub Copilot app or Agents tab users |
+
+Rules for assigning `journey`:
+
+- Use `all` for shared hub pages and conceptual introductions that every learner reads.
+- Use `terminal` for pages where the primary instructions require a shell (Codespace or local). Use `codespace` or `local` only when the content is specific to one of those environments and would not apply to the other.
+- Use `ui` for pages written exclusively for learners who stay in the GitHub browser UI.
+- Use `copilot` for pages that target the Copilot desktop app or the browser-based Agents tab (Adventure D).
+
+### `adventure` — content category
+
+Describes the role the page plays in the overall workshop structure.
+
+| Value | Meaning |
+|-------|---------|
+| `core` | Required shared path — every learner follows these pages |
+| `setup` | Environment or tool setup steps (Codespace, local, gh-aw install) |
+| `scenario-a` | Adventure A — Daily Repo Status Report |
+| `scenario-b` | Adventure B — Daily Documentation Updater |
+| `scenario-c` | Adventure C — PR Code Reviewer |
+| `scenario-d` | Adventure D — Build with GitHub Copilot (Agents tab / CCA) |
+| `advanced` | Optional post-core topics (steps 14 and above) |
+| `side-quest` | Optional deep-dive supplementary content branching off a main step |
+
+### Assignment rules by file pattern
+
+| Filename pattern | Typical `journey` | Typical `adventure` |
+|-----------------|-------------------|---------------------|
+| `NN-<slug>.md` (core/shared) | `all` | `core` or `advanced` |
+| `NNa-<slug>-terminal.md` | `terminal` | matches parent step |
+| `NNb-<slug>-ui.md` | `ui` | matches parent step |
+| `NNc-<slug>-copilot.md` | `copilot` | matches parent step |
+| `10a-*`, `11a-*`, `11a2-*` | `all` or split by sub-path | `scenario-a` |
+| `10b-*`, `11b-*` | `all` or split by sub-path | `scenario-b` |
+| `10c-*`, `11c-*` | `all` or split by sub-path | `scenario-c` |
+| `11d-*` | `copilot` | `scenario-d` |
+| `02a-*`, `06a-*` | `codespace` | `setup` |
+| `02b-*`, `06b-*` | `local` | `setup` |
+| `06c-*` | `ui` | `setup` |
+| `side-quest-NN-MM-<slug>.md` | varies (see below) | `side-quest` |
+
+Side quest `journey` assignment:
+
+- `terminal` — content is exclusively about terminal commands or `gh aw compile` (e.g., `side-quest-07-01-compile-workflow.md`).
+- `codespace` — content addresses a Codespaces-specific error or configuration (e.g., `side-quest-08-01-codespaces-actions-write.md`).
+- `ui` — content is only applicable to GitHub UI path learners (e.g., `side-quest-06-03c-copilot-github-token-ui-only.md`).
+- `copilot` — content is specific to the Copilot CCA or Agents tab environment (e.g., `side-quest-06-02-cca-codespace.md`).
+- `all` — conceptual, reference, or debugging content relevant regardless of environment (the majority of side quests).
diff --git a/workshop/00-welcome.md b/workshop/00-welcome.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 0: Welcome — What We'll Build
 
 By the end of this workshop, a real AI agent will post a comment on one of your GitHub issues — automatically, every day, without you writing shell-script workflow code.

diff --git a/workshop/01-prerequisites.md b/workshop/01-prerequisites.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 1: What You Need Before We Start
 
 _Starting with the right setup saves you from frustrating detours later._

diff --git a/workshop/02a-setup-codespace.md b/workshop/02a-setup-codespace.md
@@ -1,3 +1,7 @@
+---
+journey: codespace
+adventure: setup
+---
 # Adventure A: Set Up a Codespace _(recommended for new users)_
 > [!IMPORTANT]
 > On mobile, in the Copilot app, or using Copilot Cloud Agent (CCA)? Stop here: [Step 3b →](03b-create-your-repo-ui.md).

diff --git a/workshop/02b-setup-local.md b/workshop/02b-setup-local.md
@@ -1,3 +1,7 @@
+---
+journey: local
+adventure: setup
+---
 # Adventure B: Set Up Your Local Terminal
 
 > [!TIP]

diff --git a/workshop/03-create-your-repo.md b/workshop/03-create-your-repo.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 3: Create and Verify Your Practice Repository
 
 _Now that setup is complete, create the repository where you'll build and test your workflows._

diff --git a/workshop/03a-create-your-repo-terminal.md b/workshop/03a-create-your-repo-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: core
+---
 # Step 3a: Create Your Practice Repository — Terminal Path
 
 > _When you're done with this step, you'll have a public `my-agentic-workflows` repository cloned locally or in your Codespace, with GitHub Actions enabled and ready for the rest of the workshop._

diff --git a/workshop/03b-create-your-repo-ui.md b/workshop/03b-create-your-repo-ui.md
@@ -1,3 +1,7 @@
+---
+journey: ui
+adventure: core
+---
 # Step 3b: Create Your Practice Repository — GitHub UI Path
 
 > _When you're done with this step, you'll have a public `my-agentic-workflows` repository open in your browser, with GitHub Actions enabled and ready for the rest of the workshop — no terminal required._

diff --git a/workshop/04-github-actions-intro.md b/workshop/04-github-actions-intro.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 4: GitHub Actions in 5 Minutes
 
 > [!TIP]

diff --git a/workshop/05-agentic-workflows-intro.md b/workshop/05-agentic-workflows-intro.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 5: What Are Agentic Workflows?
 
 **Already familiar with both GitHub Actions and AI agent execution environments?**

diff --git a/workshop/06-install-gh-aw.md b/workshop/06-install-gh-aw.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 6: Install the gh-aw CLI Extension
 
 `gh-aw` is the CLI extension that compiles your agentic workflow Markdown files and triggers runs from your terminal. If you're on the GitHub UI path, no local installation is needed: an agent compiles the workflow, and GitHub Actions executes the committed lock file.

diff --git a/workshop/06a-install-terminal.md b/workshop/06a-install-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: codespace
+adventure: setup
+---
 # Step 6a: Install gh-aw — Codespace Terminal
 
 > [!NOTE]

diff --git a/workshop/06b-install-local.md b/workshop/06b-install-local.md
@@ -1,3 +1,7 @@
+---
+journey: local
+adventure: setup
+---
 # Step 6b: Install gh-aw — Local Terminal
 
 > [!NOTE]

diff --git a/workshop/06c-install-ui.md b/workshop/06c-install-ui.md
@@ -1,3 +1,7 @@
+---
+journey: ui
+adventure: setup
+---
 # Step 6c: GitHub UI Path — No Installation Needed
 
 > [!NOTE]

diff --git a/workshop/07-your-first-workflow.md b/workshop/07-your-first-workflow.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 7: Write Your First Agentic Workflow
 
 _Writing your first workflow is the moment theory becomes practice — let's make something real._

diff --git a/workshop/07a-part2-your-first-workflow-instructions.md b/workshop/07a-part2-your-first-workflow-instructions.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: core
+---
 # Step 7a (Part 2): Add Instructions and Finish the Workflow — Terminal Path
 
 _You now have a valid starter file. In this part, you complete it and push it._

diff --git a/workshop/07a-your-first-workflow-terminal.md b/workshop/07a-your-first-workflow-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: core
+---
 # Step 7a: Write Your First Agentic Workflow — Terminal Path
 
 _Writing your first workflow is the moment theory becomes practice — let's make something real._

diff --git a/workshop/07b-your-first-workflow-ui.md b/workshop/07b-your-first-workflow-ui.md
@@ -1,3 +1,7 @@
+---
+journey: ui
+adventure: core
+---
 # Step 7b: Write Your First Agentic Workflow — GitHub UI Path
 
 > [!NOTE]

diff --git a/workshop/07c-your-first-workflow-copilot.md b/workshop/07c-your-first-workflow-copilot.md
@@ -1,3 +1,7 @@
+---
+journey: copilot
+adventure: core
+---
 # Step 7c: Write Your First Agentic Workflow — GitHub Copilot Path
 
 ## 🎯 What You'll Do

diff --git a/workshop/07d-confirm-model-access.md b/workshop/07d-confirm-model-access.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 7d: Confirm Model Access
 
 ## 📋 Before You Start

diff --git a/workshop/08-run-your-workflow.md b/workshop/08-run-your-workflow.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 8: Run and Watch Your Workflow
 
 _Watching an agent work in real time makes the workflow feel concrete._

diff --git a/workshop/08b-interpret-your-run.md b/workshop/08b-interpret-your-run.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 8b: Interpret Your First Run
 
 _Your first run is more useful when you can explain what the agent did and why._

diff --git a/workshop/09-understand-output.md b/workshop/09-understand-output.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 9: Reading Workflow Output
 
 > _An agentic workflow is only as useful as what you can learn from its output — knowing how to read the results is the skill that lets you improve fast._

diff --git a/workshop/10-choose-your-scenario.md b/workshop/10-choose-your-scenario.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Step 10: Choose Your Scenario
 
 > _The best way to learn agentic workflows is to build one you'd actually use. Pick the scenario that matches what you want to automate._

diff --git a/workshop/10a-design-daily-status.md b/workshop/10a-design-daily-status.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-a
+---
 # Step 10a: Design — Daily Repo Status Report
 
 > _Great agentic workflows start with a clear brief — writing down what you want before you code anything saves hours of debugging later._

diff --git a/workshop/10b-design-daily-docs.md b/workshop/10b-design-daily-docs.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-b
+---
 # Step 10b: Design — Daily Documentation Updater
 
 > _Great [agentic workflows](https://github.github.com/gh-aw/introduction/overview/) start with a clear brief — writing down what you want before you code anything saves hours of debugging later._

diff --git a/workshop/10c-design-pr-reviewer.md b/workshop/10c-design-pr-reviewer.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-c
+---
 # Step 10c: Design — PR Code Reviewer
 
 > _Great [agentic workflows](https://github.github.com/gh-aw/introduction/overview/) start with a clear brief — writing down what you want before you code anything saves hours of debugging later._

diff --git a/workshop/11a-build-daily-status-terminal.md b/workshop/11a-build-daily-status-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: scenario-a
+---
 # Step 11a: Build the Daily Repo Status Workflow — Terminal Path
 
 _You've designed the workflow on paper — now let's turn it into real, running YAML._

diff --git a/workshop/11a-build-daily-status-ui.md b/workshop/11a-build-daily-status-ui.md
@@ -1,3 +1,7 @@
+---
+journey: ui
+adventure: scenario-a
+---
 # Step 11a: Build the Daily Repo Status Workflow — GitHub UI Path
 
 > [!NOTE]

diff --git a/workshop/11a-build-daily-status-wizard.md b/workshop/11a-build-daily-status-wizard.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-a
+---
 # Adventure A: Build Daily Status with the Add Wizard
 
 > _The add wizard is the fastest way to get a curated workflow running — it handles engine selection, secrets, and the pull request for you._

diff --git a/workshop/11a-build-daily-status.md b/workshop/11a-build-daily-status.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-a
+---
 # Step 11a: Build — Daily Repo Status Workflow
 
 _You've designed the workflow on paper — now choose how you want to create it._

diff --git a/workshop/11a2-run-daily-status-terminal.md b/workshop/11a2-run-daily-status-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: scenario-a
+---
 # Step 11a2: Compile and Run the Daily Status Workflow — Terminal Path
 
 > _The workflow file is written — now let's validate it and see it run._

diff --git a/workshop/11b-build-daily-docs-terminal.md b/workshop/11b-build-daily-docs-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: scenario-b
+---
 # Step 11b: Build the Daily Documentation Updater — Terminal Path
 
 > _You've designed the workflow on paper — now let's turn it into real, running YAML._

diff --git a/workshop/11b-build-daily-docs-ui.md b/workshop/11b-build-daily-docs-ui.md
@@ -1,3 +1,7 @@
+---
+journey: ui
+adventure: scenario-b
+---
 # Step 11b: Build the Daily Documentation Updater — GitHub UI Path
 
 > [!NOTE]

diff --git a/workshop/11b-build-daily-docs.md b/workshop/11b-build-daily-docs.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-b
+---
 # Step 11b: Build — Daily Documentation Updater
 
 _You've designed the workflow on paper — now choose how you want to create it._

diff --git a/workshop/11c-build-pr-reviewer-terminal.md b/workshop/11c-build-pr-reviewer-terminal.md
@@ -1,3 +1,7 @@
+---
+journey: terminal
+adventure: scenario-c
+---
 # Step 11c: Build the PR Code Reviewer — Terminal Path
 
 > _You've designed the workflow on paper — now let's turn it into real, running YAML._

diff --git a/workshop/11c-build-pr-reviewer-ui.md b/workshop/11c-build-pr-reviewer-ui.md
@@ -1,3 +1,7 @@
+---
+journey: ui
+adventure: scenario-c
+---
 # Step 11c: Build the PR Code Reviewer — GitHub UI Path
 
 > [!NOTE]

diff --git a/workshop/11c-build-pr-reviewer.md b/workshop/11c-build-pr-reviewer.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: scenario-c
+---
 # Step 11c: Build — PR Code Reviewer
 
 _You've designed the workflow on paper — now choose how you want to create it._

diff --git a/workshop/11d-build-copilot-agents.md b/workshop/11d-build-copilot-agents.md
@@ -1,3 +1,7 @@
+---
+journey: copilot
+adventure: scenario-d
+---
 # Adventure D: Build Any Workflow with GitHub Copilot
 
 > _You can use the [GitHub Copilot app](side-quest-01-02-environment-reference.md#github-copilot-app) or the browser-based Agents tab to start an agent session, steer the work, review the changes, and land an agentic workflow._

diff --git a/workshop/11d2-review-and-merge.md b/workshop/11d2-review-and-merge.md
@@ -1,3 +1,7 @@
+---
+journey: copilot
+adventure: scenario-d
+---
 # Adventure D (Part 2): Monitor, Review, and Merge
 
 > _Once the agent session ends, you'll review its pull request, ask for any revisions, and merge your workflow._

diff --git a/workshop/12-test-and-iterate.md b/workshop/12-test-and-iterate.md
@@ -1,3 +1,7 @@
+---
+journey: all
+adventure: core
+---
 # Test and Improve Your Workflow
 
 > _Running a workflow once is good; understanding why it did what it did — and making it better — is where the real learning happens._