@turri-dev/cli 0.0.0-stage → 0.1.1

package/docs/sandbox.md

@@ -0,0 +1,233 @@
+# The sandbox
+
+A rendering agent is building one module. It has no business reading the `.plain` specs it was
+not given, the rest of the project, or anything else on the machine - and pi's `cwd` is only
+where relative paths start: an absolute path resolves to itself and `bash` can `cd` anywhere. So
+turri fences its agents: their file tools check every path, and every command they run on this
+machine passes a command check, runs in an environment of the module's own behind an OS sandbox
+where the OS has one, and is audited afterwards. The rules live in code that runs the same on every
+platform; the OS sandbox is an extra wall under them.
+
+## What an agent can reach
+
+Each agent's file tools reach its own module and only the parts its role needs:
+
+| Role | Reads | Writes |
+| --- | --- | --- |
+| Coding agent, regression repair | its module's `code/` | its module's `code/` |
+| Conformance agent | its module's `tests/` and `code/` | its module's `tests/` |
+| Code fixer | its module's `code/` and `tests/` | its module's `code/` |
+| Explorers | its module's `code/` | nothing |
+| Test review | its module's `tests/` and `code/` | nothing |
+
+Nothing else exists for them: not another module, not turri's scratch area `plain_modules/.turri` (a test run's
+whole output reaches them through `read_output`, not by path), not the module's lineage `.plaingit`, and nothing
+above `plain_modules`. The specs it is
+building from reach it only through the prompt the harness writes. Nor does any context file: pi puts
+every `AGENTS.md` / `CLAUDE.md` from an agent's folder up into its system prompt, and turri
+turns that off for every agent it starts - so the project's own `AGENTS.md`, or yours in
+`~/.pi/agent`, never reaches a rendering agent, a judge or a skill's agent. Nor do pi's skills, which
+pi would list for an agent to load: each agent turri starts has one job, and turri runs its
+own gated skills itself. The conversation you talk to still loads both, as pi does - but for the skills turri has
+already, its own and any about \*\*\*plain (see [a project's own skills](skills-and-gates.md#a-projects-own-skills)).
+
+## Every agent knows its walls
+
+Each agent's system prompt says where its walls are, in words generated from its fence, so they say exactly what is
+enforced and are the same on every platform:
+
+- its own folder or folders, by absolute path, and what its file tools read and write there - a role that only reads
+  is told it writes nothing, "not with your file tools, not with your shell"; the conformance agent that it reads the
+  code under test but writes tests, not code; the code fixer that it reads the conformance tests but fixes the code;
+- that its shell runs on this machine, in its folder, with this machine's toolchains, a home folder and a temporary
+  folder of its own (`$HOME`, `$TMPDIR`), the package caches and an open network, and that nothing else exists for
+  it - not the specs, not the project's other folders or modules, not your home;
+- what happens on a reach outside, matter-of-fact: a command that names a path outside is refused before it runs,
+  and anything a command changes outside is put back, and it is told;
+- that the project's dependencies are its own, through the build manifest, and installing anything else is not: what
+  the machine lacks it reports with `report_environment_error`, naming what is missing, and goes no further with what
+  depends on it (see [when the environment lacks something](regenerating.md#when-the-environment-lacks-something));
+- that it may stop only what it started, and that a port something else holds means another port; that `ps` may show
+  nothing but what it started, so a server is checked with `kill -0 $!`, its log or a request;
+- that temporary files go in `$TMPDIR`, `/tmp` being outside its walls.
+
+Beside its walls, an agent that writes code or tests - the coding agent, the conformance agent, the code fixer, the
+repair agent - is told up front what it would otherwise go looking for (`src/regenerate/workspace.ts`): whether its folder is
+empty, with nothing above it to find, or holds code whose unit tests passed when it was committed; that it is not a git
+repository, and `my_diff` shows its work; the versions of the toolchains its module's implementation reqs name, probed
+once on this machine, or that one is missing; that the package caches and Maven's repository are set for it, and to
+leave `JAVA_TOOL_OPTIONS` set; and that the network is open.
+
+No other path is named - nothing into `plain_modules/.turri`. A test run or a command whose output was cut names the
+whole of it by an id - not a file in its folder, which `read` says if it is given one - and the agent reads it with
+`read_output`: not by a path into `plain_modules/.turri` or to a
+temporary file on this machine (see [long output](regenerating.md#the-tests-must-actually-pass)).
+
+## File tools
+
+`src/regenerate/confine.ts` rebuilds `read`, `write`, `edit`, `ls`, `grep` and `find` from pi's own
+factories with a check in front of every path. The check runs twice: once on the argument the
+tool was called with, and once on the absolute path the tool resolved it to, because the two can
+differ. Symlinks are resolved before comparing, so a link cannot walk out, and a glob containing
+`..` is refused outright.
+
+The record of what the code is built from, `code/.turri.json`, is the harness's: no agent reads or writes it. `read`
+refuses it, and `ls`, `grep` and `find` leave it out of what they list - as the command check, the OS sandbox and the
+audit keep it from commands.
+
+Credentials are the person's: no agent writes a `.env` or a variant of one (`.env.local`, `.env.test`) - a
+template, `.env.example`, is fine. The file tools refuse it, the command check refuses a command that would
+write one, and what a command does to one anyway is put back by the audit, the agent told why. A made-up credential makes every later run fail without anyone seeing why; a missing one is the
+judge's to report (see [regenerating the code](regenerating.md)), the person's to provide.
+
+## Commands on this machine
+
+`bash` is the case no argument check can cover - one string, and no way to read for certain where it will read or
+write. So every command an agent runs - its `bash`, a service it starts - goes through every wall at once
+(`src/regenerate/agent-shell.ts`, `agentShell`), from its role's fence, the same as its file tools':
+
+1. **the command check**, before it runs - refused with exit 126 and the reason, a line in the job's log;
+2. **the module's own environment** - not yours: the path, the locale, the terminal, the user and the toolchains'
+   variables pass, nothing else - no provider key, no token, no SSH agent; a home folder of the module's own in
+   `plain_modules/.turri/home/<module>`, kept between pulses, a `TMPDIR`, the package caches in the project, git
+   stopped at the module folder, and what `agent-env:` passes (see [credentials for the agents](config.md#credentials-for-the-agents)).
+   Every JVM - a test JVM Maven or Gradle forks too - is given the module's `TMPDIR` and home through
+   `JAVA_TOOL_OPTIONS`, since Java takes both from the system rather than from `TMPDIR` and `HOME`; each says so in a
+   "Picked up JAVA_TOOL_OPTIONS" line on its stderr;
+3. **the OS sandbox**, where one is up - Seatbelt on macOS, bubblewrap on Linux and WSL2;
+4. **the audit**, after it, which puts back what it changed that its role may not, and tells the agent.
+
+The job's log says, for each agent with a shell, which walls are up - and where no OS sandbox starts, why.
+
+The command runs through the host runner (`src/regenerate/shell.ts`): `bash -c` from the agent's folder, in a process group of
+its own. No command can hang a build: every one has a time limit - 2 minutes, or `TURRI_COMMAND_TIMEOUT` seconds: the
+agent's own `bash` unless it gives a timeout (at most 30 minutes), its unit and conformance test runs, the harness's own
+runs. A command that runs out is killed, it and everything it started, and reports exit 124 with a note on what to do
+instead: a server, a watcher or a prompt waiting for input never ends on its own, and has to be started in the
+background or given its input. A job that is stopped ends the command it is waiting on at once, the same way.
+
+A server a command leaves running in the background is its pulse's: it runs on until the pulse ends, and is killed
+then - a pulse running beside it keeps its own. Everything still running is killed when turri exits, ended by a signal
+too. A turri killed outright cannot do that itself, so one small watcher beside it does, within two seconds, from the
+groups it recorded in the temporary folder (`turri-groups/`); and groups a turri left that nothing killed are swept when
+turri next starts. On Windows there are no process groups: a command's process tree is killed with `taskkill /T /F`,
+best effort.
+
+The project's testing scripts - their static checks included - are not agents' commands: they are
+yours, and run on this machine as you would run them, unfenced, in your own environment - see [the testing scripts](regenerating.md#the-testing-scripts). The agent gets their
+output, nothing more.
+
+### The command check
+
+Before an agent's command runs, its text is checked (`src/regenerate/command-check.ts`, `checkCommand`), on every platform, and
+refused - not run - with the rule it broke and what to do instead, when it:
+
+- names a path outside the role's roots - absolute, a `..` that climbs out of the agent's folder (after the `cd`s
+  before it), or inside a quoted string (`python3 -c "..."`). `~`, `$HOME` and `$TMPDIR` are the module's own and
+  allowed, as are the package caches, the machine's system folders and the toolchains, and the devices
+  (`/dev/null`). A path is checked when it names something on disk - under a top folder such as `/Users`, `/home`,
+  `/etc` or `/tmp`, one of the fence's, or one that exists - so an API route in a curl or a JSON body is not one, and
+  nor is `/` alone, a slash in code (`case '/':`), though writing to `/` is refused;
+- names the code record, `.turri.json`;
+- writes a credential file (`.env` and its variants; a template is fine) - by redirect, `tee`, `cp`, `mv` or an edit
+  in place;
+- installs software outside the project: `sudo`, the system's package managers installing (`brew`, `apt`, `dnf`,
+  `apk`, `pacman`, `choco`, `winget`, ...), toolchain managers installing (`nvm`, `sdk`, `rustup`, `pyenv`, `asdf`,
+  ...), global installs (`npm -g`, `yarn global`, `pip --user`, `pipx`, `gem install`), a script downloaded and run
+  (`curl ... | sh`), an installer (`.pkg`, `.msi`, `.dmg`, `.run`). The project's own dependencies - `npm install`,
+  pip into its venv, `mvn`, `cargo`, `go mod` - are building the code, and pass;
+- kills what its pulse did not start: `pkill`, `killall`, `taskkill`, `fuser -k`, or `kill` aimed at a port or name
+  lookup. `kill $!` and `kill %1` pass.
+
+On Windows, drive letters, backslashes and any case are read as Windows has them. It knowingly misses a path built at
+run time (`$(...)`, a variable, a script that reads one from a file): the OS sandbox and the audit are for those.
+
+### The OS sandbox
+
+Under the check, where the OS offers one, the command runs behind an OS sandbox (`src/regenerate/os-sandbox.ts`), driven
+directly from the role's fence: Seatbelt (`sandbox-exec`) on macOS, bubblewrap on Linux and WSL2. It is an extra wall,
+never where a rule lives - where neither starts (native Windows, WSL1, a container that does not allow user
+namespaces) the check and the audit hold alone. What a command behind it reaches:
+
+- reads: its role's roots, the module's home, `TMPDIR` and the package caches, and of the machine only the system's
+  folders, every folder on the agent's `PATH` (the folder itself, not its parent: `~/.cargo/bin`, not `~/.cargo`) - but
+  a version manager's install whole, a `bin` whose parent is a version (`…/mise/installs/node/24.16.0/bin`), as its
+  tools are links into the install beside it (`npm` into `lib/node_modules`) - the folders the toolchain variables
+  point at (`JAVA_HOME`, `RUSTUP_HOME`, `NVM_DIR`, mise's `MISE_DATA_DIR`, fnm's, rbenv's, the Pythons uv fetches, ...)
+  and the project's `toolchains:` - nothing else of the person's home;
+- writes: its role's own roots - none for a role that only reads - and the module's home, `TMPDIR` and caches. On macOS
+  the developer tools' own scratch files too (`xcrun`'s database, clang's module cache), which go where macOS says, not
+  where `TMPDIR` does - and a folder of the module's own in macOS's per-user temporary folder
+  (`DIRHELPER_USER_DIR_SUFFIX`), where its JVMs keep their attach sockets, so Mockito's inline mocks, `jcmd` and
+  `jstack` attach to a JVM it started; the person's JVMs' sockets, beside it, stay out of reach;
+- never the code record; no Unix socket outside its folders (on macOS, the name service's excepted); signals and
+  process listings only within its own sandbox (bubblewrap's PID namespace, Seatbelt's same-sandbox), so `ps` shows
+  nothing else and `kill` reaches nothing else;
+- the network as this machine has it;
+- at most 4096 processes and files of at most 8 GiB, set with `ulimit` inside.
+
+`sandboxAvailable()` tries it once and says which wall is up, or why none starts and how to give it one: bubblewrap not
+installed, user namespaces off (Docker: a user that is not root, `--security-opt seccomp=unconfined`), AppArmor in the way (Docker:
+`--security-opt apparmor=unconfined`; Ubuntu 24.04: its user-namespace restriction), or Docker's masked `/proc` - for
+which bubblewrap falls back to binding the host's `/proc` rather than mounting its own.
+
+### The audit
+
+After every agent command, on every platform - a sandbox up or not - turri puts back what the command's role may not
+change inside the project (`src/regenerate/audit.ts`): the specs, `config*.yaml`, the testing scripts, every credential file
+(the agent's own folder included), the code record, the module's lineage `.plaingit` (its refs and settings), the other
+modules, the folders the role only reads, and the part of its own module it does not write - the coding agent's
+conformance tests. A changed file is put back, a new one removed, a deleted one brought back: from a copy kept before
+the command, or - another module - as its last commit has it, unless a pulse is at work in that module, whose writes are
+not this command's to undo (left, and logged). Nor is a change the conversation made while the command ran: the chat's
+`edit` and `write`, a spec diff it applied, or anything while a command of its own ran - the chat editing a spec beside a
+pulse is the person's change, not the agent's, so it is left and logged (`src/regenerate/conversation-writes.ts`). The agents
+of a pulse start without extensions, so nothing of theirs is marked so. The agent is told in its command's result what was put back; the job's
+log gets a line; you are not told, and the pulse goes on. It compares sizes and modification times, skipping
+dependencies and build output, and contents only where those differ - about 35 ms on a project of 3000 files. Outside
+the project nothing can be put back: that is the OS sandbox's, and on Windows an accepted gap.
+
+## The web
+
+Every rendering agent - render, spec change, conformance, regression repair - can also search the
+web and read a page, for a library's documentation or an error it has not seen:
+
+| Tool | What it does |
+| --- | --- |
+| `web_search` | asks DuckDuckGo (no key needed) and returns title, address and snippet per result |
+| `web_fetch` | reads one page and returns it as text - HTML without its markup, text, JSON or XML as it is; long pages come in parts |
+
+`web_fetch` reads only the public web: localhost, the private ranges and the cloud metadata address are
+refused, and so is every redirect that leads to one - what the code talks to on this machine, the agent
+reaches with its own commands.
+
+DuckDuckGo is used without a key through its Lite page, which is not an official API: it rate-limits,
+and a search that is turned away tells the agent to wait or fetch a page it knows instead.
+
+## Outside the sandbox: deploy
+
+What `deploy` starts runs on your machine unfenced: you asked to try the software, with your toolchains,
+in your browser. It runs from `dist/<module>`, a copy of the last
+commit outside `plain_modules`, so no rendering agent reaches it. Nothing is installed there without
+your say-so - every command that would install or download is put to you first, and the chat's shell
+refuses the rest. See [deploy](deploy.md).
+
+## What turri keeps beside the code
+
+It lives in `plain_modules/.turri`, which ignores itself in git:
+
+| | |
+| --- | --- |
+| `cache/` | package caches - pip, npm, cargo, Maven, Gradle, Go - so a dependency downloads once per project |
+| `home/<module>` | each module's home folder for its agents' commands, kept between pulses |
+| `tmp/<module>` | each module's `TMPDIR` |
+| `scripts/` | the throwaway copies test runs happen in, emptied after each run |
+| `logs/` | whole outputs cut short for an agent, read through `read_output` |
+| `services/` | what the services agents started printed |
+
+## What the machine lacks
+
+The agents use this machine's toolchains, and install nothing on it: not a toolchain, a system package, a driver or a
+global package. The project's own dependencies are theirs, through its package manager, into the project and its
+caches. What the machine lacks is yours to install: an agent that finds something missing reports it, the pulse stops,
+and you are told what to install - see [when the environment lacks something](regenerating.md#when-the-environment-lacks-something).

package/docs/skills-and-gates.md

@@ -0,0 +1,254 @@
+# Skills and gates
+
+A skill's review step is normally a paragraph asking the agent to check its own work. Agents talk
+their way past paragraphs. turri makes the review an edge in a graph instead: the harness
+decides when a gate runs, spawns the judges itself, and branches on a structured verdict. The
+model's only job is producing the artifact under review.
+
+pi supplies the agent runtime (sessions, tools, multi-provider models); LangGraph supplies the
+control flow. The gate syntax lives in `SKILL.md`, so a gated skill still loads in any
+spec-compliant harness - it just runs ungated there.
+
+## The syntax
+
+Under `metadata:`, which the Agent Skills spec reserves for arbitrary key-values:
+
+```yaml
+---
+name: draft-spec
+description: Drafts a ***plain spec, judged before it is kept.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+metadata:
+  gates:
+    - after: product                      # the ### step this gate guards
+      review:
+        rubric: ./references/rubric.md
+        judges: 2                         # independent sessions, not n samples of one
+        model: anthropic/claude-sonnet-5  # optional; defaults to the executor's model
+        quorum: all                       # all | majority | any
+        on_fail: retry                    # retry | escalate | abort
+        max_retries: 2
+        judge_tools: [read, ls, grep, find]   # read-only tools the rubric needs
+---
+
+## Steps
+
+### product
+...prose the executor reads...
+
+### finalize
+...
+```
+
+A skill declares its steps with a `## Steps` section whose `###` headings are the steps; without
+it the whole skill is one step, which is what most skills are. Steps are never inferred from `###`
+headings elsewhere in the body - prose skills are full of those. Each gate becomes a conditional
+edge after its step; a single-step skill is gated by naming the skill itself. None of the skills turri ships
+declares a gate today - `brood`'s phases end on the person's confirmation alone - but a project's own skill can.
+
+`paced: false` under `metadata:` lets a skill write spec changes one after another on its own:
+`write_spec_diff` otherwise refuses a new change until the user has answered a question since the
+last one - one answer, one change, as an interview writes them. `spawn` is unpaced: the tool tells it so, and after
+each change to write the next at once, not to carry on with an interview it does not have.
+
+`questioning:` under `metadata:` names the steps the questioning level caps (`src/questioning.ts`) - `brood`'s
+`[stack, product]`. When there are any and someone to ask, the harness itself asks the first question of the first
+step: how many questions those steps may ask - light (3), medium (5), thorough (10) or best judgement - and tells the
+agent the answer beside each step's instructions, with how broad each question is to be: broad at light, a whole area
+at once, narrow at thorough, an edge case at a time. Every level covers the same ground, in less or more depth. In a
+capped step `ask_user` refuses a question past the cap; the step's closing confirmation, asked with
+`confirms_phase: true`, is never counted. `end_questions` ends the step's questions sooner - best judgement's only
+end. What the questions leave open, the agent decides itself and says what it chose. The level, and how many
+questions each step has asked, are kept in the run's `run.json`, so a resumed run keeps them. A step it does not name,
+or a run with nobody to ask, is not capped.
+
+`spec-diff-per-answer:` under `metadata:` names the steps where every answer is a spec change - `brood`'s
+`[product]`, at every questioning level. There `ask_user` refuses the next question until the last answer is written
+with `write_spec_diff` (a confirmation, or a question dismissed, owes nothing), and `write_spec_diff` no longer waits
+for an answer before a change: the agent writes as many as the step needs, those it decides itself included. The
+level limits the questions, never the spec changes.
+
+A step ends when its agent's turn does. A turn that ends on a question in the reply would end the step there, half
+done, on a question no one reads - the person sees only what `ask_user` asks. So such a step is sent back, twice at
+most: to ask with `ask_user` if the question is truly the person's, or, in an unpaced skill, to decide it itself -
+then to carry on until the step is done.
+
+`phases:` under `metadata:` says what each step does, in a short line a step by its name - for the person, not
+the agent: while the skill runs, the line above the input shows its phases, and under them the one it is in with
+its line (`groundwork - the language, frameworks, storage and architecture`). A phase's name alone
+says little to someone who has not read the skill. Every skill with more than one step describes each; a line for a
+step the skill does not have is an error, as a gate after one is.
+
+A skill gets the tools its `allowed-tools` names, and nothing else: one that names none has none. So
+every skill here names its own - the file tools (`read`, `write`, `edit`, `bash`, `ls`, `grep`, `find`)
+for the ones that write specs, resources or scripts, only the reading ones for those that analyse
+and report, and turri's own (`write_spec_diff` and the ones below) where a skill uses them.
+
+What a run changed is part of its result: every file of the project it added, changed or removed -
+its specs, resources, scripts; not the built code - or that it changed none, which is said as such,
+so a run that wrote nothing is never reported as done. A skill without gates says it was not
+reviewed. A `.plain` file a skill edited with the file tools is not rendered by it: the result says
+so, for the conversation to render the change.
+
+A skill acts on the work loop with the conversation's own tools, on the conversation's loop - never
+copies of them (`src/loop-tools.ts`). Every skill with the loop has `drift`: what is left to regenerate, what
+is regenerating, and "Fully regenerated" once nothing is. One that lists `regenerate` and `halt` in `allowed-tools` -
+as `mature` does - can regenerate what a module's spec holds and halt a pulse, with why. `mature` lists two
+tools of its own as well: `watch_jobs` waits for its pulses, coming back as soon as one struggles -
+sent back four times or more, five setbacks, a spec conflict, a failure run again, over half an hour -
+with what it went through; `spec_findings` reads back, numbered and each once, what the pulses recorded
+since the run started: the assumptions and pitfalls in every codebase's working notes, a failed pulse's
+diagnosis, a spec that contradicts itself.
+
+Each step is told where its skill's files are, so a path it names - `references/intent.md` - and a
+skill it says to follow - `implement-unit-testing-script` - are found without searching.
+
+## What the harness enforces, not the model
+
+- **Whether review happens.** The gate is an edge. There is no prompt the executor can write that
+  skips it.
+- **How many attempts.** `max_retries` is a counter in graph state. The executor is never asked how
+  many tries it would like.
+- **What "fail" means.** Judges answer through a schema (`submit_verdict`), so the router branches
+  on a value. A judge that returns no verdict counts as a fail - silence is not consent.
+- **What gets reviewed.** The executor's only write path for the artifact is `write_artifact`,
+  pointed at a path the graph chose. A step that produces no artifact fails its gate without
+  spending a single judge call.
+- **Who is judging.** Each judge is a fresh session given the artifact and the rubric and nothing
+  else. It never sees the executor's transcript, because a judge that inherits the actor's
+  reasoning inherits its rationalisations.
+
+`on_fail: escalate` (and `retry` once retries are exhausted) pauses the graph on a LangGraph
+`interrupt`: in the TUI that is a real confirm dialog; with no UI there is nobody to ask, so the
+gate stands and the run stops.
+
+`judge_tools` gives a gate's judges read-only tools, for a rubric that checks what is on disk.
+Judges get nothing by default, which is right when the artifact is the whole subject.
+
+A gate can also have a `continuous` reviewer: a read-only agent that re-reads the work after every
+change the step makes and puts its findings on the executor's next tool result.
+
+## What a step can do
+
+- **Interview the user.** `ask_user` puts one question to the person. In the TUI it is a dialog;
+  from the CLI the options are numbered. Offering choices is required, not optional - a call with
+  neither `options` nor `free_form: true` is refused - and every list carries "Something else…".
+  `multi_select: true` keeps offering what is left until they are done. The skill's agent talks in a
+  session of its own that the person never sees, so what the person must read to answer - the brief
+  to confirm, the plan to approve - it passes as `ask_user`'s `context`, shown above the question in
+  the dialog; `brood`, `spawn` and `bud` pass their briefs so. The agents are told to keep it to what can be taken in at
+  a glance, about fifteen lines; one longer scrolls in a window of its own above the question (`src/question-dialog.ts`) -
+  PgUp/PgDn, Shift+Up/Down or the mouse wheel - so the question and its options always show below it. pi's own select,
+  which turri used before, put it all in its title, and a long brief pushed the options off the screen. Nothing else it wrote is shown there:
+  the last thing it said before asking - its account of a probe, a regeneration - is kept with the answer,
+  in the run's trace and the transcript, never in the dialog.
+
+  Beside "Something else…", every list an agent's question shows carries "Chat about this": the person says what they
+  want to talk over - why it is asked, what an option means for later - and it goes back to the agent that asked, as no
+  answer. A skill's agent answers in the `context` of the question asked again, since nothing else it writes reaches
+  them; the conversation's agent answers in its reply and ends its turn, the person going on in the chat. It is not
+  counted against the questioning level, and owes no spec change. The harness's own first question - how many the
+  phases may ask - has no agent to answer, and does not offer it. Either choice is backed out of with Esc, or by typing
+  nothing: the options come back, so one picked by accident costs nothing. Esc on the options themselves dismisses the
+  question.
+- **Be asked something on the side.** A skill runs inside one `cultivate` call, so the conversation can answer
+  nothing until it returns. `/btw <question>` (`btw.ts`) can: pi runs a command at once, even mid-turn, and it starts
+  an agent of its own - fresh, on the chat's model, reading the project and turri and changing nothing - shown the
+  conversation, the running skill's trace and the end of its agent's session, and the pulses. It is told it is turri,
+  as the conversation's agent is (`identity.ts`), and answers as turri, in the first person - never as an onlooker
+  who sends the person to turri with a message to pass on. Its answer goes in the
+  transcript as an entry, in no model's context: the conversation and the skill go on as if nothing was asked. While
+  a question of the skill's has the keys, `/btw <question>` typed as the answer (under "Something else…") is the
+  same: answered, and the question asked again with the answer above it - the skill's agent never sees it.
+- **Build while it interviews.** `write_spec_diff` (`brood`, `spawn`) writes a change to the
+  spec and queues its render in one call; the interview carries on while the builds run in the
+  background, one after another. `drift` shows how they stand. The person sees its calls as
+  `mutate`: a tool can be shown by a name of its own (`SHOWN_AS` in `regenerate/activity.ts`), while its
+  agent calls it by the one that says what it takes.
+- **Regenerate, and conform.** A skill that names them in `allowed-tools` gets the conversation's own
+  `regenerate`, `drift`, `halt` and `conform`, on its loop: `conform` schedules a conformance pulse for functional specs not built
+  yet, as it does from the chat. The skill never waits for them.
+- **Choose the render model**, when the user says so - `engine`, the same tool the
+  conversation has.
+
+The harness still owns the sequence. A step chooses what to ask; it does not choose whether the
+gate afterwards runs. A run is saved as it goes, so an interrupted one can be resumed where it
+stopped.
+
+While a skill runs in the chat, `cultivate`'s output leads with what its agent is doing now: the skill,
+its step and how long each has taken, its last few tool calls, and the end of what it is saying,
+refreshed every few seconds. pi shows only a running tool's first lines, and a step can take many
+minutes without a new line in the trace. The result the conversation gets back keeps the trace
+alone.
+
+## A project's own skills
+
+A project can have skills of its own, in the same format: a folder a skill, with its `SKILL.md` - steps, gates,
+rubrics in its `references/` - in `.turri/skills/` or `.agents/skills/` of the project's folder (`src/skills.ts`).
+turri finds them as it starts, beside its own, and `cultivate` lists each as the project's, with where it is; `turri
+cultivate <name>` runs one by name, as it does turri's own. They are run as turri's own are: the harness owns their
+steps and gates, and their agents get the tools their frontmatter names.
+
+A name is one skill. turri's own come first, then `.turri/skills/`, then `.agents/skills/`; a skill whose name is taken
+already is left out, and the list says so - a project's `brood` never quietly stands in for turri's. A
+skill that does not parse is said to have failed to load, by its folder.
+
+`.turri/` is turri's scratch folder and ignores itself, all but `skills/`: its `.gitignore` is `*`, `!skills/`,
+`!skills/**`, and one written before is brought up to date. pi reads `.agents/skills/` too, as skills of its own the
+chat could follow by hand - the chat is told to run any `cultivate` lists with `cultivate`, so its gates still run.
+
+The skills pi offers the chat leave out what turri has already (`src/chat-skills.ts`): a skill of a name turri runs
+itself - its own, or the project's - and any skill about \*\*\*plain, its specs or their testing scripts. pi gathers
+skills from `~/.pi/agent/skills`, `~/.agents/skills` and the `.agents/skills` of every folder from where turri started
+up to its git root, so a folder above the project can hold another tool's \*\*\*plain skills - a `load-plain-reference`
+the chat would load at the start of every session, though the whole \*\*\*plain reference, turri's
+[rules](#rules), is in its system prompt already. The person is told once which were left out. A skill about anything
+else is offered as pi offers it.
+
+A skill is found once, as turri starts: one added while it runs is there the next time. A project's skill agent runs
+as turri's do - pi's file tools and `bash` on the machine, no fence - so a project's skills are as trusted as the
+project.
+
+## Rules
+
+`genome/rules/` holds the \*\*\*plain authoring rules. Every rule, in full, is appended to the system
+prompt of the conversation and of the agents that write specs - never of the ones that write code.
+The block is byte-identical every time, so it sits inside the cached prefix - but it is ~40k
+tokens. The trade is deliberate: a rule the model has to decide to go and read is a rule it can
+skip. `src/rules.ts` is where to change it.
+
+## Trying the gate semantics
+
+The gate machinery - the no-artifact rejection, the retry loop, escalation - is verified by live
+runs rather than automated tests. To poke at it, give a skill a gate like the one in [the syntax](#the-syntax) - a
+project's own, in `.turri/skills/`, with a rubric in its `references/` - run it with `turri cultivate <name>`, then
+change the gate:
+
+| change | expected |
+| --- | --- |
+| `max_retries: 0` | the first failure escalates instead of retrying |
+| `on_fail: abort` | the first failure ends the run, exit 1 |
+| `quorum: any` | one passing judge is enough |
+| `judges: 3` | three sessions run concurrently |
+| `model: google/gemini-3-pro` | judges run on another provider; an unconfigured model falls back with a note |
+| `after: drafts` | rejected at load: `gate references unknown step 'drafts'` |
+
+A trace, with a rubric strict enough that the first draft fails:
+
+```
+> step draft  attempt 1
+  | Expired cached tokens are now ignored and removed instead of being returned.
+> gate draft  2 independent judges
+  judge 1: fail (2)
+  judge 2: fail (2)
+  retry <- gate draft
+    - [starts with Fixed:/Added:/Changed:] ...
+    - [names the source file that changed] ...
+
+> step draft  attempt 2
+  | Fixed: src/cache.ts now ignores and removes expired cached tokens instead of returning them.
+> gate draft  2 independent judges
+  judge 1: pass
+  judge 2: pass
+  advance <- gate draft
+```

package/docs/theming.md

@@ -0,0 +1,76 @@
+# Theming
+
+Two brand themes ship in `.pi/themes/`, built from the brand tokens. `turri` starts in
+`turri-dark`, the dark one; `--use-theme` picks another for that run:
+
+```bash
+turri                                       # turri-dark
+turri --use-theme turri-light/turri-dark    # follows terminal appearance
+turri --use-theme dark                      # pi's own
+```
+
+The second form follows your terminal's light/dark appearance. The default is for
+`turri` only: pi's settings are left alone, so a plain `pi` keeps its theme. With the
+themes copied to `~/.pi/agent/themes/` (`cp .pi/themes/*.json ~/.pi/agent/themes/`), `{"theme": "turri-dark"}` in
+`~/.pi/agent/settings.json` gives a plain `pi` the same one.
+
+Bad input fails quietly - an unknown `--use-theme` name and a malformed theme file both run without
+complaint - so if the colours do not change, suspect a typo rather than the mechanism.
+
+## Why there are two
+
+Half the palette is unusable on the other background. Contrast against brand black and brand
+white:
+
+| token | on `#0f0f0f` | on `#ffffff` |
+|---|---|---|
+| brand-yellow | 17.07 | 1.12 |
+| brand-green | 14.77 | 1.30 |
+| brand-green-light | 13.34 | 1.44 |
+| brand-blue | **1.97** | 9.72 |
+| brand-green-dark | 1.56 | 12.31 |
+| brand-red | 3.38 | 5.67 |
+
+So `turri-dark` carries yellow, green and green-light, and `turri-light` carries blue and
+green-dark. **Brand blue never appears as text in the dark theme** - at 1.97:1 on brand black it is
+illegible - so the dark theme's accent is brand yellow, and blue appears only in the light theme
+and in both themes' HTML-export backgrounds. The one place blue stands for something in both is the spec
+map's `◆` - a functional spec its conformance tests pass for: brand blue in a light theme, and in a dark
+one its tint 55% of the way to white, `#919aec`, 7.34:1 on brand black (`brandBlue` in
+`src/regenerate/plain-palette.ts`).
+
+`--color-brand-status-warning` on white is 3.49:1, under the 4.5:1 bar for body text, so it is used
+only for accents in the light theme, never for prose.
+
+## Backgrounds
+
+The dark theme paints no panels: the backgrounds of your messages, turri's messages and the
+tool rows are `""`, the terminal's own background, so the transcript reads as one surface whatever
+the terminal's colour is - brand black or not, no block shows up as a box. Two are deliberately
+painted, because they have to be visible to work:
+
+| token | value | why |
+|---|---|---|
+| `selectedBg` | `#223936` | a selection you cannot see is not a selection |
+| `searchMatchBg` | `#e0ff6e` | search hits, with black text on top |
+
+With tool rows carrying no background, their state is signalled by the title and the diff colours.
+
+**The window's background is your terminal's setting**, and the transcript is drawn on it. For the
+brand look, set it to brand black, `#0f0f0f`, in your terminal profile.
+
+## Spec diffs
+
+A spec diff in the panels is not painted with the theme's colours for code: those are made for code,
+and the turri themes' backgrounds are all the surface colour, so a diff drawn with them would have no
+fills and hardly any highlighting. It has a palette of its own (`src/regenerate/plain-palette.ts`), one for
+a dark theme and one for a light, picked by the theme's appearance: a hue for each piece of \*\*\*plain -
+a section's header, a concept, a link, text in quotes or backticks, a front matter key, a module,
+a comment - at least 7:1 on the surface, and a fill behind each added and removed line, green and red,
+that every colour still reads on.
+
+## The font
+
+`--font-brand` cannot be applied. pi draws into a terminal, so the typeface is your terminal
+emulator's setting, and NeueMontreal is proportional - a terminal needs a monospaced face. Set it
+in iTerm2 / Ghostty / Alacritty, not here.