raga-cli 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## [0.10.0](https://github.com/mr-jones123/raga/compare/raga-v0.9.0...raga-v0.10.0) (2026-11-01)
+
+### Features
+
+* assign models to subagent roles with /agent-setup ([937ae97](https://github.com/mr-jones123/raga/commit/937ae97887bae82215579de3966d23886d8e8d15))
+* open subagents as named sessions from /agents in the TUI or Rex panes ([8cba5d3](https://github.com/mr-jones123/raga/commit/8cba5d360d3f9c9ee0d5fd76652ae53c41f04b21))
+
+### Bug Fixes
+
+* **artifacts:** keep headless Chrome away from the macOS login keychain ([2c65a35](https://github.com/mr-jones123/raga/commit/2c65a3562a0354cbb20618aac4ddedf919ff08c0))
+* keep Raga updates and user-facing guidance on Raga ([8ff9209](https://github.com/mr-jones123/raga/commit/8ff9209ed94681e1c254a496515dd561e7b58590))
+* pick role models in a full-screen list inside /agent-setup ([df1e642](https://github.com/mr-jones123/raga/commit/df1e64234b170472d18c286140d472717699d916))
+* return partial child work when the turn budget is exhausted ([0383bc1](https://github.com/mr-jones123/raga/commit/0383bc1485b8b039d0d5b9628b8ecc12d680a426))
+
+## [0.9.0](https://github.com/mr-jones123/raga/compare/raga-v0.8.0...raga-v0.9.0) (2026-10-31)
+
+### Features
+
+* add archive compaction strategy that drops context without a summarization call ([3b682ee](https://github.com/mr-jones123/raga/commit/3b682ee878320ce897f136b8661f3b0178c9df1d))
+* add bend and raga-artifacts skills and run peak in ordinary sessions ([4fb5df2](https://github.com/mr-jones123/raga/commit/4fb5df2d32583b6d03f77d5e62c37a219978fcc7))
+* add managed local models and CI releases ([53a7325](https://github.com/mr-jones123/raga/commit/53a73254eeceba1298c98823c275fff8331bb0b8))
+* store instance memory in SQLite with selectable memory backends ([6c4997b](https://github.com/mr-jones123/raga/commit/6c4997be478c430c27ad378fa4d87bafc12f2444))
+* **tui:** add /diff dashboard for categorized git review ([03cb062](https://github.com/mr-jones123/raga/commit/03cb062df23b6591d33902f7d1bb815976dc4049))
+
+### Bug Fixes
+
+* publish CLI updates to npm through trusted publishing ([f236785](https://github.com/mr-jones123/raga/commit/f2367854e11a26576324116194ec299403cc2e6a))
+* **schemas:** regenerate keybindings schema for /diff bindings ([6ce96c7](https://github.com/mr-jones123/raga/commit/6ce96c73b6a742857be37e4bb79a83edb566106e))
+
 # Changelog
 
 Generated by scripts/raga-release.mjs from conventional commits. Do not edit by hand.

package/README.md

@@ -27,7 +27,7 @@ The RLM runtime works end to end. The adaptive layer, which lets the harness rew
 | Goal and metric loop (`--goal`, `--gate`, `--metric`) | Not started |
 | Native engineering skills (pstack, no-mistakes) | Not started |
 
-The packages still use pi's names (`@earendil-works/pi-*`). The `raga` command keeps its own user directory, `~/.raga/agent`, for logins, settings, sessions, skills, extensions, and packages. Set `RAGA_CODING_AGENT_DIR` to move it. It does not read `~/.pi/agent` or the shared `~/.agents/skills` folder, so an existing pi setup does not carry over. The `pi` command still uses `~/.pi/agent`.
+User-facing commands and messages use Raga branding. The SDK packages retain their upstream names (`@earendil-works/pi-*`); imports, extension APIs, and protocol identifiers are not renamed. The `raga` command keeps its own user directory, `~/.raga/agent`, for logins, settings, sessions, skills, extensions, and packages. Set `RAGA_CODING_AGENT_DIR` to move it. It does not read `~/.pi/agent` or the shared `~/.agents/skills` folder, so an existing pi setup does not carry over. The `pi` command still uses `~/.pi/agent`.
 
 ## Run it
 
@@ -38,7 +38,20 @@ npm install -g raga-cli
 raga
 ```
 
-`raga update` installs the newest `raga-cli` release. To run from source instead:
+### Update
+
+Exit raga, then run:
+
+```bash
+raga update
+raga --version
+```
+
+This installs the latest published `raga-cli` release without deleting your settings or sessions. Restart raga afterward. If an older version cannot update itself, run `npm install -g raga-cli@latest`. See [docs/UPDATING.md](docs/UPDATING.md) for other update targets, source checkouts, and troubleshooting.
+
+### Run from source
+
+To run from source instead:
 
 ```bash
 git clone https://github.com/mr-jones123/raga.git
@@ -65,6 +78,18 @@ On the first `--rlm` run, raga creates a Python 3.11 environment with `uv` at `~
 
 Without `--rlm`, raga behaves like pi, with `read`, `bash`, `edit`, and `write` as model tools.
 
+## Local models
+
+On macOS and Linux, `/local-models` searches Hugging Face, asks before downloading missing weights, and starts models locally. The first recommendation is the official LFM3-1.7B GGUF Q4_K_M build through llama.cpp. The same command detects MLX models automatically on Apple Silicon; no separate backend command is needed. See [docs/LOCAL-MODELS.md](docs/LOCAL-MODELS.md) for setup, cache behavior, and limits.
+
+## Review changes
+
+`/diff` opens a read-only Git review dashboard. Browse changes by category (tests, modules, GitHub workflows, documentation, dependencies, configuration), inspect staged or working-tree changes, or pick a commit from history. Open a file to scroll its diff, and toggle to its full contents without leaving raga. See [docs/DIFF.md](docs/DIFF.md) for controls.
+
+## Subagents
+
+Each `rlm_query` child is its own named Raga session with its own Python kernel. Run `/agents` to see them in a dashboard (name, state, model, tokens, cost, turns) and open one to read its cells or steer it. Optionally, Rex shows one pane per subagent. Run `/agent-setup` to choose which model each workflow role (such as `arena runners` or `bug-fix`) uses. See [docs/AGENTS.md](docs/AGENTS.md).
+
 ## What the model does in RLM mode
 
 The kernel already exists when the model's first turn starts. Each `python` call runs a cell, and variables stay defined for the whole session. The model sees at most `rlm.outputLimit` characters of each cell's output. The full output stays in `cells`.
@@ -111,9 +136,12 @@ print(counts.most_common(5))
 |---|---|
 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the pi base works and where raga's layers attach. |
 | [docs/RLM.md](docs/RLM.md) | The RLM runtime reference. |
+| [docs/AGENTS.md](docs/AGENTS.md) | Subagent sessions, the `/agents` dashboard, and Rex panes. |
 | [docs/PROGRESS.md](docs/PROGRESS.md) | Milestones, status, and decisions. |
 | [docs/BENCHMARKS.md](docs/BENCHMARKS.md) | Benchmark tasks and results. |
-| [docs/RELEASING.md](docs/RELEASING.md) | Versioning, the generated changelog, and merging upstream pi. |
+| [docs/LOCAL-MODELS.md](docs/LOCAL-MODELS.md) | Search, download, and run local Hugging Face models with llama.cpp or MLX. |
+| [docs/UPDATING.md](docs/UPDATING.md) | Install and update the CLI, extensions, and model catalogs. |
+| [docs/RELEASING.md](docs/RELEASING.md) | Automatic npm publishing, versioning, and merging upstream pi. |
 | [packages/coding-agent/docs/](packages/coding-agent/docs/) | Pi's own docs, which still apply to everything raga inherits. |
 
 ## Development
@@ -123,10 +151,10 @@ npm run check                                     # Lint, format, and type check
 ./test.sh                                         # Tests without API keys
 uv run --no-project --with pytest --with dill \
   pytest packages/coding-agent/python/tests -q     # Python kernel tests
-node scripts/raga-release.mjs check               # Commit headers since the last release
+node scripts/raga-release.mjs version             # Version from raga release tags
 ```
 
-Commit headers follow Conventional Commits, and `scripts/raga-release.mjs` builds `CHANGELOG.md` from them. [AGENTS.md](AGENTS.md) has the rules for humans and agents.
+Commit headers follow Conventional Commits. Semantic-release generates `CHANGELOG.md`, version tags, and GitHub Releases after CI passes on `main`. See [docs/RELEASING.md](docs/RELEASING.md). [AGENTS.md](AGENTS.md) has the rules for humans and agents.
 
 ## Credits
 

package/bundled-skills/README.md

@@ -2,9 +2,9 @@
 
 New instances copy this pack into their first accepted revision. Each session reads its pinned copy. Updating package assets does not rewrite an existing instance.
 
-The pack installs one skill, peak. Its 62 references hold 55 portable pstack workflows, four companion workflows, the native create-skill and raga-runtime adapters, and the managed no-mistakes workflow. It excludes make-bot-ui and editor-only services. The original public no-mistakes text stays unchanged under skills/peak/references/no-mistakes/upstream.
+The pack installs three skills. raga-artifacts makes slides and documents with Pele diagrams and exports them as HTML and PDF. bend turns rules the user states into Bend laws and proofs and checks them with the bend CLI. peak is the engineering workflow. Its 62 references hold 55 portable pstack workflows, four companion workflows, the native create-skill and raga-runtime adapters, and the managed no-mistakes workflow. It excludes make-bot-ui and editor-only services. The original public no-mistakes text stays unchanged under skills/peak/references/no-mistakes/upstream.
 
-Read [peak](skills/peak/SKILL.md) to pick a reference. Read [the native runtime](skills/peak/references/raga-runtime/SKILL.md) for the Python API. Read [the workflow guide](docs/guide/README.md) for the reference map. Workers return supervisor-owned workspace changes rather than Git commits. Skill changes go through candidate_read, candidate_write, and candidate_commit. Promotion remains a trusted operator operation.
+Read [peak](skills/peak/SKILL.md) to pick a reference. Read [the native runtime](skills/peak/references/raga-runtime/SKILL.md) for the Python API. Read [the workflow guide](docs/guide/README.md) for the reference map. In instance sessions, workers return supervisor-owned workspace changes rather than Git commits. Ordinary sessions keep code changes in the parent session and use read-only children. Skill changes go through candidate_read, candidate_write, and candidate_commit. Promotion remains a trusted operator operation.
 
 ## Sources and regeneration
 

package/bundled-skills/bundle.json

@@ -23,10 +23,20 @@
     }
   ],
   "skills": [
+    {
+      "name": "bend",
+      "path": "skills/bend/SKILL.md",
+      "source": "raga"
+    },
     {
       "name": "peak",
       "path": "skills/peak/SKILL.md",
       "source": "pstack"
+    },
+    {
+      "name": "raga-artifacts",
+      "path": "skills/raga-artifacts/SKILL.md",
+      "source": "raga"
     }
   ],
   "files": [
@@ -95,7 +105,7 @@
     },
     {
       "path": "docs/guide/01-setup.md",
-      "sha256": "56e67d324cc46c3bde1cc6c909e8b627ab11c6fdc31e0e9e8b38c38aad3f8037",
+      "sha256": "dc1bf7425558e5bb5a8d464f55b6dea40825aab1821fd6493cd44682bb2e1f94",
       "source": "pstack/docs/guide/01-setup.md",
       "sourceSha256": "384655bdecc713122ca69a485723c58462002a1d512415e94e48597d0dce2fa5",
       "adaptation": "raga native setup guide"
@@ -242,11 +252,25 @@
     },
     {
       "path": "README.md",
-      "sha256": "f49df779e23215fded1a5d1d99ce247bd4f763411689c382bcfe674386672b08",
+      "sha256": "f58c9364c2f5a4b25f589ae4bbef0557f2d7fc60a16d87fd087cee3b13013154",
       "source": "raga bundle maintenance guide",
-      "sourceSha256": "f49df779e23215fded1a5d1d99ce247bd4f763411689c382bcfe674386672b08",
+      "sourceSha256": "f58c9364c2f5a4b25f589ae4bbef0557f2d7fc60a16d87fd087cee3b13013154",
       "adaptation": "raga bundle maintenance guide"
     },
+    {
+      "path": "skills/bend/bend_tool.py",
+      "sha256": "cee21f9e40c1d95702f09bd635db3046683f95c3d78f18bd1e68e30e192ed968",
+      "source": "raga native adaptation",
+      "sourceSha256": "cee21f9e40c1d95702f09bd635db3046683f95c3d78f18bd1e68e30e192ed968",
+      "adaptation": "raga native adaptation"
+    },
+    {
+      "path": "skills/bend/SKILL.md",
+      "sha256": "89001ac986846444f277ab806c5f92f994924569e418f3da327d61c94b028d2e",
+      "source": "raga native adaptation",
+      "sourceSha256": "89001ac986846444f277ab806c5f92f994924569e418f3da327d61c94b028d2e",
+      "adaptation": "raga native adaptation"
+    },
     {
       "path": "skills/peak/playbooks/authoring-a-skill.md",
       "sha256": "4b9b7de20a9456bb17c8646e92b6591408ad68567fe33ed16f3cb6f1b07f40bf",
@@ -655,7 +679,7 @@
     },
     {
       "path": "skills/peak/references/peak-setup/SKILL.md",
-      "sha256": "f2989def1dc7f2112e8583de961d8865f20fd6333cacab05f9a64ee0399c7681",
+      "sha256": "5015abcbbb917dd931b131ec107c8b27b1264990db3f556967446b6c61b2445b",
       "source": "pstack/skills/setup-pstack/SKILL.md",
       "sourceSha256": "b45512f6ca5e96e81681984683b7472bfe892581da3a89a73cca4159438f29ed",
       "adaptation": "raga execution adaptation of skills/peak/references/peak-setup/SKILL.md"
@@ -858,16 +882,16 @@
     },
     {
       "path": "skills/peak/references/raga-runtime/raga_runtime.py",
-      "sha256": "5bb5fda3cb481df3dc149b88867a75c1efb27c612a0d3ee194d96c134035e638",
+      "sha256": "aee7412788daf1b7114f8d9fe96051ef4db7aa9cd43443319a68425c3467045e",
       "source": "raga native Python adapter",
-      "sourceSha256": "5bb5fda3cb481df3dc149b88867a75c1efb27c612a0d3ee194d96c134035e638",
+      "sourceSha256": "aee7412788daf1b7114f8d9fe96051ef4db7aa9cd43443319a68425c3467045e",
       "adaptation": "raga native Python adapter"
     },
     {
       "path": "skills/peak/references/raga-runtime/SKILL.md",
-      "sha256": "ef2891819b052f701bbd28b253612ffb76b46538d3f9c35ed4d5a7ef2f3fe342",
+      "sha256": "53a3f75e3611316a3e1a6f402989dc89ef309bc511fa624dacdf5266ef3279c7",
       "source": "raga native adaptation",
-      "sourceSha256": "ef2891819b052f701bbd28b253612ffb76b46538d3f9c35ed4d5a7ef2f3fe342",
+      "sourceSha256": "53a3f75e3611316a3e1a6f402989dc89ef309bc511fa624dacdf5266ef3279c7",
       "adaptation": "raga native adaptation"
     },
     {
@@ -1390,10 +1414,52 @@
     },
     {
       "path": "skills/peak/SKILL.md",
-      "sha256": "a45c66592cd4b3c5afcdac28e259ae37c76c43d006de664e6091dec0d778af83",
+      "sha256": "b8062baa06a1e870f988b155b16f82b8cac383e31085b1370431c84d6c29b662",
       "source": "pstack/skills/poteto-mode/SKILL.md",
       "sourceSha256": "2755f102e7a6d0496b429d1031a22fb353e1f3d523543367caeaae5c4ed6f544",
       "adaptation": "raga native delegation policy"
+    },
+    {
+      "path": "skills/raga-artifacts/artifact_tool.py",
+      "sha256": "5e4d7ca9db500877f6386a85ce7906cdff79f0c791cad4c5253c9c6d7043b721",
+      "source": "raga native adaptation",
+      "sourceSha256": "5e4d7ca9db500877f6386a85ce7906cdff79f0c791cad4c5253c9c6d7043b721",
+      "adaptation": "raga native adaptation"
+    },
+    {
+      "path": "skills/raga-artifacts/artifact.mjs",
+      "sha256": "e1ac1f55af91b00dc8c542d80a9dc536868cb7d909aa5b42c606e4d76ad09535",
+      "source": "raga native adaptation",
+      "sourceSha256": "e1ac1f55af91b00dc8c542d80a9dc536868cb7d909aa5b42c606e4d76ad09535",
+      "adaptation": "raga native adaptation"
+    },
+    {
+      "path": "skills/raga-artifacts/diagrams.md",
+      "sha256": "f5218754b25c7a441ee81ff6755a36320c559835edc574b00ac6eaf9c82b2de6",
+      "source": "raga native adaptation",
+      "sourceSha256": "f5218754b25c7a441ee81ff6755a36320c559835edc574b00ac6eaf9c82b2de6",
+      "adaptation": "raga native adaptation"
+    },
+    {
+      "path": "skills/raga-artifacts/SKILL.md",
+      "sha256": "e258a80cadf528f411ed25bc793a4b0963a38e0776485cb2df7e357fb277192a",
+      "source": "raga native adaptation",
+      "sourceSha256": "e258a80cadf528f411ed25bc793a4b0963a38e0776485cb2df7e357fb277192a",
+      "adaptation": "raga native adaptation"
+    },
+    {
+      "path": "skills/raga-artifacts/templates/doc.html",
+      "sha256": "a2f0ed6c3f7b4cbea5f5fa16436623a71ac49ad536a1129bb08911e4337eb9f6",
+      "source": "raga native adaptation",
+      "sourceSha256": "a2f0ed6c3f7b4cbea5f5fa16436623a71ac49ad536a1129bb08911e4337eb9f6",
+      "adaptation": "raga native adaptation"
+    },
+    {
+      "path": "skills/raga-artifacts/templates/slides.html",
+      "sha256": "1aa47336acfe08114464cf27e13131714c23d4f7667940a92620eb39fb626c3c",
+      "source": "raga native adaptation",
+      "sourceSha256": "1aa47336acfe08114464cf27e13131714c23d4f7667940a92620eb39fb626c3c",
+      "adaptation": "raga native adaptation"
     }
   ],
   "exclusions": [

package/bundled-skills/docs/guide/01-setup.md

@@ -1,3 +1,3 @@
 # Set up the bundled workflows
 
-Every initialized instance already contains this pinned portable bundle. There is no plugin installation step. Read [the native runtime](../../skills/peak/references/raga-runtime/SKILL.md), then [configure model roles](../../skills/peak/references/peak-setup/SKILL.md) through a candidate revision. A null role inherits the session model. Verify available tools with capability_report before choosing a terminal, browser, or formal-verification workflow. Optional integrations require explicit setup. Start with /skill:peak and a goal with observable acceptance criteria.
+Every initialized instance already contains this pinned portable bundle. There is no plugin installation step. Read [the native runtime](../../skills/peak/references/raga-runtime/SKILL.md), then assign models to roles: run `/agent-setup` in an ordinary session, or [configure model roles](../../skills/peak/references/peak-setup/SKILL.md) through a candidate revision in an instance session. A null role inherits the session model. Verify available tools with capability_report before choosing a terminal, browser, or formal-verification workflow. Optional integrations require explicit setup. Start with /skill:peak and a goal with observable acceptance criteria.

package/bundled-skills/skills/bend/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: bend
+description: Turn rules the user states in plain words into Bend laws, write the proofs, and check them with the bend CLI. Use when the user asks to formally verify, prove, or guarantee that a rule can never break.
+---
+
+# Bend formal verification
+
+You write Bend laws and proofs for the user. The user decides the rules. Bend decides whether the proofs hold. Never claim a rule is proven unless `bend` printed `ALL PROOFS CHECK`.
+
+By Bend convention, `LAWS.bend` states the rules and `PROOF.bend` proves them. Here you write both, so the user must approve every law before you write proofs. After approval, a law is the spec. Do not edit it to make a proof pass.
+
+## Load the helper
+
+Work in the Python tool. Load the helper beside this file, then find the CLI:
+
+```python
+exec(await read("<directory of this SKILL.md>/bend_tool.py"), globals())
+bend = find_bend()
+files = law_files()
+```
+
+`find_bend()` checks `BEND_BIN`, then `PATH`, then `~/.bend/bin/bend`. If it returns `None`, stop. Ask the user to install Bend with `curl -fsSL https://bend-lang.com/install.sh | sh`. Do not install it yourself.
+
+Outside the Python tool, run the same commands with bash: `bend guide`, `bend PROOF.bend --check-only`.
+
+## Read the guide first
+
+Run `guide = await bend_guide()` and keep it in a variable. Read the sections on laws and proofs, recursion and termination, quantities, and kinds before you write Bend. Search the variable for anything else you need. `bend base --types` and `bend base <name>` print the standard library.
+
+## Steps
+
+1. **Ask for the rules.** Ask the user which rules must never break, then stop and wait for the answer. Offer two or three concrete examples taken from the project. Do not invent rules. If the user asks you to choose, propose rules in plain words and wait for confirmation.
+2. **Write the laws.** Write `files["laws"]`. Start with `import Base`. Define, in Bend, the code or model each rule talks about, then add one `law` per rule. Put the user's own words in a `# LAW:` comment above each law. Keep each law to one rule.
+3. **Check that the laws parse.** Write a `files["proof"]` that only imports `./LAWS.bend as Laws`, then run `await bend_check(files["proof"])`. Expect `SOME PROOFS FAIL` with a count of open claims. Fix any other error in the laws file.
+4. **Get approval.** Show the user each law twice: the Bend text and a one-sentence plain reading. Say what the laws do not cover. Ask whether they match the intended rules. Revise and ask again until the user approves. After the user says yes, call `approve_laws(files["laws"])`. A message the user sent before you asked is not approval. `bend_check` fails until the laws are approved.
+5. **Write the proofs.** In `files["proof"]`, prove each law with `def Laws.<law name>`. Do not write a `law` in the proof file, and do not move a law out of the laws file. The laws file includes its definitions. If a proof needs any change to that file, stop, show the user the change, and call `approve_laws` again only after a new yes. Run `await bend_check(files["proof"])` after each change. Read `problems` first, then the expected and observed terms in `output`. Use `?name` to print a goal while you work.
+6. **Handle a law you cannot prove.** If the output shows the law is false, show the user the counterexample and ask how to change the rule. If you cannot find a proof, leave `?TODO` in that def and report the law as open. Never use `@unsafe` or foreign code in a proof.
+7. **Report.** A check passes only when `bend_check` returns `verdict` `passed`, which needs `ALL PROOFS CHECK` and an empty `problems` list. Run the final check through `bend_check`, not bash. Quote its `verdict` and `problems` and the verdict line from `output`. Copy each law from the laws file as written. Do not retype or restate it in Bend. List each law as proven or open. If Lean is installed, `await bend_check(files["proof"], verdict=True)` rechecks with the Lean-proven kernel. Report its result separately.
+
+## Where the files go
+
+`law_files()` reads custom file names from `.raga/verification.json`.
+
+- In an ordinary session, `files["directory"]` is `.raga/verification/`. These are the files the instance gate reads.
+- In an instance session, the sandbox hides `.raga`, so `files["directory"]` is `verification-draft/`. After the user approves, tell them to copy both files into `.raga/verification/`.
+
+## Turn on the gate
+
+Only the user can make a revision depend on these proofs. In an instance project, give the user these commands and let them run each one:
+
+- `raga verify install --approved --network` downloads the pinned Bend release the gate uses.
+- `raga verify enable --approved` requires a passing check before a harness revision becomes active.
+- `raga verify run` runs the check in the sandbox and records the verdict.
+
+## Limits
+
+- A law proves only the Bend code that `LAWS.bend` defines or imports. For a project in another language, the laws prove facts about a Bend model of the code. Say so in the report.
+- Proofs need structural recursion. Read the termination section before you write recursive defs.

package/bundled-skills/skills/bend/bend_tool.py

@@ -0,0 +1,144 @@
+"""Bend helpers for the raga Python REPL. Load with exec(await read(path), globals())."""
+
+import asyncio
+import hashlib
+import json
+import os
+import re
+import shlex
+import shutil
+
+BEND_INSTALL = "curl -fsSL https://bend-lang.com/install.sh | sh"
+CHECK_TIMEOUT = 600
+
+
+def find_bend():
+    """Path of the bend executable, or None. BEND_BIN wins, then PATH, then the installer's default."""
+    for candidate in (os.environ.get("BEND_BIN"), shutil.which("bend"), os.path.expanduser("~/.bend/bin/bend")):
+        if candidate and os.path.isfile(candidate) and os.access(candidate, os.X_OK):
+            return candidate
+    return None
+
+
+def law_files(project="."):
+    """Where LAWS.bend and PROOF.bend belong, and whether this session may write there.
+
+    An ordinary session writes the files the instance gate reads: .raga/verification/<laws> and <proof>,
+    named by .raga/verification.json. An instance session cannot write .raga, so it drafts under
+    verification-draft/ for the user to copy.
+    """
+    project = os.path.abspath(project)
+    names = {"laws": "LAWS.bend", "proof": "PROOF.bend"}
+    config = os.path.join(project, ".raga", "verification.json")
+    if os.path.isfile(config):
+        with open(config, encoding="utf-8") as handle:
+            data = json.load(handle)
+        names = {key: data.get(key) or default for key, default in names.items()}
+    instance = bool(os.environ.get("RAGA_INSTANCE_ID"))
+    directory = os.path.join(project, "verification-draft" if instance else os.path.join(".raga", "verification"))
+    return {
+        "directory": directory,
+        "laws": os.path.join(directory, names["laws"]),
+        "proof": os.path.join(directory, names["proof"]),
+        "mode": "instance" if instance else "ordinary",
+    }
+
+
+async def _run(command, cwd):
+    line = "cd " + shlex.quote(cwd) + " && " + command + " 2>&1; printf '\\nEXIT=%s\\n' $?"
+    runner = globals().get("bash")
+    if runner is not None:
+        output = await runner(line, timeout=CHECK_TIMEOUT)
+    else:
+        process = await asyncio.create_subprocess_shell(line, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT)
+        stdout, _ = await asyncio.wait_for(process.communicate(), CHECK_TIMEOUT)
+        output = stdout.decode("utf-8", "replace")
+    body, _, code = output.rstrip().rpartition("\nEXIT=")
+    return body.strip(), int(code) if code.strip().isdigit() else None
+
+
+async def bend_guide(topic=None):
+    """The Bend guide text, or one named sub-guide such as "shaders"."""
+    bend = find_bend()
+    if bend is None:
+        raise RuntimeError("bend is not installed. Ask the user to run: " + BEND_INSTALL)
+    output, code = await _run(shlex.quote(bend) + " guide" + ((" " + shlex.quote(topic)) if topic else ""), os.getcwd())
+    if code != 0:
+        raise RuntimeError(output)
+    return output
+
+
+def _digest(path):
+    with open(path, "rb") as handle:
+        return hashlib.sha256(handle.read()).hexdigest()
+
+
+def approve_laws(laws_path):
+    """Record the laws the user approved. Call only after the user says yes."""
+    with open(laws_path + ".approved", "w", encoding="utf-8") as handle:
+        handle.write(_digest(laws_path) + "\n")
+
+
+def _problems(proof_path):
+    with open(proof_path, encoding="utf-8") as handle:
+        proof = handle.read()
+    imported = re.search(r"^import\s+\./(\S+)\s+as\s+Laws\s*$", proof, re.M)
+    if not imported:
+        return ["PROOF.bend must import the laws file as Laws"]
+    problems = []
+    if re.search(r"^law\s", proof, re.M):
+        problems.append("PROOF.bend states a law. Laws belong only in the laws file")
+    laws_path = os.path.join(os.path.dirname(proof_path), imported.group(1))
+    with open(laws_path, encoding="utf-8") as handle:
+        laws = handle.read()
+    if not re.search(r"^law\s", laws, re.M):
+        problems.append("the laws file states no law")
+    problems.extend(_unused_variables(laws))
+    approval = laws_path + ".approved"
+    if not os.path.isfile(approval):
+        problems.append("the user has not approved these laws. Show them to the user and call approve_laws after a yes")
+    else:
+        with open(approval, encoding="utf-8") as handle:
+            if handle.read().strip() != _digest(laws_path):
+                problems.append("the laws changed after the user approved them. Ask the user to approve them again")
+    return problems
+
+
+def _unused_variables(laws):
+    """A law whose statement ignores one of its `for` variables usually does not say what the user meant."""
+    problems = []
+    for name, body in re.findall(r"^law\s+([\w.]+)\s*:[^\n]*\n((?:[ \t]+[^\n]*(?:\n|$))+)", laws, re.M):
+        lines = [line.split("#", 1)[0].strip() for line in body.splitlines()]
+        binders = [line[4:].split(":", 1)[0] for line in lines if line.startswith("for ")]
+        statement = " ".join(line for line in lines if line and not line.startswith("for "))
+        for binder in binders:
+            for variable in (part.strip().lstrip("+-") for part in binder.split(",")):
+                if variable and not re.search(r"(?<![\w.])" + re.escape(variable) + r"(?!\w)", statement):
+                    problems.append("law " + name + " never uses its variable " + variable)
+    return problems
+
+
+async def bend_check(proof_path, verdict=False):
+    """Run the gate on PROOF.bend. Passed needs exit 0, ALL PROOFS CHECK, and no problems.
+
+    Problems are structural: a law stated in the proof file, a laws file without laws, or laws that
+    differ from the approved ones. verdict=True adds --verdict, which rechecks with the Lean-proven
+    kernel and needs Lean installed.
+    """
+    bend = find_bend()
+    if bend is None:
+        raise RuntimeError("bend is not installed. Ask the user to run: " + BEND_INSTALL)
+    proof_path = os.path.abspath(proof_path)
+    problems = _problems(proof_path)
+    command = shlex.quote(bend) + " " + shlex.quote(os.path.basename(proof_path)) + (" --verdict" if verdict else " --check-only")
+    output, code = await _run(command, os.path.dirname(proof_path))
+    passed = code == 0 and "ALL PROOFS CHECK" in output and not problems
+    if problems:
+        output = "CHECK REJECTED: " + "; ".join(problems) + ". Bend's own output follows and does not count.\n" + output
+    return {
+        "verdict": "passed" if passed else ("failed" if code is not None else "inconclusive"),
+        "problems": problems,
+        "exit_code": code,
+        "output": output,
+        "command": command,
+    }

package/bundled-skills/skills/peak/SKILL.md

@@ -39,7 +39,7 @@ Remaining triggers:
 
 ## Reference index
 
-This is the only installed skill. Every other workflow is a reference under `references/<name>/SKILL.md`. Pick the reference whose description matches the task and read it in full before acting. Do not read them all.
+Peak, `bend`, and `raga-artifacts` are the installed skills. `bend` handles Bend formal verification, and `raga-artifacts` makes shareable slides and documents. Every other workflow is a reference under `references/<name>/SKILL.md`. Pick the reference whose description matches the task and read it in full before acting. Do not read them all.
 
 ### Principles
 
@@ -127,7 +127,7 @@ This is the only installed skill. Every other workflow is a reference under `ref
 
 **Use `spec: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). The chat that receives `/peak` runs the playbook. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow references (`how`, `why`, `interrogate`, `reflect`, `swarm`) choose a native specification and configured model for review. Respect what the reference prescribes, don't override to `poteto-agent`.
 
-**Defaults for every run_child call.** Use the pinned resource root and one of worker, poteto-agent, or comment-sicko. Read-only reviewers use read_only=True. Writing children use read_only=False, details=True. Run independent calls with asyncio.gather. Select models from agents/model-roles.json. Null inherits the parent. Same-family seats are not model-diverse.
+**Defaults for every run_child call.** Use the pinned resource root and one of worker, poteto-agent, or comment-sicko. Read-only reviewers use read_only=True. Writing children use read_only=False, details=True. Run independent calls with asyncio.gather. Select models by role with run_child(..., role=..., seat=...) and agent_roles(); see raga-runtime. Null inherits the parent. Same-family seats are not model-diverse.
 
 **Match the model to the job.** Use real configured provider/model selectors. The runtime does not accept separate effort, speed, cloud environment, or resume fields. Include each seat's configured selector in its assignment. Report an unavailable selector rather than substitute another model.
 

package/bundled-skills/skills/peak/references/peak-setup/SKILL.md

@@ -3,7 +3,7 @@ name: peak-setup
 description: Configure real native model selectors for the bundled engineering workflows through a candidate harness revision.
 ---
 
-Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Authoring targets candidate revisions. Children use run_child, not an external agent service.
+Read [the native Python adapter](../raga-runtime/SKILL.md) before executing this workflow. Call `harness_mode()` first. In an ordinary session, model roles are user settings: ask the user to run the `/agent-setup` command, which lists available models, sets the reasoning budget, and assigns each role and panel seat. Do not edit settings files yourself. The rest of this workflow is for instance sessions. Authoring targets candidate revisions. Children use run_child, not an external agent service.
 
 # Configure native model roles
 

package/bundled-skills/skills/peak/references/raga-runtime/SKILL.md

@@ -12,23 +12,37 @@ Use the Python tool. It owns one persistent kernel per session. Load this adapte
 
 `await context.history(offset=0, limit=None)` reads only this session's history. Use explicitly provided current-instance records for historical research. Never scan another project's home or transcripts. `await llm_query(prompt, system=None, model=None)` is a one-shot model call. `await llm_batch(prompts, system=None, model=None)` runs independent one-shot calls.
 
-Load `raga_runtime.py` beside this skill with `exec(await read(absolute_helper_path), globals())`, then call `await run_child(spec, task, resource_root, context_data=None, model=None, max_turns=None, read_only=True, details=False)`. The resource root is the session's pinned harness path. Independent calls run with `await asyncio.gather(...)`. Writing children require `read_only=False, details=True` and receive isolated application workspaces from the supervisor. A context value is data, never a permission grant. The supervisor pins every child to the parent's harness revision.
+Load `raga_runtime.py` beside this skill with `exec(await read(absolute_helper_path), globals())`, then call `await run_child(spec, task, resource_root, context_data=None, model=None, max_turns=None, read_only=True, details=False, role=None, seat=None)`. Independent calls run with `await asyncio.gather(...)`. A context value is data, never a permission grant.
 
-Child specifications are in `../../../agents/`. `poteto-agent` carries the engineering style. `comment-sicko` reviews comments. `worker` handles general tasks. Model selectors are real provider/model strings from the configured registry. `None` inherits the parent. Role settings live in `agents/model-roles.json` in a candidate revision. When different review seats resolve to the same family, report that the review is not model-diverse. Do not invent aliases or silently replace a rejected model.
+## Pick the session mode first
+
+Call `harness_mode()` before any child launch, `instance` call, or `memory` call. It returns `instance` or `ordinary`.
+
+In an instance session, the resource root is the pinned harness path. Writing children require `read_only=False, details=True` and receive isolated application workspaces from the supervisor. The supervisor pins every child to the parent's harness revision. A `read_only=True` child gets the parent's workspace mounted read-only.
+
+In an ordinary session, the resource root is the `bundled-skills` directory three levels above this file. That is the directory holding `skills/` and `agents/`. Children share the parent's checkout. Raga does not isolate them, collect their changes, or enforce `read_only=True`. Follow these rules:
+
+- Make every code change in this session. `run_child` refuses `read_only=False`.
+- Use `read_only=True` children for exploration, design sketches, and review. `run_child` adds a no-write instruction to each child prompt.
+- A playbook step that delegates code writing is satisfied when this session owns the diff and a read-only child reviews it.
+- `instance` and `memory` calls do not exist. Candidate authoring, child patches, integration workspaces, instance memory, and no-mistakes need instance mode. Skip those steps and report them as unavailable in ordinary mode.
+- Commit, branch, and push only when the user asks. Preserve unrelated changes in the shared checkout.
+
+Child specifications are in `../../../agents/`. `poteto-agent` carries the engineering style. `comment-sicko` reviews comments. `worker` handles general tasks. Model selectors are real provider/model strings from the configured registry. `None` inherits the parent. Roles pick models: `await agent_roles()` returns the table children resolve against, which is the user's `/agent-setup` choices in an ordinary session and the pinned revision's `agents/model-roles.json` in an instance session. Wherever a workflow says to take a model from a line of `agents/model-roles.json`, read that line from `agent_roles()` instead and launch each seat with `run_child(..., role=line, seat=i)`, omitting `seat` for a single-value role and leaving `model` unset. The host applies the assigned model and reasoning budget. A panel role's list length sets how many seats to run. When different review seats resolve to the same family, report that the review is not model-diverse. Do not invent aliases or silently replace a rejected model.
 
 `answer['content']` and `answer['ready'] = True` return a child result. The native `rlm_query` API returns text by default. `details=True` returns the supervisor's workspace and change evidence. Never promise a worktree from a plain text answer.
 
-Only the documented run_child parameters are supported. Inherited spec labels select one of the three native specifications. Tool-schema, environment, cloud branch, background, resume, effort, and file-attachment fields from other agents are not launch arguments. Read-only review does not remove ordinary sandboxed inspection tools. Configure real model selectors in agents/model-roles.json. Null inherits. A rejected selector is a prerequisite failure, never permission to choose an unapproved substitute.
+Only the documented run_child parameters are supported. Inherited spec labels select one of the three native specifications. Tool-schema, environment, cloud branch, background, resume, effort, and file-attachment fields from other agents are not launch arguments. Read-only review does not remove ordinary sandboxed inspection tools. Users assign models with `/agent-setup` in ordinary sessions, or a candidate revision of agents/model-roles.json in instance sessions. Null inherits. A rejected selector is a prerequisite failure, never permission to choose an unapproved substitute.
 
-Use `await instance.child_patch(workspace_id)` to collect a child's owned change and patch. Use `await instance.integrate(workspace_ids, command, args, timeout_ms=120000)` for one supervisor-owned integration workspace and combined verification after each merge. Inspect its accepted result and returned patch before applying changes to the root workspace. Do not create or remove Git worktrees from worker shell commands. Git administration is deliberately hidden. Portable prose that requests branches or worktrees means these supervisor APIs, not raw Git worktree mutation.
+In instance mode, use `await instance.child_patch(workspace_id)` to collect a child's owned change and patch. Use `await instance.integrate(workspace_ids, command, args, timeout_ms=120000)` for one supervisor-owned integration workspace and combined verification after each merge. Inspect its accepted result and returned patch before applying changes to the root workspace. Do not create or remove Git worktrees from worker shell commands. Git administration is deliberately hidden. Portable prose that requests branches or worktrees means these supervisor APIs, not raw Git worktree mutation.
 
 Use an in-process bounded loop for autonomous work. A process exit ends the loop. There is no persistent wake scheduler or editor automation service. Keep ownership records in the instance state and stop descendant processes before cleanup.
 
 ## Candidate authoring
 
-`await instance.info()` reports the current pin. `candidate = await instance.candidate_create()` creates an editable proposal. Read and write its allowlisted resources with `await instance.candidate_read(candidate['id'], path)` and `await instance.candidate_write(candidate['id'], path, content)`. Use `await instance.candidate_commit(candidate['id'], message)` to commit it. Ordinary model filesystem access does not expose instance state or accepted artifacts. Do not invoke management CLI commands through shell. Promotion is a user CLI operation backed by exact-revision evidence, never a model approval.
+Candidate authoring needs instance mode. `await instance.info()` reports the current pin. `candidate = await instance.candidate_create()` creates an editable proposal. Read and write its allowlisted resources with `await instance.candidate_read(candidate['id'], path)` and `await instance.candidate_write(candidate['id'], path, content)`. Use `await instance.candidate_commit(candidate['id'], message)` to commit it. Ordinary model filesystem access does not expose instance state or accepted artifacts. Do not invoke management CLI commands through shell. Promotion is a user CLI operation backed by exact-revision evidence, never a model approval.
 
-`await memory.search(query)`, `await memory.get(entry_id)`, and `await memory.observe(text, evidence)` access only this project's structured observations. Search returns observations, not an automatic proof that an earlier decision remains valid. Read the current source before reusing a lesson.
+In instance mode, `await memory.search(query)`, `await memory.get(entry_id)`, and `await memory.observe(text, evidence)` access only this project's structured observations. Search returns observations, not an automatic proof that an earlier decision remains valid. Read the current source before reusing a lesson.
 
 ## Capabilities and dependencies
 

package/bundled-skills/skills/peak/references/raga-runtime/raga_runtime.py

@@ -4,11 +4,27 @@ import os
 import shlex
 from pathlib import PurePosixPath
 
-async def run_child(spec, task, resource_root, context_data=None, model=None, max_turns=None, read_only=True, details=False):
+ORDINARY_READ_ONLY = "This child shares the parent's checkout in an ordinary raga session, and raga does not enforce read-only access here. Do not create, edit, delete, format, stage, or commit files. Do not run commands that write to the project."
+
+
+def harness_mode():
+    return "instance" if os.environ.get("RAGA_INSTANCE_ID") else "ordinary"
+
+
+async def agent_roles():
+    """Role table children resolve against: /agent-setup choices in ordinary sessions, the pinned agents/model-roles.json in instance sessions."""
+    from raga_rlm import host_request
+    return await host_request({"type": "agent.roles"})
+
+
+async def run_child(spec, task, resource_root, context_data=None, model=None, max_turns=None, read_only=True, details=False, role=None, seat=None):
     if spec not in ("worker", "poteto-agent", "comment-sicko"):
         raise ValueError("Unknown bundled child specification")
     if not read_only and not details:
         raise ValueError("Writing children require details=True for supervisor-owned change evidence")
+    ordinary = harness_mode() == "ordinary"
+    if ordinary and not read_only:
+        raise ValueError("Ordinary raga sessions have no isolated child workspaces. Make the change in this session and use read_only=True children for exploration and review")
     root = resource_root.rstrip("/")
     definition = json.loads(await read(root + "/agents/" + spec + ".json"))
     definition_path = PurePosixPath(definition["instructions"])
@@ -18,11 +34,13 @@ async def run_child(spec, task, resource_root, context_data=None, model=None, ma
     for name in definition["skills"]:
         path = root + ("/skills/peak/SKILL.md" if name == "peak" else "/skills/peak/references/" + name + "/SKILL.md")
         instructions += "\n\n" + await read(path)
-    roles = json.loads(await read(root + "/agents/model-roles.json"))
-    if model is None:
-        model = roles.get(definition["modelRole"])
-    prompt = instructions + "\n\nPinned resource root: " + root + "\n\n# Assignment\n" + task
-    return await rlm_query(prompt, context=context_data, model=model, max_turns=max_turns, read_only=read_only, details=details)
+    if model is None and role is None:
+        role = definition["modelRole"]
+    notice = "\n\n" + ORDINARY_READ_ONLY if ordinary else ""
+    prompt = instructions + "\n\nPinned resource root: " + root + notice + "\n\n# Assignment\n" + task
+    if model is not None:
+        role, seat = None, None
+    return await rlm_query(prompt, context=context_data, model=model, max_turns=max_turns, read_only=read_only, details=details, role=role, seat=seat)
 
 async def capability_report():
     commands = {