truecourse 0.7.0-next.1 → 0.7.0-next.11

package/README.md

@@ -28,12 +28,24 @@ Both store their results under `.truecourse/` and surface them in a shared [dash
   <img src="assets/demo.gif" alt="TrueCourse Screenshot" width="100%" />
 </p>
 
-Jump to: **[1. Analyze](#1-analyze--code-intelligence)** · **[2. Spec → Guard](#2-spec--guard--business-logic-drift)** · **[Dashboard](#dashboard-web-ui)**
+Jump to: **[Install](#install)** · **[1. Analyze](#1-analyze--code-intelligence)** · **[2. Spec → Guard](#2-spec--guard--business-logic-drift)** · **[Dashboard](#dashboard-web-ui)**
 
 No setup step and no database: TrueCourse creates `.truecourse/` in your repo on first use and stores everything there as plain JSON files. It uses the [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) for LLM-powered work — if `claude` isn't on your PATH, deterministic analysis still runs and LLM-dependent features are skipped.
 
 ---
 
+# Install
+
+```bash
+npm install -g truecourse
+```
+
+This puts the `truecourse` command on your PATH — every example below uses it. Prefer not to install globally? Run any command one-off with `npx truecourse <command>` instead.
+
+See [Prerequisites](#prerequisites) for Node, Claude Code, and C# requirements.
+
+---
+
 # 1. Analyze — code intelligence
 
 Static + LLM analysis of your code: architecture, security, bugs, performance, and more.
@@ -42,8 +54,8 @@ Static + LLM analysis of your code: architecture, security, bugs, performance, a
 
 ```bash
 cd <your-repo>
-npx truecourse analyze      # Runs the full analysis in-process
-npx truecourse list         # Show the violations it found
+truecourse analyze          # Runs the full analysis in-process
+truecourse list             # Show the violations it found
 ```
 
 The first analyze creates `.truecourse/` and stores results as plain JSON. View them visually with [`truecourse dashboard`](#dashboard-web-ui).
@@ -239,6 +251,29 @@ The spec, the scenarios, and a guard baseline are committable so they travel wit
 
 Like analyze, `guard/LATEST.json` is the committable baseline — commit it after merging to `main` (re-run `truecourse guard run`, commit the result), not from feature branches.
 
+### The recipe — `scenarios/recipe.json`
+
+The recipe tells guard how to build your repo and what binary the scenarios exercise:
+
+```json
+{
+  "build": "pnpm turbo build --filter=...{./tools/cli}",
+  "entry": ["node", "tools/cli/dist/index.js"],
+  "env": { "MY_FLAG": "1" }
+}
+```
+
+- `build` — one shell command, run in the repo root before scenarios execute.
+- `entry` — the entrypoint argv; each scenario's command is appended to it. Repo-relative.
+- `env` *(optional)* — extra environment variables for every scenario run.
+
+It's discovered by the LLM **once**, on your first `guard generate`, and never touched again —
+**the file is yours to edit**: an existing `recipe.json` always wins, and it's committed so the
+whole team runs the same preparation. Edit it when the discovered command isn't what you want —
+for example, if your build tool's cache can serve stale output across branch switches, harden the
+build (`turbo build --force …`, or a clean step) at the cost of slower runs. Recipe edits change
+the recipe fingerprint, so the dashboard flags runs made under an older recipe.
+
 ## Commands
 
 ```bash
@@ -266,6 +301,7 @@ truecourse spec docs unexclude <path>             # Remove a force-exclude overr
 truecourse guard generate                         # Author scenarios from spec sections (classify → generate → birth-validate)
 truecourse guard run                              # Build via the recipe + run committed scenarios; exits non-zero on any drift (CI gate)
 truecourse guard run --scenario <id>              # Run a single scenario
+truecourse guard run --verbose                    # List every scenario result (one ✓ line per pass; default shows failures only)
 truecourse guard status                           # Compact summary: section coverage, last run, last generate (LLM-free, no re-run)
 truecourse guard drifts                           # List the latest run's non-pass scenarios, most severe first (paginated; --all / --offset / --json)
 ```