@turri-dev/cli 0.1.4-next.246fd84 → 0.1.4-next.4342332

package/dist/regenerate/self-check.js

@@ -1,9 +1,9 @@
-import { readFileSync, writeFileSync } from "node:fs";
-import { join, relative, resolve, sep } from "node:path";
+import { readFileSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { workDiff } from "./lineage.js";
-import { lastPassingMs, runOnCode } from "./test-scripts.js";
+import { lastPassingMs, runOnCode, scriptsRunInPlace } from "./test-scripts.js";
 /**
  * Tools an agent checks its own work with, before the harness and the reviewer do: the diff the reviewer is shown, and
  * whether a test catches a change to the code. Neither decides anything - the testing scripts, run by the harness, still do.
@@ -43,16 +43,23 @@ export function canItFailLimitMs(buildDir, script) {
  */
 export function createCanItFailTool(options) {
     let left = options.runs ?? CAN_IT_FAIL_RUNS;
+    // In place, the change is made to the code itself for the run, and undone after it: the scripts run on the code there.
+    const inPlace = scriptsRunInPlace(options.buildDir);
     return defineTool({
         name: "can_it_fail",
         label: "Can it fail",
         description: "Check that the unit tests catch a bug: give one change to the code that breaks a behaviour the specification " +
             "states - a value or a status changed, a check taken out, a condition turned round where it cannot make a loop run for " +
             "ever - and the unit testing script " +
-            "runs on a copy of the code with that change. The code itself is never touched. The tests should fail; if they all " +
+            (inPlace
+                ? "runs with that change made to the code, which is put back as it was once the run ends, whatever its result. "
+                : "runs on a copy of the code with that change. The code itself is never touched. ") +
+            "The tests should fail; if they all " +
             "pass, no test catches that bug. Make a change that still builds and runs: a failure only because it no longer " +
             `compiles or imports says nothing about the tests. ${options.runs ?? CAN_IT_FAIL_RUNS} runs at most.`,
-        promptSnippet: "can_it_fail: whether the unit tests catch a bug you put in a copy of the code",
+        promptSnippet: "can_it_fail: whether the unit tests catch a bug you put in the code for one run",
+        // Never beside another call: in place, an edit made while the bug is in would be undone with it.
+        executionMode: "sequential",
         parameters: Type.Object({
             file: Type.String({ description: "The code file to change, relative to the code folder" }),
             find: Type.String({ description: "Text that is in the file exactly once - the code to change" }),
@@ -83,7 +90,7 @@ export function createCanItFailTool(options) {
             left -= 1;
             let run;
             try {
-                run = await runOnCode(options.buildDir, options.script, "unit testing script, with the change", (copy) => writeFileSync(join(copy, relative(options.buildDir, path)), text.slice(0, at) + replace + text.slice(at + find.length)), canItFailLimitMs(options.buildDir, options.script));
+                run = await runOnCode(options.buildDir, options.script, "unit testing script, with the change", { file: relative(options.buildDir, path), text: text.slice(0, at) + replace + text.slice(at + find.length) }, canItFailLimitMs(options.buildDir, options.script));
             }
             catch (error) {
                 return say(error instanceof Error ? error.message : String(error));

package/dist/regenerate/side-panel.js

@@ -16,7 +16,7 @@ export function createSidePanel(options) {
     const backKeys = () => {
         if (options.dock === undefined)
             return [`esc or ${options.key} back to the chat`];
-        return options.dock.docked() ? ["s full screen", "esc or ⌥⌘← to the chat", `${options.key} close`] : ["s beside the chat", `esc or ${options.key} back to the chat`];
+        return options.dock.docked() ? [`${options.key} or esc to the chat`, "ctrl+c close", "s full screen"] : ["s beside the chat", `esc or ${options.key} back to the chat`];
     };
     const waitingNote = () => 
     // A question asked while it showed waits in the chat, unanswered: the person is told it is there.

package/dist/regenerate/spec-map-view.js

@@ -52,7 +52,7 @@ export function tabBar(pages, shown, width, style, now) {
         const text = `${mark}${tabName(page)}`;
         if (page === shown)
             return style.heading(`[${text}]`);
-        return regenerating ? style.accent(text) : page.stuck ? style.error(text) : style.muted(text);
+        return regenerating ? style.accent(text) : page.stuck ? needs(style)(text) : style.muted(text);
     };
     const tabs = pages.map(label);
     const at = Math.max(0, shown === undefined ? 0 : pages.indexOf(shown));
@@ -69,6 +69,8 @@ export function tabBar(pages, shown, width, style, now) {
     }
     return truncateToWidth(lineOf(from, to), width, "…");
 }
+/** What needs the person - a stuck page, its `!` - in the warning colour: it waits on them, nothing is broken. */
+const needs = (style) => style.warning ?? style.error;
 /** Strike text through. */
 const strike = (text) => `\x1b[9m${text}\x1b[29m`;
 /** How far a group, and what is in it, is indented under its module. */
@@ -121,7 +123,7 @@ function rungGlyph(rung, style, now) {
     if (rung === "conform")
         return green(LADDER.conform);
     if (rung === "needsYou")
-        return style.error(LADDER.needsYou);
+        return needs(style)(LADDER.needsYou);
     if (rung === "takenOut")
         return style.error(LADDER.takenOut);
     if (rung === "toRegenerate")
@@ -329,7 +331,7 @@ function detailLines(item, width, style) {
     // The rest of its text - its first line is the row - against the record's, for a change.
     const rest = item.state === "changed" ? lineDiff(item.was ?? "", item.text).slice(1) : item.text.split("\n").slice(1).map((line) => ({ was: line, now: line }));
     for (const line of rest) {
-        const drawn = item.state === "removed" ? style.removed(strike(line.now ?? "")) : item.state === "changed" ? diffLine(line, style) : item.state === "new" ? style.added(line.now ?? "") : highlighted(line.now ?? "", style);
+        const drawn = item.state === "removed" ? style.removed(strike(line.now ?? "")) : item.state === "changed" ? diffLine(line, style) : highlighted(line.now ?? "", style);
         lines.push(...wrapped(drawn, width));
     }
     if (item.acceptance.length > 0) {
@@ -476,9 +478,7 @@ export function specMapLines(pages, state, width, style, _jobs = [], now = Date.
             ? style.removed(strike(first))
             : item.state === "changed" && wasFirst !== first
                 ? wordDiff(wasFirst, first, style)
-                : item.state === "new"
-                    ? style.added(first)
-                    : highlighted(first, style);
+                : highlighted(first, style);
         // Wrapped, never cut short: what follows a `…` is what a person came to read. The lines after the first hang
         // under the item's text, past its bullet.
         const [head = "", ...rest] = hanging(drawn, first, room);
@@ -488,7 +488,7 @@ export function specMapLines(pages, state, width, style, _jobs = [], now = Date.
         // The first item that needs the person says what for, and how to go about it - opened or closed.
         if (page.stuck && !toldWhy && rungOf(item) === "needsYou") {
             toldWhy = true;
-            for (const line of wrapped(needsLine(page), width, style.error))
+            for (const line of wrapped(needsLine(page), width, needs(style)))
                 add(line, mark);
         }
         if (state.open.has(row.key)) {
@@ -517,7 +517,9 @@ function paintOf(mark, style) {
         return style.success ?? style.added;
     if (mark === "regenerating" || mark === "planning")
         return style.accent;
-    if (mark === "stuck" || mark === "removed")
+    if (mark === "stuck")
+        return needs(style);
+    if (mark === "removed")
         return style.error;
     return style.muted;
 }
@@ -550,7 +552,7 @@ export function specMapHeader(page, width, style, waiting = "") {
     const strip = progressStrip(page, style);
     const count = total > 0 ? `${built} of ${total} ${total === 1 ? "functionality" : "functionalities"} built · ` : "";
     // Short, never cut off: what for, and how, is under the first `!`.
-    const status = page.stuck ? style.error(`${LADDER.needsYou} needs you`) : page.status;
+    const status = page.stuck ? needs(style)(`${LADDER.needsYou} needs you`) : page.status;
     // The module's file heads its column, under this line.
     return truncateToWidth(`${style.heading("regen")}${strip !== "" ? `  ${strip}` : ""}  ${count}${status}${waiting}`, width);
 }

package/dist/regenerate/test-scripts.js

@@ -297,6 +297,10 @@ export function setScriptTimeoutForTests(ms) {
  * own paths start - and whether they run on the code in place (the default), rather than on a fresh copy
  * (`testing-scripts-run-on: copy`).
  */
+/** Whether the testing scripts run on the code in `buildDir` itself, not on a copy of it. */
+export function scriptsRunInPlace(buildDir) {
+    return projectOfBuild(buildDir).inPlace;
+}
 function projectOfBuild(buildDir) {
     const parts = resolve(buildDir).split(sep);
     const index = parts.lastIndexOf("plain_modules");
@@ -401,30 +405,70 @@ const lastPassing = new Map();
 export function lastPassingMs(buildDir, script) {
     return lastPassing.get(`${resolve(buildDir)}\n${script}`);
 }
+/** Files changed in place for a run under way, and what each held: put back however the run ends - the process exiting too. */
+const changedInPlace = new Map();
+let restoreOnExit = false;
+function putBack(path) {
+    const original = changedInPlace.get(path);
+    if (original === undefined)
+        return;
+    writeFileSync(path, original);
+    changedInPlace.delete(path);
+}
+/**
+ * `run` with `change` made to the code itself, and undone once it ends - passed, failed, timed out, thrown, or the process
+ * exiting. Killed outright, the change is left: the next unit of work starts from the last commit (lineage.ts startWork).
+ */
+async function withChangeInPlace(buildDir, change, run) {
+    const path = resolve(buildDir, change.file);
+    if (changedInPlace.has(path))
+        throw new Error(`${change.file} is being changed for another run already.`);
+    if (!restoreOnExit) {
+        restoreOnExit = true;
+        process.once("exit", () => {
+            for (const changed of [...changedInPlace.keys()])
+                putBack(changed);
+        });
+    }
+    changedInPlace.set(path, readFileSync(path));
+    try {
+        writeFileSync(path, change.text);
+        return await run();
+    }
+    finally {
+        putBack(path);
+    }
+}
 /**
- * A script that takes the code folder - the unit testing script - run where the testing scripts
- * run. `change`: what to do to the fresh copy before it runs - only where there is a copy; never in place.
+ * A script that takes the code folder - the unit testing script - run where the testing scripts run. `change`: one file
+ * as it is for this run - made to the fresh copy, or, in place, to the code itself and undone once the run ends.
  */
 export async function runOnCode(buildDir, script, what, change, 
 /** A time limit of its own, in place of a test run's. */
 limitMs) {
     const project = projectOfBuild(buildDir);
+    const passed = (run, started) => {
+        if (change === undefined && run.exitCode === 0)
+            lastPassing.set(`${resolve(buildDir)}\n${script}`, Date.now() - started);
+        return run;
+    };
     if (project.inPlace) {
-        if (change !== undefined)
-            throw new Error("This runs only where the testing scripts run on a copy: here they run in place, on the code itself.");
-        return runScript(project.root, script, [resolve(buildDir)], buildDir);
+        const inPlace = () => runScript(project.root, script, [resolve(buildDir)], buildDir, limitMs !== undefined ? { limitMs } : {});
+        const started = Date.now();
+        if (change === undefined)
+            return passed(await inPlace(), started);
+        reportActivity(`  changing ${change.file} in place for the ${what} - put back once it has run`);
+        return withChangeInPlace(buildDir, change, inPlace);
     }
     const staging = stagingFor(buildDir);
     rmSync(staging.root, { recursive: true, force: true });
     ensureInModulesScratch(buildDir, staging.root);
     try {
         reportActivity(`  copying ${stageBuild(buildDir, staging.build)} files of the code for the ${what}`);
-        change?.(staging.build);
+        if (change !== undefined)
+            writeFileSync(join(staging.build, change.file), change.text);
         const started = Date.now();
-        const run = await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs);
-        if (change === undefined && run.exitCode === 0)
-            lastPassing.set(`${resolve(buildDir)}\n${script}`, Date.now() - started);
-        return run;
+        return passed(await runOnCopy(staging.root, script, [staging.build], buildDir, limitMs), started);
     }
     finally {
         rmSync(staging.root, { recursive: true, force: true });

package/dist/regenerate/unit-review.js

@@ -96,7 +96,7 @@ export function unitReviewTask(options) {
                 "  assertion so loose any answer passes, an expected value computed the way the code computes it.",
                 ...(options.canItFail === true
                     ? [
-                        "- A test you doubt can fail, check: can_it_fail puts a bug in a copy of the code - a condition turned round, a",
+                        "- A test you doubt can fail, check: can_it_fail puts a bug in the code for one run - a condition turned round, a",
                         "  value changed - and runs the unit tests on it. A test that still passes cannot fail: raise it as bad, with the",
                         `  bug it missed. ${REVIEWER_CAN_IT_FAIL_RUNS} runs a session: spend them on the tests the work rests on.`,
                     ]

package/dist/regenerate-cli.js

@@ -19,10 +19,15 @@ its conformance tests too when they are on.
   --start-over             start over, without asking, a codebase regenerated without a module it now requires -
                            with no terminal to ask and without it, the run stops there
   --from-scratch           delete the module's code and conformance tests (its lineage keeps them) and regenerate all of it
+  --from-scratch-chain     the same for every module of its requires chain, built again from the bottom - after
+                           modules were split or moved
   --harness-model <p/id>   config.turri.yaml's harness-model for this run: the planner and the conformance chooser
   --coding-model <p/id>    its coding-model, --model too: the agents that build; p/id:level for how hard a model thinks
   --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
+  --mutation-testing <true|false>
+                           its mutation-testing: whether the coding agent and the reviewer can put a bug in the code
+                           for one test run (can_it_fail), to see that a test catches it
   --conformance-tests <all|chosen|module|false>
                            its conformance-tests: which conformance tests are written and run
   --build-dir <dir>        as the run ends, however it ends, export the code there: the furthest-built codebase's
@@ -31,7 +36,7 @@ its conformance tests too when they are on.
                            as it starts, as each pulse ends and as it exits (docs/headless.md)
 
   PLAIN_TEMPLATE_DIRS      colon-separated template directories`;
-const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review"]);
+const { positional, options } = parseArgs(process.argv.slice(2), ["--dry-run", "--start-over", "--from-scratch", "--from-scratch-chain"], USAGE, ["--build-dir", "--report", "--conformance-tests", "--harness-model", "--judge-model", "--review", "--mutation-testing"]);
 const { report, buildDir } = headlessOptions(options, true);
 const named = positional[0] ?? readProjectConfig(process.cwd()).module;
 // Functional specs named after the file: regenerated again though their spec did not change.
@@ -40,9 +45,10 @@ if (!named) {
     console.error(`${USAGE}\n\nNo file given, and ${CONFIG_FILE} names no module.`);
     process.exit(1);
 }
+const scratch = options["from-scratch-chain"] !== undefined ? "chain" : options["from-scratch"] !== undefined ? "module" : undefined;
 // A dry run starts nothing, and from scratch deletes before it plans: the two do not go together.
-if (options["from-scratch"] !== undefined && options["dry-run"] !== undefined) {
-    console.error("--from-scratch deletes the module's code before anything is planned: it cannot be a dry run.");
+if (scratch !== undefined && options["dry-run"] !== undefined) {
+    console.error(`--from-scratch${scratch === "chain" ? "-chain" : ""} deletes the code before anything is planned: it cannot be a dry run.`);
     process.exit(1);
 }
 runLoop({
@@ -54,8 +60,8 @@ runLoop({
     startOver: options["start-over"] !== undefined,
     ask: (loop) => again.length > 0
         ? loop.regenerateAgain(named, again)
-        : options["from-scratch"] !== undefined
-            ? loop.fromScratch(named)
+        : scratch !== undefined
+            ? loop.fromScratch(named, { chain: scratch === "chain" })
             : loop.bringUp(named),
 }).catch((error) => {
     console.error(error instanceof Error ? error.message : error);

package/dist/release-cli.js

@@ -4,6 +4,7 @@ import { configForSpec, modelSpec, projectModels, readProjectConfig } from "./co
 import { createDeployState } from "./release-tools.js";
 import { runReleaseAgent } from "./release-agent.js";
 import { listDeployed, runningDeployed, stopDeployed } from "./regenerate/release.js";
+import { c } from "./module-report.js";
 const USAGE = `usage: turri release [file.plain] [options]
 
 Releases the module on top of the spec's requires chain, which holds the code of the ones below, and
@@ -20,12 +21,6 @@ harness-model (the agent's model).
   --in-module <module>     the codebase to take, when modules built on this one branch
   --guidance <text>        how this project releases it: the scripts to run, in order
   --model <provider/id>    the agent's model (default: harness-model)`;
-const c = {
-    dim: (s) => `\x1b[2m${s}\x1b[0m`,
-    bold: (s) => `\x1b[1m${s}\x1b[0m`,
-    green: (s) => `\x1b[32m${s}\x1b[0m`,
-    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
-};
 const PROBLEMS = "If you are having problems, use chat mode to deploy: run turri and ask to try it.";
 function parseArgs(argv) {
     const positional = [];
@@ -76,7 +71,7 @@ function followLogs() {
                 closeSync(fd);
                 offsets.set(item.log, size);
                 for (const line of buffer.toString("utf8").split("\n").filter((l) => l !== ""))
-                    console.log(`${c.cyan(`[${item.name}]`)} ${line}`);
+                    console.log(`${c.accent(`[${item.name}]`)} ${line}`);
             }
             if (running.length === 0) {
                 clearInterval(timer);
@@ -119,7 +114,7 @@ async function main() {
     console.log(`\n\n${c.dim(PROBLEMS)}`);
     if (runningDeployed().length === 0)
         process.exit(0);
-    console.log(c.green(c.bold("\nRunning - Ctrl-C stops it.")) + c.dim(" Its output follows.\n"));
+    console.log(c.success(c.bold("\nRunning - Ctrl-C stops it.")) + c.dim(" Its output follows.\n"));
     await followLogs();
     process.exit(0);
 }

package/dist/review/live.js

@@ -79,7 +79,8 @@ export function createLiveReviewer(opts) {
             pending.push(finding);
             all.push(finding);
         }
-        if (violations.length === 0) {
+        // No verdict - its turn stopped before it gave one - clears nothing: the scope is looked at again next pass.
+        if (captured !== undefined && violations.length === 0) {
             cleared.push(scope);
         }
         else if (captured?.question) {

package/dist/run-report.js

@@ -22,6 +22,9 @@ const emptyTotals = () => ({
     llm_calls: 0,
     agent_turns: 0,
     compactions: 0,
+    provider_retries: 0,
+    provider_stalls: 0,
+    turns_stopped: 0,
     model_seconds: 0,
 });
 function addUsage(totals, usage) {
@@ -43,8 +46,14 @@ function addEvent(totals, event, tokens) {
     }
     else if (event.kind === "turn")
         totals.agent_turns += 1;
-    else
+    else if (event.kind === "compaction")
         totals.compactions += 1;
+    else if (event.kind === "provider_retry")
+        totals.provider_retries += 1;
+    else if (event.kind === "provider_stall")
+        totals.provider_stalls += 1;
+    else
+        totals.turns_stopped += 1;
 }
 function sumTotals(a, b) {
     const sum = emptyTotals();
@@ -181,6 +190,32 @@ export function startRunReport(options) {
             list,
         };
     };
+    /** The spec gaps the pulses' agents met, in the order the pulses started: questions a person would want to decide. */
+    const specGapsOf = (jobs) => jobs.flatMap((job) => {
+        const details = job.details;
+        return (details?.specGaps ?? []).map((gap) => ({
+            module: job.module ?? null,
+            pulse: job.pulse ?? null,
+            pulse_id: job.id,
+            landed: job.status === "succeeded" && details?.landed === true,
+            question: gap.question,
+            assumption: gap.assumption,
+        }));
+    });
+    /** Each request the provider failed and was waited out or stalled on, and each turn turri ended itself: why, and where. */
+    const turnIncidentsOf = () => events
+        .filter((event) => event.kind === "provider_retry" || event.kind === "provider_stall" || event.kind === "stopped")
+        .map((event) => ({
+        kind: event.kind,
+        pulse_id: event.job ?? null,
+        role: event.role ?? null,
+        model: event.model ?? null,
+        ...(event.kind === "stopped"
+            ? { reason: event.reason ?? null }
+            : event.kind === "provider_stall"
+                ? { silent_seconds: Math.round((event.waitMs ?? 0) / 1000) }
+                : { error: event.error ?? null, attempt: event.attempt ?? null, of: event.of ?? null, wait_seconds: Math.round((event.waitMs ?? 0) / 100) / 10 }),
+    }));
     const functionalitiesOf = (counts) => {
         if (counts === undefined)
             return null;
@@ -228,6 +263,7 @@ export function startRunReport(options) {
             build_dir: options.buildDir !== undefined ? resolve(options.buildDir) : null,
             conformance_tests: options.conformanceTests,
             review: options.review ?? null,
+            mutation_testing: options.mutationTesting ?? null,
             models: {
                 ...Object.fromEntries(Object.entries(options.models).map(([role, choice]) => [role, { model: choice.model ?? null, thinking: choice.thinking ?? null }])),
                 observed: Object.fromEntries([...new Set(events.map((event) => event.role ?? "unknown"))].sort().map((role) => [role, [...new Set(events.filter((event) => (event.role ?? "unknown") === role).map((event) => event.model ?? "unknown"))].sort()])),
@@ -245,6 +281,8 @@ export function startRunReport(options) {
             usage: usageOf(jobs),
             pulses: pulsesOf(jobs, now),
             functionalities: functionalitiesOf(attempt(sources.completion)),
+            spec_gaps: specGapsOf(jobs),
+            turn_incidents: turnIncidentsOf(),
             ...(exitParts ?? {}),
             logs: {
                 jobs_dir: fromProject(join(projectRoot, ".turri", "jobs")),

package/dist/validate-cli.js

@@ -1,4 +1,5 @@
 import { checkPlainTargets, formatCheckResults } from "./plain/check.js";
+import { c } from "./module-report.js";
 const USAGE = `usage: turri validate <file.plain | directory> [options]
 
 Validates a ***plain specification statically: parses it, resolves its imports and
@@ -8,12 +9,6 @@ required modules, and reports every error without rendering anything.
   --json                 machine-readable output
 
   PLAIN_TEMPLATE_DIRS    colon-separated template directories`;
-const c = {
-    dim: (s) => `\x1b[2m${s}\x1b[0m`,
-    bold: (s) => `\x1b[1m${s}\x1b[0m`,
-    green: (s) => `\x1b[32m${s}\x1b[0m`,
-    red: (s) => `\x1b[31m${s}\x1b[0m`,
-};
 const argv = process.argv.slice(2);
 const templateDirs = [];
 const positional = [];
@@ -43,10 +38,10 @@ if (json) {
 else {
     const output = formatCheckResults(results)
         .split("\n")
-        .map((line) => line.startsWith("PASS") ? c.green(line) : line.startsWith("FAIL") ? c.red(line) : c.dim(line))
+        .map((line) => line.startsWith("PASS") ? c.success(line) : line.startsWith("FAIL") ? c.error(line) : c.dim(line))
         .join("\n");
     console.log(output);
     const failed = results.filter((r) => !r.ok).length;
-    console.log(`\n${failed === 0 ? c.green(c.bold("all specs valid")) : c.red(c.bold(`${failed} of ${results.length} failed`))}`);
+    console.log(`\n${failed === 0 ? c.success(c.bold("all specs valid")) : c.error(c.bold(`${failed} of ${results.length} failed`))}`);
 }
 process.exit(results.every((r) => r.ok) ? 0 : 1);

package/docs/README.md

@@ -1,20 +1,13 @@
 # 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 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.
 
 ## 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.
+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.
 
 ## By question