feat: add event provisioning examples and guidelines for workshop assets (#1624)

Author: mnkiefer

.github/workflows/guidelines.md

@@ -27,6 +27,13 @@ Use these rules across workshop authoring/editing workflows to keep the tutorial
 - Keep command-heavy content narrow, purposeful, and optional when possible.
 - When terminal use is unavoidable, point learners to Codespaces as a low-friction bridge.
 
+## Event provisioning surfaces
+
+- Some workshop content is intentionally reused in provisioned event environments such as an org profile README and a learner-repository Codespaces launcher.
+- The maintained example assets live in `workshop/examples/event-provisioning/` and represent downstream copies, not primary authored content.
+- When you change workshop onboarding language that should also appear in those provisioned surfaces, update the marked source blocks in `workshop/00-welcome.md` and keep the examples in sync.
+- For provisioned learner repositories, prefer a Codespaces launcher entry point that starts at Step 4 or Step 5 because org invite, repository creation, and Codespace creation are already complete.
+
 ## Positioning agentic workflows as an Actions-compatible superset
 
 - Present agentic workflows as a **smooth transition from classic GitHub Actions**, not a replacement that forces learners to start over.
@@ -197,7 +204,7 @@ This rule does not override clearly superior choices for all learners. It is a t
 
 ## Consistency check
 
-Before finalizing workshop edits, quickly confirm that early steps remain UI-first, do not require `gh` before it is truly needed, and do not reference Node.js as a prerequisite.
+Before finalizing workshop edits, quickly confirm that early steps remain UI-first, do not require `gh` before it is truly needed, do not reference Node.js as a prerequisite, and keep any event-provisioning examples synchronized with the marked workshop source content.
 
 ## Activity numbering for a sortable adventure graph
 

AGENTS.md

@@ -16,6 +16,7 @@ automated tooling (author review, student simulation, order checks) under `.gith
 README.md               # Workshop landing page (GitHub Skills style)
 AGENTS.md               # This file — tips for AI agents
 workshop/               # Step-by-step workshop content (00-welcome.md … 16-connect-data-source.md)
+  examples/event-provisioning/ # Example assets for provisioned org README and learner-repo Codespaces launchers
 .github/
   workflows/            # Agentic workflow definition files (*.md) and compiled lock files (*.lock.yml)
   skills/               # Copilot skill definitions for agentic-workflows and agentic-workflow-designer
@@ -66,13 +67,17 @@ The following rules are **disabled** in `.markdownlint-cli2.yaml` — do not add
 
 **Never configure Codespace badges or `devcontainer.json` to open from this (`gh-aw-workshop`) repository.** The workshop repository itself is not a suitable Codespace base — learners work in their own practice repositories, not a clone of this one. Any Codespace badge or devcontainer setup must point to the learner's own repository.
 
+The checked-in examples under `workshop/examples/event-provisioning/` are exceptions for template authoring only. They exist so event provisioning systems can copy a launcher into each learner's own repository; do not treat them as launchers for this repository itself.
+
 ## Working with workshop content
 
 - Workshop steps are numbered files in `workshop/` (e.g., `07-your-first-workflow.md`).
 - Images referenced in workshop steps live in `workshop/images/`.
 - Keep `workshop/README.md` in sync whenever you add or rename a step.
 - Run the markdown linter before committing any workshop step edits.
 - When adding a new step, follow the existing file naming pattern and update the curriculum table in both `workshop/README.md` and `workshop/00-welcome.md`.
+- When editing shared intro or onboarding copy that may be reused outside the workshop pages, preserve and update the HTML reuse markers in `workshop/00-welcome.md`.
+- Treat `workshop/examples/event-provisioning/` as maintained examples. Keep the org-profile README and devcontainer launcher aligned with the corresponding marked source content in `workshop/00-welcome.md`.
 
 ## Working with agentic workflow files
 

workshop/00-welcome.md

@@ -4,7 +4,9 @@
 
 # Welcome — What We'll Build
 
-By the end of this workshop, a real AI agent will create an issue with a summary of the activity in your repostiory over the latest 24h, every day, without you writing shell-script workflow code.
+<!-- reuse:event-org-readme-intro:start -->
+By the end of this workshop, a real AI agent will create an issue with a summary of the activity in your repository over the latest 24h, every day, without you writing shell-script workflow code.
+<!-- reuse:event-org-readme-intro:end -->
 
 ![Sample daily repository status report generated by the finished workflow](images/00-daily-repo-status-output.svg)
 

workshop/examples/event-provisioning/README.md

@@ -0,0 +1,16 @@
+# Event Provisioning Examples
+
+This folder contains example assets for workshop events that pre-provision a GitHub organization, learner repositories, and Codespaces.
+
+Use these files as source material for the provisioned environment:
+
+- [org-profile-README.md](org-profile-README.md) is an example org welcome README for `.github-private/profile/README.md`.
+- [devcontainer.json](devcontainer.json) is an example provisioned-repo Codespaces launcher for `.devcontainer/devcontainer.json`.
+
+The reusable source content in the workshop pages is marked with HTML comments:
+
+- `<!-- reuse:event-org-readme-intro:start -->` ... `<!-- reuse:event-org-readme-intro:end -->` in [00-welcome.md](../../00-welcome.md)
+- `<!-- reuse:event-org-readme-what-youll-do:start -->` ... `<!-- reuse:event-org-readme-what-youll-do:end -->` in [00-welcome.md](../../00-welcome.md)
+- `<!-- reuse:event-provisioned-start:start -->` ... `<!-- reuse:event-provisioned-start:end -->` in [00-welcome.md](../../00-welcome.md)
+
+Those markers make it clear which workshop prose is safe to mirror into event-specific surfaces without reauthoring it from scratch.

workshop/examples/event-provisioning/devcontainer.json

@@ -0,0 +1,17 @@
+{
+  "name": "gh-aw workshop launcher: provisioned codespaces terminal",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu-24.04",
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "GitHub.copilot",
+        "GitHub.copilot-chat"
+      ]
+    }
+  },
+  "postCreateCommand": "bash -lc 'gh extension install github/gh-copilot --force && gh extension install github/gh-aw --force'",
+  "postAttachCommand": "bash -lc 'url=https://github.github.com/gh-aw/workshop/#j=codespaces-terminal&s=foundation&t=04-github-actions-intro; printf \"\\nWorkshop URL: %s\\n\\n\" \"$url\"; if command -v xdg-open >/dev/null 2>&1; then xdg-open \"$url\" >/dev/null 2>&1 || true; fi; gh --version; gh aw --version'"
+}

workshop/examples/event-provisioning/org-profile-README.md

@@ -0,0 +1,29 @@
+# GitHub Agentic Workflows Workshop
+
+Welcome to the provisioned workshop organization. Your event setup can create your practice repository, invite you to the org, and open a Codespace before you begin.
+
+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.
+
+## What You'll Do
+
+You'll build an [agentic workflow](https://github.github.com/gh-aw/introduction/overview/): a GitHub Action that uses AI to inspect your repository, decide what matters, and publish a useful status report on a schedule — practical enough to adapt for real teams.
+
+What makes it different from regular GitHub Actions:
+
+- It reasons about live repository state instead of only following a fixed script.
+- It turns signals into decisions — spotting stale pull requests or flagging CI trouble without hard-coding every branch.
+- It produces stakeholder-ready output automatically — a daily report people can actually use.
+
+## Start Here
+
+If your workshop organizer already created your repository and Codespace for you, start at one of these workshop entry points:
+
+- [Step 4: GitHub Actions in 5 Minutes](https://github.github.com/gh-aw/workshop/#j=codespaces-terminal&s=foundation&t=04-github-actions-intro)
+- [Step 5: What Are Agentic Workflows?](https://github.github.com/gh-aw/workshop/#j=codespaces-terminal&s=foundation&t=05-agentic-workflows-intro)
+
+Then continue with:
+
+- [Step 6a: Install gh-aw — Codespace Terminal](https://github.github.com/gh-aw/workshop/#j=codespaces-terminal&s=foundation&t=06a-install-terminal)
+- [Step 7a: Write Your First Agentic Workflow — Terminal Path](https://github.github.com/gh-aw/workshop/#j=codespaces-terminal&s=foundation&t=07a-your-first-workflow-terminal)
+
+If you want the full workshop from the beginning instead, start at [Step 0: Welcome](https://github.github.com/gh-aw/workshop/#j=codespaces-terminal&s=foundation&t=00-welcome).