From 37329590bc5e99143a0ac94106630323453e038a Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 12 Jan 2026 23:10:08 +0000
Subject: [PATCH 1/2] Add instructor documentation for Epic Workshop agent
 authoring

Co-authored-by: me <me@kentcdodds.com>
---
 instructor/.gitkeep                         |   1 +
 instructor/agent-brief-template.md          |  85 +++++++++++++
 instructor/epic-workshop-anatomy.md         | 132 ++++++++++++++++++++
 instructor/exercise-authoring.md            | 106 ++++++++++++++++
 instructor/mdx-style-guide.md               | 111 ++++++++++++++++
 instructor/readme.md                        |  34 +++++
 instructor/validation-and-quality.md        | 105 ++++++++++++++++
 instructor/workshop-design-playbook.md      | 121 ++++++++++++++++++
 instructor/workshop-template-checklist.md   |  66 ++++++++++
 reference-workshops/mcp-auth                |   1 +
 reference-workshops/mcp-ui                  |   1 +
 reference-workshops/mocking-techniques      |   1 +
 reference-workshops/react-fundamentals      |   1 +
 reference-workshops/react-performance       |   1 +
 reference-workshops/react-server-components |   1 +
 reference-workshops/web-forms               |   1 +
 16 files changed, 768 insertions(+)
 create mode 100644 instructor/.gitkeep
 create mode 100644 instructor/agent-brief-template.md
 create mode 100644 instructor/epic-workshop-anatomy.md
 create mode 100644 instructor/exercise-authoring.md
 create mode 100644 instructor/mdx-style-guide.md
 create mode 100644 instructor/readme.md
 create mode 100644 instructor/validation-and-quality.md
 create mode 100644 instructor/workshop-design-playbook.md
 create mode 100644 instructor/workshop-template-checklist.md
 create mode 160000 reference-workshops/mcp-auth
 create mode 160000 reference-workshops/mcp-ui
 create mode 160000 reference-workshops/mocking-techniques
 create mode 160000 reference-workshops/react-fundamentals
 create mode 160000 reference-workshops/react-performance
 create mode 160000 reference-workshops/react-server-components
 create mode 160000 reference-workshops/web-forms

diff --git a/instructor/.gitkeep b/instructor/.gitkeep
new file mode 100644
index 0000000..8b13789
--- /dev/null
+++ b/instructor/.gitkeep
@@ -0,0 +1 @@
+
diff --git a/instructor/agent-brief-template.md b/instructor/agent-brief-template.md
new file mode 100644
index 0000000..a1c473b
--- /dev/null
+++ b/instructor/agent-brief-template.md
@@ -0,0 +1,85 @@
+# Agent brief template (copy/paste for instructors)
+
+Use this prompt to instruct an agent to generate a complete Epic Workshop on a topic.
+
+## Prompt
+
+### Context
+
+You are building an **Epic Workshop** repository using the Epic Workshop format.
+
+You must:
+
+- scope the topic appropriately for a workshop
+- design a cohesive set of exercises with small deltas
+- generate exercises/steps in the correct directory structure
+- write all required `README.mdx`/`FINISHED.mdx` files
+- add tests or other verification for each step
+- validate by running through the workshop using the **Epic Workshop MCP server tools**
+
+### Inputs
+
+- **Topic**: <PUT TOPIC HERE>
+- **Audience**: <BEGINNER | INTERMEDIATE | ADVANCED>
+- **Timebox**: <e.g. 2 hours / 4 hours / 1 day>
+- **Assumed prerequisites**:
+  - <list>
+- **Target outcomes** (3–7 bullets):
+  - <list>
+- **Preferred stack/runtime** (if any):
+  - <e.g. React, Node, Remix, Cloudflare Workers, etc.>
+- **Constraints**:
+  - All filenames must be lower-kebab-case.
+  - Keep problem→solution diffs small and focused.
+
+### Repository starting point
+
+Start from an existing template:
+
+- clone/copy `workshop-template/` into a new repo directory
+- update root `package.json#name` and `package.json#epicshop` metadata
+- ensure `npm run setup` and `npm start` work
+
+### Deliverables (must produce all)
+
+1. **Workshop plan** (before writing code):
+   - title + subtitle
+   - outcomes
+   - exercise list with step titles and acceptance criteria
+   - app type per exercise (simple vs project)
+   - tests plan per step
+2. **Workshop implementation**:
+   - correct `exercises/` structure
+   - all MDX instructions written
+   - problem/solution apps created for each step
+   - tests (or verification) for each step
+3. **Validation proof**:
+   - demonstrate the workshop can be navigated using the Epic Workshop MCP tools:
+     - `get_workshop_context`
+     - `set_playground`
+     - `get_exercise_step_context`
+     - `open_exercise_step_files`
+     - `get_exercise_step_progress_diff`
+     - `get_what_is_next`
+   - ensure at least one full exercise is completable end-to-end
+
+### Working agreement (iteration)
+
+Work in an iterative loop:
+
+- implement **exercise 01 fully**, validate it, then proceed
+- do not generate the entire workshop without intermediate validation
+- when you discover missing prerequisites or scope issues, adjust the plan and continue
+
+### Tone and instruction style
+
+Write learner instructions that include:
+
+- what to do
+- why it matters
+- where to work (use `<InlineFile />` when helpful)
+- acceptance criteria
+- at least one helpful tip or gotcha when appropriate
+
+Now begin by producing the **Workshop plan** only.
+
diff --git a/instructor/epic-workshop-anatomy.md b/instructor/epic-workshop-anatomy.md
new file mode 100644
index 0000000..227faec
--- /dev/null
+++ b/instructor/epic-workshop-anatomy.md
@@ -0,0 +1,132 @@
+# Epic Workshop anatomy (repo structure + conventions)
+
+This is the **non-negotiable “shape”** of an Epic Workshop. Agents should follow this exactly unless there’s a strong reason not to.
+
+## Core definitions
+
+- **Workshop**: the entire repository.
+- **Workshop app**: the Epic Workshop app that renders exercises and runs apps/tests.
+- **Exercise**: each directory inside `exercises/` like `01.topic-name/`.
+- **Exercise step**: each subdirectory inside an exercise like `01.problem.some-step/` and `01.solution.some-step/`.
+- **Problem app**: the starting state for a step.
+- **Solution app**: the finished state for a step.
+- **Playground**: where learners do their work; “Set to Playground” copies a chosen app into `playground/`.
+
+## Canonical directory structure
+
+At a high level:
+
+```
+.
+├── README.md
+├── package.json
+├── package-lock.json
+├── epicshop/
+│   ├── package.json
+│   ├── setup.js
+│   └── ... workshop app helpers ...
+├── exercises/
+│   ├── README.mdx
+│   ├── FINISHED.mdx
+│   ├── 01.some-exercise/
+│   │   ├── README.mdx
+│   │   ├── FINISHED.mdx
+│   │   ├── 01.problem.some-step/
+│   │   │   ├── README.mdx
+│   │   │   └── ... app files ...
+│   │   └── 01.solution.some-step/
+│   │       ├── README.mdx
+│   │       └── ... app files ...
+│   └── 02.next-exercise/
+│       └── ...
+└── playground/
+    └── (generated by “Set to playground”)
+```
+
+### Naming rules
+
+- **Exercise directories**: `NN.exercise-title` (e.g. `01.js-hello-world`, `07.csrf`).
+- **Step directories**: `NN.problem.step-name` and `NN.solution.step-name`.
+- **All names should be lower-kebab-case**.
+- Use **2-digit** exercise folders when possible (many repos do both; be consistent in a workshop).
+
+## App types: “simple” vs “project”
+
+The workshop app supports two app types:
+
+### Simple app
+
+If there is **no** `package.json` with a `dev` script in the app directory, it’s treated as a *simple app*.
+
+Common patterns:
+
+- `index.html` + inline `<script>` for early fundamentals steps.
+- `index.tsx` / `index.ts` / `index.js` without an `index.html` (the workshop app can generate HTML).
+- Optional `index.css`.
+
+Simple apps can also include an `api.server.ts` (or `.js`, `.tsx`, etc.) exporting `loader` and/or `action` (Remix-like) for server-backed steps.
+
+**Important**: simple apps are served from the workshop app; they are not fully isolated. If you need real server/runtime isolation, use a project app.
+
+### Project app
+
+If the app directory includes a `package.json` with a `dev` script, it’s treated as a *project app*.
+
+The workshop app will:
+
+- run `npm run dev` for that app (with a `PORT` env)
+- iframe the running app
+
+Therefore, **the app’s `dev` script must bind to `process.env.PORT`**.
+
+## Instructions: required MDX files
+
+These are the files instructors/agents must generate:
+
+- `exercises/README.mdx`: workshop intro.
+- `exercises/**/README.mdx`: exercise intro.
+- `exercises/**/**.problem.*/README.mdx`: step problem instructions.
+- `exercises/**/**.solution.*/README.mdx`: step solution instructions.
+- `exercises/**/FINISHED.mdx`: exercise outro (reflection + feedback).
+- `exercises/FINISHED.mdx`: workshop wrap-up.
+
+> If the workshop is “launched” (published), all of the above should also embed an `EpicVideo`.
+
+## Tests (how the workshop app decides to show the test tab)
+
+The test tab appears when either is true:
+
+1. The app has a `package.json` with a `test` script (the UI shows a button to run it).
+2. The app has `*.test.*` files in its root (tests are compiled/bundled and run in-browser).
+
+For simple apps, in-browser tests typically use `@epic-web/workshop-utils/test`.
+
+## Diffs (how learners get unstuck)
+
+The diff tab compares problem/solution (or playground/solution) while filtering noise.
+
+It ignores:
+
+- patterns from root `.gitignore`
+- patterns from exercise `.gitignore` (if present)
+- extra patterns from `epicshop/.diffignore` (root and/or per-exercise)
+
+Use `.diffignore` if learners are overwhelmed by irrelevant file changes.
+
+## Repo-level configuration (`package.json#epicshop`)
+
+The root `package.json` should include an `epicshop` object with (at minimum):
+
+- `title` (required)
+- `githubRoot` or `githubRepo` (required for proper file links)
+
+Common additions:
+
+- `subtitle`
+- `instructor` (name/avatar/xHandle)
+- `product` (host/slug + optional discord metadata)
+- `stackBlitzConfig`
+- `testTab.enabled`
+- `initialRoute`
+- `scripts.postupdate`
+
diff --git a/instructor/exercise-authoring.md b/instructor/exercise-authoring.md
new file mode 100644
index 0000000..eb2b7c2
--- /dev/null
+++ b/instructor/exercise-authoring.md
@@ -0,0 +1,106 @@
+# Exercise authoring (steps, tests, and “set to playground”)
+
+This guide is for producing workshop content that is **cohesive, iterative, and easy to validate**.
+
+## Authoring loop (per exercise)
+
+For exercise `NN.some-title`:
+
+1. Write `exercises/NN.some-title/README.mdx` (intro).
+2. Implement step 01:
+   - create `01.problem.step-name/` app
+   - create `01.solution.step-name/` app
+   - write both `README.mdx` files
+   - add tests (or another verification mechanism)
+3. Repeat for steps 02..N.
+4. Write `exercises/NN.some-title/FINISHED.mdx` (outro + reflection).
+5. Validate the entire exercise in the workshop app (and via MCP tools).
+
+## Step structure (problem vs solution)
+
+### Problem directory responsibilities
+
+The problem app should:
+
+- include everything required to run
+- contain a **focused gap** aligned to the step objective
+- fail tests (or visibly be incorrect) in a way learners can fix
+
+### Solution directory responsibilities
+
+The solution app should:
+
+- implement the objective cleanly
+- pass tests
+- avoid unrelated refactors (keep the diff small)
+
+## Writing good step instructions (README.mdx)
+
+### Problem README.mdx should include
+
+- **Context**: why this change matters.
+- **Task**: what to implement.
+- **Constraints**: what not to do / what to preserve.
+- **Acceptance criteria**: how learners know they’re done.
+- **Where to work**: pointers using `<InlineFile />` when helpful.
+
+### Solution README.mdx should include
+
+- **What changed** (conceptually).
+- **Why it works**.
+- Optional: alternatives, tradeoffs, and “watch out for this next time.”
+
+## Tests and verification
+
+Use tests to give learners fast feedback.
+
+The workshop app shows the test tab when:
+
+- the app has a `test` script in `package.json`, OR
+- there are `*.test.*` files in the app root (compiled and run in-browser)
+
+### Simple app tests
+
+For “simple” apps, prefer in-browser tests using:
+
+- `@epic-web/workshop-utils/test` (exports `testStep`, `expect`, and `dtl`)
+
+### Project app tests
+
+For “project” apps, prefer:
+
+- unit tests for pure logic
+- e2e tests (e.g. Playwright) when the step objective is a user flow
+
+## Diffs: keep them helpful
+
+The diff tab is a core “unblocker.”
+
+Best practices:
+
+- keep steps small so the diff is readable
+- avoid formatting-only changes
+- avoid changing generated or irrelevant files
+- consider `epicshop/.diffignore` if certain files always create noise
+
+## Playground copy hooks (advanced)
+
+If you need custom behavior before/after “Set to playground,” you can add:
+
+- `epicshop/pre-set-playground.js`
+- `epicshop/post-set-playground.js`
+
+These can exist:
+
+- at the workshop root, or
+- inside an exercise directory (overrides the root hook)
+
+They receive env vars like:
+
+- `EPICSHOP_PLAYGROUND_SRC_DIR`
+- `EPICSHOP_PLAYGROUND_DEST_DIR`
+- `EPICSHOP_PLAYGROUND_WAS_RUNNING`
+- `EPICSHOP_PLAYGROUND_IS_STILL_RUNNING` (post only)
+
+Use this sparingly; hooks increase complexity.
+
diff --git a/instructor/mdx-style-guide.md b/instructor/mdx-style-guide.md
new file mode 100644
index 0000000..3b1eaf1
--- /dev/null
+++ b/instructor/mdx-style-guide.md
@@ -0,0 +1,111 @@
+# MDX style guide (Epic Workshop format)
+
+Epic Workshops rely heavily on MDX for instructions. Consistency matters because learners scan.
+
+## Code blocks
+
+Epic Workshop MDX supports code block options (from `@kentcdodds/md-temp`).
+
+Example options:
+
+````mdx
+```tsx filename=app/filename.tsx nocopy nonumber remove=1,3-5 add=2,6-8 lines=3,9-12
+// code...
+```
+````
+
+Notes:
+
+- `sh` blocks may not auto-number; add `nonumber` when desired.
+- Prefer `filename=...` for “look here” snippets.
+- Use `remove=` and `add=` when teaching diffs inside instructions.
+
+## Callouts
+
+Available callout components:
+
+- `<callout-muted>` (gray)
+- `<callout-info>` (blue)
+- `<callout-warning>` (yellow)
+- `<callout-danger>` (red)
+- `<callout-success>` (green)
+
+Optional classes:
+
+- `class="aside"`: smaller helper text
+- `class="important"`: larger/bolder emphasis
+- `class="notification"`: supports a title (warning/danger only)
+
+## Useful MDX components
+
+### `InlineFile`
+
+Use to link to a file learners should open:
+
+```mdx
+<InlineFile file="app/root.tsx" />
+<InlineFile file="index.html">Open the step file</InlineFile>
+```
+
+### `LinkToApp`
+
+Use to link to a route in the running app:
+
+```mdx
+<LinkToApp to="/dashboard" />
+<LinkToApp to="/dashboard">Go to dashboard</LinkToApp>
+```
+
+### `DiffLink`, `NextDiffLink`, `PrevDiffLink`
+
+Use to send learners straight to a diff.
+
+Example:
+
+```mdx
+<DiffLink app1="02/01.solution" app2="02/02.problem">
+	Compare these two steps
+</DiffLink>
+```
+
+Shortcuts:
+
+```mdx
+<NextDiffLink>Check the upcoming changes</NextDiffLink>
+<PrevDiffLink>Check the changes that were made</PrevDiffLink>
+```
+
+## Embedding videos
+
+### `EpicVideo`
+
+For launched/published workshops, embed the canonical Epic video:
+
+```mdx
+<EpicVideo url="https://www.epicweb.dev/workshops/.../some-lesson" />
+```
+
+### `VideoEmbed`
+
+For non-Epic videos:
+
+```mdx
+<VideoEmbed
+	title="Some title"
+	url="https://www.youtube.com/embed/..."
+/>
+```
+
+## Mermaid diagrams
+
+Mermaid is supported:
+
+````mdx
+```mermaid
+sequenceDiagram
+  A->>B: hello
+```
+````
+
+Use diagrams when a concept is hard to explain text-only (protocol flows, lifecycles, pipelines).
+
diff --git a/instructor/readme.md b/instructor/readme.md
new file mode 100644
index 0000000..bf48e30
--- /dev/null
+++ b/instructor/readme.md
@@ -0,0 +1,34 @@
+# Epic Workshop instructor docs
+
+This directory is **for instructors** who want to use an agent to build an Epic Workshop on *any* topic.
+
+The goal: you (the instructor) can clone `workshop-template/`, open an agent, and say:
+
+> “I want to teach about X, build me the workshop for that.”
+
+…and the agent will reliably:
+
+- **scope** the workshop appropriately
+- **research** the topic and choose a coherent project
+- **design** a linear, iterative exercise flow (when reasonable)
+- **author** exercises in the Epic Workshop format (MDX + problem/solution apps)
+- **validate** by running the workshop and “taking” it using the Epic Workshop MCP server tools
+
+## How to use these docs
+
+1. Read `epic-workshop-anatomy.md` to understand the required repo structure.
+2. Use `workshop-design-playbook.md` to scope and outline the workshop.
+3. Use `exercise-authoring.md` + `mdx-style-guide.md` while generating steps and instructions.
+4. Give the agent `agent-brief-template.md` as its “contract”.
+5. Use `validation-and-quality.md` to make the agent prove the workshop works end-to-end.
+
+## Files in this directory
+
+- `agent-brief-template.md`: copy/paste prompt an instructor gives to an agent to generate a new workshop on a topic.
+- `epic-workshop-anatomy.md`: structure, naming, app types (simple vs project), and required files.
+- `workshop-design-playbook.md`: how to scope, research, and design a cohesive exercise flow.
+- `exercise-authoring.md`: how to write steps, problems/solutions, tests, and “set to playground” behavior.
+- `mdx-style-guide.md`: Epic Workshop MDX conventions (callouts, code blocks, components, diffs).
+- `validation-and-quality.md`: how the agent validates via the `@epic-web/workshop-mcp` tools + CLI.
+- `workshop-template-checklist.md`: repo-level checklist (package.json config, scripts, CI, deployment readiness).
+
diff --git a/instructor/validation-and-quality.md b/instructor/validation-and-quality.md
new file mode 100644
index 0000000..cd45ca0
--- /dev/null
+++ b/instructor/validation-and-quality.md
@@ -0,0 +1,105 @@
+# Validation and quality (agent must prove it works)
+
+This is the acceptance gate. A workshop is not “done” when files exist — it’s done when a learner can complete it.
+
+## What must be validated
+
+For every exercise and step:
+
+- the workshop app can load instructions (no broken MDX)
+- “Set to playground” works for problem and solution
+- the dev server (if any) starts
+- tests (if present) run and pass in the solution
+- the problem is meaningfully incomplete (tests fail or behavior is wrong)
+- diffs are helpful (small, focused, not noisy)
+
+## Run locally via CLI (baseline)
+
+Most Epic workshops ship scripts like:
+
+- `npm run setup`
+- `npm start` / `npm run dev` (usually delegates to `npx --prefix ./epicshop epicshop start`)
+
+The agent should use these to sanity check:
+
+- install succeeds
+- workshop app boots
+- at least one representative exercise step runs
+
+## Validate “as a learner” using the Epic Workshop MCP server
+
+Epic Workshops have an MCP server designed to help learners inside a workshop repo:
+
+- package: `@epic-web/workshop-mcp`
+- typical MCP server name: `epicshop`
+
+### MCP server configuration (Cursor example)
+
+```json
+{
+	"mcpServers": {
+		"epicshop": {
+			"command": "npx",
+			"args": ["-y", "@epic-web/workshop-mcp@latest"]
+		}
+	}
+}
+```
+
+### Critical requirement
+
+Run your editor/assistant with the **workshop repo as the working directory**, so the MCP server can find:
+
+- `package.json#epicshop`
+- `exercises/**`
+- `playground/`
+
+## MCP tools the agent should use for validation
+
+The MCP server exposes tools the agent can call to simulate a learner moving through the workshop:
+
+- `login`: login to Epic (optional; enables progress tracking + transcripts if available)
+- `logout`
+- `get_workshop_context`: overview of workshop structure + top-level instructions
+- `get_exercise_context`: context for a single exercise
+- `get_exercise_step_context`: context for a single step (problem+solution instructions)
+- `set_playground`: set playground to next step or a specific exercise/step/type
+- `open_exercise_step_files`: open the important files for the current step in the editor
+- `get_exercise_step_progress_diff`: diff between the user’s playground work and the solution
+- `get_diff_between_apps`: diff between any two apps (by name/path)
+- `view_video`: view an embedded Epic video URL (useful for launched workshops)
+- `update_progress`: mark a lesson/step as complete (when using progress tracking)
+- `get_user_info`, `get_user_access`, `get_user_progress`
+- `get_what_is_next`: the best “driver” tool for linear navigation
+- `get_quiz_instructions`: helper for using the quiz prompt flow
+
+### Recommended validation workflow (agent)
+
+1. Call `get_workshop_context` and verify the workshop outline matches the intended scope.
+2. Call `set_playground` with no args repeatedly to ensure progression works.
+3. For each step:
+   - call `get_exercise_step_context` and verify instructions are present
+   - call `open_exercise_step_files` and ensure file references exist
+   - check `get_exercise_step_progress_diff` after making expected changes in `playground/`
+4. Confirm that the diff is small and that acceptance criteria are achievable without “guesswork.”
+
+## Quality checklists (what “good” means)
+
+### Instruction quality
+
+- Clear acceptance criteria
+- Explicit “where to work”
+- Explains *why* (not just *what*)
+- Notes at least one common pitfall for tricky steps
+
+### Step delta quality
+
+- Problem → solution diff is focused
+- No unrelated refactors
+- No massive dependency churn between steps
+
+### Test/feedback quality
+
+- Learners have a reliable way to know they’re done
+- Failures point to the right area (not cryptic)
+
diff --git a/instructor/workshop-design-playbook.md b/instructor/workshop-design-playbook.md
new file mode 100644
index 0000000..290fa36
--- /dev/null
+++ b/instructor/workshop-design-playbook.md
@@ -0,0 +1,121 @@
+# Workshop design playbook (scope → research → outline → steps)
+
+This is the “front-loaded planning” section. If the planning is weak, the workshop will be incoherent even if the code is correct.
+
+## The quality bar (what “great” looks like)
+
+A great Epic Workshop:
+
+- **Teaches one coherent set of skills** (not “everything about X”).
+- Has a **linear progression** where each step builds directly on the previous one.
+- Uses **tiny deltas** between problem → solution so the diff tab is helpful.
+- Gives learners **fast feedback** (tests, visible UI behavior, or verifiable output).
+- Includes **just enough scaffolding** so learners do the learning, not boilerplate.
+- Provides **good instructions** (what/why/how, common pitfalls, and what “done” looks like).
+
+## Step 0: Instructor inputs (what the agent needs from you)
+
+Before any code generation, the agent must produce and get agreement on:
+
+- **Audience**: beginner/intermediate/advanced; what they already know.
+- **Prereqs**: minimum required knowledge + environment constraints.
+- **Timebox**: total duration and desired # of exercises.
+- **Core outcomes** (3–7 bullets): what learners can do at the end.
+- **Capstone artifact**: what learners will have built by the end.
+- **Non-goals**: explicitly what won’t be covered.
+
+## Step 1: Scope the workshop into a “single project”
+
+Pick a project that naturally forces the concepts:
+
+- If you’re teaching **forms**: choose a form-heavy app with realistic constraints.
+- If you’re teaching **performance**: choose a UI with measurable perf bottlenecks.
+- If you’re teaching **MCP**: choose a server with a clear tool/resource surface.
+
+Avoid “toy apps” unless the workshop is explicitly fundamentals-level.
+
+## Step 2: Build a concept map and dependency chain
+
+Write down:
+
+- **Concepts** to teach
+- **Dependencies** between them (“you must understand A before B”)
+- **Common misconceptions** you want to flush out
+
+Then order concepts by dependency, and cluster into exercises.
+
+## Step 3: Design exercises (macro-structure)
+
+Each exercise should have:
+
+- **Title**: a user-centered capability, not an implementation detail.
+- **Goal**: what the learner achieves.
+- **Why**: why this matters in real projects.
+- **New constraints**: what got harder compared to last exercise.
+
+Recommended cadence:
+
+- **5–10 exercises** for a medium workshop
+- **2–6 steps** per exercise
+
+## Step 4: Design steps (micro-structure)
+
+Each step must be a small, testable delta.
+
+For each step, define:
+
+- **Problem state**: what is missing/broken.
+- **Acceptance criteria**: objective “done” conditions.
+- **Hints**: where to look + common gotchas.
+- **Solution delta**: what changes from problem to solution.
+
+### “Small delta” rule of thumb
+
+If the diff between problem and solution feels like “a new feature,” split it into multiple steps.
+
+## Step 5: Choose app type per exercise/step
+
+- Use **simple apps** for:
+  - early fundamentals
+  - UI-only steps
+  - minimal dependencies
+- Use **project apps** for:
+  - realistic full-stack flows
+  - databases/auth
+  - multi-file apps with routing/build tooling
+
+## Step 6: Plan the instructor narrative and tone
+
+Many Epic Workshops use a light narrative voice (“Product Manager explains user needs”) plus occasional “helper” characters.
+
+This is optional, but helps with:
+
+- motivation (“why”)
+- pacing
+- reducing dry instruction blocks
+
+## Step 7: Produce the workshop outline artifact
+
+Before generating code, the agent must output:
+
+- Workshop title + subtitle
+- 3–7 outcomes
+- A numbered list of exercises, each with:
+  - goal
+  - list of steps (titles)
+  - per-step acceptance criteria
+  - app type (simple vs project)
+  - tests plan (how learners verify)
+
+This outline becomes the “contract” the agent implements.
+
+## Step 8: Generate in an iterative loop
+
+The agent should build:
+
+1. **Exercise 01 fully** (including tests + README.mdx + FINISHED.mdx).
+2. Validate it end-to-end.
+3. Repeat for exercise 02, etc.
+
+Do **not** generate the entire workshop in one pass without validation.
+
diff --git a/instructor/workshop-template-checklist.md b/instructor/workshop-template-checklist.md
new file mode 100644
index 0000000..059b995
--- /dev/null
+++ b/instructor/workshop-template-checklist.md
@@ -0,0 +1,66 @@
+# Workshop template checklist (repo-level “definition of done”)
+
+Use this as a final checklist when cloning `workshop-template/` and generating a new workshop.
+
+## Required repo contents
+
+- `README.md` includes:
+  - prerequisites
+  - setup instructions using `epicshop` (e.g. `npx --yes epicshop@latest add <repo>`)
+  - how to start (`npm start`)
+- root `package.json` includes:
+  - `name` (repo name)
+  - `private: true`
+  - `epicshop.title` (required)
+  - `epicshop.githubRoot` or `epicshop.githubRepo` (required)
+  - scripts:
+    - `start` (typically `npx --prefix ./epicshop epicshop start`)
+    - `setup` (typically `node ./epicshop/setup.js`)
+    - `lint`, `typecheck` (as applicable)
+- `epicshop/` directory exists with its own `package.json` and `setup.js`
+- `exercises/` directory exists with:
+  - `README.mdx`
+  - `FINISHED.mdx`
+  - at least one exercise folder with at least one step pair
+
+## Exercise completeness
+
+For each exercise:
+
+- `README.mdx` intro exists
+- `FINISHED.mdx` outro exists
+- each step has:
+  - `NN.problem.*` with `README.mdx`
+  - `NN.solution.*` with `README.mdx`
+  - runnable app files
+
+## Config hygiene
+
+- `epicshop.subtitle` set (recommended)
+- `epicshop.instructor` set (recommended)
+- `epicshop.product.host` and `.slug` set for launched workshops (required for progress tracking)
+- `epicshop.stackBlitzConfig` set or explicitly disabled (`null`) where unsupported
+- `epicshop.testTab.enabled` set appropriately
+- `epicshop.initialRoute` set if the app should load a non-`/` route
+
+## Diff hygiene
+
+- diffs between steps are readable and focused
+- add `epicshop/.diffignore` only if learners would otherwise see noise
+
+## CI baseline (recommended)
+
+A typical `validate.yml`:
+
+- checks out code (or uses `epicshop add <repo>` into a temp directory)
+- runs `npm run typecheck`
+- runs `npm run lint`
+- (optionally) runs tests
+
+## Deployment readiness (optional)
+
+If deploying the workshop:
+
+- set `EPICSHOP_DEPLOYED=true` in deployed env
+- ensure `epicshop.githubRoot` points to the correct branch/path so file links work
+
diff --git a/reference-workshops/mcp-auth b/reference-workshops/mcp-auth
new file mode 160000
index 0000000..749b6af
--- /dev/null
+++ b/reference-workshops/mcp-auth
@@ -0,0 +1 @@
+Subproject commit 749b6af3d14536f198ded7d4f42ea628ceb118d4
diff --git a/reference-workshops/mcp-ui b/reference-workshops/mcp-ui
new file mode 160000
index 0000000..f218caa
--- /dev/null
+++ b/reference-workshops/mcp-ui
@@ -0,0 +1 @@
+Subproject commit f218caa21ddd33e40d82d780759faa8f60117eee
diff --git a/reference-workshops/mocking-techniques b/reference-workshops/mocking-techniques
new file mode 160000
index 0000000..06a02db
--- /dev/null
+++ b/reference-workshops/mocking-techniques
@@ -0,0 +1 @@
+Subproject commit 06a02db9ede9c0d583ecab0c5b34944c034ac7e1
diff --git a/reference-workshops/react-fundamentals b/reference-workshops/react-fundamentals
new file mode 160000
index 0000000..69b78fb
--- /dev/null
+++ b/reference-workshops/react-fundamentals
@@ -0,0 +1 @@
+Subproject commit 69b78fb9c13621de0124a65c43a3cb8caf564ff3
diff --git a/reference-workshops/react-performance b/reference-workshops/react-performance
new file mode 160000
index 0000000..0171913
--- /dev/null
+++ b/reference-workshops/react-performance
@@ -0,0 +1 @@
+Subproject commit 0171913da7693c05be26fdd4070ee4c7e59fd743
diff --git a/reference-workshops/react-server-components b/reference-workshops/react-server-components
new file mode 160000
index 0000000..80035af
--- /dev/null
+++ b/reference-workshops/react-server-components
@@ -0,0 +1 @@
+Subproject commit 80035afd8239ca1eee09ed505997a74c69a266bd
diff --git a/reference-workshops/web-forms b/reference-workshops/web-forms
new file mode 160000
index 0000000..e5b6143
--- /dev/null
+++ b/reference-workshops/web-forms
@@ -0,0 +1 @@
+Subproject commit e5b61431747ce803c4b205bff2ee92d2a4ffa506

From 7dbdecd50bd8e522f2c785f9ee44176e99d8330c Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Mon, 12 Jan 2026 23:17:45 +0000
Subject: [PATCH 2/2] Add emoji guide for workshop narration; update instructor
 readme.

Co-authored-by: me <me@kentcdodds.com>
---
 instructor/emoji-guide.md | 15 +++++++++++++++
 instructor/readme.md      |  2 ++
 2 files changed, 17 insertions(+)
 create mode 100644 instructor/emoji-guide.md

diff --git a/instructor/emoji-guide.md b/instructor/emoji-guide.md
new file mode 100644
index 0000000..eaef619
--- /dev/null
+++ b/instructor/emoji-guide.md
@@ -0,0 +1,15 @@
+# Epic Workshop emoji/character guide
+
+Use these characters consistently in workshop MDX to keep a familiar narrative voice across Epic Workshops.
+
+- **Peter the Product Manager 👨‍💼**: helps us know what our users want
+- **Kellie the Co-worker 🧝‍♀️**: your co-worker who sometimes does work ahead of your exercises
+- **Kody the Koala 🐨**: will tell you when there's something specific you should do
+- **Lily the Life Jacket 🦺**: will help you with any TypeScript-specific parts of the exercises
+- **Marty the Money Bag 💰**: will give you specific tips (and sometimes code) along the way
+- **Nancy the Notepad 📝**: will encourage you to take notes on what you're learning
+- **Olivia the Owl 🦉**: will give you useful tidbits/best practice notes
+- **Dominic the Document 📜**: will give you links to useful documentation
+- **Barry the Bomb 💣**: will be hanging around anywhere you need to blow stuff up (delete code)
+- **Alfred the Alert 🚨**: will occasionally show up in test failure messages with potential explanations for why tests are failing
+
diff --git a/instructor/readme.md b/instructor/readme.md
index bf48e30..a1f1591 100644
--- a/instructor/readme.md
+++ b/instructor/readme.md
@@ -17,6 +17,7 @@ The goal: you (the instructor) can clone `workshop-template/`, open an agent, an
 ## How to use these docs
 
 1. Read `epic-workshop-anatomy.md` to understand the required repo structure.
+2. Read `emoji-guide.md` if you want to match the “Epic Workshop cast” voice.
 2. Use `workshop-design-playbook.md` to scope and outline the workshop.
 3. Use `exercise-authoring.md` + `mdx-style-guide.md` while generating steps and instructions.
 4. Give the agent `agent-brief-template.md` as its “contract”.
@@ -25,6 +26,7 @@ The goal: you (the instructor) can clone `workshop-template/`, open an agent, an
 ## Files in this directory
 
 - `agent-brief-template.md`: copy/paste prompt an instructor gives to an agent to generate a new workshop on a topic.
+- `emoji-guide.md`: canonical character/emoji mapping used in Epic Workshop narration.
 - `epic-workshop-anatomy.md`: structure, naming, app types (simple vs project), and required files.
 - `workshop-design-playbook.md`: how to scope, research, and design a cohesive exercise flow.
 - `exercise-authoring.md`: how to write steps, problems/solutions, tests, and “set to playground” behavior.