@turri-dev/cli 0.1.2 → 0.1.3-next.26f08c5

package/dist/spec-diff-cli.js

@@ -2,16 +2,25 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { checkPlainFile } from "./plain/check.js";
 import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.js";
-import { parseArgs, runLoop } from "./loop-cli.js";
+import { parseArgs } from "./cli-options.js";
+import { headlessOptions, runLoop } from "./loop-cli.js";
 const USAGE = `usage: turri spec-diff <file.plain> <diff-file> [options]
 
 Applies a change to the specs, given as a git diff of the .plain files, and builds it: the headless
 counterpart of regenerate, given a diff. The diff is applied first, unless it is already in; then, as
 turri regenerate does, what is left to build is planned into jobs and built.
 
-  --model <provider/id>    model for the agents (default: config.turri.yaml's coding-model)
-  --start-over             start over, without asking, a codebase regenerated without a module it now requires`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE);
+  --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner, the conformance chooser, a diagnosis
+  --coding-model <p/id>    its coding-model, --model too: the agents that build
+  --start-over             start over, without asking, a codebase regenerated without a module it now requires
+  --judge-model <p/id>     its judge-model: the judge and the test review
+  --review <true|false>    its review: whether the code and its tests are reviewed once they pass
+  --conformance-tests <all|chosen|module|false>
+                           its conformance-tests: which conformance tests are written and run
+  --build-dir <dir>        as the run ends, export the code there (see turri regenerate --help)
+  --report <file.json>     write a report of the run there (see turri regenerate --help)`;
+const { positional, options } = parseArgs(process.argv.slice(2), ["--start-over"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { report, buildDir } = headlessOptions(options, true);
 const [plainFile, diffFile] = positional;
 if (plainFile === undefined || diffFile === undefined) {
     console.error(USAGE);
@@ -28,9 +37,11 @@ if (!check.ok) {
 }
 runLoop({
     plainFile,
-    ...(options.model !== undefined ? { model: options.model } : {}),
     startOver: options["start-over"] !== undefined,
-    ask: (loop) => loop.bringUp(plainFile, options.model !== undefined ? { model: options.model } : {}),
+    ...(buildDir !== undefined ? { buildDir } : {}),
+    ...(report !== undefined ? { report } : {}),
+    command: ["spec-diff", ...process.argv.slice(2)],
+    ask: (loop) => loop.bringUp(plainFile),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);
     process.exit(1);

package/docs/config.md

@@ -5,7 +5,7 @@ is optional: with no file at all, turri finds the testing scripts on its own, tu
 tests on wherever a module has test reqs, and runs on pi's configured model. A project whose
 parts are on different stacks - a backend and a frontend - adds a file per stack,
 `config.turri.<stack>.yaml`, beside it, and chooses the stack to build with (see
-[stacks](#stacks)). turri never writes a `config.yaml`: it may be another tool's - codeplain's - and
+[stacks](#stacks)). turri never writes a `config.yaml`: it may be another tool's, and
 is read only by a project that has no file of turri's yet (see [the old config.yaml](#the-old-configyaml)).
 
 `turri init-config` starts one: the two models, a strong one to talk to and a smaller one to write the code. It
@@ -42,7 +42,7 @@ change one by changing it. The optional ones, which have no value of their own -
 skill that writes them), `module`, `conformance-budget`, `judge-model`, `models` - are there commented out, each with an
 example: uncomment one to use it. A key taken out of the file is still read as the table below says.
 
-Beside a `config.yaml` - codeplain's - the new file takes from it the keys turri reads too, each in its place, its
+Beside a `config.yaml` - another tool's, say - the new file takes from it the keys turri reads too, each in its place, its
 testing scripts above all, and says which it left (see [the old config.yaml](#the-old-configyaml)); `config.yaml`
 is left as it is. A `config.turri.yaml` already there keeps everything but its two models, which it sets - `--force` writes the whole
 file again - and a `config.yaml` turri read until then is copied to it first. It takes a folder other than the current
@@ -133,7 +133,7 @@ models:                              # each agent role's model, thinking and tur
 | `release-after-pulse` | `true` or `false`: whether every pulse that lands code releases it, in the chat, as its last stage - before the module's next pulse starts, whatever the chat is doing: an agent on the coding model looks for the project's release guidance as the chat does (what was passed to `release` this conversation, AGENTS.md, the project's skills) and, when it says to release after a build, does what it says - see [deploy](deploy.md#after-every-pulse). One release a pulse that lands; a release that fails is said in the pulse's report, and what it landed stays | `false` |
 | `unittests-script` | the unit testing script, by path from the project root - it runs the code's static checks too, exiting 80 when only they fail (see [the static checks](regenerating.md#the-static-checks)) | looked for - see below |
 | `conformance-tests-script` | the conformance testing script, by path from the project root | looked for - see below |
-| `prepare-environment-script` | optional, as codeplain has it: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
+| `prepare-environment-script` | optional: run as `<script> <build>` before every run of the conformance testing script, which runs only once it passes - see [the testing scripts](regenerating.md#the-testing-scripts). turri never writes one | the one `prepare_environment*.sh` at the root or in `test_scripts/`, else none |
 | `compact-at` | how many tokens of work - past its instructions - an agent kept through a job holds before the harness compacts it between turns; at least 1000; the project's alone | 100,000 - see [agent sessions](regenerating.md#agent-sessions) |
 | `max-specs-per-pulse` | the most functional specs the planner groups into one pulse - what builds one feature goes together, up to this many; a stack's file wins | 3 |
 | `max-lines-per-pulse` | the most lines of spec in one pulse - its functional specs with the definitions they bring; a group past it is split again, a functional spec a pulse; a stack's file wins | 120 |
@@ -145,7 +145,7 @@ models:                              # each agent role's model, thinking and tur
 | `testing-scripts-run-on` | what the testing scripts run on - always on this machine, in your environment. `in-place`: the real build and tests folders, the script at its own path, from the project - so a script that finds a host codebase from its own path finds it. `copy`: a fresh copy of the code, staged in `plain_modules/.turri/scripts/`, with the script copied beside it; it gives the coding agent `can_it_fail` (see [the testing scripts](regenerating.md#the-testing-scripts)) | `in-place` |
 
 Keys are written with dashes; underscores are read the same (`conformance_tests`). A key turri
-does not know is ignored - a codeplain `config.yaml`, read while it is the old file, carries several - and so is a value of the
+does not know is ignored - another tool's `config.yaml`, read while it is the old file, may carry several - and so is a value of the
 wrong type, as if it were not there. `model:`, from before there were separate models, is read as
 `coding-model`.
 
@@ -218,8 +218,13 @@ They are defaults. What is asked for wins over them:
 | model | wins over the config |
 | --- | --- |
 | harness | `turri --harness-model <m>` (or pi's own `--model`), and pi's `/model` in the conversation |
-| coding | `turri --coding-model <m>`, `engine` in the conversation, and `--model` / `--coding-model` on `turri regenerate`, `conform` and `spec-diff` |
-| judge | `--judge-model` on `turri conform` |
+| coding | `turri --coding-model <m>`, `engine` in the conversation |
+| judge | - |
+
+`turri regenerate`, `conform` and `spec-diff` read `--harness-model`, `--coding-model` (or `--model`),
+`--judge-model`, `--review` and `--conformance-tests` differently: as the keys themselves, as if the file had
+them. Each takes its key's value and its place in the order above - a `models:` entry still wins over it - so a
+headless run is the same as a chat with those keys in the file.
 
 A job keeps the model it was queued with: choosing another holds for what is queued after.
 
@@ -231,8 +236,8 @@ codebase are not run, and no agent is shown the conformance testing script. No k
 `false`: conformance tests are off by default. `all` (or `true`) means on wherever a module has
 `***test reqs***` - a module without them has nothing to write conformance tests from, so it writes
 none, but still keeps the codebase's existing ones passing. Asked in the
-conversation, or with `--conformance` / `--no-conformance` on the command line, a render does
-otherwise.
+conversation (`conform`), or with `--conformance-tests all|chosen|module|false` on `turri regenerate` and
+`spec-diff` - for that run, the file left as it is - a render does otherwise.
 
 `spawn` writes `conformance-tests: false` into a new project unless you ask for tests;
 `brood` asks, whatever the key says, offering what it says first.
@@ -346,8 +351,14 @@ The first time turri itself writes a setting there with `/turri-config`, it copi
 `config.turri.yaml` and each `config.<name>.yaml` to `config.turri.<name>.yaml` first, leaves the old
 files as they are, and from then on reads only the new ones. `turri init-config` copies the stacks'
 files the same way, but writes `config.turri.yaml` as its quick start, taking from `config.yaml` only
-the keys turri reads too - codeplain's `unittests-script`, `conformance-tests-script` and
+the keys turri reads too - `unittests-script`, `conformance-tests-script` and
 `prepare-environment-script`, say - each in its place in the file, and saying which keys it left:
-`template_dir`, `verbose`, `api`, codeplain's alone. The two models are the vendor's, never taken. To change a
+`template_dir`, `verbose`, `api`, the other tool's alone. The two models are the vendor's, never taken. To change a
 setting by hand in such a project, do the same: copy the files to their new names, and edit the
-copies - never `config.yaml`.
+copies - never `config.yaml`. Writing a `config.turri.yaml` of your own beside it is the same move: from then on
+`config.yaml` is not read, its testing scripts with it. For a headless run that only needs conformance tests or
+another judge, or review, those options leave the files alone: `--conformance-tests`, `--judge-model`, `--review true|false`, and the models' too.
+
+Keys turri does not read - another tool's `verbose`, `api-key`, `build-folder`, ... - are ignored without a word, and so
+is a value of the wrong type. A file that does not parse as YAML is read as empty, so its testing scripts are then
+looked for by name.

package/docs/development.md

@@ -18,6 +18,12 @@ which tests reach which mutant (`vitest.stryker.config.ts`, the suite without th
 mutant against those tests. `scripts/mutation.mjs` sets two things in Stryker's vitest runner the suite needs - forked
 workers, and a test-name filter that matches vitest 5's names - again after every `npm install`.
 
+The `mutation` workflow (`.github/workflows/mutation.yml`) runs it on GitHub, started by hand: Actions, mutation, Run
+workflow. It takes the parts to run, space-separated (empty for every part), each a job of its own side by side, on
+four cores (`TURRI_MUTATION_CONCURRENCY`; six here). Each part's `mutation.html` and `mutation.json` are uploaded as an
+artifact, `mutation-<part>`, and summed up on the run's page. Stryker's incremental file is cached from run to run, so
+a run tests again only the mutants whose code or tests changed; tick `fresh` to test every one again.
+
 Working on turri itself, `npm link` points the global `turri` at this clone, so edits
 take effect immediately. `npm run chat` starts pi with the extension loaded from `src/`.
 

package/docs/headless.md

@@ -14,7 +14,8 @@ Everything marked `✗` stops the run, so fix those first. Two more things matte
   a module's implementation reqs name that this machine lacks.
 - **The models.** In a project, `turri doctor` sends each model `config.turri.yaml` names one short request, as turri's
   agents will - so a key the provider refuses, a model pi does not know or an account without access to it shows now,
-  not an hour into the run.
+  not an hour into the run. Models the run is given on the command line are given to doctor the same way -
+  `--harness-model`, `--coding-model`, `--judge-model`, read as the config's keys - and are checked with the config's.
 - **Credentials that do not expire mid-run.** An API key in the environment
   (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...) or pi's saved login - whatever
   `doctor` shows as the model provider.
@@ -62,9 +63,14 @@ conformance-tests: true            # write and run conformance tests where there
 ```
 
 The same file names the [testing scripts](regenerating.md#the-testing-scripts); every key is in
-[the project config](config.md). Options on the command
-line win over it; `turri regenerate`, `spec-diff` and `conform` take its
-`coding-model` too, and `--coding-model` means the same as `--model` on every one of them.
+[the project config](config.md). `turri regenerate`, `spec-diff` and `conform` take five of its keys on
+the command line too - `--harness-model`, `--coding-model` (`--model` is the same), `--judge-model`,
+`--review` and, but for `conform`, `--conformance-tests`. Each is read as if the file had it, in its place:
+it takes that key's value, and every key keeps its place in the order the config resolves them in - a
+`models:` entry still wins over `harness-model`, `coding-model` or `judge-model`, the planner and the
+conformance chooser run on the harness model, the judge falls back on the coding model. So a run with
+the options is the same as one, or a chat, with those keys in `config.turri.yaml` - and a `config.yaml`
+the project has is left as it is.
 A project whose parts are on different stacks keeps each stack's settings in
 `config.turri.<stack>.yaml` beside it ([stacks](config.md#stacks)). Choose the one to build with
 `--stack <name>` - on any command: `regenerate`, `conform`, `spec-diff`, `glimpse`, `release`, `cultivate` -
@@ -75,29 +81,39 @@ Useful options - `turri regenerate --help` lists all of them:
 
 | | |
 | --- | --- |
-| `--model <provider/id>` | the model every agent runs on (`--coding-model` too), with `:level` for its thinking (`provider/id:high`); default, `config.turri.yaml`'s `coding-model`, then its `harness-model`, then pi's configured model |
-| `--judge-model <provider/id>` | `conformance`: the model of the judge and the test review; default, `config.turri.yaml`'s `judge-model`, then the coding model |
+| `--harness-model <provider/id>` | `harness-model`: the planner, the conformance chooser, the diagnosis of a failed pulse |
+| `--coding-model <provider/id>` | `coding-model` (`--model` too): the agents that build - with `:level` for how hard it thinks (`provider/id:high`); not given, the harness model's |
+| `--judge-model <provider/id>` | `judge-model`: the judge and the test review; not given, the coding model |
+| `--conformance-tests <all\|chosen\|module\|false>` | `conformance-tests`, with its values (`true` is `all`) |
+| `--review <true\|false>` | `review`: whether the code and its tests are reviewed once they pass |
 | `--stack <name>` | build with the stack's `config.turri.<name>.yaml` over `config.turri.yaml`; default, `TURRI_STACK`, else none |
-| `--to <frid>` | queue functionalities only up to this one |
-| `--only` | build just this module, not the ones it requires |
-| `--build-dir <dir>` | where the code goes; default `plain_modules/<module>/code` |
+| `--start-over` | start over, unasked, a codebase built without a module it now requires - without a terminal, a run that needs it and lacks it stops |
+| `--build-dir <dir>` | as the run ends, export the code there - see below |
+| `--report <file.json>` | write [the run report](#the-run-report) there |
+
+An option a command does not take is refused, not ignored.
 
 `turri regenerate` queues the jobs the chat's `regenerate` does - a spec diff that brings what
 is built in line, when it no longer matches the spec, then one render functionality job per
 functional spec not built, each with its conformance job - and runs them all to the end, the queue
 master reworking them as in the chat (see [a whole module](regenerating.md#a-whole-module)).
-Conformance tests follow `conformance-tests:` in `config.turri.yaml`.
+Conformance tests follow `conformance-tests:` in `config.turri.yaml`, or `--conformance-tests`.
 
 ## In the morning
 
-The command exits `0` only when every module is complete. The log says, per functionality, what
-was built and whether its tests passed; the last lines summarise each module.
+The command exits `0` only when every module is complete: its code regenerated from the spec as it is
+now, and its conformance tests written for what is built when they are on - no pulse failed, nothing
+halted, nothing waiting for a start over. Anything else exits `1`, and the last lines say which
+module is not complete, and why. The log says, per functionality, what was built and whether its
+tests passed.
 
 | | |
 | --- | --- |
 | `plain_modules/<module>/code/` | the code and unit tests |
 | `plain_modules/<module>/tests/` | the conformance tests |
 | `plain_modules/<module>/code/.turri.json` | the marshalled plain tree the code is built from |
+| `.turri/jobs/` | each pulse's log: its agents, its test runs, how it ended |
+| `.turri/debug/` | each agent's whole conversation |
 
 And what happened, step by step, in the module's history:
 
@@ -105,13 +121,112 @@ And what happened, step by step, in the module's history:
 git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module> log --stat
 ```
 
+### Where the code is
+
+A module that `requires` others is built in its own codebase on top of theirs: the code of
+`plain_modules/<module>/code` holds every module below it. `--build-dir <dir>` exports it as the run
+ends, however it ends - done, failed, stopped by a signal: the last commit of the furthest-built
+codebase of the chain, with the harness's own files (`.turri.json`, the notes) left out, so what is in
+it is only what landed, its unit tests passing. The folder's contents are replaced each time; a
+folder that holds the project, or one inside `plain_modules`, is refused. Point an external test
+suite at it.
+
+### The run report
+
+`--report <file.json>` writes one JSON summary of the run, for a benchmark or CI to read rather than
+the log. It is written as the run starts, again as each pulse ends, and last as the process exits -
+whether the run is done, a pulse failed, the provider failed, it crashed, or `SIGTERM` / `SIGINT` /
+`SIGHUP` stopped it. Only a process killed outright (`SIGKILL`) keeps the one written as its last pulse
+ended. Each write replaces the file whole (written beside it, then renamed), so a reader never sees
+half of one. Keys are snake_case, numbers are numbers, and `schema_version` changes only when a field
+changes meaning or goes; new fields may appear in the same version. Paths in `pulses`,
+`functionalities` and `logs` are relative to `project_dir`.
+
+```jsonc
+{
+  "schema_version": 1,
+  "turri": { "version": "0.1.1", "git_commit": "48dacfc…", "git_dirty": false },  // commit: null outside a clone
+  "command": ["regenerate", "app.plain", "--model", "…", "--report", "report.json"],
+  "spec_file": "/work/app.plain", "project_dir": "/work", "build_dir": "/work/out",  // build_dir: null without one
+  "conformance_tests": "all",                                                       // all | chosen | module | false
+  "review": false,
+  "models": {
+    "harness": { "model": "…", "thinking": "medium" },  // the planner, the chooser, the diagnosis
+    "coding":  { "model": "…", "thinking": "low" },
+    "judge":   { "model": "…", "thinking": "medium" },
+    "observed": { "coding": ["provider/id:low"], "planner": ["provider/id:medium"] }  // what each role really ran on
+  },
+  "started_at": "…", "finished_at": "…", "duration_seconds": 4351.4,
+  "outcome": {
+    "status": "completed",  // completed | incomplete | failed | interrupted | crashed | running (written mid-run)
+    "exit_code": 0, "signal": null, "error": null,
+    "modules": [{ "module": "app", "state": "complete" }]  // complete | incomplete | halted | start_over_needed | running, with "why"
+  },
+  "usage": {
+    "total": {
+      "input_tokens": 0, "output_tokens": 0, "cache_read_tokens": 0, "cache_write_tokens": 0, "cost_usd": 0,
+      "llm_calls": 0, "agent_turns": 0, "compactions": 0, "model_seconds": 0
+    },
+    "in_pulses": { },       // the pulses' usage added up - the same fields
+    "outside_pulses": { },  // the planner, the conformance chooser, a failed pulse's diagnosis
+    "by_model": { "provider/id:low": { } },
+    "by_role": { "coding": { }, "reviewer": { }, "planner": { } },
+    "by_pulse_kind": { "code": { }, "conformance": { } }
+  },
+  "pulses": {
+    "counts": { "total": 7, "landed": 5, "failed": 1, "stopped": 0, "rolled_back": 2, "running": 0, "not_started": 0 },
+    "list": [{
+      "id": "2a058729", "module": "app", "number": 1, "kind": "code", "title": "…",
+      "status": "succeeded", "landed": true, "failed_for_good": false,
+      "started_at": "…", "duration_seconds": 512.3, "usage": { },
+      "agents": [{ "label": "app 1 coding agent", "model": "…", "turns": 14, "compactions": 0, "input_tokens": 0, "…": 0 }],
+      "log_file": ".turri/jobs/….log", "error": null
+    }]
+  },
+  "functionalities": {
+    "total": { "specified": 12, "completed": 10, "conformance_tested": 8 },
+    "modules": [
+      { "module": "base", "specified": 4, "completed": 4, "conformance_tested": 4, "incomplete_frids": [] },
+      { "module": "app", "specified": 8, "completed": 6, "conformance_tested": 4, "incomplete_frids": ["7", "8"] }
+    ],
+    "codebases": ["plain_modules/app/code"]
+  },
+  "build_dir_export": { "exported": true, "dir": "/work/out", "module": "app", "commit": "8036b3b", "files": 23 },
+  "logs": { "jobs_dir": ".turri/jobs", "debug_dir": ".turri/debug", "sessions_dir": ".turri/sessions" }
+}
+```
+
+**Usage.** Every model response an agent gets counts, in a pulse or not. `total` is `in_pulses` plus
+`outside_pulses`, and `in_pulses` is the pulses' own usage added up - the figures their lines in the
+notes and the pulse logs print - so the totals can be checked by hand against them. `llm_calls` counts
+model responses, a compaction's included; `agent_turns` the harness's requests to an agent, each as
+many responses as it takes; `model_seconds` the time from each request to its response's end, added
+up - several agents working at once each count theirs, so it can exceed the run's duration. Tokens and
+cost are as the provider reports them to pi. `by_model`, `by_role` and `by_pulse_kind` split the same
+calls; a role or model turri could not tell is `unknown`.
+
+**Pulses.** `landed`: its work is committed. `rolled_back`: it ended without landing - failed,
+stopped, or did not pass - and everything it wrote was undone. A pulse that failed is tried once more
+before it counts as failed; both tries are the one pulse.
+
+**Completed functional specs** - the pass rate, the figure to compare runs by.
+A functional spec is completed when the code record of the codebase the run delivers - the
+furthest-built of the chain, the one `--build-dir` exports - as last committed, holds it as the spec has
+it now: the same text, every file it links holding the same, no definition it uses changed, and not
+marked to regenerate again. A record moves only when a pulse lands, and a pulse lands only once the
+code's unit tests pass (its conformance tests too, when they are on), so completed means landed and
+passing. Each module counts its own functional specs: a module below the tip counts from what the
+tip's code was built on, and a module above the delivered codebase has none completed.
+`conformance_tested` is those of the completed ones whose conformance tests are recorded as written
+for them as they are now (`plain_modules/<module>/tests/.turri.json`).
+
 ## If it stopped
 
 Run the same command again. Functionalities already built from the current spec are left alone,
 and modules that are complete are skipped, so it picks up where it stopped - after a crash, a
 provider outage, or a machine that went to sleep anyway. Whatever the stopped run left
 half-written is undone first: each step starts from the module's last commit. A functionality whose spec has changed
-since counts as not built, so editing the spec and re-running rebuilds what changed. `--force`
+since counts as not built, so editing the spec and re-running rebuilds what changed. `--from-scratch`
 rebuilds everything.
 
 ## Rebuilding one functionality
@@ -125,14 +240,53 @@ it is - without rebuilding the ones before it. To change what it does, change it
 spec is what the code is built from, and a change made there lasts. Then it updates the
 functionality's conformance tests and runs every conformance test in the codebase, since a change can break something built
 later as easily as something built earlier. It works in the codebase the functionality now lives
-in: when later modules are built on top of this one, the furthest-built of them (`--in <module>`
-picks one when there are several). It exits `0` when everything passes, and refuses when there is
-no code yet - build it with `module` first.
+in: when later modules are built on top of this one, the furthest-built of them. It exits `0` when
+everything passes, and refuses when there is no code yet - regenerate the module first.
 
 Several changes do not need one command each: after editing the spec, re-running `turri regenerate`
 brings the code up to it - one spec diff for what changed in what is built, then the functional
 specs not built yet.
 
+## In a container
+
+A benchmark or CI task runs it with no terminal and nothing to ask, so give it everything up front:
+
+```bash
+turri regenerate app.plain --harness-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+  --coding-model amazon-bedrock/eu.anthropic.claude-sonnet-5-5 \
+  --conformance-tests all --review false --judge-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+  --start-over --build-dir /out/build --report /out/report.json < /dev/null
+```
+
+- **What it needs:** Node 22.19 or newer, `bash`, `git` (each module's history, and the spec diffs
+  the work is planned from), `/bin/sh` with `kill` and `sleep`, a writable `HOME` (pi keeps
+  `~/.pi/agent/auth.json` there, even with no login - or set `PI_CODING_AGENT_DIR`) and `TMPDIR`, and
+  the toolchains the project's testing scripts and implementation reqs name. `turri doctor` in the project, given
+  the run's models, checks them all and that each model answers - at the start of the task's log, not when a pulse
+  fails:
+
+  ```bash
+  turri doctor --harness-model amazon-bedrock/eu.anthropic.claude-opus-5-5 \
+    --coding-model amazon-bedrock/eu.anthropic.claude-sonnet-5-5 --judge-model amazon-bedrock/eu.anthropic.claude-opus-5-5
+  ```
+
+  It exits 1 on anything marked `✗`.
+- **Without bubblewrap:** a container that cannot make user namespaces - no
+  `--security-opt seccomp=unconfined` - has no OS sandbox. turri runs anyway, the command check and the
+  audit holding alone under the agents' commands; `turri doctor` shows it as `!`, not `✗`. Installing
+  the `bubblewrap` package is worth it where it can start.
+- **As another user:** run it as the user who will own `plain_modules/`. git refuses a repository
+  another user made (`dubious ownership`), so do not let root create it first.
+- **Amazon Bedrock:** `AWS_BEARER_TOKEN_BEDROCK` (or the usual AWS credentials) and `AWS_REGION` are
+  enough - no pi login. An `eu.` inference profile needs an EU region. A model id pi does not know
+  stops the first pulse; `turri --list-models bedrock` lists the ones it does.
+- **A project with only a `config.yaml`:** it is read while there is no `config.turri*.yaml` -
+  `unittests-script`, `conformance-tests-script` and `prepare-environment-script` included, relative to
+  the project; the keys turri does not know are ignored. Do not write a `config.turri.yaml` beside it to
+  turn on conformance tests or review: from then on `config.yaml` is not read. The options above do it instead.
+- **Long test suites:** a testing script run is stopped after 120 seconds; set `TURRI_COMMAND_TIMEOUT`
+  (seconds) for more.
+
 ## Asking in words instead
 
 pi's print mode runs one request and exits, with the render tools waiting for their work rather

package/docs/installation.md

@@ -68,7 +68,7 @@ In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `
 | --- | --- |
 | each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH: the agents use this machine's toolchains and install none, so a missing one is yours to install |
 | the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
-| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--no-models` skips it |
+| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--harness-model`, `--coding-model` (`--model`) and `--judge-model` name models as the config's keys, as `turri regenerate` reads them - checked in a project or not. `--no-models` skips it |
 
 Removing that file is the one thing `doctor` changes, and it asks first; `turri doctor --yes` says yes. Run without a
 terminal - piped, or in CI - it asks nothing and changes nothing. Run it again whenever something breaks;

package/docs/parser.md

@@ -9,7 +9,7 @@
 | `src/plain/spec.ts` | `plain_spec.py` - functionality ids, the per-functionality context, linked resources, ranges |
 | `src/plain/concepts.ts` | `concept_utils.py` - concept extraction, validation, topological ordering |
 | `src/plain/markdown.ts` | mistletoe's AST + `PlainRenderer` (mdast + a matching serializer) |
-| `src/plain/liquid.ts` | `plain2code_nodes.py` + the two filters in `plain_spec.py` (liquidjs) |
+| `src/plain/liquid.ts` | the reference implementation's Liquid nodes + the two filters in `plain_spec.py` (liquidjs) |
 | `src/plain/files.ts` | `file_utils.open_from` / `get_loaded_templates`, base64 blob detection |
 | `src/plain/stdlib.ts` | nothing - turri's own: `stdlib/` is a reserved import prefix, read from turri's standard library only, and a project module at such a path is an error (see [the standard library](authoring-plain.md#the-standard-library)) |
 

package/docs/regenerating.md

@@ -495,7 +495,7 @@ scripts are not linked from the specs; a link to one is ignored.
 They are required: a build with no unit testing script, or with conformance on and no conformance
 testing script, stops before it starts and says which skill adds it.
 
-**The prepare script** is codeplain's, and optional: turri never writes one, and runs one the project has -
+**The prepare script** is optional: turri never writes one, and runs one the project has -
 `prepare-environment-script:` in the config, else the one `prepare_environment*.sh` at the root, else in
 `test_scripts/` - on the build, before every run of the conformance testing script: the harness's own, and the agents'
 `run_conformance_tests`. Both get the same build folder - the code in place, or the same fresh copy - so what it sets up
@@ -685,7 +685,7 @@ change to the code brings that module's code in, so the codebase stops: it has t
 and conformance tests taken out, committed so its history keeps them, and the chain built again from the
 bottom. That is never done unasked. In the chat the model asks the person, saying why, and calls
 `regenerate` with `from_scratch` once they agree; `turri regenerate` and `spec-diff` ask at the terminal, and
-`--start-over` agrees in advance - with no terminal and no flag, nothing more is built there.
+`--start-over` agrees in advance - with no terminal and no flag, the run stops there, exit 1, saying so.
 
 ## Conformance tests
 

package/docs/using.md

@@ -13,8 +13,10 @@ banner - the jellyfish it is named after, swimming until the conversation fills
 terminal that shows images (Kitty, Ghostty, WezTerm, Warp, iTerm2), and drawn in text in any other, tmux
 included - swimming a stroke a loop, its tentacles following its bell, frames `scripts/jellyfish-frames.mjs`
 writes -
-where commands will run, the rules and skills loaded - rather than pi's startup header
-and resource list; `turri --verbose` shows those too. Talk to it: ask it to start a
+turri's version (and, run from a clone, the commit it is on, and whether the clone has changes), where commands
+will run, the rules and skills loaded - rather than pi's startup header and resource list; `turri --verbose` shows
+those too. pi's "Update Available" notice is left out - turri's pi is a pinned dependency `pi update` never
+touches - and the terminal's tab reads `🪼 turri - <folder>`, not pi's `π`. Talk to it: ask it to start a
 project, add a feature, render a module, fix a spec. It decides which skill or tool applies - but
 not *how* a skill runs: `cultivate` hands the work to the gated runner, which owns the steps, the
 gates and the judges (see [skills and gates](skills-and-gates.md)).

package/genome/skills/implement-conformance-testing-script/SKILL.md

@@ -36,7 +36,7 @@ bash run_conformance_tests_<lang>.sh <build_folder> <conformance_tests_folder>
 
 Both arguments are absolute paths: `<build_folder>` is the module's generated code (`plain_modules/<module>/code`), and `<conformance_tests_folder>` is the folder holding the whole suite. The harness runs the script on the person's machine - macOS, Linux or WSL, with its toolchains, in the person's own environment - and its exit code alone decides whether the conformance tests pass.
 
-Every conformance script is self-contained: toolchain check, argument validation, stage the build into `<temp>/<lang>_<basename of $1>`, install dependencies there in isolation, check the tests in `$2` statically, run the suite in `$2` against it, clean up on exit. Nothing is prepared ahead of time by another script - unless the project already has a `prepare_environment*.sh` (codeplain's prepare script, or one `prepare-environment-script:` names): turri runs it on the same build before every run of the conformance script, so keep it, and let the conformance script rely on what it sets up rather than doing it again. Never write a prepare script yourself.
+Every conformance script is self-contained: toolchain check, argument validation, stage the build into `<temp>/<lang>_<basename of $1>`, install dependencies there in isolation, check the tests in `$2` statically, run the suite in `$2` against it, clean up on exit. Nothing is prepared ahead of time by another script - unless the project already has a `prepare_environment*.sh` (a prepare script the project brought, or one `prepare-environment-script:` names): turri runs it on the same build before every run of the conformance script, so keep it, and let the conformance script rely on what it sets up rather than doing it again. Never write a prepare script yourself.
 
 ## How conformance scripts differ from unit-test scripts
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.2",
+  "version": "0.1.3-next.26f08c5",
   "license": "MIT",
   "type": "module",
   "repository": {