Teach-ready docs: template setup, run of show, CI agent at zero dollars

README.md

@@ -20,6 +20,16 @@ Go top to bottom. The full map with every link is [docs/README.md](docs/README.m
 5. Agent track and electives: [docs/README.md](docs/README.md#5-agent-track).
 6. After the workshop: [take-home](docs/take-home.md).
 
+## Use this template
+
+This repo is a GitHub template. Click "Use this template", then set these in your copy before CI is useful:
+
+- Secret `CLAUDE_CODE_OAUTH_TOKEN` (your own subscription) or `ANTHROPIC_API_KEY` (a team workspace key). The review job needs one; without it that job fails and the rest still run. See [auth modes](docs/factory/auth-modes.md).
+- Labels `factory:triage`, `factory:planned`, `factory:ready`, `plan:approved` and `assignment`. The factory moves a ticket between them.
+- `levels.json` owns every file a level ships. A new source file needs an owner there, or `make check` fails.
+
+Teaching it? Use the [run of show](docs/run-of-show.md).
+
 ## Install the factory in your own repo
 
 ```

docs/README.md

@@ -2,6 +2,8 @@
 
 One app, Worksheet Studio, with two workshops: Claude Code, beginner to pro, and the Software Factory. Both share the levels and the labs. Pick yours with `make lab PATH_ID=pro` or `make lab PATH_ID=factory`, then take its parts in order.
 
+Teaching a room? Open the [run of show](run-of-show.md).
+
 ## Set up
 
 1. `make doctor` checks your machine.

docs/factory/f13-spend-and-safety.md

@@ -105,6 +105,17 @@ printf '%s' '{"tool_input":{"command":"cat .env"}}' > /tmp/call.json && node .cl
 
 Expect the "Blocked" message and `exit 2`. Your own Claude Code session may refuse to run this line for the same reason. If so, run it in a plain terminal.
 
+## When a CI agent fails at zero dollars
+
+A review job can fail while the account shows credit. Four things this repo hit:
+
+- **"Credit balance is too low".** The API key's balance did not cover the Claude Code client in CI. `review.yml` uses `CLAUDE_CODE_OAUTH_TOKEN` for that reason. Check the error text before you top up anything.
+- **A shared token is not individual use.** A team should put an API key from its own workspace in the secret ([auth modes](auth-modes.md)).
+- **`push` events are refused** by the review action. Trigger it on `pull_request`, as `review.yml` does.
+- **`show_full_output: true` leaks.** It prints the agent's tool output into a public log. Never merge it to a public repo.
+
+A failed agent job is a signal, not a blocker: the gate jobs do not depend on it.
+
 ## Discussion
 
 - The run cap stops new calls at 75 percent by default, and the last call can still use the rest. Is that the share you would choose, and is `capUsd` an amount you would accept losing on a bad night?

docs/run-of-show.md

@@ -0,0 +1,36 @@
+# Run of show
+
+Two workshops share this repo. Pick the one you teach. Every block has one live command and a fallback if it misbehaves.
+
+Before the room fills: `make doctor`, `npm ci`, `make check`. Fallback for a slow laptop: `make levels LEVEL=<name>` writes a finished copy to `supplied/<name>/`.
+
+## Claude Code, beginner to pro
+
+Learners run `make lab PATH_ID=pro` once. Lanes: `start`, `daily`, `team`, `advanced`.
+
+| Block    | Teach                              | Live command              | Fallback                                             |
+| -------- | ---------------------------------- | ------------------------- | ---------------------------------------------------- |
+| Open     | the app and the gate               | `make check`              | read `docs/README.md` aloud                          |
+| Start    | ask, plan first, local memory      | `make lab ID=start-01`    | [walkthrough-start](labs/walkthrough-start.md)       |
+| Daily    | rules, skills, hooks               | `make lab ID=daily-01`    | [walkthrough-daily](labs/walkthrough-daily.md)       |
+| Team     | deny rules, review rules, plugin   | `make lab ID=team-01`     | [walkthrough-team](labs/walkthrough-team.md)         |
+| Advanced | reviewer subagent, cost, worktrees | `make lab ID=advanced-01` | [walkthrough-advanced](labs/walkthrough-advanced.md) |
+| Close    | what to take home                  | `make progress`           | [take-home](take-home.md)                            |
+
+Individuals work at their own pace with `make next`. A team splits by lane and compares `make progress`.
+
+## Software Factory
+
+Learners run `make lab PATH_ID=factory` once. Lanes: `start`, `daily`, `factory`.
+
+| Block    | Teach                                | Live command                           | Fallback                                           |
+| -------- | ------------------------------------ | -------------------------------------- | -------------------------------------------------- |
+| Open     | the path from ticket to merged PR    | `make factory ISSUE=1 FLAGS=--dry-run` | [F0](factory/f0-overview.md)                       |
+| Contract | intent, acceptance first             | `make lab ID=factory-01`               | [walkthrough-factory](labs/walkthrough-factory.md) |
+| Checks   | evidence the model cannot argue with | `make lab ID=factory-05`               | read [F4](factory/f4-test.md)                      |
+| Review   | three voters, two needed             | `make lab ID=factory-06`               | read [F5](factory/f5-review.md)                    |
+| Maintain | a metric outside its band            | `make lab ID=factory-07`               | read [F7](factory/f7-maintain.md)                  |
+| Spend    | caps, keys, hooks                    | `make factory ISSUE=1 FLAGS=--dry-run` | [F13](factory/f13-spend-and-safety.md)             |
+| Close    | pick an assignment                   | `make progress`                        | [F10](factory/f10-assignments.md)                  |
+
+Individuals use the dry run and never need a key. A team that runs live uses a workspace API key with a spend limit, and reads [when a CI agent fails at zero dollars](factory/f13-spend-and-safety.md#when-a-ci-agent-fails-at-zero-dollars) first.

levels.json

@@ -194,6 +194,7 @@
     "scripts/prove/sharing.ts",
     "docs/levels/sharing.md",
     "docs/when-to-use-what.md",
+    "docs/run-of-show.md",
     "tests/structure/when-to-use-what.test.ts",
     "docs/recordings/sharing.cast",
     "docs/recordings/sharing.gif",