@turri-dev/cli 0.1.11-next.be75b46 → 0.1.11

package/README.md

@@ -10,11 +10,11 @@
 
 **turri** is named after *Turritopsis dohrnii*, the immortal jellyfish that regenerates itself from its young form, again and again - as **turri** regenerates the code from the durable intent - see [the name](#the-name).
 
-**turri** has a desktop app too: [turri-app](https://github.com/turri-oss/turri-app).
+**turri** has a desktop app too: [turri desktop](https://github.com/turri-oss/turri-desktop).
 
 ## Quick start
 
-**turri** is built on [pi](https://pi.dev), the coding agent, and runs wherever pi runs: macOS, Linux, WSL; native Windows best effort, with Git Bash. You need git, bash and [Node](https://nodejs.org/en/download) 22.19 or newer - a Linux distribution's own `nodejs` package is often older. The agents use this machine's toolchains, fenced by a command check and an audit everywhere, and an OS sandbox where the OS has one - Seatbelt on macOS, bubblewrap on Linux (`apt install bubblewrap`) - see [installation](docs/installation.md#installation).
+**turri** is built on [pi](https://pi.dev), the coding agent, and runs wherever [pi](https://pi.dev) runs: macOS, Linux, WSL; native Windows best effort, with Git Bash. You need git, bash and [Node](https://nodejs.org/en/download) 22.19 or newer - a Linux distribution's own `nodejs` package is often older. The agents use this machine's toolchains, fenced by a command check and an audit everywhere, and an OS sandbox where the OS has one - Seatbelt on macOS, bubblewrap on Linux (`apt install bubblewrap`) - see [installation](docs/installation.md#installation).
 
 ```bash
 npm install -g @turri-dev/cli # puts `turri` on your PATH
@@ -23,7 +23,7 @@ turri doctor              # checks the machine
 
 To follow `main` as it moves, or work on turri itself, run it [from a clone](#from-a-clone) instead.
 
-`doctor` checks for Node 22.19+, bash, the OS sandbox and a model provider for pi; in a project, the toolchains its modules need, what its testing scripts run against this machine, and that each model `config.turri.yaml` names answers with your credentials. It changes nothing without asking: when a check fails - the OS sandbox does not start, say - it says why, and the command for you to run. Run it again whenever something breaks. What each check means: [installation](docs/installation.md).
+`doctor` checks for Node 22.19+, bash, the OS sandbox and a model provider for [pi](https://pi.dev); in a project, the toolchains its modules need, what its testing scripts run against this machine, and that each model `config.turri.yaml` names answers with your credentials. It changes nothing without asking: when a check fails - the OS sandbox does not start, say - it says why, and the command for you to run. Run it again whenever something breaks. What each check means: [installation](docs/installation.md).
 
 Then start it in your project, signed in to your model providers:
 
@@ -101,7 +101,7 @@ With **turri** you work on the durable intent. You say what the software must do
 
 ## How it works
 
-**turri** captures the durable intent in [\*\*\*plain](https://plainlang.org/), a language for saying what software should do. \*\*\*plain breaks the intent down into functionalities - small units, each a single thing the software does - and **turri** regenerates the code from them piece by piece.
+**turri** captures the durable intent in [\*\*\*plain](https://plainlang.org/docs/), a language for saying what software should do. \*\*\*plain breaks the intent down into functionalities - small units, each a single thing the software does - and **turri** regenerates the code from them piece by piece.
 
 1. **Define.** You say what the software should do; **turri** writes it down as \*\*\*plain.
 2. **Review and refine.** You review \*\*\*plain and change it with **turri** until it says what you mean.
@@ -127,7 +127,7 @@ So the tools speak its language: **`regenerate`** regenerates the code from \*\*
 
 ## Models
 
-`init-config`'s models are only a starting point. **turri** is built on [pi](https://github.com/earendil-works/pi), so any model pi supports works - Anthropic, OpenAI, Google, Amazon Bedrock, OpenRouter, a local one. A model is reached as pi reaches it - `/login`, in `turri` as in `pi`, the provider's API key in the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...), or a cloud account - and named as pi names it, `provider/model-id`, with `:high`, `:low` and so on for how hard it thinks. It uses three: the **harness** model you talk to, which writes \*\*\*plain and plans the work - worth a capable one - and the **coding** and **judge** models its agents build and judge with, which can be smaller and cheaper, such as GPT-6 Luna or Gemini 3.1 Flash Lite. `turri --harness-model` and `--coding-model` choose them for a session, and pi's `/model` switches the one you talk to as you go; to keep them for the project, set them with `/turri-config harness-model`, `/turri-config coding-model` and so on - each role's too, as `models.<role>` - or write them in its `config.turri.yaml`:
+`init-config`'s models are only a starting point. **turri** is built on [pi](https://pi.dev), so any model [pi](https://pi.dev) supports works - Anthropic, OpenAI, Google, Amazon Bedrock, OpenRouter, a local one. A model is reached as [pi](https://pi.dev) reaches it - `/login`, in `turri` as in `pi`, the provider's API key in the environment (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...), or a cloud account - and named as [pi](https://pi.dev) names it, `provider/model-id`, with `:high`, `:low` and so on for how hard it thinks. It uses three: the **harness** model you talk to, which writes \*\*\*plain and plans the work - worth a capable one - and the **coding** and **judge** models its agents build and judge with, which can be smaller and cheaper, such as GPT-6 Luna or Gemini 3.1 Flash Lite. `turri --harness-model` and `--coding-model` choose them for a session, and [pi](https://pi.dev)'s `/model` switches the one you talk to as you go; to keep them for the project, set them with `/turri-config harness-model`, `/turri-config coding-model` and so on - each role's too, as `models.<role>` - or write them in its `config.turri.yaml`:
 
 ```yaml
 harness-model: anthropic/claude-opus-5-5    # the model you talk to: a capable one
@@ -179,7 +179,7 @@ turri regenerate app.plain      # regenerate the code from ***plain: planned int
 turri regenerate app.plain 3    # regenerate functionality 3, changed or not
 ```
 
-More: [using **turri**](docs/using.md); to render \*\*\*plain overnight, see [running unattended](docs/headless.md).
+More: [using **turri**](docs/using.md); to regenerate \*\*\*plain overnight, see [running unattended](docs/headless.md).
 
 ## Documentation
 
@@ -192,7 +192,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | [Using **turri**](docs/using.md) | the conversation, skills, tools, pulses and regen, choosing models, the command line |
 | [The project config](docs/config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](docs/deploy.md) | trying what is built: the last commit in `dist/<module>`, started on your machine, nothing installed without asking |
-| [Running unattended](docs/headless.md) | rendering \*\*\*plain overnight or in CI: the command, keeping it running, the results, resuming, rebuilding one functionality |
+| [Running unattended](docs/headless.md) | regenerating \*\*\*plain overnight or in CI: the command, keeping it running, the results, resuming, rebuilding one functionality |
 | [Authoring \*\*\*plain](docs/authoring-plain.md) | what \*\*\*plain is made of, the authoring rules, the skills that write and fix it, checking it |
 | [Regenerating](docs/regenerating.md) | what each build does and in which order: functionalities, modules, regeneration, changes to \*\*\*plain, conformance and acceptance tests, working notes, what the code is built from |
 | [The sandbox](docs/sandbox.md) | what agents can reach, the walls every command passes, time limits, the web tools |

package/dist/{spec-diff-cli.js → change-plain-cli.js}

@@ -4,9 +4,9 @@ import { checkPlainFile } from "./plain/check.js";
 import { applySpecDiff, revertSpecDiff } from "./regenerate/regenerate.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]
+const USAGE = `usage: turri change-plain <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
+Applies a change to ***plain, 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.
 
@@ -40,7 +40,7 @@ runLoop({
     startOver: options["start-over"] !== undefined,
     ...(buildDir !== undefined ? { buildDir } : {}),
     ...(report !== undefined ? { report } : {}),
-    command: ["spec-diff", ...process.argv.slice(2)],
+    command: ["change-plain", ...process.argv.slice(2)],
     ask: (loop) => loop.bringUp(plainFile),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/cli.js

@@ -78,7 +78,7 @@ const COMMANDS = {
     glimpse: { module: "./regenerate-cli.ts", blurb: "plan the work and print the first job's prompt, starting nothing", args: ["--dry-run"] },
     drift: { module: "./drift-cli.ts", blurb: "what is left to regenerate: how far the code has drifted from its spec" },
     conform: { module: "./conform-cli.ts", blurb: "write and run a module's conformance tests" },
-    "spec-diff": { module: "./spec-diff-cli.ts", blurb: "apply a change to the specs, given as a git diff, and regenerate it" },
+    "change-plain": { module: "./change-plain-cli.ts", blurb: "apply a change to ***plain, given as a git diff, and regenerate it" },
     validate: { module: "./validate-cli.ts", blurb: "validate a ***plain spec, regenerating nothing" },
     lineage: { module: "./lineage-cli.ts", blurb: "a module's lineage: what was regenerated into it, and when" },
     ledger: { module: "./ledger-cli.ts", blurb: "what turri did here: the last runs and their pulses, or one pulse, from the ledger" },

package/dist/extension.js

@@ -669,11 +669,11 @@ function turriExtension(pi, host) {
                 : "It changed no file in the project - whatever it said it wrote is not there. Say so to the user; do not report the work as done.";
             // A skill that edits the specs with the file tools builds nothing: the change is the conversation's to render.
             const specsChanged = changes.filter((path) => path.endsWith(".plain"));
-            const unrendered = specsChanged.length > 0 && !skill.allowedTools.includes("write_spec_diff")
+            const unrendered = specsChanged.length > 0 && !skill.allowedTools.includes("change_plain")
                 ? `${specsChanged.join(", ")} changed, and nothing is regenerated from that yet: call regenerate for it, and the code is brought up to the spec.`
                 : "";
             const gated = skill.steps.some((step) => step.gate !== undefined);
-            const first = skill.allowedTools.includes("write_spec_diff") ? firstRegeneration(jobs.list(), began) : {};
+            const first = skill.allowedTools.includes("change_plain") ? firstRegeneration(jobs.list(), began) : {};
             const ttfr = first.started === undefined
                 ? ""
                 : `Time to first regeneration: ${formatElapsed(first.started)} - its first pulse started that long after ${skill.name} began` +
@@ -1125,7 +1125,7 @@ export function projectConfigBlock(root) {
         return [
             ...settings(readProjectConfig(dir), withStack(undefined, () => findTestScripts(dir)), dir === root ? `${projectConfigFile(dir)}, for the specs here:` : `${relative(root, dir)}/${projectConfigFile(dir)}, for the specs in ${relative(root, dir)}/ - built in ${relative(root, dir)}/plain_modules:`, where, stacks.length > 0 ? "project of stacks" : "project"),
             ...(stacks.length > 0
-                ? ["", `Stacks: ${stacks.join(", ")} - chosen now: ${chosen ?? "none, so the project's file alone"}. Each module is built with the stack of its part, pinned to its pulses whatever is chosen after: a stack named after the module is its own - backend.plain is built with config.turri.backend.yaml - with nothing to choose. For a module whose stack has another name, pass it as stack to regenerate, conform, glimpse and write_spec_diff. Choose one for the whole session with the stack tool only when the user asks.`]
+                ? ["", `Stacks: ${stacks.join(", ")} - chosen now: ${chosen ?? "none, so the project's file alone"}. Each module is built with the stack of its part, pinned to its pulses whatever is chosen after: a stack named after the module is its own - backend.plain is built with config.turri.backend.yaml - with nothing to choose. For a module whose stack has another name, pass it as stack to regenerate, conform, glimpse and change_plain. Choose one for the whole session with the stack tool only when the user asks.`]
                 : []),
             // A stack: its file over the project's, for everything built while it is chosen.
             ...stacks.flatMap((stack) => [
@@ -1298,7 +1298,7 @@ function setRenderModelTool(pi, conversation) {
         label: "Engine",
         description: "The engine: which model the agents that regenerate the code run on. With no model, say which it is. With one, choose it " +
             "for the rest of this session: for spec changes " +
-            "(render spec diff pulses, and the ones write_spec_diff queues), for functionalities (render, module, " +
+            "(render spec diff pulses, and the ones change_plain queues), for functionalities (render, module, " +
             "regenerate with functionalities named, conformance), or for everything. By default " +
             "each runs on the model the project's config.turri.yaml names, or else the conversation's model. The model may be given as provider/model-id or by name as " +
             "the user said it; a name that fits more than one model, or none with credentials, comes back as a " +

package/dist/genome.js

@@ -12,7 +12,7 @@ import { DISMISSED } from "./ask.js";
 import { createQuestioning, levelOf, questioningQuestion } from "./questioning.js";
 import { createSpecDiffTools } from "./spec-tools.js";
 import { createMatureTools, MATURE_TOOLS } from "./mature-tools.js";
-const WRITE_SPEC_DIFF = "write_spec_diff";
+const CHANGE_PLAIN = "change_plain";
 /** The conversation's tools a skill acts on the work loop with - never pi built-ins. */
 const LOOP_TOOLS = ["regenerate", "drift", "halt", "conform"];
 /** How much of what the agent said before a question is shown with it: its end, where the brief is. */
@@ -77,14 +77,14 @@ export async function runSkill(opts) {
     const questions = {
         refusal: (confirmsPhase) => diffPerAnswer() && diffs?.pace.owed() === true
             ? "This question was not asked: the last answer is not in the spec yet. Every answer in this phase is a spec " +
-                "change, built at once - write it with write_spec_diff first, then ask."
+                "change, built at once - write it with change_plain first, then ask."
             : questioning?.refusal(confirmsPhase),
         answered: (confirmsPhase) => questioning?.answered(confirmsPhase),
         end: () => questioning?.end() ?? "No questioning level was chosen: ask what the phase needs.",
     };
-    // A skill whose unit of work is a spec change gets write_spec_diff: the change is applied
+    // A skill whose unit of work is a spec change gets change_plain: the change is applied
     // and its build queued in one step.
-    const diffs = opts.renderQueue !== undefined && skill.allowedTools.includes(WRITE_SPEC_DIFF)
+    const diffs = opts.renderQueue !== undefined && skill.allowedTools.includes(CHANGE_PLAIN)
         ? createSpecDiffTools({
             loop: opts.renderQueue,
             cwd: opts.cwd,
@@ -125,7 +125,7 @@ export async function runSkill(opts) {
     customTools.push(...(opts.sharedTools ?? []));
     const names = customTools.map((tool) => tool.name);
     // Tools this harness provides are never pi built-ins, even when it did not provide them.
-    const builtins = skill.allowedTools.filter((t) => !names.includes(t) && t !== WRITE_SPEC_DIFF && !MATURE_TOOLS.includes(t) && !LOOP_TOOLS.includes(t));
+    const builtins = skill.allowedTools.filter((t) => !names.includes(t) && t !== CHANGE_PLAIN && !MATURE_TOOLS.includes(t) && !LOOP_TOOLS.includes(t));
     const executor = await createExecutor({
         cwd: opts.cwd,
         customTools,

package/dist/identity.js

@@ -27,8 +27,9 @@ export function conversationIdentity(surface) {
 }
 const IDENTITY_BEFORE = [
     "<turri>",
-    "You are turri - always lowercase - a coding agent with the power of regenerative software. The software is its",
-    "***plain; the code is regenerated from it. You help the person write ***plain, and you regenerate the code from it a",
+    "You are turri - always lowercase - the first coding agent with the power of regenerative software. The software is",
+    "its ***plain; the code is regenerated from it. You write the ***plain with the person - they say what the software",
+    "should do, and you write it down as ***plain, shaping it with them - and you regenerate the code from it a",
     "change at a time - with agents that write the code and tests, while you decide what runs next and when the work is",
     "done - record what each piece was regenerated from, and prove it against conformance tests written from the ***plain",
     "alone. When the code goes bad, you regenerate it from the ***plain. You are named after Turritopsis dohrnii, the",
@@ -37,9 +38,10 @@ const IDENTITY_BEFORE = [
     "gone bad is regenerated from it, whole, rather than patched. Say it as that likeness, not as a fact about a",
     "jellyfish.",
     "",
-    "Asked who or what you are, say it in those words: you are turri, a coding agent with the power of regenerative",
-    "software - you help them write ***plain and regenerate the code from it. Not an assistant, and not a helper with",
-    "specifications: ***plain is the language they write, and naming it is the point. Your replies are Markdown, where",
+    "Asked who or what you are, say it in those words: you are turri, the first coding agent with the power of",
+    "regenerative software - you write ***plain with them and regenerate the code from it. Never say they write the",
+    "***plain and you help: you write it, together. Not an assistant, and not a helper with specifications: ***plain is",
+    "the language the software is written in, and naming it is the point. Your replies are Markdown, where",
     "three asterisks start bold italics: write the name escaped, \\*\\*\\*plain, so it shows as ***plain.",
     "",
     "Speak as turri, in the first person - I, my pulses, my agents - to the person, in whole sentences. Never speak of",
@@ -53,7 +55,7 @@ const IDENTITY_BEFORE = [
     "  allow-to-stop-jobs in config.turri.yaml are about pulses. \"Job\" in what you read is a pulse; say pulse.",
 ];
 const IDENTITY_AFTER = [
-    "- mutate, in a skill's activity, is write_spec_diff: a spec change written and regenerated in one step.",
+    "- mutate, in a skill's activity, is change_plain: a spec change written and regenerated in one step.",
     "- Regenerate is the word for what you do to the code: never grow, grew or grown - older text, a tool's description",
     "  or a report may still say it, and means regenerate.",
 ];

package/dist/loop-cli.d.ts

@@ -1,7 +1,7 @@
 import { type DriftReport, type ModuleStatus, type WorkLoop } from "./regenerate/loop.ts";
 import { type ModuleState } from "./run-report.ts";
 /**
- * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
+ * What every command that builds - `turri regenerate`, `conform`, `change-plain` - does around its own
  * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
  * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
  * and exit 1 when any failed or a module is not complete. With `dryRun`, the work is planned and the prompt of the first job each codebase would

package/dist/loop-cli.js

@@ -17,7 +17,7 @@ import { listFiles } from "./regenerate/testing.js";
 import { startRunReport } from "./run-report.js";
 import { configKeyOptions, optionValue } from "./cli-options.js";
 /**
- * What every command that builds - `turri regenerate`, `conform`, `spec-diff` - does around its own
+ * What every command that builds - `turri regenerate`, `conform`, `change-plain` - does around its own
  * request of the work loop, as the chat does it: the project's models, a job that fails run once more and, failing again,
  * diagnosed, a line as each job starts and ends; then the loop run until nothing more can start, how each job ended,
  * and exit 1 when any failed or a module is not complete. With `dryRun`, the work is planned and the prompt of the first job each codebase would

package/dist/regenerate/activity.js

@@ -173,10 +173,10 @@ export function withinModules(text) {
 }
 /**
  * What the person is shown a tool as, where that is not the name its agent calls it by. The agent's name says
- * what the call takes - `write_spec_diff` takes a diff of the spec - and the shown one speaks turri's language.
+ * what the call takes - `change_plain` takes a diff of the spec - and the shown one speaks turri's language.
  */
 const SHOWN_AS = {
-    write_spec_diff: "mutate",
+    change_plain: "mutate",
 };
 /** A tool's name as the person is shown it. */
 export function shownName(name) {

package/dist/self-invocation.js

@@ -15,7 +15,7 @@ const TOOL_FOR = {
     conform: "conform",
     cultivate: "cultivate",
     release: "release",
-    "spec-diff": "regenerate",
+    "change-plain": "regenerate",
     chat: "nothing - you are the conversation already",
     ask: "nothing - you are the conversation already",
 };
@@ -31,7 +31,7 @@ const NPM_SCRIPT = {
 const ENTRY = {
     "regenerate-cli": "regenerate",
     "conform-cli": "conform",
-    "spec-diff-cli": "spec-diff",
+    "change-plain-cli": "change-plain",
     "cultivate-cli": "cultivate",
     "release-cli": "release",
 };
@@ -43,10 +43,10 @@ const AT_COMMAND = String.raw `(?:^|[\s;&|()\x60$])`;
  * agent - and neither are setup and doctor.
  */
 export function selfInvocation(command) {
-    const cli = new RegExp(`${AT_COMMAND}(?:npx\\s+)?turri\\s+(regenerate|glimpse|conform|cultivate|release|spec-diff)\\b`).exec(command);
+    const cli = new RegExp(`${AT_COMMAND}(?:npx\\s+)?turri\\s+(regenerate|glimpse|conform|cultivate|release|change-plain)\\b`).exec(command);
     if (cli)
         return cli[1];
-    const launcher = new RegExp(`(?:bin/turri\\.mjs|src/cli\\.ts)\\s+(regenerate|glimpse|conform|cultivate|release|spec-diff)\\b`).exec(command);
+    const launcher = new RegExp(`(?:bin/turri\\.mjs|src/cli\\.ts)\\s+(regenerate|glimpse|conform|cultivate|release|change-plain)\\b`).exec(command);
     if (launcher)
         return launcher[1];
     // turri alone, or with options, is the conversation - where a command starts, not a word an argument names (`which turri`).
@@ -83,7 +83,7 @@ const PI_CONFIGURES = new Set([
 export function askedForCommandLine(message) {
     const text = message.toLowerCase();
     return (/\b(headless|command[ -]line|cli|terminal|shell|in bash|via bash|through bash|npm run|nohup)\b/.test(text) ||
-        /\bturri\s+(regenerate|glimpse|conform|spec-diff|cultivate|release)\b/.test(text) ||
+        /\bturri\s+(regenerate|glimpse|conform|change-plain|cultivate|release)\b/.test(text) ||
         /(^|\s)turri\s+-p\b/.test(text) ||
         /(^|\s)pi\s+-p\b/.test(text));
 }
@@ -102,7 +102,7 @@ export const TOOLS_NOT_CLI = [
     "<turri-tools>",
     "In this conversation, you do your work with your tools - regenerate, conform, cultivate and the rest - which run as",
     "background jobs the user can watch and halt. To try what is regenerated, release it - never by hand in plain_modules. Never",
-    "run your own command line (turri regenerate, glimpse, conform, spec-diff, cultivate, release, turri itself; npm run",
+    "run your own command line (turri regenerate, glimpse, conform, change-plain, cultivate, release, turri itself; npm run",
     "regenerate and the like) or start another pi through bash:",
     "that is a separate headless run the user cannot see or stop. Only when the user explicitly asks for the",
     "command line, run it. Configuring pi itself - pi install, update, list, config, auth, or its settings files -",

package/dist/skill.d.ts

@@ -70,7 +70,7 @@ export interface Skill {
     allowedTools: string[];
     steps: StepSpec[];
     /**
-     * Whether `write_spec_diff` needs an answer from the user between two new changes - one answer,
+     * Whether `change_plain` needs an answer from the user between two new changes - one answer,
      * one change, as an interview writes them. `metadata.paced: false` turns it off, for a skill that
      * writes the specs on its own.
      */
@@ -81,8 +81,8 @@ export interface Skill {
      */
     questioning: string[];
     /**
-     * The steps where each answer is a spec change (`metadata.spec-diff-per-answer`): the next question waits until the
-     * last answer is written with `write_spec_diff`, and changes the agent decides itself need no answer before them.
+     * The steps where each answer is a spec change (`metadata.change-plain-per-answer`): the next question waits until the
+     * last answer is written with `change_plain`, and changes the agent decides itself need no answer before them.
      */
     diffPerAnswer: string[];
     /**

package/dist/skill.js

@@ -109,11 +109,11 @@ export function loadSkill(skillDir) {
             throw new Error(`${name}: 'metadata.questioning' names unknown step '${stepName}'`);
         }
     }
-    const perAnswer = data.metadata?.["spec-diff-per-answer"];
+    const perAnswer = data.metadata?.["change-plain-per-answer"];
     const diffPerAnswer = Array.isArray(perAnswer) ? perAnswer.map(String) : [];
     for (const stepName of diffPerAnswer) {
         if (!steps.some((s) => s.name === stepName)) {
-            throw new Error(`${name}: 'metadata.spec-diff-per-answer' names unknown step '${stepName}'`);
+            throw new Error(`${name}: 'metadata.change-plain-per-answer' names unknown step '${stepName}'`);
         }
     }
     for (const stepName of gatesByStep.keys()) {

package/dist/spec-tools.js

@@ -28,7 +28,7 @@ export function createSpecDiffTools(options) {
     let owed = false;
     let answeredSinceLastDiff = true;
     const writeDiff = defineTool({
-        name: "write_spec_diff",
+        name: "change_plain",
         label: "Write spec diff",
         description: "Apply a change to the ***plain specs, given as a git diff of the .plain files, and start building it in " +
             "the background. The diff is applied with git; if the specs no longer parse, it is undone and nothing is " +
@@ -36,7 +36,7 @@ export function createSpecDiffTools(options) {
             "every change is built, whatever it touches.",
         promptSnippet: "apply a git diff of the .plain specs and start building it",
         promptGuidelines: [
-            "Every change to a .plain file in the product phase goes through write_spec_diff, as a git diff with paths relative to the project root. It writes the change and starts its build in one step.",
+            "Every change to a .plain file in the product phase goes through change_plain, as a git diff with paths relative to the project root. It writes the change and starts its build in one step.",
             skillPaced
                 ? "One change per answer, and a new one only after the user has answered a question about it. Set fixes_earlier to correct something already written."
                 : "Write the changes one after another, on your own: no answer is needed between them, and none is asked for. Set fixes_earlier to correct something already written.",

package/dist/stacks.js

@@ -77,7 +77,7 @@ export function registerStacks(pi, cwd) {
             "For the session; a pulse already running keeps the stack it started with. Without a name, says the stacks and the one chosen.",
         promptSnippet: "choose the stack - its testing scripts and settings - that everything is built with",
         promptGuidelines: [
-            "Switch the stack only when the user asks for it, and say which you chose. A module is built with the stack named after it by itself; to build one whose stack has another name, pass that stack as stack to regenerate, conform, glimpse or write_spec_diff instead: it is pinned to that module's pulses, and the session's choice stays as it is.",
+            "Switch the stack only when the user asks for it, and say which you chose. A module is built with the stack named after it by itself; to build one whose stack has another name, pass that stack as stack to regenerate, conform, glimpse or change_plain instead: it is pinned to that module's pulses, and the session's choice stays as it is.",
         ],
         parameters: Type.Object({
             name: Type.Optional(Type.String({ description: "The stack to choose, or none. Omitted: the stacks there are, and the one chosen" })),

package/dist/tools.js

@@ -164,7 +164,7 @@ export function createEndQuestionsTool(questioning) {
         label: "End questions",
         description: "End this phase's questions: you have asked what the person must decide, and you decide what is left " +
             "yourself, saying what you chose. Afterwards ask_user asks only the phase's closing confirmation, and " +
-            "write_spec_diff needs no answer between changes.",
+            "change_plain needs no answer between changes.",
         promptSnippet: "end this phase's questions and decide what is left yourself",
         parameters: Type.Object({}),
         async execute() {

package/docs/README.md

@@ -1,31 +1,31 @@
 # turri documentation
 
-turri implements regenerative software: the \*\*\*plain specs are the durable definition of what a system does, and the code is generated from them, validated against them, and regenerated as they change. The [project README](../README.md) says why, and how to install and start; these pages go into each part.
+turri is the first coding agent with the power of regenerative software: [\*\*\*plain](https://plainlang.org/docs/) captures the durable definition of what a system does, and the code is regenerated from it and validated against. The [project README](../README.md) says why, and how to install and start; these pages go into each part.
 
 ## Start here
 
 1. [Installation](installation.md) - get a machine ready: `turri doctor`, and what turri needs of this machine.
-2. [Using turri](using.md) - the conversation, the skills and tools, background jobs and their logs, choosing the model that renders, the command line.
-3. [Authoring \*\*\*plain](authoring-plain.md) - writing the specs: what a spec is made of, the authoring rules, the skills that write and fix specs.
-4. [Rendering](regenerating.md) - turning the specs into code: what each build does, in which order, and what has to pass before it moves on.
+2. [Using turri](using.md) - the conversation, the skills and tools, background jobs and their logs, choosing the model that codes, the command line.
+3. [Authoring \*\*\*plain](authoring-plain.md) - writing \*\*\*plain: what is it made out of, the authoring rules, the skills that write and fix it.
+4. [Regenerating](regenerating.md) - turning \*\*\*plain into code: what each build does, in which order, and what has to pass before it moves on.
 
 ## By question
 
 | to find out… | read |
 | --- | --- |
 | what my machine needs, and why a check failed | [installation](installation.md) |
-| what turri needs of this machine, and what `turri doctor` checks | [installation](installation.md#what-turri-setup-checks) |
+| what turri needs of this machine, and what `turri doctor` checks | [installation](installation.md#what-turri-doctor-checks) |
 | how to start a project, or add a feature, in a conversation | [using](using.md#in-a-conversation) |
-| which model renders, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
+| which model codes, and how to change it | [using](using.md#choosing-a-model), [the project config](config.md#models) |
 | what `config.turri.yaml` can set, and what happens without it | [the project config](config.md) |
 | how a backend and a frontend on different stacks share one project | [the project config](config.md#stacks) |
-| which ready-made stacks a spec can import - a FastAPI backend, a React frontend | [the standard library](authoring-plain.md#the-standard-library) |
+| which ready-made stacks \*\*\*plain can import - a FastAPI backend, a React frontend | [the standard library](authoring-plain.md#the-standard-library) |
 | everything an agent was sent and did, to debug it | [using](using.md#agent-logs) |
-| how to render a spec overnight, and resume it | [running unattended](headless.md) |
+| how to regenerate \*\*\*plain overnight, and resume it | [running unattended](headless.md) |
 | how to rebuild one functionality | [running unattended](headless.md#rebuilding-one-functionality) |
-| what goes in which section of a spec | [authoring \*\*\*plain](authoring-plain.md#what-a-spec-is-made-of) |
+| what goes in which section of \*\*\*plain | [authoring \*\*\*plain](authoring-plain.md#what-plain-is-made-of) |
 | which skill does what | [authoring \*\*\*plain](authoring-plain.md#the-skills) |
-| what happens when a spec changes | [regenerating the code](regenerating.md#when-the-spec-changes) |
+| what happens when \*\*\*plain changes | [regenerating the code](regenerating.md#when-plain-changes) |
 | why a test was not allowed to be deleted | [regenerating the code](regenerating.md#the-tests-must-actually-pass) |
 | how to try what is built, and what deploy may install | [deploy](deploy.md) |
 | what the agents can and cannot reach | [the sandbox](sandbox.md) |
@@ -42,9 +42,9 @@ turri implements regenerative software: the \*\*\*plain specs are the durable de
 | [Using turri](using.md) | the conversation, the tools, background jobs, choosing a model, module history, the command line |
 | [The project config](config.md) | `config.turri.yaml` and each stack's `config.turri.<stack>.yaml`: where they are read from, every key, models and their inheritance, conformance, the testing scripts, stacks and choosing one, the old `config.yaml` |
 | [Deploy](deploy.md) | trying what is built: dist/<module>, the last commit, starting it on your machine, `turri release` |
-| [Running unattended](headless.md) | rendering overnight or in CI: before you leave it, the command, the results, resuming, rebuilding one functionality |
-| [Authoring \*\*\*plain](authoring-plain.md) | a \*\*\*plain project, what a spec is made of, the rules, writing specs with the agent, the skills, checking a spec |
-| [Rendering](regenerating.md) | where things go, one job, a whole module and how its work is cut into jobs, each job's cases, spec changes, conformance tests, the two records of what is built |
+| [Running unattended](headless.md) | regenerating overnight or in CI: before you leave it, the command, the results, resuming, rebuilding one functionality |
+| [Authoring \*\*\*plain](authoring-plain.md) | a \*\*\*plain project, what \*\*\*plain is made of, the rules, writing \*\*\*plain with the agent, the skills, checking \*\*\*plain |
+| [Regenerating](regenerating.md) | where things go, one job, a whole module and how its work is cut into jobs, each job's cases, \*\*\*plain changes, conformance tests, the two records of what is built |
 | [The sandbox](sandbox.md) | what an agent can reach, the file-tool fence, the command check, the OS sandbox, the audit |
 | [Skills and gates](skills-and-gates.md) | the gate syntax, what the harness enforces, what a step can do, the rules, trying the gates |
 | [The \*\*\*plain parser](parser.md) | the TypeScript port, `turri validate`, inheritance, the iterator, fidelity |