@turri-dev/cli 0.0.0-stage → 0.1.1

package/docs/deploy.md

@@ -0,0 +1,109 @@
+# Trying what is built: deploy
+
+Ask to try it - "let me try it", "run the app" - at any time, even while a render is running. The
+chat calls `deploy`: it puts the module's code, as it was last built, in `dist/<module>` in the
+project, and starts it on your machine. An app with a backend and a frontend is started whole, and
+you are told where to open your browser. For a command-line tool or a library you get a few commands
+to paste, run from `dist/<module>`, and what they print.
+
+Every pulse that lands code - a render, a spec diff, a conformance run, a functionality regenerated - ends with
+"Want to try it? Just ask me - I'll set it up from what's built so far." When a render's conformance
+tests follow as a pulse of their own, the conformance pulse says it, once they pass too.
+
+## When the project says how it is released
+
+Every release starts the same way: the module's last commit - what last landed whole - goes in
+`dist/<module>`, as below. Not everything is tried from there, though. An integration that a host
+application loads goes on into the host's own tree, with the host's own scripts, and then the host
+is started. So the model asks itself whether there is guidance for how this project is released -
+in what you said, the project's AGENTS.md, a skill, anything it was given - and passes it to
+`release` whole:
+
+- **There is guidance.** The code goes on from `dist/<module>` as the guidance says, on your machine,
+  from the host codebase - the git repository the project is in, or else where **turri** runs: the
+  scripts it names, in their order, and any change it says the host needs. The code is taken from
+  `dist`, never from `plain_modules`, where a pulse may be writing; where the host's tooling reads
+  `plain_modules` itself, the model points it at `dist`, or does by hand from `dist` what it does. When
+  to release - after every pulse, say - is the guidance's to say too. The rules below hold as they do for `dist`: the
+  model runs the project's scripts and installs what they need itself, and what keeps running - a
+  start script, a server - is started with `activate`. Nothing built is changed.
+- **There is none.** The default: it is started from `dist/<module>`, as below, as best it can be.
+
+Guidance is whatever says it, in any words - a line in AGENTS.md such as *integrations are released
+with `scripts/deploy_integrations.sh`, then the app is started with `scripts/start.sh`*, or the
+same said in the chat.
+
+The chat reacts to every pulse that finishes as it finishes, without waiting for you to speak: guidance
+that says to release after a build - *release each integration once it is regenerated* - is followed then.
+It never has to work out whether what a pulse landed is already out: `release` does. When the module's
+last commit is what its last release in this conversation shipped, it does nothing - nothing exported,
+nothing stopped, what runs left running - and says so; `again: true` releases it anyway, for when what
+that release said to do was not done.
+
+## What goes in dist
+
+- **The module on top.** Code accumulates up a `requires` chain: a module starts from a copy of the
+  code of the one it requires. So deploy always takes the module on top of the spec's chain - the
+  project's `module` from `config.turri.yaml` unless another spec is named. Before the module on top has
+  anything built, it takes the nearest one below it that has, and says so.
+- **Its last commit.** Each `plain_modules/<module>` is a git repository (`.plaingit`), and every unit
+  of work starts from a commit and ends with one. What a pulse is writing right now is half-done, so it
+  is left out: deploy exports the commit - `git archive` of `code/` - which is the working tree with
+  every unstaged and untracked change put back, and no `node_modules`, `.venv`, `target` or other
+  build leftovers, whatever the stack. The working tree the pulse is using is never read or touched.
+  The harness's own files - `.turri.json`, the agents' notes - are left out too.
+- **Replaced whole.** Each deploy stops what the last one of the module started, empties
+  `dist/<module>` and exports again. Change nothing there you want to keep. `dist/` is not added to
+  `.gitignore`: whether it is committed is yours to decide.
+
+## Starting it
+
+It runs on your machine, outside the [sandbox](sandbox.md) - with your toolchains, where your
+browser can reach it. The chat reads how the code runs (its README, manifests and entry points),
+then:
+
+1. **Checks the toolchains** it needs (`node`, `python3`, `go`, ...). One is missing: it installs it
+   with the machine's package manager (`brew` on macOS, `apt` or `dnf` on Linux).
+2. **Installs what it needs itself.** Dependencies into a virtual environment or `node_modules`, a
+   build that downloads packages, an image pull, a guided release's project scripts: it runs them in
+   its own shell, as any agent with a shell would, and fixes what fails. Nothing is put to you - there
+   is no dialog to answer.
+3. **Starts what serves** with `activate`: in the background, in its own process group, its
+   output in `.turri/deploy/<module>-<name>.log`. It waits until something answers at the
+   server's URL - up to a minute - so the URL you are given has answered once; one that exits first
+   comes back with the end of its output. A port something else holds is said, with what holds it,
+   and nothing is started there: the app is not moved to a port you were not told about.
+
+What it started is listed by the `pulses` tool and by **`/halt`**, and stopped by **`/halt activated <name>`**, by
+`halt`, by the next deploy of the module, and when the chat exits.
+
+## After every pulse
+
+With `release-after-pulse: true` in `config.turri.yaml`, turri releases what each pulse lands itself, as the
+pulse's last stage (`releasing what this pulse landed`): the pulse ends once it is released, so the
+module's next pulse starts on what is out, and the chat - waiting on your answer to a question, say - has
+no part in it. One release a pulse that lands, in order.
+
+The release is done by an agent on the coding model, thinking low - it follows steps, and a small model does that
+well - the same one `turri release` runs, and it finds
+the guidance as the chat would: what was passed to `release` earlier in the conversation, the project's
+AGENTS.md and its skills. When nothing there says to release after a build, it releases nothing and says
+so. Its last words go in the pulse's report - "Released after the pulse: ..." - and the chat, seeing them,
+does not release it again. A release that fails is said there too; what the pulse landed stays.
+
+Off by default: without the key, releasing after a pulse is the chat's, when its guidance says so.
+
+## On the command line
+
+```bash
+turri release [file.plain] [--in-module <module>] [--guidance <text>] [--model <provider/id>]
+```
+
+The same, without the chat: a one-off agent on `coding-model`, thinking low (or `--model`; without either,
+pi's default) is given the project's AGENTS.md and what `--guidance <text>` says, looks for guidance in
+them, and releases as above - as the guidance says, or to `dist/<module>` - then works out how to
+start it and starts it here, installing what it needs without asking. It stays in the foreground with the servers'
+output; `Ctrl-C` stops them. If it does not get there, deploy from the chat instead.
+
+`turri regenerate`, `spec-diff` and `conform` end a build that landed with
+`To try it: turri release <spec>`.

package/docs/development.md

@@ -0,0 +1,75 @@
+# Development
+
+```bash
+npm run typecheck   # types
+npm test            # the whole suite, about a minute
+```
+
+The suite runs the projects' testing scripts on this machine, as turri does. The fixture scripts stage each run in a
+folder of their own, as test files running side by side would otherwise share one.
+
+## Mutation testing
+
+`npm run mutation` runs [Stryker](https://stryker-mutator.io) over the core of regeneration - the parts in
+`stryker.config.mjs` - one part at a time, each part's report in `reports/mutation/<part>/`. A part with a report is
+skipped, so a run that is stopped goes on from the part it was in; `npm run mutation -- <part>` runs one again, and
+`npm run mutation -- --summary` sums up the reports there are. It takes hours: each part runs the suite once to find
+which tests reach which mutant (`vitest.stryker.config.ts`, the suite without the files that run real commands behind the sandbox), then each
+mutant against those tests. `scripts/mutation.mjs` sets two things in Stryker's vitest runner the suite needs - forked
+workers, and a test-name filter that matches vitest 5's names - again after every `npm install`.
+
+Working on turri itself, `npm link` points the global `turri` at this clone, so edits
+take effect immediately. `npm run chat` starts pi with the extension loaded from `src/`.
+
+The package on npm is built: Node runs no `.ts` file inside a `node_modules`, so `npm run build` (`scripts/build.mjs`,
+over `tsconfig.build.json`) compiles `src/` into `dist/`, file for file - each file as deep as its source, so it finds
+`genome/`, `stdlib/` and `.pi/` the same way - with its imports' `.ts` rewritten to `.js`, and copies the other files
+in `src/` beside them. `npm pack` and `npm publish` run it first (`prepack`), and the package holds `dist/`, not
+`src/`. `bin/turri.mjs` runs `src/cli.ts` where there is one and `dist/cli.js` otherwise; `cli.ts` starts pi with
+the launcher and extension beside itself, whichever they are. To try the package as users get it:
+`npm pack`, then `npm install -g ./turri-dev-cli-<version>.tgz`.
+
+## Layout
+
+| path | what it is |
+|---|---|
+| `bin/turri.mjs` | the launcher: checks the Node version, then loads `src/cli.ts` |
+| `src/cli.ts` | the `turri` command and its subcommands |
+| `src/setup.ts`, `src/environment.ts`, `src/stack.ts` | `turri doctor`, and what it checks - this machine, and in a project what its modules need of it |
+| `src/extension.ts` | the pi extension: every tool and command the conversation has |
+| `src/skill.ts` | parses `SKILL.md` into steps and gates |
+| `src/graph.ts` | compiles a skill into a LangGraph `StateGraph`: step -> gate -> route |
+| `src/judge.ts` | runs independent judges, applies the quorum, builds the critique |
+| `src/genome.ts` | `runSkill()` - the one entry point the CLI and the extension share |
+| `src/pi.ts` | pi session factories for executors, sub-agents and judges |
+| `src/spec-tools.ts` | `write_spec_diff` |
+| `src/loop-tools.ts` | `regenerate`, `drift` and `halt` - one definition each, for the conversation and the skills alike |
+| `src/mature-tools.ts` | `mature`'s own two: `watch_jobs` and `spec_findings` |
+| `src/plain/` | the \*\*\*plain parser - see [parser](parser.md) - and `highlight.ts`, which highlights \*\*\*plain with plyn's grammar, `plain.tmLanguage.json` (`npm run grammar:sync` refreshes it from [plyn](https://github.com/plainlang/plyn)) |
+| `src/regenerate/conformance.ts` | conformance tests: writing them, and fixing the test or the code until they pass |
+| `src/regenerate/regenerate.ts`, `src/regenerate/conform.ts` | a code job - a spec diff rendered in the code - and a conformance job |
+| `src/regenerate/loop.ts`, `src/regenerate/records.ts`, `src/regenerate/drift.ts`, `src/regenerate/jobs.ts` | the work loop, the records and the work derived from them, and background jobs |
+| `src/regenerate/chunk-plan.ts`, `src/regenerate/cases.ts` | cutting the work into jobs, and what a job's agents are told by its cases |
+| `src/regenerate/regression.ts` | the whole conformance suite run, and the repair agent that may not touch tests |
+| `src/regenerate/lineage.ts` | module history in `.plaingit` |
+| `src/regenerate/release.ts`, `src/release-tools.ts`, `src/release-cli.ts` | deploy: the last commit to `dist/<module>`, what installs software, what it starts on the host - see [deploy](deploy.md) |
+| `src/regenerate/confine.ts`, `src/regenerate/agent-shell.ts`, `src/regenerate/command-check.ts`, `src/regenerate/os-sandbox.ts`, `src/regenerate/audit.ts`, `src/regenerate/agent-env.ts`, `src/regenerate/shell.ts` | the file-tool fence and the walls around every agent command: the check, the OS sandbox, the audit, the module's environment, the host runner - see [sandbox](sandbox.md) |
+| `src/regenerate/engine.ts` | choosing and resolving render models |
+| `src/regenerate/job-panel.ts`, `src/regenerate/transcript-view.ts`, `src/regenerate/diff-view.ts` | the job panel, the side panel's colours, and a spec diff as they show it - highlighted and banded |
+| `src/regenerate/spec-map.ts`, `src/regenerate/spec-map-view.ts` | regen: each item's mark, from the records, the `.plain` files and the work loop's plan (`mapPlan`), and the map drawn |
+| `src/regenerate/debug-log.ts` | each render agent's whole conversation, always streamed to `.turri/debug/` |
+| `genome/` | what turri knows and can do: `genome/skills/`, the skill library, and `genome/rules/`, the \*\*\*plain authoring rules |
+
+## Known edges
+
+- Judges default to the executor's model. Real separation wants a different provider - set
+  `model:` on the gate. An unconfigured model falls back to the executor's with a note rather than
+  failing the run.
+- The executor keeps one session across steps and retries, so context builds up with attempts. Long
+  skills want compaction or a session per step.
+- A gate's escalation lives in memory (LangGraph's `MemorySaver`): it must be answered in the same
+  run.
+- The gate machinery has no automated coverage; see
+  [trying the gate semantics](skills-and-gates.md#trying-the-gate-semantics).
+- Jobs live in memory: there is no resuming a job after pi exits. The work itself is on disk, so a
+  killed job leaves a partial build rather than nothing.

package/docs/headless.md

@@ -0,0 +1,148 @@
+# Running unattended
+
+Given a spec, build it without a conversation - overnight, in CI, on a spare machine.
+
+## Before you leave it
+
+```bash
+turri doctor
+```
+
+Everything marked `✗` stops the run, so fix those first. Two more things matter for a long run:
+
+- **The toolchains.** The agents use this machine's: run `turri doctor` in the project, and it says which toolchain
+  a module's implementation reqs name that this machine lacks.
+- **The models.** In a project, `turri doctor` sends each model `config.turri.yaml` names one short request, as turri's
+  agents will - so a key the provider refuses, a model pi does not know or an account without access to it shows now,
+  not an hour into the run.
+- **Credentials that do not expire mid-run.** An API key in the environment
+  (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...) or pi's saved login - whatever
+  `doctor` shows as the model provider.
+
+Check the spec parses, without spending anything:
+
+```bash
+cd ~/my-project                  # the directory that holds the spec
+turri validate app.plain
+```
+
+## Run it
+
+```bash
+turri regenerate app.plain --model anthropic/claude-sonnet-5
+```
+
+That builds every functionality in order - code and unit tests, then conformance tests when the
+module has `***test reqs***`, then every conformance test so far - and advances only when they
+pass. A module that `requires` others builds them first, bottom up. When it is done it prints
+`To try it: turri release <spec>` - see [deploy](deploy.md).
+
+Keep it running when the terminal closes and the laptop would sleep, and keep the log:
+
+```bash
+# macOS: caffeinate keeps the machine awake for as long as the command runs
+nohup caffeinate -is turri regenerate app.plain --model anthropic/claude-sonnet-5 > render.log 2>&1 &
+
+# Linux
+nohup turri regenerate app.plain --model anthropic/claude-sonnet-5 > render.log 2>&1 &
+```
+
+Or run it in `tmux` / `screen` to look in on it. `tail -f render.log` follows it either way.
+
+The project's `config.turri.yaml`, in the folder you run it from, can give the defaults, so a run can
+be just `turri regenerate`:
+
+```yaml
+module: app.plain                         # what to build when no file is given
+coding-model:                             # the model every agent runs on, and how hard it thinks
+  model: anthropic/claude-sonnet-5
+  thinking: medium
+judge-model: anthropic/claude-opus-5-5    # the judge and the test review (default: coding-model)
+conformance-tests: true            # write and run conformance tests where there are test reqs (default: false)
+```
+
+The same file names the [testing scripts](regenerating.md#the-testing-scripts); every key is in
+[the project config](config.md). Options on the command
+line win over it; `turri regenerate`, `spec-diff` and `conform` take its
+`coding-model` too, and `--coding-model` means the same as `--model` on every one of them.
+A project whose parts are on different stacks keeps each stack's settings in
+`config.turri.<stack>.yaml` beside it ([stacks](config.md#stacks)). Choose the one to build with
+`--stack <name>` - on any command: `regenerate`, `conform`, `spec-diff`, `glimpse`, `release`, `cultivate` -
+or `TURRI_STACK`: `turri regenerate backend.plain --stack backend`. With none chosen,
+`config.turri.yaml` alone is used; a stack the project has no file for is refused.
+
+Useful options - `turri regenerate --help` lists all of them:
+
+| | |
+| --- | --- |
+| `--model <provider/id>` | the model every agent runs on (`--coding-model` too), with `:level` for its thinking (`provider/id:high`); default, `config.turri.yaml`'s `coding-model`, then its `harness-model`, then pi's configured model |
+| `--judge-model <provider/id>` | `conformance`: the model of the judge and the test review; default, `config.turri.yaml`'s `judge-model`, then the coding model |
+| `--stack <name>` | build with the stack's `config.turri.<name>.yaml` over `config.turri.yaml`; default, `TURRI_STACK`, else none |
+| `--to <frid>` | queue functionalities only up to this one |
+| `--only` | build just this module, not the ones it requires |
+| `--build-dir <dir>` | where the code goes; default `plain_modules/<module>/code` |
+
+`turri regenerate` queues the jobs the chat's `regenerate` does - a spec diff that brings what
+is built in line, when it no longer matches the spec, then one render functionality job per
+functional spec not built, each with its conformance job - and runs them all to the end, the queue
+master reworking them as in the chat (see [a whole module](regenerating.md#a-whole-module)).
+Conformance tests follow `conformance-tests:` in `config.turri.yaml`.
+
+## In the morning
+
+The command exits `0` only when every module is complete. The log says, per functionality, what
+was built and whether its tests passed; the last lines summarise each module.
+
+| | |
+| --- | --- |
+| `plain_modules/<module>/code/` | the code and unit tests |
+| `plain_modules/<module>/tests/` | the conformance tests |
+| `plain_modules/<module>/code/.turri.json` | the marshalled plain tree the code is built from |
+
+And what happened, step by step, in the module's history:
+
+```bash
+git --git-dir=plain_modules/<module>/.plaingit --work-tree=plain_modules/<module> log --stat
+```
+
+## If it stopped
+
+Run the same command again. Functionalities already built from the current spec are left alone,
+and modules that are complete are skipped, so it picks up where it stopped - after a crash, a
+provider outage, or a machine that went to sleep anyway. Whatever the stopped run left
+half-written is undone first: each step starts from the module's last commit. A functionality whose spec has changed
+since counts as not built, so editing the spec and re-running rebuilds what changed. `--force`
+rebuilds everything.
+
+## Rebuilding one functionality
+
+```bash
+turri regenerate app.plain 3
+```
+
+It rebuilds just functionality 3 over the code that already exists - after its spec changed, or as
+it is - without rebuilding the ones before it. To change what it does, change its spec first: the
+spec is what the code is built from, and a change made there lasts. Then it updates the
+functionality's conformance tests and runs every conformance test in the codebase, since a change can break something built
+later as easily as something built earlier. It works in the codebase the functionality now lives
+in: when later modules are built on top of this one, the furthest-built of them (`--in <module>`
+picks one when there are several). It exits `0` when everything passes, and refuses when there is
+no code yet - build it with `module` first.
+
+Several changes do not need one command each: after editing the spec, re-running `turri regenerate`
+brings the code up to it - one spec diff for what changed in what is built, then the functional
+specs not built yet.
+
+## Asking in words instead
+
+pi's print mode runs one request and exits, with the render tools waiting for their work rather
+than starting background jobs:
+
+```bash
+nohup turri -p "Render app.plain as a whole module, with conformance tests" > render.log 2>&1 &
+```
+
+It reports what it did at the end, and nothing streams in between, so for long runs
+`turri regenerate` is the better choice. The interview skill (`brood`) needs
+someone to answer; without one they decide and record their assumptions, and a gate that escalates
+to a human stops the run.

package/docs/images/how-turri-works.svg

@@ -0,0 +1,50 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="16 -5 1100 490" width="1100" height="490" role="img" aria-labelledby="d-title d-desc">
+      <title id="d-title">How turri works</title>
+      <desc id="d-desc">You describe changes to turri; turri asks and reports back. turri writes the ***plain specs, which you read and review with turri. Then turri loops without end: it reads the specs, regenerates the code from them, and tests the code against them.</desc>
+      <style>
+@font-face { font-family: "Archivo"; font-weight: 900; src: url(data:font/woff2;base64,d09GMgABAAAAAAN0ABAAAAAABuQAAAMZAAIAQgAAAAAAAAAAAAAAAAAAAAAAAAAAGhYbehwqBmA/U1RBVFoARBEICoIAgV8BNgIkAxQLDAAEIAWESgcgDAcbnQUgrgN4MoaXUIIRo4bSsCiga71j9UcNccO+yjyC+P1os19OzJJmreeIVRLJ+4WIehOXTKRJJRSJ8Pyncf+de2ce5wNCgxqZAC0ct6/blrChgUdrbfZNUdmKmpz5LBKSlaKpfEIsfsMjiZDIAa9FmMiRBO5xu8oTYkgzRXzs+9+lkO3UTW0sDfC/Eg80wzWI0sVrASYYaPgX/QUUUZwVWGASpe6a4qnU8vN++BgB6gBkCJEIgRo+ovDC4Pg8xPbtoA4xEkgQEHs5W4cACBAkpkf0mAcJRkVgEgAAgTGBCIQQJjCRXOsngM9xiaHI0vMFJWTvskM4oi4XP9X6lXQAfsTmjZMjkCBh+cB/UGwghwgga+BnGCIQoidAGwEm8do+ioSAtZ0iEiB2445KnDAtK24IZGGvBwgEUSMWkGMczoAAZBA8JHWfFAGq6DHYzcYSIRCVLqQT6bgAkGIzEQeUgBqc3whsB6D43F9FhbTpcmwPhZZSSaVRteGjj59qv27LeOjVk2PYcSj5hTCSqg9DMZq5r2qx/exN7XkyKJ65eHCjDr99TrmSxrrQ/ddvbRP77/bfbnTXBClNV3Wb/V8OzhdlfN+zmyYuvQ78yq+N29b1NhUoOpktvThzPnRiPpgdaR7/8x/4q21F2Fy8K2X997rzFrMa3zXdVG/2h9xezABAgEzWr9dWPOVvgPgG+P6P4MdMl+X/1lRRbBQToAIDAqr30kH43z8jcK3MVqyLdCnxtj+kNzsyh0CpnxcQsFXvUo4KA+AWpkJC3CvMzFdFyPA9lG6KhlN4yVpBkZIhoC76oBCMMUIa2QnfHuyS7wR203cG/ql5BtMxm0QgQlSUiOkoDzVEHCqTbY9IcsBAVbAZZJw96CIyCAw2JwwIhkImR6tw4fpJ462YXZW6GTRVyml0kl2Mo0KNYyZOVdLpkkNE1TjaAtmLq9pHZVHt2KOYxREwuYutVpgIESIlKzdh0oi2kNVNXUEsmhfLSQw6qnQVhlhynlg3gWQfui5Ikww2zQ7VCFSTkj2zjI2LdG6ANOUYfxXpj+RRAAA=) format("woff2"); }
+@font-face { font-family: "Archivo"; font-weight: 800; src: url(data:font/woff2;base64,d09GMgABAAAAAARoABAAAAAACJwAAAQNAAIAQgAAAAAAAAAAAAAAAAAAAAAAAAAAGhYbgRAcKgZgP1NUQVRaAEwRCAqEcIQUATYCJAMcCxAABCAFhGoHIAwHGxgHKB6FccNdgjLFEIv53uLyOp7///3+N9e+57sm0yTgybwE8f4rdCIhkRhdNGRC4VMilffzedb7TYcZyRkQmwJOF4CK41InIf9hXSYupz+WPr61fmGAXUCBJToX/m9+bNFHYwImlGY9dw/0QE2Pto0FGJB3TbabIke9urYiGAWUiH4RDNuQg3atvrUXPF6zdQrw0ODXaHrF1yjAmY3SFD8GlZ0L4lAlTLPL0UnJ/fIYmVhii1q6qEK3JOFBTgBoVdFFcaB+0WYB77Aof+fwXxCQP/HwfnsTXAAuqlP8D7R7aBUQqHHaPmAFJmJQh1kYDtBOeDoRQuDkmUiHQF7o2DIUgqbftAgIlUA8IEKGsCigUyqhAAGF/VwQSXc+N1xZ2/KEkh7VAzxCmfp/naUWmJuTGJHdgwkwAMYxhN8AGQCgAaKUEtmc9w139ZoOjmDPstnQRLsdn221WsH17b5TrrNOHABvDt7EZ5/ej/AJFoulj7zk6slgHOF0137XPZb+2ecPIzRxk+LQSZsywKgp5fju1U3FMD5x3a5jGsN7hCMCUv/s2/bKh24R+AZxs8+EMJw2YeXOrcHkMM/CjjsWtnQtADFmhTLwvqUbNwbjy9fvuxc4gA/usTywFOADFFFpJskqM0X0FzGC6/Pju4o3xkiPRid8ITPi0smIxJgrY2JWFcZ31+UzQ+DvSA2byKWYZJ6JSVRFzr371fH3Fss0vNFpV08yjN+40JocFHFQyw2Nv1ucGptSfAcqRobHllTrLa6KGk0M9BuKy4zMWHMKFZ4SPLLsid/6rJjmmhxW8IG2RyHXZqYFxn1fC5dHBscQ1WaSrKbGEINDFJACzdaG5ExZeny6PCM5KUPe/wZZJnzE+0aR7FFb6vz357/zCT+1Lixvi+d0l2an4GfVfrDwStzwZlFdmIlTdd9jf9tr5vOXtY5l75dtLqt+s/noT/ekh+bWKAAIypVR2eOTTM/Sf84Y9hbw52/YQcBpUYX3/7hedptMjwL6FQifI/1JhvhvHAOxWw3ULLhbPIgvagCl4Gh7PRBVjiYY8IyDzTa73ZgP0ElzAT4CCh3HdtBl3CndueX9YJOk+ywnx9fvMK0NCIxmHKQRDGcW7QLTWZIJhOi2TAhEDzkL5ZpzcJWSCkVDTEhEJ0qOrIsYpZcO8o0qGlyKIWagnMFOs5IEH5dOitTTuZU0tLkke/N0VLRKZMokJF6+lR5HBi4luUwd5BTEOPS00vWiqPBl+h2dHIfRg09OA6tFGd5C1jHpGmyOfzc+IT3Zp2jkyJAlSzZChzbtmhDWW7fB0sH+aK6TxJQUolCvLQIDyepHKC4xHl076Vx7fblybDJNsUetGFc3Je9KChjQk0mzV39D/6dOnwsA) format("woff2"); }
+@font-face { font-family: "JetBrains Mono"; font-weight: 500; src: url(data:font/woff2;base64,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) format("woff2"); }
+@font-face { font-family: "JetBrains Mono"; font-weight: 700; src: url(data:font/woff2;base64,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) format("woff2"); }
+text { font-variant-ligatures: none; font-feature-settings: "calt" 0, "liga" 0; }
+.lbl { font-family: "JetBrains Mono", ui-monospace, Menlo, monospace; font-size: 15px; font-weight: 500; fill: #0f0f0f; }
+.node { font-family: "Archivo", "Helvetica Neue", Arial, sans-serif; font-weight: 800; font-size: 22px; }
+.sub { font-family: "JetBrains Mono", ui-monospace, Menlo, monospace; font-weight: 700; font-size: 12px; letter-spacing: 0.06em; }
+.flow { fill: none; stroke: #0f0f0f; stroke-width: 2.25; stroke-linecap: round; }
+.review { stroke-dasharray: 9 7; }
+@media (prefers-reduced-motion: no-preference) {
+  .spin { transform-box: fill-box; transform-origin: 50% 58%; animation: turn 6s linear infinite; }
+  @keyframes turn { to { transform: rotate(360deg); } }
+}
+</style>
+      <rect x="16" y="-5" width="1100" height="490" rx="18" fill="#e0ff6e"/>
+      <defs>
+        <marker id="head" viewBox="0 0 10 10" refX="10" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
+          <path d="M0 0 L10 5 L0 10 z" fill="#0f0f0f"/>
+        </marker>
+      </defs>
+      <path class="flow review" d="M120 142 V 70 Q 120 40 150 40 H 955 Q 985 40 985 70 V 158"/>
+      <text class="lbl" x="552" y="28" text-anchor="middle">review loop</text>
+      <path class="flow" d="M174.4 180 L 474.8 180" marker-end="url(#head)"/>
+      <text class="lbl" x="324" y="166" text-anchor="middle">describe changes</text>
+      <path class="flow" d="M474.8 220 L 174.4 220" marker-end="url(#head)"/>
+      <text class="lbl" x="324" y="246" text-anchor="middle">asks · reports</text>
+      <path class="flow" d="M641.2 180 L 900 180" marker-end="url(#head)"/>
+      <text class="lbl" x="771" y="166" text-anchor="middle">writes</text>
+      <path class="flow" d="M900 220 L 641.2 220" marker-end="url(#head)"/>
+      <text class="lbl" x="771" y="246" text-anchor="middle">reads</text>
+      <path class="flow" d="M538 244 L 538 380" marker-end="url(#head)"/>
+      <text class="lbl" x="524" y="318" text-anchor="end">regenerates</text>
+      <path class="flow" d="M578 380 L 578 244" marker-end="url(#head)"/>
+      <text class="lbl" x="592" y="318" text-anchor="start">tests against ***plain</text>
+      <text class="spin" x="880" y="372" text-anchor="middle" font-family="Archivo, sans-serif" font-weight="900" font-size="44" fill="#0f0f0f">↻</text>
+      <circle cx="120" cy="200" r="58" fill="none" stroke="#0f0f0f" stroke-width="2.5"/>
+      <text class="node" x="120" y="208" text-anchor="middle" fill="#0f0f0f">you</text>
+      <rect x="470" y="156" width="176" height="88" rx="44" fill="#0f0f0f"/>
+      <text x="558" y="212" text-anchor="middle" font-family="Archivo, sans-serif" font-weight="900" font-size="34" letter-spacing="-1" fill="#e0ff6e">turri</text>
+      <rect x="900" y="158" width="170" height="84" rx="6" fill="#223936"/>
+      <text x="985" y="208" text-anchor="middle" font-family="JetBrains Mono, ui-monospace, monospace" font-weight="700" font-size="24" fill="#c5dcd9">***plain</text>
+      <rect x="473" y="380" width="170" height="84" rx="6" fill="#e0ff6e" stroke="#0f0f0f" stroke-width="2.5" stroke-dasharray="7 6"/>
+      <text class="node" x="558" y="420" text-anchor="middle" fill="#0f0f0f">code</text>
+      <text class="sub" x="558" y="444" text-anchor="middle" fill="#0f0f0f">DISPOSABLE</text>
+    </svg>

package/docs/installation.md

@@ -0,0 +1,118 @@
+# Installation
+
+**turri** runs wherever pi runs - macOS, Linux, WSL - with git, bash and Node 22.19 or newer (a Linux
+distribution's own `nodejs` package is often older: take it from nodejs.org, nvm or NodeSource). Native Windows is
+best effort: it needs bash on the PATH (Git for Windows' Git Bash), and has no OS sandbox under the agents' commands.
+
+The agents' commands run on this machine, with its toolchains - see [the sandbox](sandbox.md). Each is checked before
+it runs and audited after, on every platform; under them an OS sandbox fences it where the OS has one: Seatbelt on
+macOS, always there, and bubblewrap on Linux and WSL 2 - `apt install bubblewrap`, or your distribution's package.
+
+```bash
+npm install -g @turri-dev/cli   # puts `turri` on your PATH
+turri doctor           # checks the machine: what turri needs, and what is missing
+```
+
+Then, in the project that holds your specs:
+
+```bash
+cd ~/my-project
+turri init-config   # a config.turri.yaml with the model you talk to and the one that writes the code, every other setting at its default
+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`.
+
+## From a clone
+
+To work on turri itself, put the clone on your PATH instead:
+
+```bash
+git clone git@github.com:plainlang/turri.git && cd turri
+npm install
+npm link              # puts `turri` on your PATH, pointing at this clone
+```
+
+A clone runs its TypeScript sources directly - Node strips the types - so edits take effect immediately. The package
+on npm runs JavaScript compiled from them instead (`npm run build`, into `dist/`, run by `npm pack` and `npm publish`
+before they pack), as Node runs no `.ts` file inside a `node_modules`. `bin/turri.mjs` runs `src/` where there is one,
+and `dist/` otherwise.
+
+## In Docker
+
+`docker/Dockerfile` builds an image with Node, git, bash, bubblewrap and **turri** linked; the agents' commands and the
+testing scripts run inside it, so add the toolchains your projects need first. It runs **turri** as the user who owns
+the project folder mounted at `/work`, never as root - bubblewrap as root in a container lacks the capability to make
+its namespaces - and with seccomp and AppArmor unconfined the OS sandbox starts. `systempaths=unconfined` lets it mount
+a `/proc` of its own; without it, it binds the container's. The build, the run, Windows and the keys:
+[turri in Docker](../docker/README.md).
+
+## What `turri doctor` checks
+
+It checks, in order, and says exactly what to run for anything missing:
+
+| what | why | if it is missing |
+| --- | --- | --- |
+| Node 22.19+ | pi needs 22.19, as does a clone running turri's `.ts` sources directly | install a newer Node |
+| bash | every command an agent runs, and every testing script, runs with it | on Windows, Git for Windows; elsewhere, the system's package manager |
+| the OS sandbox | the wall under the command check and the audit | macOS has Seatbelt; on Linux, `apt install bubblewrap`. Where it does not start it says why and how to give it one - 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: `sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`), Docker's masked `/proc` (`--security-opt systempaths=unconfined`, or nothing: turri binds the container's `/proc` instead). Without one, the check and the audit hold alone |
+| a model provider | the agents need a model | run `pi` and `/login`, or set an API key (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`, ...) |
+| `turri` on PATH | so it runs from any project | `npm install -g @turri-dev/cli`, or `npm link` in a clone |
+| turri and `pi` apart | `turri` starts pi with turri; a plain `pi` stays pi | an older `turri setup` wrote a file that loads turri into every `pi` - `doctor` offers to remove it |
+
+In a project - a folder with `config.turri.yaml` (or the old `config.yaml`) or `plain_modules` - it checks what the project needs of this machine too:
+
+| what | |
+| --- | --- |
+| each module's toolchains | what its implementation reqs name - Python, Node, Java, Go, Rust, C/C++, Zig, ... - against this machine's PATH: the agents use this machine's toolchains and install none, so a missing one is yours to install |
+| the testing scripts | what in them this machine does not have: a program named by its whole path that is not here (a macOS-only `/usr/libexec/java_home` on Linux), a toolchain they run that is not on the PATH |
+| the models | each model `config.turri.yaml` names - `harness-model`, `coding-model`, `judge-model`, every role under `models:` - sent one short request through pi, with the credentials turri's agents will use, for any provider pi supports. One that answers is ready; for one that does not, it says what the provider said and what to do: the credentials pi reads for that provider (`AWS_PROFILE` and `AWS_REGION` for Amazon Bedrock, `OPENAI_API_KEY`, `/login`, ...), model access in the Bedrock console, the closest model ids pi knows for one it does not. `--no-models` skips it |
+
+Removing that file is the one thing `doctor` changes, and it asks first; `turri doctor --yes` says yes. Run without a
+terminal - piped, or in CI - it asks nothing and changes nothing. Run it again whenever something breaks;
+`turri doctor --no-models` leaves out the models' requests.
+
+The chat is told every turn which wall is up and what the project's modules need of this machine that it lacks. What they need is worked out from every spec of the project - seconds, on a project of long requires chains - so it is worked out once the chat is up and again after a turn in which a spec changed, never while your message waits: a turn is told what was known last.
+
+## turri and `pi`
+
+`turri` runs pi from this project's `node_modules`, with turri loaded, so no global pi install is needed. A plain
+`pi` is left as it is: starting pi does not start turri, and turri puts nothing into pi's own folders.
+
+An older `turri setup` could load turri into every `pi`, with a one-line file in `~/.pi/agent/extensions/` pointing at
+this clone. `turri doctor` says when it is there, and offers to remove it. Until it is gone, `turri`
+leaves out its own `-e`: pi treats a tool registered twice as an error.
+
+`turri` starts in the `turri-dark` theme. A plain `pi` keeps its own theme; to give it
+`turri-dark` too, in `~/.pi/agent/settings.json`:
+
+```json
+{ "theme": "turri-dark" }
+```
+
+### Project trust
+
+pi will not auto-discover a project-local extension until you trust the project, and `-p` has no
+way to ask - so `npm run chat` and `npm run ask` pass `-e` explicitly. Once you have run `pi`
+interactively in this directory and accepted the trust prompt, plain `pi` picks the extension up
+on its own. A `defaultProjectTrust` key in `.pi/settings.json` does *not* work - a project cannot
+vouch for itself; that setting only counts in `~/.pi/agent/settings.json`.
+
+## Environment
+
+Models and credentials come from your pi configuration (`~/.pi/agent`) or provider environment
+variables - the same resolution `pi` itself uses. Put the rest in your shell profile:
+
+```bash
+export PLAIN_TEMPLATE_DIRS=~/path/to/standard_template_library   # shared templates
+export GEMINI_API_KEY=...        # and leave GOOGLE_API_KEY unset
+```
+
+For Gemini, `GEMINI_API_KEY` is what makes pi *offer* the google provider, but when
+`GOOGLE_API_KEY` is also set pi uses that one for the calls and says so.
+
+| variable | |
+| --- | --- |
+| `PLAIN_TEMPLATE_DIRS` | colon-separated template directories, e.g. the standard library |
+| `TURRI_COMMAND_TIMEOUT` | seconds a command may run before it is stopped - an agent's own, its tests (default `120`) |

package/docs/parser.md

@@ -0,0 +1,108 @@
+# The \*\*\*plain parser
+
+`src/plain/` is a TypeScript port of the reference \*\*\*plain parser - `plain_file.py`,
+`plain_spec.py`, `concept_utils.py`, and the `file_utils.py` helpers they depend on.
+
+| module | ports |
+|---|---|
+| `src/plain/parser.ts` | `plain_file.py` - sections, acceptance tests, imports/requires, marshalling |
+| `src/plain/spec.ts` | `plain_spec.py` - functionality ids, the per-functionality context, linked resources, ranges |
+| `src/plain/concepts.ts` | `concept_utils.py` - concept extraction, validation, topological ordering |
+| `src/plain/markdown.ts` | mistletoe's AST + `PlainRenderer` (mdast + a matching serializer) |
+| `src/plain/liquid.ts` | `plain2code_nodes.py` + the two filters in `plain_spec.py` (liquidjs) |
+| `src/plain/files.ts` | `file_utils.open_from` / `get_loaded_templates`, base64 blob detection |
+| `src/plain/stdlib.ts` | nothing - turri's own: `stdlib/` is a reserved import prefix, read from turri's standard library only, and a project module at such a path is an error (see [the standard library](authoring-plain.md#the-standard-library)) |
+
+## Checking a spec
+
+```bash
+turri validate <file.plain>        # one spec
+turri validate .                   # every .plain file in a directory
+turri validate <file.plain> --json
+```
+
+It uses this repo's own parser, so it needs no external tool, no API key and no credits: it parses
+the file, resolves its imports and required modules, and reports every syntax, concept and
+structure error with the line it is on.
+
+```
+PASS  d365_export.plain  6 functionalities (1, 2, 3, 4, 5, 6), requires d365_restore_api
+
+FAIL  broken.plain  PlainSyntaxError
+        Plain syntax error: Syntax error at line 3: Invalid specification heading
+        (`Nope:`). Allowed headings: definitions, implementation reqs, test reqs, ...
+```
+
+The exit code is 0 only when every file passed. In a conversation the same check is `validate`.
+
+## Two rules of inheritance
+
+- A module that **`requires`** another inherits its functional specs, transitively: it is built on
+  top of that module's code.
+- A module that **`import`s** another inherits its definitions, implementation reqs and test reqs.
+
+## The functional-spec iterator
+
+`getFrids` walks functionalities depth-first through nested sections; `getSpecificationsForFrid`
+builds what a single functionality is rendered with. `iterateFunctionalSpecs` pairs them:
+
+```ts
+import { plainFileParser, iterateFunctionalSpecs } from "./src/plain/index.ts";
+
+const [moduleName, tree] = plainFileParser("my_app.plain", ["."]);
+
+for (const { frid, specifications, codeVariables } of iterateFunctionalSpecs(tree)) {
+  // definitions and reqs in scope from the outside in, every functionality up to and
+  // including this one, and only this one's acceptance tests
+  console.log(frid, specifications["functional specs"].length);
+}
+```
+
+## Parsing once
+
+A module's parse reads its imports and the whole of its `requires` chain, so a long chain asks for the same
+files over and over: bringing an 18-module chain up to its spec parsed for minutes. Two caches keep it to once.
+Inside `withParseCache`, one question about the specs, each file is parsed once. Between calls, a parse is kept
+with a fingerprint of every file directly in its template folders and the current one - name, size,
+modification time, and a `.plain` file's text - and handed out again, as a copy, while the fingerprint is the
+same; a spec that does not parse is kept as that too. What a parse returns is unchanged: the cache only decides
+whether to parse again.
+
+## Fidelity
+
+The port is checked against the Python implementation directly, not only against the ported
+assertions. Both parsers are run over a corpus and their module name, marshalled tree, required
+modules, functionality ids and per-functionality specifications compared:
+
+| corpus | files | identical | differences |
+|---|---|---|---|
+| `tests/data/` fixtures | 84 | 80 | 4 error strings (below) |
+| `hycu-dynamics-365-modules` | 47 | 47 | none |
+
+The 4 differences are all the same thing: template partials (`implement.plain`,
+`implement_2.plain`, `header.plain`, `pr_implement.plain`) are meant to be included with
+arguments, not parsed alone. Both implementations reject them for the same reason - an undefined
+Liquid variable - but the message text comes from the template engine, and liquidjs phrases it
+differently from liquid2.
+
+Real specs exposed three places where mdast and mistletoe disagree, each covered by
+`tests/plain/renderer.test.ts`:
+
+- **Inline decoding.** mdast resolves `\"` to `"` and forgets whether emphasis was written with `_`
+  or `*`; mistletoe round-trips the source. Inline leaf nodes are pinned back to their original
+  source slice at parse time.
+- **List geometry.** mistletoe indents an item's continuation lines by its `prepend`, measured in
+  coordinates with the enclosing item's indentation stripped - not by the column gap between parent
+  and child. An acceptance test rendered detached from its functionality keeps 6 and 10 spaces where
+  the naive reading gives 4 and 8.
+- **Lazy continuation lines.** A paragraph's continuation lines carry leading whitespace that is not
+  part of the text; keeping it in the raw slice indents the line twice.
+
+Two deliberate differences from the Python source:
+
+- The `test_plainfile.py` tests drive the acceptance-test helpers with `MagicMock` tokens and patch
+  the inner helper to count calls. ESM has no equivalent, so those tests build real ASTs from
+  markdown and assert the same observable outcome.
+- `networkx`'s `topological_sort` is reimplemented rather than replaced with a generic one: it
+  flattens `topological_generations`, so the ordering of independent concepts follows graph
+  insertion order, and the Python tests assert that exact sequence.