@turri-dev/cli 0.1.5-next.6df6879 → 0.1.6-next.056c770

package/.pi/themes/turri-dark.json

@@ -45,7 +45,7 @@
     "mdHeading": "white",
     "mdLink": "neon",
     "mdLinkUrl": "path",
-    "mdCode": "siestaTan",
+    "mdCode": "neonHover",
     "mdCodeBlock": "white",
     "mdCodeBlockBorder": "lines",
     "mdQuote": "grauzone",

package/README.md

@@ -190,7 +190,7 @@ Start at the [documentation index](docs/README.md), or go straight to a page:
 | | |
 | --- | --- |
 | [Installation](docs/installation.md) | doctor, what turri needs of this machine, **turri** and `pi`, environment variables |
-| [Examples](examples/README.md) | projects to build with turri step by step: cognio from an empty folder, a CLI, a backend service with conformance tests, a REST API integration |
+| [Examples](examples/README.md) | projects to build with turri step by step: cognio from an empty folder, guestbook - a backend and a frontend in minutes - a CLI, a backend service with conformance tests, a REST API integration |
 | [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 |

package/dist/cli.js

@@ -19,7 +19,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { CODING_MODEL_ENV, chatModels } from "./chat-models.js";
 import { readProjectConfig } from "./config.js";
-import { extensionInstalledGlobally, PACKAGE_ROOT, themesInstalledGlobally } from "./environment.js";
+import { extensionInstalledGlobally, PACKAGE_ROOT, themesInstalledGlobally, versionLine } from "./environment.js";
 import { dropNoise } from "./quiet.js";
 /**
  * Start pi with this project's extension and themes already wired in.
@@ -92,6 +92,7 @@ const SETUP_COMMANDS = {
 const USAGE = [
     "usage: turri [options]          open the conversation here: pi, with turri's tools and themes loaded",
     "       turri <command> [args]",
+    "       turri --version          turri's version, and pi's",
     "",
     `  ${"options".padEnd(12)} --harness-model <m>  the model you chat with   --coding-model <m>  the model renders run on`,
     `  ${"".padEnd(12)} --stack <name>  build with config.turri.<name>.yaml over config.turri.yaml - here and in every command`,
@@ -139,6 +140,11 @@ if (command === "-h" || command === "--help") {
     console.log(USAGE);
     process.exit(0);
 }
+// turri's version, not pi's alone: pi's --version would answer for it.
+if (command === "-v" || command === "--version") {
+    console.log(versionLine());
+    process.exit(0);
+}
 // turri alone is the conversation, and so is turri with pi's options - `turri -c`, `turri --harness-model <m>`. A word
 // turri does not know is an error below, not a conversation started on it.
 if (command === undefined || command.startsWith("-"))

package/dist/config.js

@@ -1,6 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { copyFileSync, existsSync, readdirSync, readFileSync, statSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { load as loadYaml } from "js-yaml";
 import { projectDirOf } from "./regenerate/paths.js";
 /**
@@ -157,6 +157,22 @@ export function chooseStack(stack) {
 export function withStack(stack, work) {
     return pinnedStack.run({ stack }, work);
 }
+/** Whether a stack is pinned here - named by the call that asked for the work, or kept by the pulse it runs in. */
+export function stackPinned() {
+    return pinnedStack.getStore() !== undefined;
+}
+/**
+ * The stack a module is built with: the one pinned - named by the call, or kept by the pulse - else the stack named
+ * after the module, config.turri.backend.yaml for backend.plain, else the one chosen for the session; none, when none
+ * of them is.
+ */
+export function stackForModule(plainFile) {
+    const root = projectDirOf(resolve(plainFile));
+    if (stackPinned())
+        return stackOf(root);
+    const own = basename(plainFile).replace(/\.plain$/, "");
+    return stacksOf(root).includes(own) ? own : stackOf(root);
+}
 /** The words that choose no stack: the project's config alone. */
 export const NO_STACK = ["none", "off", "base", "-"];
 /**
@@ -478,10 +494,10 @@ function agentEnvSetting(value) {
 function withoutUndefined(config) {
     return Object.fromEntries(Object.entries(config).filter(([, value]) => value !== undefined));
 }
-/** The config a spec is built with: its project's, with the stack chosen over it. */
+/** The config a spec is built with: its project's, with its module's stack over it (`stackForModule`). */
 export function configForSpec(plainFile) {
     const root = projectDirOf(resolve(plainFile));
-    return readProjectConfig(root, stackOf(root));
+    return readProjectConfig(root, stackForModule(plainFile));
 }
 /** One config file, read, or nothing of it when it is not there or does not parse. */
 function readConfigFile(path) {

package/dist/environment.js

@@ -68,6 +68,32 @@ export function turriOnPath() {
     const found = which.status === 0 ? which.stdout.trim().split("\n")[0] : undefined;
     return found === "" ? undefined : found;
 }
+/** The version of the pi turri runs on, as Node finds it - undefined when it is not installed. */
+export function piVersion() {
+    try {
+        // Its entry point, then up to the package.json that names it.
+        for (let dir = dirname(fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"))); dirname(dir) !== dir; dir = dirname(dir)) {
+            const file = join(dir, "package.json");
+            if (!existsSync(file))
+                continue;
+            const pkg = JSON.parse(readFileSync(file, "utf8"));
+            if (pkg.name === "@earendil-works/pi-coding-agent")
+                return pkg.version;
+        }
+    }
+    catch {
+        /* not installed: left out */
+    }
+    return undefined;
+}
+/**
+ * What `turri --version` prints: turri's version - from a clone, its commit too, as the banner says it - and pi's
+ * beside it. pi's own `--version` says only pi's, which read as turri's.
+ */
+export function versionLine(identity = turriIdentity(), pi = piVersion() ?? null) {
+    const clone = identity.git_commit !== null ? `, from a clone, ${identity.git_commit.slice(0, 7)}${identity.git_dirty === true ? " with changes" : ""}` : "";
+    return `turri ${identity.version ?? "0.0.0"}${clone}${pi !== null ? ` (pi ${pi})` : ""}`;
+}
 /** turri's version, and the commit when it runs from a clone. */
 export function turriIdentity() {
     let version = null;

package/dist/extension.js

@@ -1041,7 +1041,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 - a backend's spec with the backend stack: pass it as stack to regenerate, conform and glimpse, and it is pinned to that module's pulses, whatever is chosen after. Choose one for the whole session with the stack tool 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 write_spec_diff. 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) => [

package/dist/loop-tools.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { basename, relative, resolve } from "node:path";
 import { defineTool } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { chosenStack, CONFIG_FILE, readProjectConfig, stackConfigFile, stackNamed, stackOf, stacksOf, withStack } from "./config.js";
+import { CONFIG_FILE, readProjectConfig, stackConfigFile, stackForModule, stackNamed, stacksOf, withStack } from "./config.js";
 import { checkPlainFile } from "./plain/check.js";
 import { describeDrift, describeModules } from "./regenerate/loop.js";
 import { pulseName } from "./regenerate/jobs.js";
@@ -28,29 +28,38 @@ export const MODEL_PARAM = Type.Optional(Type.String({
 export const STACK_PARAM = Type.Optional(Type.String({
     description: "In a project of stacks: the stack that builds this module - its config.turri.<stack>.yaml over config.turri.yaml, " +
         "its testing scripts, toolchains and models - for every pulse of it, whatever stack is chosen later. \"none\": " +
-        "config.turri.yaml alone. Omitted: the stack chosen now.",
+        "config.turri.yaml alone. Omitted: the stack named after the module - config.turri.backend.yaml for backend.plain - " +
+        "else the one chosen now.",
 }));
 /**
- * `work` with the stack a call names - or, none named, the one chosen now - chosen for it: what it asks for is built with
- * that stack. A project of stacks that would be built with none, when config.turri.yaml alone names no unit testing
- * script, is refused before anything is planned: its pulses would all stop for want of one.
+ * Why a module asked for with no stack named cannot be built: a project of stacks where it has no stack of its own and
+ * none is chosen, and config.turri.yaml alone names no unit testing script - every pulse would stop for want of one.
+ * The stacks and the script each names, and what to do. Undefined when it can be built.
  */
-export function withCallStack(plainFile, named, work) {
+export function stacklessBuild(plainFile) {
     const root = projectDirOf(plainFile);
-    const stack = named !== undefined ? stackNamed(root, named) : chosenStack();
-    return withStack(stack, () => {
-        const stacks = stacksOf(root);
-        if (named === undefined && stackOf(root) === undefined && stacks.length > 0 && findTestScripts(root).unit === undefined) {
-            const scripts = stacks.map((each) => {
-                const unit = withStack(each, () => findTestScripts(root).unit);
-                return `${each}${unit !== undefined ? ` (${stackConfigFile(each)}: ${relative(root, unit)})` : ""}`;
-            });
-            throw new Error(`Nothing was started: ${basename(plainFile)} would be built with no stack - ${CONFIG_FILE} alone - and that names no unit testing ` +
-                `script, so every pulse would stop. The project's stacks: ${scripts.join(", ")}. Pass the stack that builds ` +
-                `${basename(plainFile)} as stack - or ask the user which, when the spec does not make it plain.`);
-        }
-        return work();
+    const stacks = stacksOf(root);
+    if (stacks.length === 0 || stackForModule(plainFile) !== undefined || findTestScripts(root).unit !== undefined)
+        return undefined;
+    const scripts = stacks.map((each) => {
+        const unit = withStack(each, () => findTestScripts(root).unit);
+        return `${each}${unit !== undefined ? ` (${stackConfigFile(each)}: ${relative(root, unit)})` : ""}`;
     });
+    return (`${basename(plainFile)} would be built with no stack - ${CONFIG_FILE} alone - and that names no unit testing script, so every ` +
+        `pulse would stop. No stack is named after it, and none is chosen. The project's stacks: ${scripts.join(", ")}. Pass the ` +
+        `stack that builds ${basename(plainFile)} as stack - or ask the user which, when the spec does not make it plain.`);
+}
+/**
+ * `work` with the stack a call names chosen for it - or, none named, as it is: each module is then built with its own
+ * (`stackForModule`). A module that could not be built that way is refused before anything is planned (`stacklessBuild`).
+ */
+export function withCallStack(plainFile, named, work) {
+    if (named !== undefined)
+        return withStack(stackNamed(projectDirOf(plainFile), named), work);
+    const stackless = stacklessBuild(plainFile);
+    if (stackless !== undefined)
+        throw new Error(`Nothing was started: ${stackless}`);
+    return work();
 }
 export const WAIT_PARAM = Type.Optional(Type.Boolean({
     description: "Block until the work finishes instead of returning a pulse id. Defaults to false in the " +
@@ -164,7 +173,7 @@ export function regenerateTool(options) {
             "A change to a file the spec links - an API surface, a mapping document - is a change to the spec: regenerate sees it by itself, and regenerates every functional spec that uses what links it.",
             "Never stop pulses and start them again yourself to follow a spec change: regenerate does it.",
             "Set from_scratch only when the user asks for the module to be regenerated from scratch - started over, its code deleted - in this conversation, or agrees to it when a module's status says it has to start over: never to fix a pulse that did not land.",
-            "In a project of stacks - a backend and a frontend, each with its config.turri.<stack>.yaml - pass stack: the one that builds this module's part, the backend's spec with the backend stack. It is pinned to the module's pulses: regenerate a backend and a frontend side by side, each with its own, without switching the stack chosen. What it says back names the stack each module is built with.",
+            "In a project of stacks - a backend and a frontend, each with its config.turri.<stack>.yaml - a module is built with the stack named after it by itself: backend.plain with config.turri.backend.yaml. Pass stack only for a module whose stack has another name. It is pinned to the module's pulses: a backend and a frontend regenerate side by side, each with its own, without switching the stack chosen. What it says back names the stack each module is built with.",
             'from_scratch "module" takes out the code where the module is built; the modules below keep theirs, and the module starts from a copy of the code below it. "chain" takes out every codebase of its requires chain, the base\'s too, and builds all of it again from the bottom: use it after modules were split, merged or moved (refactor-module), or when the user asks for the whole chain.',
         ],
         parameters: Type.Object({

package/dist/regenerate/loop.js

@@ -13,7 +13,7 @@ import { adoptDigests, chainTree, codeTree, conformanceTarget, REGENERATE_AGAIN,
 import { describeSpecDiffConformance, renderSpecDiffConformance } from "./conform.js";
 import { conformanceDirFor } from "./conformance.js";
 import { modulesRoot } from "./paths.js";
-import { budgetFor, chosenStack, choosingWhen, configForSpec, conformanceSwitchedOn, withStack } from "../config.js";
+import { budgetFor, choosingWhen, configForSpec, conformanceSwitchedOn, stackForModule, stackPinned, withStack } from "../config.js";
 import { describeSpecChange } from "./prompt.js";
 import { resolveTemplateDirs } from "./paths.js";
 import { builtTips, copyRequiredCode, importingModules, isImportModule, newlyRequired, resolveRequiresChain, startFromScratch } from "./requires.js";
@@ -1032,8 +1032,8 @@ export function createWorkLoop(options) {
         return { status, jobs: (state.running !== undefined ? listed.slice(1) : listed).map((item) => item.job), scheduled: (state.running !== undefined ? listed.slice(1) : listed).map((item) => (item.entry.waitsFor !== undefined ? { title: item.entry.title, specs: item.entry.cases.add.map((touched) => touched.text) } : undefined)) };
     };
     /**
-     * Look after a codebase - its chain up to it - from now on; says its state. `pin`: the stack it is built with from now
-     * on - kept, when `keep` and it has one already.
+     * Look after a codebase - its chain up to it - from now on; says its state. `pin`: its stack is worked out again - its
+     * tip's (`stackForModule`) - unless `keep`, and it has one: a spec change keeps the stack it was asked for with.
      */
     const track = (chain, askedFile, request, pin) => {
         const tip = tipOf(chain);
@@ -1050,8 +1050,10 @@ export function createWorkLoop(options) {
         }
         state.chain = chain;
         state.askedFile = askedFile;
-        if (pin !== undefined && (pin.keep !== true || state.stack === undefined))
-            state.stack = { name: pin.name };
+        // Kept only when it is a stack: a module pinned to none - built before its stack's file was there - takes its own.
+        const keep = pin?.keep === true && !stackPinned() && state.stack?.name !== undefined;
+        if (pin !== undefined && !keep)
+            state.stack = { name: stackForModule(tip.plainFile) };
         // Its model as its stack has it: a stack's file can name a coding model of its own.
         const model = request.model ?? inStack(state, () => options.modelFor?.(tip.plainFile));
         if (model !== undefined)
@@ -1066,9 +1068,9 @@ export function createWorkLoop(options) {
             const files = codebasesOf(resolve(options.cwd, plainFile));
             for (const file of files)
                 asked.set(file, { ...asked.get(file), ...request });
-            // Asked for, it is built with the stack chosen now - pinned, whatever is chosen later; a spec change keeps the one
-            // it was asked for with.
-            const pin = { name: chosenStack(), keep: specChange === true };
+            // Asked for, it is built with its stack - the one the call names, its own, or the one chosen now - pinned, whatever
+            // is chosen later; a spec change keeps the one it was asked for with.
+            const pin = { keep: specChange === true };
             const states = withParseCache(() => files.flatMap((file) => chainsFor(file).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request, pin)))));
             // Asked again, a halted codebase is tried again - one the person halted too, unless only its spec changed.
             for (const state of states) {
@@ -1191,7 +1193,7 @@ export function createWorkLoop(options) {
                     }
                 }
             }
-            const tracked = withParseCache(() => (wentBack ? [own] : chainsFor(file)).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request, { name: chosenStack() }))));
+            const tracked = withParseCache(() => (wentBack ? [own] : chainsFor(file)).flatMap((chain) => toBuild(chain).map((entry) => track(chain.slice(0, chain.indexOf(entry) + 1), file, request, {}))));
             // The module asked for, in its own codebase - and those below it: never the codebases built on it.
             const asking = tracked.find((state) => tipEntry(state).buildDir === self.buildDir);
             const states = asking !== undefined ? tracked.filter((state) => own.some((entry) => entry.buildDir === tipEntry(state).buildDir)) : tracked;

package/dist/spec-tools.js

@@ -8,6 +8,9 @@ import { applySpecDiff, plainFilesOf, revertSpecDiff } from "./regenerate/regene
 import { MissingFunctionalitiesError } from "./plain/errors.js";
 import { describeModules } from "./regenerate/loop.js";
 import { reviewNote } from "./tools.js";
+import { STACK_PARAM, stacklessBuild, withCallStack } from "./loop-tools.js";
+import { stackNamed } from "./config.js";
+import { projectDirOf } from "./regenerate/paths.js";
 /**
  * Writing a spec change as a diff, and building it, as one step.
  *
@@ -37,12 +40,14 @@ export function createSpecDiffTools(options) {
             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.",
+            "In a project of stacks, the change is built with the stack named after the module - backend.plain with config.turri.backend.yaml - by itself. For a module whose stack has another name, pass it as stack. A change that cannot be built yet for want of a stack is written all the same: carry on, and pass the stack with the next change.",
             "To take something out of what is already written and queued - the user drops a page or a feature - write the diff that removes it from every spec that names it, with fixes_earlier. What is left to build is worked out from the spec each time, and a build the change undoes is stopped by itself; never stop builds to drop a change - it stays in the files.",
         ],
         parameters: Type.Object({
             plain_file: Type.String({ description: "The .plain file of the module the change is built for" }),
             diff: Type.String({ description: "The change, as a git diff (diff --git a/<file> b/<file> ...)" }),
             fixes_earlier: Type.Optional(Type.Boolean({ description: "This corrects something already written - a contradiction, a review finding" })),
+            stack: STACK_PARAM,
             guidance: Type.Optional(Type.String({
                 description: "How to plan the queue for this change, in a sentence or two - which functional specs go together, what first - as the " +
                     "user said it or as the interview settled it. A strong preference for the planner. Omit when there is none.",
@@ -87,12 +92,25 @@ export function createSpecDiffTools(options) {
                 answeredSinceLastDiff = false;
             owed = false;
             liveReview?.notice(`${params.plain_file}, after the change to ${touched.join(", ")}`);
-            // In the files, the change is work: the loop works out what is left to build and plans it.
-            // A spec change, not a request: a module the person halted stays halted.
-            const statuses = await loop.bringUp(params.plain_file, { specChange: true, ...(params.guidance !== undefined ? { guidance: params.guidance } : {}) });
+            // In the files, the change is work: the loop works out what is left to build and plans it - with the stack the call
+            // names, else the module's own. A spec change, not a request: a module the person halted stays halted. The change
+            // is written whatever the stack: one that cannot be built yet is said, and built once it can - nothing is lost.
+            const building = resolve(cwd, params.plain_file);
+            let stackless;
+            try {
+                stackless = params.stack === undefined ? stacklessBuild(building) : (stackNamed(projectDirOf(building), params.stack), undefined);
+            }
+            catch (error) {
+                stackless = error instanceof Error ? error.message : String(error);
+            }
+            const statuses = stackless === undefined
+                ? await withCallStack(building, params.stack, () => loop.bringUp(params.plain_file, { specChange: true, ...(params.guidance !== undefined ? { guidance: params.guidance } : {}) }))
+                : [];
             const lines = [
                 result === "applied" ? `Applied the change to ${touched.join(", ")}.` : `The change to ${touched.join(", ")} was already applied.`,
-                `Building in the background:\n${describeModules(statuses)}\n`,
+                stackless === undefined
+                    ? `Building in the background:\n${describeModules(statuses)}\n`
+                    : `Not built yet - ${stackless} The change is in the spec: pass stack with the next change, or call regenerate with it, and everything written so far is built.\n`,
                 // An interview goes back to its questions; a skill that writes on its own, straight to its next change - a stop to ask ends it.
                 paced
                     ? "Carry on with the interview."

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. To build a part of the project another stack builds - a backend's, a frontend's - pass that stack as stack to regenerate, conform or glimpse 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 write_spec_diff 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/docs/config.md

@@ -216,22 +216,22 @@ coding-model:
   thinking: high
 ```
 
-A stack is chosen, never worked out from the spec:
+Which stack builds a module, first match wins:
 
-- **In the chat, for a module**, by the chat's model: `regenerate`, `conform` and `glimpse` take a `stack`, and it builds each module with the stack of its part - `backend.plain` with `backend` - leaving the session's choice as it is. A backend and a frontend can be regenerated side by side this way, each with its own.
-- **In the chat, for the session**, 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. `/stack` alone says which is chosen now; a module asked for without a stack of its own is built with it.
-- **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 one a call names.** `regenerate`, `conform`, `glimpse` and `write_spec_diff` take a `stack`; the chat's model passes it for a module whose stack has a name of its own, leaving the session's choice as it is.
+- **The stack named after the module** - `config.turri.backend.yaml` builds `backend.plain` - with nothing to choose or pass. Name each stack after the module it builds, and a backend and a frontend are each built with their own, side by side - in the chat, in a brood as each change is written, and on the command line.
+- **The one chosen for the session** - 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. `/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`.
-- **Pinned to a module when it is asked for.** A module is built with the stack chosen - or named in the call - when it is asked for, from its first pulse to its last: the pulses planned after it, its test runs, the scripts found, its plans and its conformance tests, whatever stack is chosen meanwhile. A pulse waiting for a free slot keeps the stack it was queued with. A change to its spec keeps its stack; asked for again, it takes the one chosen then. What `regenerate` says back names each module's stack, and so does a pulse's report.
-- **Refused with none, when that cannot build.** In a project of stacks, a module asked for with no stack - none named, none chosen - is refused before anything is planned when `config.turri.yaml` alone names no unit testing script: every pulse would stop for want of one. The refusal names the stacks and the script each names. `stack: none` builds with `config.turri.yaml` alone all the same.
+- **Pinned to a module when it is asked for.** A module is built with the stack it was asked for with, from its first pulse to its last: the pulses planned after it, its test runs, the scripts found, its plans and its conformance tests, whatever stack is chosen meanwhile. A pulse waiting for a free slot keeps the stack it was queued with. A change to its spec keeps its stack - unless it was built with none and has a stack of its own now; asked for again, its stack is worked out again. What `regenerate` says back names each module's stack, and so does a pulse's report.
+- **Refused with none, when that cannot build.** In a project of stacks, a module asked for with no stack - none named, none named after it, none chosen - is refused before anything is planned when `config.turri.yaml` alone names no unit testing script: every pulse would stop for want of one. The refusal names the stacks and the script each names. A spec change `write_spec_diff` writes is never refused: it is written, and said not to be built yet - passed the stack, everything written is built. `stack: none` builds with `config.turri.yaml` alone all the same.
 - **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 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, each stack named after the module it builds.
 
 ## The old config.yaml
 

package/docs/installation.md

@@ -17,7 +17,7 @@ turri init-config   # a config.turri.yaml with the model you talk to and the one
 turri               # pi, with turri's tools, skills and themes loaded
 ```
 
-The package is `@turri-dev/cli` - npm keeps the name `turri` back, as too like another package's - and the command it puts on your PATH is `turri`. `npm install -g @turri-dev/cli@next` gets the latest prerelease instead, built from the last commit on `main`.
+The package is `@turri-dev/cli` - npm keeps the name `turri` back, as too like another package's - and the command it puts on your PATH is `turri`. `npm install -g @turri-dev/cli@next` gets the latest prerelease instead, built from the last commit on `main`. Installed again - `@latest` or `@next` - it replaces the one there. `turri --version` says which turri runs, and the pi under it: `turri 0.1.6 (pi 1.3.0)`, and from a clone its commit too.
 
 ## From a clone
 

package/docs/theming.md

@@ -26,10 +26,10 @@ Both themes, the command line's colours, the spec diff's, the banner's jellyfish
 | path | `#3e5a6b` | the editor's border, what is dim: `dim`, line numbers |
 | grauzone | `#85a3b2` | body text, and what can be skimmed: `text`, `muted` |
 | white | `#f4f7f9` | headings, tool titles, what you typed, the jellyfish's shine |
-| siesta tan | `#e9d8c8` | inline code, \*\*\*plain's text in quotes or backticks |
+| siesta tan | `#e9d8c8` | strings in code, \*\*\*plain's text in quotes or backticks |
 | eggplant | `#732553` | a removed line's fill in a spec diff |
 | neon | `#5ce1e6` | links, focus, the selection, section labels, \*\*\*plain's concepts in a spec diff: `accent`, `mdLink`, regen's `◆` |
-| neon hover | `#8eebee` | types in code, an added line's fill in a light theme's spec diff |
+| neon hover | `#8eebee` | inline code - siesta tan beside white text was too close to tell apart, and tiring to read - types in code, an added line's fill in a light theme's spec diff: `mdCode` |
 | pink | `#ff5c8d` | the wordmark, the jellyfish's bell, and what is done - its `✓`, the spec map's `◇` and `◆`: `success` |
 | pink hover | `#ff7fa6` | \*\*\*plain's section headers, a removed line's `-`, keywords in code |
 | orange | `#ff7a3d` | the jellyfish's gut, the `$` of bash mode, and everything that asks for you - what failed (`✗`), what works with limits, what needs you (the spec map's `!`): `error`, `warning` |

package/docs/using.md

@@ -102,7 +102,7 @@ In `print`, `json` and `rpc` modes the process ends when the answer is written,
 
 The chat reads the project's `config.turri.yaml` afresh every turn and follows it: its agent is told what it sets, and the render tools default to it - `module` when you ask to build without naming one, `conformance-tests: false` to render without conformance tests (none written, none of the existing ones run) unless you ask for them, `coding-model` for what renders run on, and the testing scripts. `harness-model` is what `turri` starts on. What you ask for in the conversation wins. Every key, what happens without it, and how the models inherit: [the project config](config.md).
 
-A project whose parts are on different stacks gives each stack its own `config.turri.<stack>.yaml` beside `config.turri.yaml` - `config.turri.backend.yaml`, `config.turri.frontend.yaml` - with its testing scripts, models and conformance over the project's. A stack is chosen, never worked out: ask for the backend and the chat's model regenerates it with `stack: backend`, the frontend with `stack: frontend` - each pinned to its module's pulses, so both can be built side by side - or choose one for the session with `/stack backend`. The chat is told each stack's and which is chosen, and the status bar shows it. See [stacks](config.md#stacks).
+A project whose parts are on different stacks gives each stack its own `config.turri.<stack>.yaml` beside `config.turri.yaml` - `config.turri.backend.yaml`, `config.turri.frontend.yaml` - with its testing scripts, models and conformance over the project's. A stack named after its module builds it - `config.turri.backend.yaml` builds `backend.plain` - with nothing to choose, so a backend and a frontend are each built with their own, side by side, a brood's changes too; for a stack named otherwise the chat's model passes it as `stack`, or choose one for the session with `/stack backend`. The chat is told each stack's and which is chosen, and the status bar shows it. See [stacks](config.md#stacks).
 
 A project with only a `config.yaml` - turri's file before it had its own name, or another tool's - is read from it until turri first writes a setting, which copies it to `config.turri.yaml`; see [the old config.yaml](config.md#the-old-configyaml).
 

package/genome/skills/brood/SKILL.md

@@ -102,7 +102,7 @@ Create the module structure and frontmatter so there is a `.plain` file to build
 
 Write no definitions, no functional specs, no `***test reqs***` and no `***acceptance tests***`.
 
-End the phase with the unit tests: their framework, as a `:UnitTests:` requirement, and the unit testing script, which every build needs from the first one on. If turri already finds a script - named by `unittests-script:` in `config.turri.yaml` at the project root, or the one `run_unittests*.sh` in the root or in `test_scripts/` - keep it. Otherwise write `test_scripts/run_unittests_<language>.sh` with the `implement-unit-testing-script` skill, for the language and framework just settled. Do not link it from the specs. Without it, every build stops before it starts. When this module sits in a project beside another on a different stack - a frontend beside a backend, sharing only an imported module - its script is its stack's: name it in that stack's `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`) - `config.turri.frontend.yaml` for the stack `frontend` - not in `config.turri.yaml`, which is the project's and holds what the stacks share. A stack is chosen, never worked out: this module is built with its own - in the chat, `regenerate` with `stack: <stack>`, pinned to its pulses whatever stack is chosen after; `--stack <stack>` on the command line - so say which stack builds it.
+End the phase with the unit tests: their framework, as a `:UnitTests:` requirement, and the unit testing script, which every build needs from the first one on. If turri already finds a script - named by `unittests-script:` in `config.turri.yaml` at the project root, or the one `run_unittests*.sh` in the root or in `test_scripts/` - keep it. Otherwise write `test_scripts/run_unittests_<language>.sh` with the `implement-unit-testing-script` skill, for the language and framework just settled. Do not link it from the specs. Without it, every build stops before it starts. When this module sits in a project beside another on a different stack - a frontend beside a backend, sharing only an imported module - its script is its stack's: name it in that stack's `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`) - `config.turri.frontend.yaml` for the stack `frontend` - not in `config.turri.yaml`, which is the project's and holds what the stacks share. Name the stack after this module - `config.turri.frontend.yaml` for `frontend.plain` - and it is built with it by itself, with nothing to choose. A stack the project already has under another name is passed as `stack` to `write_spec_diff`.
 
 The unit testing script runs the static checks too - the formatter, linter and type checker the stack names, which count as the unit tests do; `implement-unit-testing-script` says which for each language. There is no separate static checks script.
 

package/genome/skills/brood/references/testing.md

@@ -19,7 +19,7 @@ Write no `***acceptance tests***`, no functional specs and no `***implementation
 3. **How the tests reach the software** - as a subprocess of the CLI, over HTTP against a server the tests start, through the public entry point it exports. Author it.
 4. **Setup and outside services** - fixtures, test data, databases, third-party APIs: started for real, faked, or mocked at the boundary. Author each decision as its own requirement.
 5. **How the whole suite is run** - the one command that discovers every test. Author it.
-6. **The conformance testing script** - if turri already finds one (named by `conformance-tests-script:` in `config.turri.yaml`, or the one `run_conformance_tests*.sh` in the project root or in `test_scripts/`), check it runs the suite the way the test reqs now say, and keep it. Otherwise write `test_scripts/run_conformance_tests_<language>.sh` with `implement-conformance-testing-script`, to match the test reqs. Never link it from the specs. If `test_scripts/` would hold two of a kind, name the one to use in `config.turri.yaml`. In a project whose parts are on different stacks, name each stack's script in its own `config.turri.<stack>.yaml` (`conformance-tests-script:`), and build each part with its own stack - in the chat, `regenerate` with `stack: <stack>`, pinned to that part's pulses; `--stack <stack>` on the command line.
+6. **The conformance testing script** - if turri already finds one (named by `conformance-tests-script:` in `config.turri.yaml`, or the one `run_conformance_tests*.sh` in the project root or in `test_scripts/`), check it runs the suite the way the test reqs now say, and keep it. Otherwise write `test_scripts/run_conformance_tests_<language>.sh` with `implement-conformance-testing-script`, to match the test reqs. Never link it from the specs. If `test_scripts/` would hold two of a kind, name the one to use in `config.turri.yaml`. In a project whose parts are on different stacks, name each stack's script in its own `config.turri.<stack>.yaml` (`conformance-tests-script:`), each stack named after the module it builds - `config.turri.backend.yaml` for `backend.plain` - so each part is built with its own by itself.
 7. **Anything else** - anything about testing the user wants to add or change.
 
 Run `validate` on every module you changed. The product phase's first build needs the test reqs and the conformance testing script both there: without them it stops before it starts.

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

@@ -208,7 +208,7 @@ The harness never runs `.ps1` scripts. These notes apply only to an optional cop
 4. Pick the right row from the [Dependency isolation](#dependency-isolation) table — use the same flag/env var in steps 7, 7b and 8 — and the checks from [Static checks of the tests](#static-checks-of-the-tests).
 5. Add the language-appropriate "no tests discovered" guard from [No tests discovered detection](#no-tests-discovered-detection), and the guard against conformance tests in the build folder from [Tests in the build folder](#tests-in-the-build-folder).
 6. Save the new script as `test_scripts/run_conformance_tests_<lang>.sh` and `chmod +x` it. Write a `.ps1` copy only if the user wants to run it by hand on Windows.
-7. **Make sure turri finds the script.** Do not link it from the specs - turri finds the conformance testing script in the project root (the folder that holds `plain_modules/`) and puts it, whole, into the prompts of the agents that write and review the conformance tests itself, whenever conformance tests are written for a build; a link to it from a spec is ignored. It looks, in order, at `config.turri.yaml` in the root (`conformance-tests-script: <path relative to the root>`) - with the chosen stack's `config.turri.<stack>.yaml` over it, then for the one `run_conformance_tests*.sh` in the root, then for the one in `test_scripts/`. Saving the script in `test_scripts/` (or the root) is enough when it is the only one there. If the project keeps it elsewhere, name it in `config.turri.yaml` as `conformance-tests-script:` - and when the project has only a `config.yaml`, copy it to `config.turri.yaml` first (and each `config.<name>.yaml` to `config.turri.<name>.yaml`) and edit the copy; `config.yaml` may be another tool's, and is never written. If the project has modules on different stacks - e.g. a Python backend and a React frontend side by side, sharing only an imported module - each part is on a stack of its own, and each stack names its own script in its own file beside `config.turri.yaml`: `conformance-tests-script:` in `config.turri.backend.yaml` for the stack `backend`, in `config.turri.frontend.yaml` for the stack `frontend`. A stack is chosen, never worked out: each part is built with its own - in the chat, `regenerate` with `stack: <stack>`, pinned to that part's pulses whatever stack is chosen after; `--stack <stack>` on the command line - so say which stack builds which part. turri never guesses between two. The script is required: with conformance testing on, a build without one stops before it starts. The `***test reqs***` still describe the conformance framework and command in words; do not paraphrase the script into them.
+7. **Make sure turri finds the script.** Do not link it from the specs - turri finds the conformance testing script in the project root (the folder that holds `plain_modules/`) and puts it, whole, into the prompts of the agents that write and review the conformance tests itself, whenever conformance tests are written for a build; a link to it from a spec is ignored. It looks, in order, at `config.turri.yaml` in the root (`conformance-tests-script: <path relative to the root>`) - with the chosen stack's `config.turri.<stack>.yaml` over it, then for the one `run_conformance_tests*.sh` in the root, then for the one in `test_scripts/`. Saving the script in `test_scripts/` (or the root) is enough when it is the only one there. If the project keeps it elsewhere, name it in `config.turri.yaml` as `conformance-tests-script:` - and when the project has only a `config.yaml`, copy it to `config.turri.yaml` first (and each `config.<name>.yaml` to `config.turri.<name>.yaml`) and edit the copy; `config.yaml` may be another tool's, and is never written. If the project has modules on different stacks - e.g. a Python backend and a React frontend side by side, sharing only an imported module - each part is on a stack of its own, and each stack names its own script in its own file beside `config.turri.yaml`: `conformance-tests-script:` in `config.turri.backend.yaml` for the stack `backend`, in `config.turri.frontend.yaml` for the stack `frontend`. Name each stack after the module it builds - `config.turri.backend.yaml` for `backend.plain` - and that module is built with it by itself, with nothing to choose; a stack named otherwise is passed as `stack` to `regenerate` in the chat, or `--stack <stack>` on the command line. turri never guesses between two. The script is required: with conformance testing on, a build without one stops before it starts. The `***test reqs***` still describe the conformance framework and command in words; do not paraphrase the script into them.
 
 ## Anti-Patterns
 

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

@@ -139,7 +139,7 @@ Notes:
 3. Translate each of the eight steps above into the equivalent commands for the target language **and** shell. The toolchain check, dependency install, static checks and test invocation are the language-specific parts; the rest is mechanical translation between Bash and PowerShell syntax.
 4. Pick the dependency-isolation mechanism from the [Dependency isolation](#dependency-isolation) table and use it consistently in steps 6, 7 and 8, and the checks from the [Static checks](#static-checks) table.
 5. Save the new script as `test_scripts/run_unittests_<lang>.sh` (a `.ps1` copy next to it only if the user wants to run it by hand on Windows). For Bash, `chmod +x` it.
-6. **Make sure turri finds the script.** Do not link it from the specs - turri finds the unit testing script in the project root (the folder that holds `plain_modules/`) and puts it, whole, into the prompt of the coding agent itself; a link to it from a spec is ignored. It looks, in order, at `config.turri.yaml` in the root (`unittests-script: <path relative to the root>`) - with the chosen stack's `config.turri.<stack>.yaml` over it, then for the one `run_unittests*.sh` in the root, then for the one in `test_scripts/`. Saving the script in `test_scripts/` (or the root) is enough when it is the only one there. If the project keeps it elsewhere, name it in `config.turri.yaml` as `unittests-script:` - and when the project has only a `config.yaml`, copy it to `config.turri.yaml` first (and each `config.<name>.yaml` to `config.turri.<name>.yaml`) and edit the copy; `config.yaml` may be another tool's, and is never written. If the project has modules on different stacks - e.g. a Python backend and a React frontend side by side, sharing only an imported module - each part is on a stack of its own, and each stack names its own script in its own file beside `config.turri.yaml`: `unittests-script:` in `config.turri.backend.yaml` for the stack `backend`, in `config.turri.frontend.yaml` for the stack `frontend`. A stack is chosen, never worked out: each part is built with its own - in the chat, `regenerate` with `stack: <stack>`, pinned to that part's pulses whatever stack is chosen after; `--stack <stack>` on the command line - so say which stack builds which part. turri never guesses between two. The script is required: a build without one stops before it starts.
+6. **Make sure turri finds the script.** Do not link it from the specs - turri finds the unit testing script in the project root (the folder that holds `plain_modules/`) and puts it, whole, into the prompt of the coding agent itself; a link to it from a spec is ignored. It looks, in order, at `config.turri.yaml` in the root (`unittests-script: <path relative to the root>`) - with the chosen stack's `config.turri.<stack>.yaml` over it, then for the one `run_unittests*.sh` in the root, then for the one in `test_scripts/`. Saving the script in `test_scripts/` (or the root) is enough when it is the only one there. If the project keeps it elsewhere, name it in `config.turri.yaml` as `unittests-script:` - and when the project has only a `config.yaml`, copy it to `config.turri.yaml` first (and each `config.<name>.yaml` to `config.turri.<name>.yaml`) and edit the copy; `config.yaml` may be another tool's, and is never written. If the project has modules on different stacks - e.g. a Python backend and a React frontend side by side, sharing only an imported module - each part is on a stack of its own, and each stack names its own script in its own file beside `config.turri.yaml`: `unittests-script:` in `config.turri.backend.yaml` for the stack `backend`, in `config.turri.frontend.yaml` for the stack `frontend`. Name each stack after the module it builds - `config.turri.backend.yaml` for `backend.plain` - and that module is built with it by itself, with nothing to choose; a stack named otherwise is passed as `stack` to `regenerate` in the chat, or `--stack <stack>` on the command line. turri never guesses between two. The script is required: a build without one stops before it starts.
 
 ## Anti-Patterns
 

package/genome/skills/init-plain-project/SKILL.md

@@ -96,7 +96,7 @@ Call the corresponding implementation skills in order. Each skill writes a Bash
 
 ### 6. Check turri finds the scripts
 
-turri finds the testing scripts in the project root, not through the specs: first in `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`, paths relative to the root), then the one `run_unittests*.sh` / `run_conformance_tests*.sh` in the root, then the one of each kind in `test_scripts/`. It puts them into the prompts of the agents that write and run the tests itself, so do not link them from `template/base.plain` (a link to one is ignored). Confirm every generated script is in `test_scripts/` and is the only one of its kind there - or, if the project wants it, that a `config.turri.yaml` at the root names the one to use and the path resolves. A project with parts on different stacks (e.g. a Python backend and a React frontend sharing an imported `base`) keeps one `config.turri.yaml` for what they share and gives each stack its own `config.turri.<stack>.yaml` beside it - `config.turri.backend.yaml`, `config.turri.frontend.yaml` - naming that stack's `unittests-script:` and `conformance-tests-script:`. A stack is chosen, never worked out: each part is built with its own - in the chat, `regenerate` with `stack: <stack>`, pinned to that part's pulses whatever stack is chosen after; `--stack <stack>` on the command line - so say which stack builds which part. When the project has only a `config.yaml`, copy it to `config.turri.yaml` first - and each `config.<name>.yaml` to `config.turri.<name>.yaml` - and write the copies; never write `config.yaml`.
+turri finds the testing scripts in the project root, not through the specs: first in `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`, paths relative to the root), then the one `run_unittests*.sh` / `run_conformance_tests*.sh` in the root, then the one of each kind in `test_scripts/`. It puts them into the prompts of the agents that write and run the tests itself, so do not link them from `template/base.plain` (a link to one is ignored). Confirm every generated script is in `test_scripts/` and is the only one of its kind there - or, if the project wants it, that a `config.turri.yaml` at the root names the one to use and the path resolves. A project with parts on different stacks (e.g. a Python backend and a React frontend sharing an imported `base`) keeps one `config.turri.yaml` for what they share and gives each stack its own `config.turri.<stack>.yaml` beside it - `config.turri.backend.yaml`, `config.turri.frontend.yaml` - naming that stack's `unittests-script:` and `conformance-tests-script:`. Name each stack after the module it builds - `config.turri.backend.yaml` for `backend.plain` - and that module is built with it by itself, with nothing to choose; a stack named otherwise is passed as `stack` to `regenerate` in the chat, or `--stack <stack>` on the command line. When the project has only a `config.yaml`, copy it to `config.turri.yaml` first - and each `config.<name>.yaml` to `config.turri.<name>.yaml` - and write the copies; never write `config.yaml`.
 
 Do **not** run `validate` here — keeping this skill light is the whole point. The user can run it when they want validation.
 

package/genome/skills/spawn/SKILL.md

@@ -38,7 +38,7 @@ Read what is already there first: an existing `.plain` file, `config.turri.yaml`
 
 - Templates go in `template/`; import paths omit the `template/` prefix. Resources go in `resources/`.
 - Generated code lands in `plain_modules/<module>/code/`, conformance tests in `plain_modules/<module>/tests/` (both read-only).
-- One module, unless the intent needs two stacks - a web frontend and an API backend. Then two modules side by side, neither requiring the other, sharing what they both mean through one imported module in `template/`. Each is on a stack of its own, whose testing scripts are named in `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`) - `config.turri.backend.yaml`, `config.turri.frontend.yaml`. A stack is chosen, never worked out: each part is built with its own - in the chat, `regenerate` with `stack: <stack>`, pinned to that part's pulses whatever stack is chosen after; `--stack <stack>` on the command line - so say which stack builds which part.
+- One module, unless the intent needs two stacks - a web frontend and an API backend. Then two modules side by side, neither requiring the other, sharing what they both mean through one imported module in `template/`. Each is on a stack of its own, whose testing scripts are named in `config.turri.<stack>.yaml` beside `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`) - `config.turri.backend.yaml`, `config.turri.frontend.yaml`. Name each stack after the module it builds - `config.turri.backend.yaml` for `backend.plain` - and that module is built with it by itself, with nothing to choose; a stack named otherwise is passed as `stack` to `regenerate` in the chat, or `--stack <stack>` on the command line.
 
 ## Steps
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@turri-dev/cli",
-  "version": "0.1.5-next.6df6879",
+  "version": "0.1.6-next.056c770",
   "license": "MIT",
   "type": "module",
   "repository": {