@turri-dev/cli 0.0.0-stage → 0.1.2-next.48dacfc

package/dist/stacks.js

@@ -0,0 +1,97 @@
+/**
+ * Choosing a stack: `config.turri.<stack>.yaml` laid over `config.turri.yaml` for everything built from then on - a
+ * backend's testing scripts, then a frontend's. `/stack` and the `stack` tool in the chat, `--stack <name>` on the
+ * command line (cli.ts). The choice itself is kept in config.ts (`chooseStack`), for the session only.
+ */
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { chooseStack, chosenStack, hasProjectConfig, stackConfigFile, stacksOf } from "./config.js";
+/** The words that choose no stack: the project's config alone. */
+const NONE = ["none", "off", "base", "-"];
+/** The stacks of the projects here: the folder's own, and those of the projects one folder down (specs kept in plain/). */
+export function knownStacks(root) {
+    const below = (() => {
+        try {
+            return readdirSync(root, { withFileTypes: true })
+                .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules" && entry.name !== "plain_modules")
+                .map((entry) => join(root, entry.name))
+                .filter(hasProjectConfig);
+        }
+        catch {
+            return [];
+        }
+    })();
+    return [...new Set([root, ...below].flatMap(stacksOf))].sort();
+}
+/** Choose `name` - or none - among the stacks here, and say what is chosen now; a stack the project has no file for is refused. */
+export function switchStack(root, name) {
+    const stacks = knownStacks(root);
+    const wanted = name?.trim() ?? "";
+    if (wanted === "" || NONE.includes(wanted.toLowerCase())) {
+        chooseStack(undefined);
+        return "No stack chosen: everything is built with the project's config.turri.yaml alone, from now on.";
+    }
+    if (!stacks.includes(wanted)) {
+        throw new Error(stacks.length > 0
+            ? `There is no stack ${wanted} here. The stacks: ${stacks.join(", ")} - or none.`
+            : `This project has no stacks: a stack is a ${stackConfigFile("<stack>")} beside config.turri.yaml.`);
+    }
+    chooseStack(wanted);
+    return `Stack ${wanted} chosen: everything is built with ${stackConfigFile(wanted)} over config.turri.yaml from now on - a pulse already running keeps the stack it started with.`;
+}
+/** /stack and the chat's stack tool. */
+export function registerStacks(pi, cwd) {
+    pi.registerCommand("stack", {
+        description: "Choose the stack everything is built with - its config.turri.<stack>.yaml over config.turri.yaml: /stack [name | none]",
+        getArgumentCompletions: (prefix) => {
+            const items = [...knownStacks(cwd), "none"].filter((stack) => stack.startsWith(prefix)).map((stack) => ({ value: stack, label: stack }));
+            return items.length > 0 ? items : null;
+        },
+        handler: async (args, ctx) => {
+            let name = args.trim();
+            if (name === "") {
+                const stacks = knownStacks(cwd);
+                if (stacks.length === 0)
+                    return ctx.ui.notify(`This project has no stacks: a stack is a ${stackConfigFile("<stack>")} beside config.turri.yaml.`, "info");
+                const now = chosenStack();
+                const label = (stack) => `${stack}${stack === now ? "  (chosen now)" : ""}`;
+                const none = `none - config.turri.yaml alone${now === undefined ? "  (chosen now)" : ""}`;
+                const picked = await ctx.ui.select("Build with which stack?", [...stacks.map(label), none]);
+                if (picked === undefined)
+                    return;
+                name = picked === none ? "none" : (stacks.find((stack) => label(stack) === picked) ?? "");
+            }
+            try {
+                ctx.ui.notify(switchStack(cwd, name), "info");
+            }
+            catch (error) {
+                ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+            }
+        },
+    });
+    pi.registerTool(defineTool({
+        name: "stack",
+        label: "Stack",
+        description: "Choose the stack everything is built with from now on - the project's config.turri.yaml with the stack's " +
+            "config.turri.<stack>.yaml over it: its testing scripts, toolchains, models - or none, the project's file alone. " +
+            "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, or for work on a part of the project another stack builds - a backend's, a frontend's - and say which you chose.",
+        ],
+        parameters: Type.Object({
+            name: Type.Optional(Type.String({ description: "The stack to choose, or none. Omitted: the stacks there are, and the one chosen" })),
+        }),
+        async execute(_id, params, _signal, _onUpdate, ctx) {
+            if (params.name === undefined) {
+                const stacks = knownStacks(cwd);
+                const text = stacks.length > 0 ? `The stacks: ${stacks.join(", ")}. Chosen now: ${chosenStack() ?? "none"}.` : "This project has no stacks.";
+                return { content: [{ type: "text", text }], details: {} };
+            }
+            const text = switchStack(cwd, params.name);
+            return { content: [{ type: "text", text }], details: {} };
+        },
+    }));
+}

package/dist/stdlib.js

@@ -0,0 +1,100 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+import { STDLIB_DIR } from "./regenerate/paths.js";
+export function stdlibTemplates(dir = STDLIB_DIR) {
+    const found = [];
+    const walk = (at) => {
+        let entries;
+        try {
+            entries = readdirSync(at, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory())
+                walk(join(at, entry.name));
+            else if (entry.name.endsWith(".plain"))
+                found.push(join(at, entry.name));
+        }
+    };
+    walk(dir);
+    return found
+        .map((file) => {
+        const text = readFileSync(file, "utf8").trim();
+        return {
+            name: `stdlib/${relative(dir, file).split(sep).join("/").replace(/\.plain$/, "")}`,
+            description: /^description:\s*(.+)$/m.exec(text)?.[1]?.trim() ?? "",
+            text,
+        };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/** A stack to import - not a kind's `common`, not a conformance template, and not a language's. */
+export function isStack(template) {
+    return !template.name.endsWith("/common") && !template.name.includes("/conformance/") && !template.name.startsWith("stdlib/lang/");
+}
+/** A stack's conformance template: `stdlib/backend/python-fastapi` has `stdlib/backend/conformance/python-fastapi`. */
+export function conformanceOf(stack) {
+    const slash = stack.lastIndexOf("/");
+    return `${stack.slice(0, slash)}/conformance/${stack.slice(slash + 1)}`;
+}
+const KINDS = [
+    { kind: "backend", title: "Backends" },
+    { kind: "frontend", title: "Frontends" },
+    { kind: "cli", title: "Command-line tools" },
+    { kind: "library", title: "Libraries" },
+];
+/**
+ * The catalogue appended to the stdlib rule: every stack with its conformance template and what it is, the
+ * shared templates, and the folder they are all in - an absolute path, so an agent reads the one it imports
+ * instead of looking for it. The text of each is not in it: there are too many to carry in every prompt.
+ */
+export function stdlibCatalogue(templates = stdlibTemplates(), dir = STDLIB_DIR) {
+    if (templates.length === 0)
+        return "";
+    const names = new Set(templates.map((template) => template.name));
+    const row = (template) => `| \`${template.name}\` | ${names.has(conformanceOf(template.name)) ? `\`${conformanceOf(template.name)}\`` : "none"} | ${template.description} |`;
+    const shared = templates.filter((template) => !isStack(template) && !template.name.includes("/conformance/"));
+    return [
+        "## What there is",
+        "",
+        `Every template is a file in ${dir}: \`stdlib/backend/python-fastapi\` is \`${dir}/backend/python-fastapi.plain\`. Read the ones a module imports - the stack, its language, its kind's \`common\`, and their conformance templates - before writing its specs.`,
+        "",
+        ...KINDS.flatMap(({ kind, title }) => {
+            const stacks = templates.filter((template) => isStack(template) && template.name.startsWith(`stdlib/${kind}/`));
+            return stacks.length === 0 ? [] : [`### ${title}`, "", "| import | its conformance tests | what it is |", "| --- | --- | --- |", ...stacks.map(row), ""];
+        }),
+        "### What the stacks import",
+        "",
+        "| template | what it is |",
+        "| --- | --- |",
+        ...shared.map((template) => `| \`${template.name}\` | ${template.description} |`),
+    ]
+        .join("\n")
+        .trim();
+}
+/** How many stacks the standard library has, for the banner. */
+export function stdlibStackCount(templates = stdlibTemplates()) {
+    return templates.filter(isStack).length;
+}
+/** The standard library as the person reads it, with `/stdlib`: each kind's stacks, what each is, and how to import one. */
+export function describeStdlib(templates = stdlibTemplates(), dir = STDLIB_DIR) {
+    if (templates.length === 0)
+        return "The standard library is empty: turri's stdlib/ folder holds no templates.";
+    const width = Math.max(...templates.filter(isStack).map((template) => template.name.length));
+    return [
+        `The ***plain standard library - ${stdlibStackCount(templates)} stacks a spec can import instead of writing its implementation reqs:`,
+        ...KINDS.flatMap(({ kind, title }) => {
+            const stacks = templates.filter((template) => isStack(template) && template.name.startsWith(`stdlib/${kind}/`));
+            return stacks.length === 0 ? [] : ["", `${title}:`, ...stacks.map((template) => `  ${template.name.padEnd(width)}  ${template.description}`)];
+        }),
+        "",
+        "Import one in a spec's frontmatter, and its conformance tests beside it when you want them:",
+        "  import:",
+        "    - stdlib/backend/python-flask",
+        "    - stdlib/backend/conformance/python-flask",
+        "",
+        `The templates are in ${dir}. Or ask - "build this as a Flask backend" - and the agent imports it.`,
+    ].join("\n");
+}

package/dist/terminal-images.js

@@ -0,0 +1,46 @@
+import { resetCapabilitiesCache } from "@earendil-works/pi-tui";
+/**
+ * Whether the terminal turri runs in can show images, and how, settled before pi-tui guesses wrong.
+ *
+ * pi-tui reads it from the environment, and a terminal started from another inherits that one's
+ * variables: Zed opened from Ghostty still has GHOSTTY_RESOURCES_DIR, which pi-tui takes for Ghostty,
+ * so it sends images Zed draws as nothing. The terminal a process is really in is the one that set
+ * TERM_PROGRAM - or, for Kitty and Ghostty, TERM - last. When that one shows no images, pi-tui is told
+ * so through its own PI_IMAGE_PROTOCOL, which it reads each time it looks again (pi re-applies its
+ * settings' overrides, so one set in code would not last). A PI_IMAGE_PROTOCOL the person set is kept.
+ */
+/** TERM_PROGRAM as the terminals that show images set it: Kitty's graphics protocol, or iTerm2's. */
+const SHOWS_IMAGES = new Set(["kitty", "ghostty", "wezterm", "warpterminal", "iterm.app"]);
+/** The first iTerm2 that speaks the Kitty graphics protocol */
+const ITERM2_KITTY_FROM = [3, 7];
+/** What PI_IMAGE_PROTOCOL turri sets for this terminal: none where it shows no images, kitty for an iTerm2 that speaks it, else nothing. */
+export function imageProtocolFor(env = process.env) {
+    if (env.PI_IMAGE_PROTOCOL !== undefined)
+        return undefined;
+    const term = env.TERM?.toLowerCase() ?? "";
+    if (term.includes("kitty") || term.includes("ghostty"))
+        return undefined;
+    const program = env.TERM_PROGRAM?.toLowerCase();
+    if (program === undefined || program === "")
+        return undefined;
+    if (!SHOWS_IMAGES.has(program))
+        return "none";
+    // pi-tui shows no images under tmux or screen; telling it Kitty's would override that.
+    const multiplexed = env.TMUX !== undefined || env.STY !== undefined || term.startsWith("tmux") || term.startsWith("screen");
+    if (program === "iterm.app" && !multiplexed && atLeast(env.TERM_PROGRAM_VERSION, ITERM2_KITTY_FROM))
+        return "kitty";
+    return undefined;
+}
+/** Whether a version such as `3.7.4beta1` is `from` or later; an unreadable one is not. */
+function atLeast(version, from) {
+    const parts = /^(\d+)\.(\d+)/.exec(version ?? "");
+    if (parts === null)
+        return false;
+    const [major, minor] = [Number(parts[1]), Number(parts[2])];
+    return major > from[0] || (major === from[0] && minor >= from[1]);
+}
+const protocol = imageProtocolFor();
+if (protocol !== undefined) {
+    process.env.PI_IMAGE_PROTOCOL = protocol;
+    resetCapabilitiesCache();
+}

package/dist/tools.js

@@ -0,0 +1,242 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+/**
+ * Personal tools.
+ *
+ * `write_artifact` is the executor's only way to produce output: it can read the
+ * repo, but everything it makes lands in one sandboxed directory under a name the
+ * graph chose. That is what lets the gate know exactly what to review - there is
+ * no "find the thing the agent probably changed" step.
+ */
+export function createWriteArtifactTool(runDir) {
+    const root = resolve(runDir);
+    return defineTool({
+        name: "write_artifact",
+        label: "Write artifact",
+        description: "Write this step's deliverable. Path must be the artifact path given in the step instructions. " +
+            "Overwrites any previous attempt.",
+        promptSnippet: "write the current step's deliverable to its artifact path",
+        parameters: Type.Object({
+            path: Type.String({ description: "Artifact path, exactly as given in the step instructions" }),
+            content: Type.String({ description: "Full contents of the artifact" }),
+        }),
+        async execute(_id, params) {
+            const target = resolve(root, params.path);
+            if (relative(root, target).startsWith("..")) {
+                throw new Error(`write_artifact: '${params.path}' escapes the artifact directory`);
+            }
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, params.content, "utf8");
+            return {
+                content: [{ type: "text", text: `Wrote ${params.content.length} bytes to ${params.path}` }],
+                details: { path: params.path, bytes: params.content.length },
+            };
+        },
+    });
+}
+export const VerdictSchema = Type.Object({
+    verdict: Type.Union([Type.Literal("pass"), Type.Literal("fail")], {
+        description: "'fail' if ANY rubric criterion is violated. There is no partial credit.",
+    }),
+    violations: Type.Array(Type.Object({
+        criterion: Type.String({ description: "The rubric criterion, quoted" }),
+        evidence: Type.String({ description: "The exact text from the artifact that violates it" }),
+        fix: Type.String({ description: "One concrete instruction that would resolve it" }),
+    }), { description: "Empty when verdict is 'pass'. Never empty when verdict is 'fail'." }),
+});
+/**
+ * The judge's only tool. Forcing the verdict through a schema is the difference
+ * between a decision the graph can branch on and a paragraph someone has to read.
+ * `terminate` stops the judge session as soon as the verdict lands.
+ */
+export function createVerdictTool(onVerdict) {
+    return defineTool({
+        name: "submit_verdict",
+        label: "Submit verdict",
+        description: "Submit your review verdict. Call this exactly once. Do not reply with prose.",
+        parameters: VerdictSchema,
+        async execute(_id, params) {
+            onVerdict(params);
+            return {
+                content: [{ type: "text", text: "Verdict recorded." }],
+                details: params,
+                terminate: true,
+            };
+        },
+    });
+}
+import { isChat, runAsk } from "./ask.js";
+import { describeFindings, describeQuestions } from "./review/live.js";
+/**
+ * Lets a skill step put a question to the person running it.
+ *
+ * A gated skill otherwise runs to completion with nobody to ask, which is fine for work
+ * that is fully specified and useless for an interview. The harness still owns the
+ * sequence - the step decides what to ask, not whether the gate afterwards runs.
+ */
+/**
+ * `gate`, for an interview that holds its questions to rules - the questioning level's cap (questioning.ts), an answer
+ * written as a spec change before the next question: a question it refuses is not asked, and `confirms_phase` marks a
+ * phase's closing confirmation, which the cap never counts.
+ *
+ * `talks`: where the asker answers a person who chose "Chat about this" - `"reply"`, the conversation's agent, in its
+ * reply; `"context"`, a skill's agent, whose replies nobody sees, as the `context` of the question asked again. Such a
+ * choice is no answer: neither the cap nor `onAnswered` counts it.
+ */
+export function createAskUserTool(ask, onAnswered, said, gate, talks = "context") {
+    return defineTool({
+        name: "ask_user",
+        label: "Ask the user",
+        description: "Put one question to the user and wait for their answer. Ask exactly one thing at a time. " +
+            "Offer concrete options in `options` so the user can pick rather than type - that is the " +
+            "normal case, and a question with neither options nor free_form is refused rather than asked.",
+        promptSnippet: "ask the user one question, offering options to pick from",
+        promptGuidelines: [
+            "Every ask_user call should carry `options` unless the answer genuinely cannot be anticipated; picking from a list is far quicker for the user than typing. A free-form question needs free_form: true.",
+            "Use multi_select: true when several answers can apply at once, rather than asking the same question repeatedly.",
+            "The dialog shows the question, its options and `context` alone - nothing you wrote before it. When the user must read something to answer - the brief to confirm, the plan to approve - pass it as `context`; never put an account of your work there (what a probe returned, what a regeneration did).",
+            "Keep `context` short enough to take in at a glance - a heading or two and short bullets, a line each, about fifteen lines at most: what the person decides on, not every detail. The details are in the spec; say where, and they can ask.",
+        ],
+        parameters: Type.Object({
+            question: Type.String({ description: "One question. Never bundle two." }),
+            options: Type.Optional(Type.Array(Type.String(), {
+                description: "Concrete choices to offer. The user can always pick \"Something else…\" and type instead, or " +
+                    "\"Chat about this\" to talk the question over with you first, so offering options never traps them.",
+            })),
+            multi_select: Type.Optional(Type.Boolean({ description: "Let the user pick several of the options." })),
+            context: Type.Optional(Type.String({
+                description: "What the user must read to answer, shown above the question - the brief to confirm, the plan to approve. Only that: never an account of what you did.",
+            })),
+            free_form: Type.Optional(Type.Boolean({
+                description: "Ask without options, for a genuinely open question. Required when options is omitted.",
+            })),
+            ...(gate !== undefined
+                ? {
+                    confirms_phase: Type.Optional(Type.Boolean({
+                        description: "This asks the person to confirm the phase's summary before it ends. It is not counted among the phase's questions.",
+                    })),
+                }
+                : {}),
+        }),
+        async execute(_id, params) {
+            const confirmsPhase = params.confirms_phase === true;
+            const refusal = gate?.refusal(confirmsPhase);
+            if (refusal !== undefined) {
+                return { content: [{ type: "text", text: refusal }], details: { question: params.question, answer: "" } };
+            }
+            const answer = await ask({
+                question: params.question,
+                options: params.options,
+                multiSelect: params.multi_select,
+                freeForm: params.free_form,
+                ...(params.context !== undefined && params.context.trim() !== "" ? { context: params.context } : {}),
+                ...(said !== undefined ? { said: said() } : {}),
+                chattable: true,
+            });
+            if (isChat(answer)) {
+                return { content: [{ type: "text", text: `${answer}\n\n${talkBack(talks)}` }], details: { question: params.question, answer } };
+            }
+            gate?.answered(confirmsPhase);
+            onAnswered?.(answer, confirmsPhase);
+            return {
+                content: [{ type: "text", text: answer }],
+                details: { question: params.question, answer },
+            };
+        },
+    });
+}
+export { runAsk };
+/** What the asker is told to do when the person chose to talk about its question rather than answer it. */
+function talkBack(talks) {
+    return talks === "reply"
+        ? "Answer what they said in your reply, and end your turn there: they go on in the chat. Ask the question again " +
+            "with ask_user only once it is settled - changed, if what they said calls for it. It was not counted as answered."
+        : "Answer what they said, then ask the question again with ask_user - changed, if what they said calls for it. Put " +
+            "your answer to them in the question's `context`: nothing else you write reaches them. It was not counted as a " +
+            "question, and nothing is owed for it.";
+}
+/** Ends the questions of a phase the questioning level caps: what is left, the agent decides itself. */
+export function createEndQuestionsTool(questioning) {
+    return defineTool({
+        name: "end_questions",
+        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.",
+        promptSnippet: "end this phase's questions and decide what is left yourself",
+        parameters: Type.Object({}),
+        async execute() {
+            return { content: [{ type: "text", text: questioning.end() }], details: {} };
+        },
+    });
+}
+/**
+ * Everything the reviewer has to say since the last tool call.
+ *
+ * It rides along on the tool results the interviewer is already getting, so a finding
+ * lands between two questions without the interviewer having to remember to go looking
+ * for one.
+ */
+export function reviewNote(liveReview) {
+    if (liveReview === undefined)
+        return "";
+    const parts = [];
+    const findings = liveReview.take();
+    if (findings.length > 0)
+        parts.push(describeFindings(findings));
+    const questions = liveReview.takeQuestions();
+    if (questions.length > 0)
+        parts.push(describeQuestions(questions));
+    return parts.length === 0 ? "" : `\n\n${parts.join("\n\n")}`;
+}
+/**
+ * With a live reviewer, a way to answer the reviewer's questions. How the builds stand, a skill reads with the
+ * conversation's own drift (loop-tools.ts), the reviewer's findings riding along on it (`withReviewNote`).
+ */
+export function createReviewTools(liveReview) {
+    if (liveReview === undefined)
+        return [];
+    const reply = defineTool({
+        name: "reply_to_review",
+        label: "Reply to review",
+        description: "Answer a question the reviewer asked, after putting it to the user. The answer is carried " +
+            "into the reviewer's next pass. Use this only for questions the reviewer raised by id.",
+        promptSnippet: "hand the user's answer back to the reviewer",
+        parameters: Type.Object({
+            question_id: Type.String({ description: 'The id the reviewer gave, e.g. "q1"' }),
+            answer: Type.String({ description: "What the user decided, in their terms" }),
+        }),
+        async execute(_id, params) {
+            const accepted = liveReview.reply(params.question_id, params.answer);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: accepted
+                            ? `Answer to ${params.question_id} passed to the reviewer. Make sure the specs say the same thing.`
+                            : `No open review question with id '${params.question_id}'.`,
+                    },
+                ],
+                details: { accepted },
+            };
+        },
+    });
+    return [reply];
+}
+/** A tool whose every result carries what the reviewer has said since the last one. */
+export function withReviewNote(tool, liveReview) {
+    if (liveReview === undefined)
+        return tool;
+    return {
+        ...tool,
+        async execute(id, params, signal, onUpdate, ctx) {
+            const result = await tool.execute(id, params, signal, onUpdate, ctx);
+            const note = reviewNote(liveReview);
+            if (note === "")
+                return result;
+            return { ...result, content: [...result.content, { type: "text", text: note.trimStart() }] };
+        },
+    };
+}

package/dist/validate-cli.js

@@ -0,0 +1,52 @@
+import { checkPlainTargets, formatCheckResults } from "./plain/check.js";
+const USAGE = `usage: turri validate <file.plain | directory> [options]
+
+Validates a ***plain specification statically: parses it, resolves its imports and
+required modules, and reports every error without rendering anything.
+
+  --template-dir <dir>   extra template directory (repeatable)
+  --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 = [];
+let json = false;
+for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--template-dir")
+        templateDirs.push(argv[++i]);
+    else if (arg === "--json")
+        json = true;
+    else if (arg === "-h" || arg === "--help") {
+        console.log(USAGE);
+        process.exit(0);
+    }
+    else
+        positional.push(arg);
+}
+const target = positional[0] ?? ".";
+const results = checkPlainTargets(target, templateDirs);
+if (results.length === 0) {
+    console.error(`No .plain files found in ${target}.`);
+    process.exit(1);
+}
+if (json) {
+    console.log(JSON.stringify(results, null, 2));
+}
+else {
+    const output = formatCheckResults(results)
+        .split("\n")
+        .map((line) => line.startsWith("PASS") ? c.green(line) : line.startsWith("FAIL") ? c.red(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`))}`);
+}
+process.exit(results.every((r) => r.ok) ? 0 : 1);

package/docs/README.md

@@ -0,0 +1,58 @@
+# 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.
+
+## 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.
+
+## 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) |
+| 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) |
+| 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) |
+| 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 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) |
+| 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) |
+| 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) |
+| how skill review gates and judges work | [skills and gates](skills-and-gates.md) |
+| how the parser matches the reference implementation | [the \*\*\*plain parser](parser.md) |
+| where the code for something lives | [development](development.md#layout) |
+
+## All pages
+
+| page | covers |
+| --- | --- |
+| [Installation](installation.md) | doctor, what turri needs of this machine, turri and `pi`, environment variables |
+| [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 |
+| [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 |
+| [Theming](theming.md) | the turri themes, contrast, backgrounds, the font |
+| [Development](development.md) | tests, the source layout, known edges |