@turri-dev/cli 0.0.0-stage → 0.1.1

package/docs/authoring-plain.md

@@ -0,0 +1,245 @@
+# Authoring \*\*\*plain
+
+Rendering turns a spec into code; authoring is the half that decides what gets built. The code is
+only ever as good as the spec - a fact in the wrong section is silently ignored, a functional spec
+that is too big comes out half-built, two specs that contradict each other break each other's
+tests. So this repo carries as much for writing specs as for rendering them: the authoring rules,
+a library of skills that apply them, and independent review of what they write.
+
+The rule underneath all of it: **the specs are the source of truth**. The generated code in
+`plain_modules/` is never edited by hand. A bug is fixed in the spec, and a change that is wanted
+goes into the spec - that is what persists and what the next render builds from.
+
+## A \*\*\*plain project
+
+```
+my-project/
+  app.plain            # a root module: what the software does
+  users.plain          # another module, perhaps one that `requires` app
+  template/            # import modules: shared definitions and reqs
+  resources/           # files specs link to: schemas, API specs, sample data
+  test_scripts/        # scripts that run the unit and conformance tests
+  plain_modules/       # generated - code, tests, history; never edited by hand
+```
+
+## What a spec is made of
+
+A `.plain` file is one module: optional YAML frontmatter, then up to four sections, in this order.
+
+| section | holds | e.g. |
+| --- | --- | --- |
+| `***definitions***` | the concepts, written `:CamelCase:` - every concept is defined before it is used | `- :Task: is a unit of work with a title and a due date.` |
+| `***implementation reqs***` | HOW it is built: stack, architecture, coding standards, and everything about unit tests | `- :Implementation: is written in Python 3.12.` |
+| `***test reqs***` | everything about the black-box conformance tests: framework, how they run, mocking | `- :ConformanceTests: use pytest and call the CLI as a subprocess.` |
+| `***functional specs***` | WHAT it does - observable, language-agnostic behaviour, one functionality per item, in the order they are built | `- A :User: can add a :Task:.` |
+
+Under a functional spec, a nested `***acceptance tests***` list states how that one
+functionality is checked end to end.
+
+The frontmatter connects modules:
+
+| field | |
+| --- | --- |
+| `description` | one line on what the module is |
+| `import` | take the definitions, implementation reqs and test reqs of an import module - shared content, no functional specs of its own |
+| `requires` | build on top of another module: its functional specs and its generated code come first |
+| `exported_concepts` | which concepts a module that `requires` this one may use |
+| `required_concepts` | concepts an import module expects the importing module to define |
+
+Beyond that: a spec links to files under `resources/` with markdown link syntax, and the file's
+contents go to the renderer with the spec; lines starting with `>` are comments for people; and
+files are processed with Liquid first, so a template can be included with parameters.
+
+**Section ownership is the rule that bites.** The renderer reads each kind of fact only from the
+section that owns it. A tech choice written into a functional spec, or a behaviour written into
+the implementation reqs, is not flagged - it is simply not read.
+
+## The standard library
+
+turri ships a standard library of import modules in `stdlib/` that settle everything about a
+generic piece of software on one stack except what it does: its language and framework, layout,
+configuration, error handling, logging, shutdown, and how it is unit and conformance tested. A spec
+imports one and writes only its own concepts and functional specs:
+
+```plain
+---
+import:
+  - stdlib/backend/python-flask
+  - stdlib/backend/conformance/python-flask    # leave it out to skip conformance tests
+---
+
+***functional specs***
+
+- ...
+```
+
+| kind | stacks - each with `stdlib/<kind>/conformance/<stack>` beside it |
+| --- | --- |
+| `stdlib/backend/` | `python-fastapi`, `python-flask`, `python-django`, `typescript-express`, `typescript-fastify`, `typescript-nestjs`, `java-springboot`, `go-nethttp`, `go-gin`, `rust-axum` |
+| `stdlib/frontend/` | `react-vite`, `vue-vite`, `sveltekit-spa`, `angular` |
+| `stdlib/cli/` | `python-typer`, `python-click`, `python-argparse`, `typescript-commander`, `go-cobra`, `go-flag`, `rust-clap`, `java-picocli` |
+| `stdlib/library/` | `python`, `typescript`, `java-maven`, `java-gradle`, `go`, `rust` |
+
+It is built in three layers, and a stack imports the other two:
+
+- **The language** - `stdlib/lang/python`, `typescript`, `java`, `go`, `rust`: the version, the
+  dependency manager, formatting, linting and type checking (ruff and mypy for Python; Prettier, ESLint
+  and `tsc --noEmit` for TypeScript), how a failure is reported (an exception, a returned error, a
+  `Result`), the logging library, and the unit test framework and layout. A module on a stack the library does not have can import its language alone.
+  The formatter, linter and type checker a language names are enforced by the testing scripts, which
+  run them with the tests - the unit testing script on the code, the conformance testing script on the
+  tests - and count them as the tests (see [the static checks](regenerating.md#the-static-checks)).
+- **The kind's `common`** - what every stack of a kind shares:
+
+  | kind | settles |
+  | --- | --- |
+  | backend | settings from the environment into one typed object, checked at start (exit 1 when one is missing); handler, service and repository layers; domain errors turned in one place into `{"error": {"code", "message"}}` - `not_found` 404, `conflict` 409, `validation_error` 422 with `details` per field, `unauthenticated` 401, `forbidden` 403, `internal_error` 500 with no message and the stack trace logged; JSON logs on standard output with `timestamp`, `level`, `logger`, `message` and `request_id`, level from `LOG_LEVEL`, one line per request, never a secret or a body; `X-Request-ID` taken or made and sent back; shutdown on SIGTERM within 10 seconds |
+  | frontend | one API layer that turns a failed call into an `ApiError` with the backend's error code, or `network_error`; errors shown in place, and a page for anything else at the root; one logger module, no `console` elsewhere; accessible roles and test ids |
+  | cli | settings from flags, then `<TOOL>_<SETTING>`, then defaults; the work apart from parsing; errors as `Error: <message>` on standard error, exit 0, 1, 2 for a usage error, 130 on Ctrl-C, a stack trace only with `--debug`; logs on standard error, warnings by default, `--verbose`, `--debug` |
+  | library | one public entry point; one base error type, with a dependency's errors wrapped; logs through the language's logging with no output set up; no environment variables, output or global state |
+
+- **The stack** - the framework and how it does each of those: for `python-flask`, an application
+  factory, one Blueprint per resource, Pydantic for bodies, `@app.errorhandler` for the error body,
+  structlog JSON logs with the request id bound in a hook, Gunicorn. For `go-cobra`, `RunE`
+  commands with Cobra's own error printing off, so `main` alone writes the error and picks the exit
+  code, and slog on standard error.
+
+Each conformance template imports its kind's `conformance/common`: a backend's tests start the
+built service on a free port and reach it over HTTP only, checking a failure by status and
+`error.code`; a frontend's run the served build in Chromium through Playwright with the backend
+stood in; a command-line tool's run the built tool as a process; a library's go through its public
+entry point.
+
+- **Conformance tests apart.** A spec without the conformance template has no test reqs, so no
+  conformance tests are written or run for it. Turning them on later is adding that one import.
+- **A reserved name.** An import that starts with `stdlib/` is always turri's template, never
+  a file of the project's. A project with a module at such a path - `stdlib/backend/python-fastapi.plain`
+  beside the spec, in its `template/` folder or in `PLAIN_TEMPLATE_DIRS` - gets an error saying the
+  name is reserved, so which one a spec builds on never depends on what is on disk beside it.
+- **No concepts.** Its requirements are on the predefined `:Implementation:`, `:UnitTests:` and
+  `:ConformanceTests:` only, so it never collides with a spec's own definitions.
+- **Pinned to a toolchain.** It names its stack's toolchain - Python 3.12, Node.js 24, Java 21, Go 1.25, Rust -
+  which the agents use from this machine; `turri doctor` says when the machine lacks it.
+- **Not storage, not the testing scripts.** A module with a database says which on top of its
+  stack. It still needs its unit testing script, and a conformance testing script when it has
+  conformance tests.
+- **Known to the agents.** The `stdlib` rule, in every spec-writing agent's system prompt, says when
+  to import which, and lists every template with what it is and the folder it is in, read from
+  `stdlib/` when the rules load. `spawn` and `brood` import a stack when the one chosen
+  is in it, and its conformance template when conformance tests are on.
+- **Only what this machine can build.** The agents use this machine's toolchains and install none, so
+  a Go stack on a laptop without Go stops at its first build. Every spec-writing agent and the
+  conversation are told which of the standard library's languages the machine can build now - Python
+  needs `uv`, TypeScript and every frontend `node` and `npm`, Go `go`, Rust `cargo`, Java a JDK
+  (`src/stack.ts`, `toolchainsBlock`) - and `spawn` and `brood` offer, and choose, only stacks in those.
+  A stack the person names in a language the machine lacks is not refused: they are told what to install
+  first, and that `turri doctor` checks it.
+
+A requirement beyond the stack - storage, an outside service - is added on top of it. A module that
+differs from its stack on something the stack settles - another framework, another layout - writes
+its own instead: an import cannot be taken back in part.
+
+## The rules
+
+`genome/rules/` holds the authoring rules. They are in the system prompt of every agent that
+writes specs - the conversation, the interview skills, the reviewers - so they are not something
+an agent has to decide to go and read.
+
+| rule | covers |
+| --- | --- |
+| `module-structure.md` | the file skeleton, frontmatter fields, section order, module kinds, section ownership |
+| `definitions.md` | concept syntax, predefined concepts, define before use, no circular definitions, granularity |
+| `func-specs.md` | voice, the complexity limit, chronological order, no conflicts, language agnosticism, testability, acceptance tests |
+| `impl-reqs.md` | HOW not WHAT, unit tests live here, what belongs and what does not |
+| `test-reqs.md` | conformance tests only, what belongs, test types |
+| `concise-specs.md` (+ two example banks) | keeping specs short enough for a person to review: no obvious lines, plain words, no uncheckable adjectives, no hedging |
+| `bullet-continuation.md` | bullets and continuation lines in every section |
+| `linked-resources.md` | a linked resource is one text file on disk, or a PNG or JPEG image for a model that reads images; protocol artifacts are linked, never transcribed |
+| `import-modules.md`, `requires-modules.md` | the two ways modules build on each other |
+| `exported-concepts.md`, `required-concepts.md` | which concepts cross module boundaries |
+| `integrations.md` (+ standalone, embedded, embedded testing) | specs for REST API integrations, deployed standalone or embedded in an existing codebase |
+| `stdlib.md` | the standard library: when to import which template, and every template with what it is and where it is, read from `stdlib/` |
+
+The ones that shape a spec most:
+
+- **One functionality is at most ~200 lines of code.** A bigger one is split before it is written
+  (`analyze-if-func-spec-too-complex`, `break-down-func-spec`).
+- **Functional specs are in build order.** Each is rendered on top of the ones before it.
+- **They state facts, with a concrete subject.** "A :User: can add a :Task:" - not "Implement
+  adding tasks", not "The system should…".
+- **Nothing a test cannot check.** No `robust`, `seamless`, `as appropriate`; state the checkable
+  fact or cut the word.
+- **No two specs contradict each other.** A conflict is found and resolved when a spec is added,
+  not when its tests fail.
+
+## Writing specs with turri
+
+In a conversation (`turri`), say what you want and the matching skill runs. Two build a
+project from scratch, and write each spec change as a git diff that is built in the background the
+moment it is written. `brood` interviews you one question at a time and writes the specs as
+you answer; `spawn`, its quick twin, asks only what you want to build and which stack - or leaves the stack
+to it - and writes the rest on its own:
+
+| skill | phases | how a spec change is written |
+| --- | --- | --- |
+| `brood` | intent → stack → testing → product, feature by feature | first, how many questions the stack and product phases may ask - light 3, medium 5, thorough 10 or best judgement, broader with fewer, covering the same ground - and what they leave open turri decides itself, each decision a spec change of its own; every product answer is still a spec change, built before the next question; in testing, whether there are conformance tests, their `***test reqs***` and script - written as files, building nothing; then one spec change per answer, across whatever sections it needs, as a git diff with `write_spec_diff`, rendered as a render spec diff job and conformance tested as it is built |
+| `spawn` | intent → groundwork → product | only the intent and the stack are asked - the stack one question, `You choose` first, skipped when the user named one; the stack and the unit tests are written as files, with conformance tests off unless the user asks for them; then one spec change per feature, in build order, as a git diff with `write_spec_diff`, one after another with no answer between them. Changes after it are asked for in the conversation, as spec diffs, and what is left to build is worked out again from the spec |
+
+`mature` starts from a spec you already have, rough or hand-written, and runs on its own until
+it is fully rendered - every functionality built from the spec as it stands, its tests passing. It
+renders what is not built and watches the agents building it; when one struggles on something the
+spec leaves open or unclear - sent back again and again, the judge going back and forth, a spec
+conflict - it writes what the spec should say as a spec diff, stops that build, and renders it again.
+What the builds had to decide themselves - their assumptions, pitfalls, a failed build's diagnosis -
+goes into the spec the same way, when a user, a caller or a test can see it. It never asks: it takes
+the reading that fits the rest of the spec, and marks each such decision in its report. It leaves
+code, environment and turri problems to the builds, and stops when a functionality keeps
+struggling after the spec was clarified, when two cycles change nothing, or after twenty.
+
+For an existing project, `bud` works the same way, scoped to one feature: intent → scope →
+product → review. After a short feature-intent interview it asks product questions one at a time -
+a trigger and its outcome, an edge case, a rule - and every answer is one spec change, a git diff
+written with `write_spec_diff` and built the moment it is written. A change to something already
+specified, built or still to build, is put to the user first and is a spec diff too: what is left to
+build is worked out again from the spec.
+
+What keeps the interview honest is the harness, not the interviewer:
+
+- **Every question offers choices** (`ask_user` refuses a question without them), and each
+  answer maps to one spec change.
+- **Every answer is written before the next question.** In `brood`'s product phase `ask_user` refuses
+  a new question until the last answer is a spec change - see [skills and gates](skills-and-gates.md).
+- **Each phase ends on the person's confirmation** of a short summary, not on the interviewer's word.
+
+## The skills
+
+Every skill in `genome/skills/` can be run from a conversation; most are also used by the bigger ones. A project's own,
+in `.turri/skills/` or `.agents/skills/`, can be too (see [skills and gates](skills-and-gates.md#a-projects-own-skills)).
+
+| to… | skills |
+| --- | --- |
+| start a project | `brood`, `spawn`, `init-plain-project` |
+| make a rough spec build | `mature` |
+| add to a spec | `bud`, `add-functional-spec`, `add-functional-specs`, `add-concept`, `add-implementation-requirement`, `add-test-requirement`, `add-acceptance-test`, `add-resource`, `add-template` |
+| check what is written | `analyze-if-func-spec-too-complex`, `analyze-2-func-specs`, `analyze-func-specs`, `resolve-section-ownership` |
+| fix what is written | `break-down-func-spec`, `resolve-spec-conflict`, `debug-specs` |
+| restructure modules | `create-import-module`, `create-requires-module`, `refactor-module`, `consolidate-concepts` |
+| set up the project to build | `implement-unit-testing-script`, `implement-conformance-testing-script`, `check-plain-env` |
+
+`debug-specs` is the one for a running application that misbehaves: it reads the generated code
+to find the cause, traces it back to the spec, and fixes only the `.plain` files.
+
+## Checking a spec
+
+```bash
+turri validate app.plain     # or validate in a conversation
+```
+
+It parses the spec with this repo's own parser, resolves its imports and required modules, and
+reports every syntax, concept and structure error with its line - no model, no API key. The
+interview skills run it before a phase ends, and `write_spec_diff`
+refuses a change that leaves a file that does not parse. Pass the project directory to check every
+module at once.
+
+What `check` cannot see - a fact in the wrong section, a spec that is too big, two that conflict,
+wording no test can check - is what the rules, the skills and the reviewers are for.

package/docs/config.md

@@ -0,0 +1,353 @@
+# The project config
+
+A project says how its specs are built in `config.turri.yaml`, at the project root. Everything in it
+is optional: with no file at all, turri finds the testing scripts on its own, turns conformance
+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
+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
+asks which vendor's models you use - `--vendor` says it without asking, and with neither, as from a script, it is
+`other`:
+
+| vendor | harness-model | coding-model | key pi reads |
+| --- | --- | --- | --- |
+| `anthropic` | `anthropic/claude-opus-5-5` | `anthropic/claude-haiku-5-5` | `ANTHROPIC_API_KEY` |
+| `openai` | `openai/gpt-6-astra` | `openai/gpt-6-luna` | `OPENAI_API_KEY` |
+| `google` | `google/gemini-3.1-pro-preview` | `google/gemini-3.1-flash-lite` | `GEMINI_API_KEY` |
+| `amazon-bedrock`, Anthropic | `amazon-bedrock/<region>.anthropic.claude-opus-5-5` | `amazon-bedrock/<region>.anthropic.claude-haiku-5-5` | `AWS_PROFILE` or `AWS_BEARER_TOKEN_BEDROCK`, and `AWS_REGION` |
+| `amazon-bedrock`, OpenAI | `amazon-bedrock/<region>.openai.gpt-6-astra` | `amazon-bedrock/<region>.openai.gpt-6-luna` | `AWS_PROFILE` or `AWS_BEARER_TOKEN_BEDROCK`, and `AWS_REGION` |
+| `other` | `anthropic/claude-opus-5-5` | `google/gemini-3.1-flash-lite` | `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` |
+
+Amazon Bedrock asks two more things - whose models, Anthropic's or OpenAI's (`--maker`), and the region of the
+inference profile they run in (`--region`): `global`, `us`, `eu`, `jp` or `au` for Anthropic's, `global` or `us` for
+OpenAI's. It says which `AWS_REGION` to set for it - pi calls Bedrock in `us-east-1` when none is. A `config.turri.yaml`
+already there keeps everything but its two models, which it sets; `--force` writes the whole file again.
+
+Each is written with how hard it thinks - `harness-model: openai/gpt-6-astra:medium`, `coding-model:
+openai/gpt-6-luna:low` - so the file shows it. The reviews and judges run on the coding model but think medium (see
+[models per role](#models-per-role)).
+
+They are an example, not a requirement - any model [pi](https://pi.dev) supports works, signed in any way pi
+supports; `other` is the starting point for another provider. What we recommend is that split, a capable model to
+talk to and a smaller, cheaper one for the coding. Once written, it says what to do next: the key to set in your
+shell - or `/login` in turri, which pi keeps in `~/.pi/agent/auth.json` - and that the file belongs to that folder:
+turri reads the nearest `config.turri.yaml` upwards from where it starts, so one written anywhere else is not seen.
+
+Below them it writes every other setting out, each with what it does and the value turri uses for it - `review: false`,
+`turn-limit: 120`, `parallel-jobs` as this machine's cores make it - so the file says how the project is built, and you
+change one by changing it. The optional ones, which have no value of their own - the testing scripts (written in by the
+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
+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
+one as its argument.
+
+## Where it is read from
+
+A spec belongs to its **project**: the nearest folder, from the spec's own folder up, that holds a
+`config.turri.yaml`, a stack's `config.turri.<stack>.yaml`, the old `config.yaml` or a `plain_modules/`.
+Without any of them, the spec's own folder is the project. That folder's config is the one read, and
+its `plain_modules/` is where the code is built, wherever turri was started. So a project that keeps
+its specs in `plain/`, with `plain/config.turri.yaml`, builds `plain/app.plain` by
+`plain/config.turri.yaml` even when `turri` runs in the folder above.
+
+When it is read:
+
+- **In the chat**, afresh: the chat's agent is told what it says on every turn, and each render
+  reads it when it is queued. An edit to the file holds from the next turn and the next render, with
+  no restart. The agent is told the config of the session's folder and of the projects one folder
+  down.
+- **On the command line**, once, when the command starts. `turri regenerate` takes `module:` from
+  the folder it is run in, and the rest from the spec's own project.
+
+## Changing it from the chat
+
+`/turri-config` changes any key in the chat, and writes it into the `config.turri.yaml` of the folder turri was started in -
+its comments, and the commented-out examples, kept. Alone, it lists every key with what it is now, and asks for the
+value of the one you pick the way the key takes it: `true` or `false`, one of its words, a number from a few offered or
+typed, a model from those this machine can reach and then how hard it thinks, a script or a `.plain` file the project
+has, rules ticked on and off. `/turri-config review` asks for review's value; `/turri-config review false` sets it, and
+`/turri-config review unset` takes it out, back to its default. Completion offers the keys, then each one's values.
+Each role's model and turn limit is `models.<role>` and `models.<role>.turn-limit` - `models.coding`,
+`models.planner.turn-limit`.
+
+Each change says when it takes effect. None needs turri started again - what turri fixes as it starts is changed as it
+runs:
+
+| when | keys |
+| --- | --- |
+| now | `harness-model` and `models.chat` - the conversation switches to it; `parallel-jobs` - a pulse waiting for a slot starts if there is one now; `allow-to-stop-jobs` |
+| your next message | `rules-off` - for the conversation; a skill's agents from the next skill run |
+| the next pulse - one running keeps what it started with | `coding-model`, `judge-model`, every other `models.<role>`, `review`, `turn-limit`, `compact-at`, `agent-env`, `toolchains` |
+| the next time the work is planned | `conformance-tests`, `conformance-budget`, `max-specs-per-pulse`, `max-lines-per-pulse` |
+| the next test run - the running pulse's too | the testing scripts, `testing-scripts-run-on` |
+| the next pulse that lands - the running one too | `release-after-pulse` |
+| the next regeneration that names no `.plain` file | `module` |
+
+A coding model chosen this session - `--coding-model`, or `engine` - gives way to one set here: the last word wins. It
+says, too, what wins over the change: `models.chat` over `harness-model` (and so on), and a stack's
+`config.turri.<stack>.yaml`, which is not changed here, while that stack is chosen. In a project still read from
+`config.yaml`, the first change copies it to `config.turri.yaml` first - see [the old config.yaml](#the-old-configyaml).
+
+## The keys
+
+```yaml
+module: app.plain                    # what to build when no .plain file is named
+harness-model:                       # the model you chat with
+  model: anthropic/claude-opus-5-5
+  thinking: high
+coding-model:                        # every render (default: harness-model)
+  model: amazon-bedrock/eu.anthropic.claude-sonnet-5
+  thinking: low
+judge-model:                         # the verdicts of a conformance run (default: coding-model)
+  model: amazon-bedrock/eu.anthropic.claude-sonnet-5
+  thinking: medium
+conformance-tests: true              # write and run conformance tests where there are test reqs (default: false)
+unittests-script: test_scripts/run_unittests_python.sh
+conformance-tests-script: test_scripts/run_conformance_tests_python.sh
+testing-scripts-run-on: copy         # what the testing scripts run on: copy - a fresh copy (default: in-place - the code itself)
+turn-limit: 150                      # seconds each agent turn has (default: 120; 0 for none)
+models:                              # each agent role's model, thinking and turn limit - see below
+  default: amazon-bedrock/global.openai.gpt-6-luna
+  coding: { model: amazon-bedrock/eu.anthropic.claude-sonnet-5, thinking: high, turn-limit: 180 }
+  explorer: google/gemini-3.1-flash-lite
+```
+
+| key | what it sets | left out |
+| --- | --- | --- |
+| `module` | the `.plain` file `turri regenerate` and the chat's `regenerate` build when none is named, from the project root | a file has to be named |
+| `harness-model` | the model `turri` starts on - the one you talk to - the one that diagnoses a job that failed for good, and, in the conversation, the planner that cuts the work into jobs (on whatever model the chat is on when it plans); under `turri regenerate`, the planner too | pi's configured model |
+| `coding-model` | every render: functionalities, spec diffs, conformance tests, repairs, planning spec diffs, the explorer | `harness-model` |
+| `judge-model` | the judge and the test review of a conformance run | `coding-model` |
+| `conformance-tests` | `all` (or `true`): conformance tests for every functional spec of every module with test reqs, written once each module's code is built, before anything is built on it. `chosen`: for the functional specs chosen - every one with acceptance tests, and those the chooser picks as each code pulse ends, from what that pulse regenerated. `module`: the same, but the chooser is asked once, when the whole module is regenerated, and plans the conformance pulses too. Under both, the choice is made inside the pulse, before anything is built on the module, and the pulse's report says what was chosen and why; those the person asks for with `conform` are written too; once chosen, a functional spec keeps them, and they are rewritten when it changes - see [who chooses, and when](regenerating.md#conformance-tests-in-the-work-loop). `false`: none written, and none of the existing ones run - until the conversation asks with `conform` | `false` |
+| `conformance-budget` | under `conformance-tests: chosen` or `module`: how many of a module's functional specs may be chosen for conformance tests, beside those with acceptance tests - a count (`2`) or a share of its functional specs (`30%`, rounded up, at least one). Every choice for the module counts, whenever it was made; the chooser is told what is left, and can choose no more. Your own `conform` is not limited. A stack's `config.turri.<stack>.yaml` can set its own | no limit |
+| `review` | `true` or `false`: whether the code and its unit tests - and the conformance tests - are reviewed once they pass: two reviews at most, the second weighed by the arbiter; off, a job lands once its tests pass - see [regenerating the code](regenerating.md#the-code-and-its-unit-tests-are-reviewed) | `false` |
+| `rules-off` | a list of rule names - `integrations`, `concise-specs`, the files of `genome/rules/` without `.md` - left out of the conversation's prompt and every spec-writing agent's: a rule this project's own skills or AGENTS.md replace, such as one that says to probe a live API before any spec is written. The project's alone | none |
+| `allow-to-stop-jobs` | `true` or `false`: whether turri stops a running job the spec has moved on from - a functional spec it regenerates changed, or a file one links was edited - rolls it back and regenerates the spec as it now is. `false`: the job runs to its end and lands, and what changed since is regenerated on top of it by the next job - see [regenerating the code](regenerating.md). Your own `halt` stops a job either way | `true` |
+| `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 |
+| `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 |
+| `parallel-jobs` | how many jobs the chat runs at once - modules that share nothing build side by side up to it; read when the chat starts, from the folder it starts in | half this machine's cores, between one and four - see [how many jobs at once](#how-many-jobs-at-once) |
+| `agent-env` | credentials the agents' commands need while they work - a live API probed, tests run against a real service: `files: [...]`, dotenv files by path from the project root, every variable in them; `vars: [...]`, variables by name from the environment turri was started in. A stack's `config.turri.<stack>.yaml` adds its own to the project's. See [credentials for the agents](#credentials-for-the-agents) | none: an agent's commands get no credential |
+| `toolchains` | folders of this machine an agent's commands may read beside the system's, the `PATH`'s and those the toolchain variables point at - a toolchain installed somewhere unusual (`[/srv/zig]`). A stack's add to the project's. See [the OS sandbox](sandbox.md#the-os-sandbox) | none |
+| `turn-limit` | seconds each turn of an agent a job starts has, for every role without its own (`models:`); `0` for none. The config is the only place it is set. A turn past it ends at its next request to the model - see [regenerating the code](regenerating.md) | 120 |
+| `models` | each agent role's own model, thinking and turn limit - see [models per role](#models-per-role) | every role on `coding-model`, the conversation's side on `harness-model` |
+| `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
+wrong type, as if it were not there. `model:`, from before there were separate models, is read as
+`coding-model`.
+
+## Models per role
+
+`models:` gives each kind of agent its own model, thinking level and turn limit. Each entry is a model
+(`provider/id`, or `provider/id:thinking`) or `{ model, thinking, turn-limit }`, any of which may be left out:
+
+| role | the agents |
+| --- | --- |
+| `default` | every role not named below - but the conversation's side |
+| `chat` | `turri`'s model - the same as `harness-model`, which it wins over |
+| `chooser`, `planner`, `diagnosis` | the conversation's side: the conformance chooser of `turri regenerate`, the planner's agents, the diagnosis of a failed job. Unnamed, the chat's model |
+| `release` | `turri release`'s agent and release-after-pulse's: it follows steps - a script, a start command - so it runs on the coding model, thinking low |
+| `coding` | the coding agent, the code fixer of a conformance run and the repair agent - the same as `coding-model`, which it wins over. `--model` on the command line, or a model chosen in the conversation (`engine`), wins over both |
+| `conformance` | the conformance agent |
+| `explorer` | the explorers of a conformance run |
+| `reviewer` | the review of the code and its unit tests |
+| `test-reviewer` | the review of the conformance tests - `judge-model` too, when it is set |
+| `judge` | the judge of a failing conformance run - the same as `judge-model`, which it wins over |
+| `arbiter` | the arbiters that weigh a second review |
+| `debugger` | the fresh look at unit tests that keep failing the same way, or a coding agent going round in circles. Unnamed, `judge-model` when it is set, else the harness model - not `default` |
+
+What an entry leaves out it takes from `default`: `reviewer: { thinking: low }` runs the default model, thinking
+little. A turn limit is the role's own, else `default`'s, else `turn-limit:`, else two minutes. A stack's `config.turri.<stack>.yaml` lays its own `models:` over the project's, role by role - all but
+`chat`, the project's alone.
+
+A role whose thinking nothing names - neither its entry, `default`'s, nor a `:level` on the model it runs on - thinks
+as its kind of work needs: **low** for the agents that do the work (`coding`, `conformance`, `explorer`, `release`),
+which work from specs that leave little to guess and take many turns, and **medium** for the ones that judge
+(`reviewer`, `test-reviewer`, `judge`, `arbiter`, `debugger`, `planner`, `chooser`, `diagnosis`), where a wrong
+call costs pulses. A judging role that falls back on the coding model takes its model alone, not its thinking. The
+conversation keeps its own level, as pi sets it.
+
+The thinking level reaches the model as each provider takes it. OpenAI's models on Bedrock are sent it as their
+reasoning effort (`none`, `low`, `medium`, `high`, `xhigh`) by turri itself, as pi sends them none.
+
+## How many jobs at once
+
+Jobs on the same module, or on modules of one `requires` chain, always run one after another.
+Modules that share nothing - a backend, a frontend, a worker, ten of them - build side by side, each
+pulse's builds and tests running on this machine beside your own work. So the chat runs at most `parallel-jobs` jobs
+at once; a job whose turn has come waits for a free slot past that, and its line says so. Unset, it is half this
+machine's cores, at least one and at most four. The config is the only place it is set. It is the project's alone,
+never read from a stack's file.
+
+The testing scripts all run on this machine, each on a copy of its module's code, so they never
+share files - but they do share its network: two modules whose conformance scripts start a server
+on the same port collide when they run at once. Give each its own.
+
+## Models
+
+Each model is a model reference and a thinking level - `off`, `minimal`, `low`, `medium`, `high`,
+`xhigh` or `max` - and either may be left out:
+
+```yaml
+coding-model:
+  model: google/gemini-3.1-flash      # the provider and the model id, as pi names them
+  thinking: medium
+judge-model: google/gemini-3.1-pro:high   # the same, as one string
+harness-model: anthropic/claude-opus-5-5  # a model alone
+```
+
+What a model leaves out it takes from the one it inherits: `judge-model` from `coding-model` - its model, not its
+thinking, which the judging roles have their own of - and `coding-model` from `harness-model`. So with only a harness model, everything runs on it;
+`coding-model: {thinking: low}` renders on the harness model, thinking less.
+
+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` |
+
+A job keeps the model it was queued with: choosing another holds for what is queued after.
+
+## Conformance tests
+
+`conformance-tests:` is the one switch, and the chat, every render and `brood`'s testing phase
+follow it. `false` turns them off entirely: no conformance tests are written, the ones already in a
+codebase are not run, and no agent is shown the conformance testing script. No key is the same as
+`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.
+
+`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.
+
+## The testing scripts
+
+A build needs a unit testing script - and, with conformance on, a conformance testing script - to
+decide when it is done. They are looked for at the project root, in this order:
+
+1. named in the config - the chosen stack's file first, then `config.turri.yaml` - by path from the root;
+2. the one `run_unittests*.sh` / `run_conformance_tests*.sh` in the project root;
+3. the one of each in `test_scripts/`.
+
+The optional prepare script - `prepare-environment-script:`, else the one `prepare_environment*.sh` - is looked for the
+same way, and run on the build before the conformance testing script.
+
+A folder holding two of a kind is not guessed between: name the one to use. A script named inside
+`plain_modules/` is refused - agents write there, so it could be changed by the work it judges. The
+scripts are never linked from the specs. What they are and how they run is in
+[regenerating the code](regenerating.md#the-testing-scripts).
+
+## Credentials for the agents
+
+An agent's commands do not get the environment turri was started in: it holds your providers' API keys, cloud
+credentials and tokens. They get only the path, the locale, the terminal and the user, the variables that locate your
+toolchains (`JAVA_HOME`, `NVM_DIR`, `RUSTUP_HOME`, ... - the ones in your home found even when your shell sets none),
+and turri's own: a home folder of the module's own (`plain_modules/.turri/home/<module>`, kept between pulses, with a
+git identity of its own), a `TMPDIR`, the package caches in `plain_modules/.turri/cache`, and git stopped at the module
+folder, so a project that is itself a repository is never found from the code.
+
+A project whose agents need a credential while they work names it:
+
+```yaml
+agent-env:
+  files: [.env]              # every variable of these dotenv files, by path from the project root
+  vars: [D365_TENANT_ID]     # these variables, from the environment turri was started in
+```
+
+What it names reaches every agent with a shell, as environment variables of its commands only - the file stays where
+it is, outside every agent's reach - and never replaces turri's own home, `TMPDIR` or caches. A stack's file adds
+to the project's. A file that is not there, or a variable unset or empty, is reported as missing. The testing scripts
+are not affected: they run in your own environment.
+
+Their values never appear in what an agent is shown or what turri writes: each is replaced by its name -
+`[D365_CLIENT_SECRET]` - whole, URL-encoded, or split over a command's output as it streams: in every tool result and
+refusal an agent is given (and so in the session transcripts, which hold only those), in the whole outputs kept for
+`read_output`, and in the job and debug logs. A value shorter than four characters is not masked - `1` or `eu` is
+everywhere in ordinary output.
+
+## Stacks
+
+One project can hold parts that share nothing but a common module - a Python backend and a React
+frontend side by side, each importing `base` from `template/`, neither requiring the other - each
+needing its own testing scripts. Each stack gets a file of its own beside `config.turri.yaml`,
+`config.turri.<stack>.yaml`, holding what differs for it - typically its testing scripts, its
+`toolchains:`, its models:
+
+```
+config.turri.yaml            # the project's: harness-model, coding-model, conformance-tests
+config.turri.backend.yaml    # the stack backend: its testing scripts
+config.turri.frontend.yaml   # the stack frontend: its testing scripts, and a coding model of its own
+backend.plain                # import: [base, python_fastapi_template]
+frontend.plain               # import: [base, react_vite_template]
+template/                    # base.plain, python_fastapi_template.plain, react_vite_template.plain
+test_scripts/                # both stacks' scripts
+```
+
+```yaml
+# config.turri.frontend.yaml
+unittests-script: test_scripts/run_unittests_typescript.sh
+conformance-tests-script: test_scripts/run_conformance_tests_typescript.sh
+coding-model:
+  thinking: high
+```
+
+A stack is chosen, never worked out from the spec:
+
+- **In the chat**, with `/stack` - a list of the project's stacks and none - or `/stack backend`, `/stack none`.
+  The chat's model has a `stack` tool too, and switches the stack when you ask it to, or for work on a part another
+  stack builds. `/stack` alone says which is chosen now.
+- **On the command line**, with `--stack <name>` on any command - `turri regenerate`, `conform`, `spec-diff`, `glimpse`,
+  `release`, `cultivate` - and on `turri --stack backend` for the chat; or with `TURRI_STACK` in the environment.
+
+The choice lasts for the session only: nothing remembers it, and turri started again has none chosen. A stack the
+project has no file for is refused, with the stacks it has. With none chosen, `config.turri.yaml` alone is used.
+
+How a stack's config is made:
+
+- **Laid over `config.turri.yaml`, key by key.** What the stack's file gives wins; what it leaves out
+  is the project's. A model it names takes what it leaves out from the project's same model - above,
+  with the stack frontend chosen, everything renders on the project's coding model, thinking `high`.
+- **For everything built while it is chosen.** Every pulse that starts, every test run and every
+  script found from then on is the chosen stack's; a pulse already running keeps the stack it
+  started with. Choose the stack before building the part it is for: `/stack backend`, then
+  `regenerate backend.plain`.
+- **The project's alone.** `module:`, `harness-model:`, `parallel-jobs:`, `rules-off:` and `compact-at:` are read
+  only from `config.turri.yaml` - there is one conversation, one module built when none is named, one machine.
+  `agent-env:` and `toolchains:` in a stack's file add to the project's.
+
+The chat is told each stack's config and the one chosen. The skills that write testing scripts put
+each stack's in its own file once a project has two stacks, and say which stack to choose before
+building each part.
+
+## The old config.yaml
+
+turri's settings were once in `config.yaml`, and a stack's in `config.<stack>.yaml`. A `config.yaml`
+may be another tool's, so turri never writes one. While a project folder has no `config.turri*.yaml`
+at all, turri still reads its `config.yaml`, and each `config.<name>.yaml` as the stack `<name>`.
+
+The first time turri itself writes a setting there with `/turri-config`, it copies `config.yaml` to
+`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
+`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
+setting by hand in such a project, do the same: copy the files to their new names, and edit the
+copies - never `config.yaml`.