truecourse 0.6.0 → 0.6.6-next.0

package/README.md

@@ -323,7 +323,31 @@ The first `truecourse analyze` (or `truecourse add`) in a fresh repo asks whethe
 ## Prerequisites
 
 - Node.js >= 20
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI on your PATH. Deterministic rules run without it; LLM-powered rules and the Spec → Verify pipeline need it.
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI on your PATH — optional. The default `cli` transport spawns it for LLM-powered work; deterministic rules and the `agent` transport (below) don't need it.
+
+## LLM transport (`--llm-transport`)
+
+Every LLM-powered step — `analyze`'s LLM rules, and the whole Spec → Verify pipeline (`spec scan`, `spec resolve`, `contracts generate`) — reaches the model through a pluggable **transport**, chosen with `--llm-transport`:
+
+| Mode | How it reaches the model | Needs |
+|---|---|---|
+| **`cli`** *(default)* | spawns `claude -p …` per call | the `claude` binary on PATH, signed in. No API key. |
+| **`agent`** | a **filesystem mailbox** under `--io <dir>` | nothing — no `claude` binary, no API key |
+
+In **`agent`** mode the tool doesn't call the model itself: for each prompt it writes `requests/<id>.json` (`{ stage, system, user, schema, … }`) into the `--io` directory and waits for a matching `responses/<id>.json` (`{ text }`). An **orchestrating agent that is itself an LLM** — e.g. a [Claude Code routine](https://code.claude.com/docs/en/routines) — watches that directory and answers each prompt. This lets contract generation and `analyze`'s LLM rules run **inside a headless cloud session with no `claude` binary and no API key**.
+
+```bash
+# default: spawn the claude CLI
+truecourse analyze --llm
+truecourse contracts generate
+
+# agent transport: the tool parks prompts in ./io and an external agent answers them
+truecourse analyze --llm --llm-transport agent --io ./io
+truecourse spec scan          --llm-transport agent --io ./io
+truecourse contracts generate --llm-transport agent --io ./io
+```
+
+Accepted by: `analyze`, `spec scan`, `spec resolve`, `contracts generate`. (On `analyze`, `--llm` / `--no-llm` is a *separate* flag — it decides **whether** LLM rules run; `--llm-transport` decides **how** to reach the model.) Both modes send identical prompts and parse identical schema-validated JSON — only the delivery differs.
 
 ## Configuration
 
@@ -332,13 +356,15 @@ TrueCourse talks to Claude Code via the `claude` CLI. You can tune how that inte
 For packaged installs (`npx truecourse` or `npm install -g truecourse`), the simplest place to set them is `~/.truecourse/.env`. The file is loaded automatically on every invocation:
 
 ```
-CLAUDE_CODE_BINARY=claude             # override the `claude` binary on PATH
+CLAUDE_CODE_BINARY=claude             # override the `claude` binary on PATH (CLAUDE_CODE_BIN also accepted)
 CLAUDE_CODE_MODEL=                    # Claude Code --model flag (empty = default)
 CLAUDE_CODE_TIMEOUT_MS=120000         # per-call timeout (ms)
 CLAUDE_CODE_MAX_RETRIES=2             # retry attempts on parse/validation failure
 CLAUDE_CODE_MAX_CONCURRENCY=10        # max concurrent `claude` processes per run
 ```
 
+Every command that uses Claude (`analyze` with LLM rules, `spec scan`, `spec resolve`, `contracts generate`) runs a quick up-front preflight: it makes one tiny `claude` call to confirm the CLI is installed and logged in, and aborts with the CLI's own error message if not — so an expired login is caught immediately instead of failing every extraction subprocess at the end of a long run. `CLAUDE_CODE_BINARY` is the canonical way to point at a non-default binary; `CLAUDE_CODE_BIN` is honored as a legacy alias.
+
 **`CLAUDE_CODE_MAX_CONCURRENCY`** caps how many Claude CLI processes TrueCourse spawns in parallel during a single run. Default `10`. Raise it on CI runners with spare headroom; lower it on resource-constrained machines (e.g. 8 GB laptops, shared VMs) to avoid OOM on large repos. Must be a positive integer.
 
 For a one-off override, prefix the command: