Agent workshop documentation

instructor/.gitkeep

@@ -0,0 +1 @@
+

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.
+

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
+

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`
+

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.
+