teamrunner 0.0.2__tar.gz → 0.0.4__tar.gz

{teamrunner-0.0.2 → teamrunner-0.0.4}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -20,7 +20,7 @@ body:
     attributes:
       label: TeamRunner version
       description: The output of `teamrunner --version`
-      placeholder: teamrunner 0.0.2
+      placeholder: teamrunner 0.0.4
     validations:
       required: true
   - type: input

{teamrunner-0.0.2 → teamrunner-0.0.4}/.github/ISSUE_TEMPLATE/question.yml

@@ -15,4 +15,4 @@ body:
     id: version
     attributes:
       label: TeamRunner version, if it matters
-      placeholder: teamrunner 0.0.2
+      placeholder: teamrunner 0.0.4

{teamrunner-0.0.2 → teamrunner-0.0.4}/.github/workflows/tests.yml

@@ -68,3 +68,12 @@ jobs:
           teamrunner explain debate
           teamrunner run debate --rehearse -m "Should cities ban cars from their centres?"
           teamrunner runs debate
+
+      # The website's tutorial (teamrunner.ai/tutorial.html), replayed with this build:
+      # a change that would break the tutorial fails here, before it is released
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          repository: teamrunner/teamrunner.ai
+          path: website
+      - name: The website's tutorial
+        run: python website/tests/test_tutorial.py website/tutorial.html

teamrunner-0.0.4/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+TeamRunner is in preview: 0.0.x versions are a soft launch, and until 0.1.0
+is announced a version may change in ways that break teams and run folders
+made with an earlier one. Each such change is listed here.
+
+## 0.0.4
+
+- **Local browser interface:** `teamrunner ui [folder]` (`gui` is an alias)
+  opens the team's files in a browser. Edit with offline syntax highlighting,
+  save, validate with clickable problems, inspect resolved instructions and
+  flow diagrams, create teams from examples, manage members and set up keys.
+- Start one run at a time with defaults, a message, a file or a task file;
+  rehearse for free, follow events live, stop cleanly and re-run saved inputs
+  with the current team. Browse and search run history, read conversations,
+  outputs and records, inspect what members could read, and download raw files.
+- Compare two runs' numbered member versions, outputs, cost and paths. New
+  event logs keep exact member source text and fingerprints, the declared
+  flow graph and the recorded engine path for source diffs and arrow counts.
+  Older logs remain readable and label missing historical data explicitly.
+  A saved `resolved/team.yaml`, when present, can be copied to a new team for
+  editing; ordinary runs do not yet save a complete resolved team.
+- The interface uses the CLI's Python functions, adds no Python runtime
+  dependencies or database, and bundles its editor, Markdown renderer and
+  Mermaid diagrams for offline use. It binds only to `127.0.0.1`, requires a
+  random access token, confines editing to the opened folder, keeps run
+  records read-only and never displays stored key values.
+- The README's tutorial gives a browser alternative beside each CLI step.
+- UI review fixes: teams under an unrelated folder named `runs` remain editable;
+  actual run records stay read-only. Case-only renames work on macOS, rename
+  selects the old filename, and new-member names are checked before creation.
+  Non-UTF-8 files and validation in an empty workspace show friendly messages.
+- Files changed on disk reload automatically when there are no unsaved edits.
+  The file tree refreshes automatically and after runs finish. macOS uses its
+  native Trash operation, preserving Finder's Put Back support. The runs list
+  keeps comparison controls aligned and offers column navigation on narrow screens.
+- Live transcripts append new cards and populate read context on demand;
+  member-version history is cached in memory and invalidated when run files change.
+  The historical diagram helpers have been reformatted for readability.
+- **Two email tools**: `read_email` hands a member one email from a folder of
+  `.eml` files in the package (`mailbox`, `max_chars`); `save_draft` saves a
+  reply in the run's `work/outbox/` and never sends it. By default a draft can
+  answer only the email's sender (`reply_only: false` lifts that).
+- Runs started in the same second get their own folders instead of failing
+  with `FileExistsError`.
+
+## 0.0.3
+
+- **Backup models**: `model:` and `default_model:` may name several models,
+  separated by commas, in order of preference
+  (`default_model: openai/gpt-6-luna, anthropic/claude-sonnet-4-5`). Before the
+  first turn each member gets the first one available, for the whole run; the
+  console says so whenever a member is not on its first choice, and `run.json`,
+  `events.jsonl` and `teamrunner runs` record it. A profile's `name:` still
+  names one model.
+- The examples name their model once, as `default_model:` in `team.yaml`.
+- All six examples use Gemma 4 31B through OpenRouter with one API key.
+  The fact checker reads public sources instead of requiring Brave Search;
+  reference lookups use Crossref without a catalogue key. Reference lists
+  and findings are shared in the meeting messages so the next checker and
+  the editor can read them.
+- Gemma 4 tool calls on OpenRouter no longer compete with strict JSON
+  formatting: during tool use the final format is requested in the prompt,
+  and the runner still validates the declared outputs.
+- The README's tutorial and its five ideas hold only what works today; what is
+  designed but not built yet (experiments, the whiteboard) is in `PREVIEW.md`.
+  The README installs with uv or pip and needs one key.
+- Comments in the examples, and the `.gitignore` `teamrunner new` writes, no
+  longer cite internal design notes.
+
+## 0.0.2 — the first preview
+
+What the roadmap calls 0.1, the org package: a folder of text files that gets
+a job done.
+
+- **Teams from files**: a folder with `team.yaml` is a team; each member is a
+  Markdown file (settings on top, the prompt as prose); `chair.md` is the
+  script of who acts when, with rounds and decisions; with no chair, members
+  take turns in name order. Model profiles in `models/` share a model and its
+  settings across a team.
+- **Commands**: `new` (empty, `--from` an example or another team, or
+  `--describe` for a team written by a model), `validate` (with `--online`
+  to check the models), `explain`, `run` (with `--message`, `--file`,
+  `--task-file`; `--rehearse` runs the whole flow with no model and no cost),
+  `runs`, `show`, `gather`, `skill`.
+- **Toolkeepers** hold the tools, with an access list and guardrails, and four
+  built-in tools: `web_search_brave`, `read_page`, `read_file`, and `run_code`
+  (Python in a WebAssembly sandbox).
+- **Every run is logged** in the team's `runs/` folder: `run.json`,
+  `events.jsonl` and `output.md`, with costs, and the Python, LiteLLM and Deno
+  versions it ran on. Search results are read by the team but not kept,
+  unless `keep_results: true`.
+- **Six examples ship**: `round_robin`, `multi_agent_debate`,
+  `orchestrators_lite`, `fact_checked`, `reference_check`, and
+  `hiring_committee` (a hidden-profile task, after Stasser and Titus 1985).
+- Models from OpenAI, Anthropic and Google, and local models through Ollama.
+  macOS, Linux and Windows; Python 3.10 to 3.13.
+- Licensed GPL-3.0-or-later; the examples, the files `new` writes and the
+  authoring guide are MIT-0.
+
+## 0.0.1
+
+Reserved the name on PyPI. No working code.

{teamrunner-0.0.2 → teamrunner-0.0.4}/NOTICE

@@ -5,7 +5,17 @@ TeamRunner is licensed under GPL-3.0-or-later (see LICENSE). The shipped
 examples, the files `teamrunner new` writes and the authoring guide are
 MIT-0 (see examples/LICENSE).
 
-TeamRunner bundles no third-party code. It depends on these packages, which
+TeamRunner bundles CodeMirror 5.65.21 (MIT), by Marijn Haverbeke and others,
+for offline browser editing. Its licence and pinned source information are
+in src/teamrunner/ui/static/vendor/LICENSE and SOURCE.txt.
+The offline run viewer also bundles Marked 18.1.3 (MIT) and DOMPurify
+3.4.17 (Apache-2.0 OR MPL-2.0). Their licences and pinned source information
+are in the same vendor folder, under marked-* and dompurify-*.
+
+Offline flow diagrams bundle Mermaid 12.3.0 (MIT); its licence, source
+information and bundled dependency notices are in vendor/mermaid-*.
+
+It depends on these packages, which
 pip installs separately, each under its own licence:
 
   LiteLLM        MIT

{teamrunner-0.0.2 → teamrunner-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: teamrunner
-Version: 0.0.2
+Version: 0.0.4
 Summary: The experimentation platform for agent organizations — run multi-agent orchestrations and factorial experiments entirely from text files.
 Project-URL: Homepage, https://github.com/teamrunner/teamrunner
 Project-URL: Repository, https://github.com/teamrunner/teamrunner
@@ -53,7 +53,7 @@ experiments/advocate_model/  [v0.2]
 └── experiment.yaml          ← base: ../../debate — GPT vs. Claude as advocate, 20 replications
 ```
 
-> Everything unmarked is in the first release, **0.1**. **[v0.2]** arrives with experiments; **[v0.3]** with richer organizations (managers, private information, subteams, parallel work).
+> Everything unmarked works today, in the preview. Marked parts are designed but not built yet: **[v0.2]** arrives with experiments; **[v0.3]** with richer organizations (managers, private information, subteams, parallel work).
 
 ```bash
 teamrunner run debate --message "Remote work makes teams more productive"
@@ -68,13 +68,14 @@ No Python. No graph-building API. No framework vocabulary. If you can edit a tex
 - [Why we built it](#why-we-built-it)
 - [The five ideas](#the-five-ideas)
 - [Tutorial: your first debate in 10 minutes](#tutorial-your-first-debate-in-10-minutes)
-- [Tutorial part 2: your first experiment](#tutorial-part-2-your-first-experiment)
+- [Use TeamRunner in your browser](#use-teamrunner-in-your-browser)
 - [What lands in a run folder](#what-lands-in-a-run-folder)
   - [What your runs keep, and where your words go](#what-your-runs-keep-and-where-your-words-go)
 - [Going further: the worked examples](#going-further-the-worked-examples)
 - [What TeamRunner is not](#what-teamrunner-is-not)
 - [Status and roadmap](#status-and-roadmap)
 - [Questions, bugs and ideas](#questions-bugs-and-ideas)
+- [What's coming](PREVIEW.md): designed, not built yet
 
 ---
 
@@ -142,7 +143,7 @@ not your own opinion of the motion.
 
 **2. A folder is a team if it contains `team.yaml`.** Everything inside is a member, and a member is one of three things: a **worker** (an agent with a goal), a **team** (**[v0.3]** a subfolder with its own `team.yaml` — just another node in its parent's flow: *its turn means running its own internal flow to completion*, like a subcommittee: it deliberates on its own whiteboard, and the parent hears only its report — `report_from:` in its `team.yaml` says whose words those are), or a **toolkeeper** (the member who holds the keys to a tool). Complexity is contained by hierarchy, not by syntax. There is no registry file listing your agents; the file browser is the org chart.
 
-Tools are not members. An organization doesn't hand every worker every tool; a factory has a tool crib, with someone at the window who checks who may take what, and everyone else asks there. So the only members who touch tools are toolkeepers — a toolkeeper holds the guardrails (timeouts, no network, which folders), decides by a plain access list rather than a prompt, and its text body is simply what the team is told about it. Who may use a toolkeeper, and on what terms, is up to the toolkeeper's own access list — one toolkeeper can give different members different terms, the way a library gives professors and students different cards. The whole folder — team and toolkeepers — is a **package**: copy it anywhere and it gets the same job done. The work itself comes from outside: you hand the team a topic when you run it, or it uses the default written in `team.yaml`.
+The whole folder — team and toolkeepers — is a **package**: copy it anywhere and it gets the same job done. The work itself comes from outside: you hand the team a topic when you run it, or it uses the default written in `team.yaml`.
 
 **3. Every team has a chair, and there are no hidden if-statements.** Someone always decides who acts next, and TeamRunner makes you say who:
 
@@ -152,45 +153,40 @@ Tools are not members. An organization doesn't hand every worker every tool; a f
 
 Every routing decision is logged as an event attributed to whoever made it. Which means *protocol vs. discretion* — a script vs. a manager exercising judgment — is itself something you can A/B test by swapping one file for the other (**[v0.3]**).
 
-**4. One whiteboard for who sees what.** Everything an agent knows arrives through one of:
+**4. Tools sit with a toolkeeper.** Tools are not members. An organization doesn't hand every worker every tool; a factory has a tool crib, with someone at the window who checks who may take what, and everyone else asks there. So the only members who touch tools are toolkeepers — a toolkeeper holds the guardrails (timeouts, no network, which folders), decides by a plain access list rather than a prompt, and its text body is simply what the team is told about it. Who may use a toolkeeper, and on what terms, is up to the toolkeeper's own access list — one toolkeeper can give different members different terms, the way a library gives professors and students different cards.
 
-| Layer | Org analogue | Who reads | Who writes |
-|---|---|---|---|
-| **The whiteboard** (`whiteboard.yaml`) | the meeting, and the official record | everyone, unless a `read_by` line says otherwise | per item `written_by`; whatever anyone says is posted automatically; always logged |
-| **Memory** | what you were in the room for | you | nobody — history is append-only |
+**5. Every run is kept, and no agent can touch the record.** Every run gets its own folder in `runs/` with every prompt, everything said, every decision about who acts next, every tool call, the model that answered, tokens, time and cost (see [What lands in a run folder](#what-lands-in-a-run-folder)). The run log is the researcher's camera, outside the simulation: **no agent can ever read or write it** — a hard guarantee, without which every study of who knows what leaks.
 
-Everything said is posted on the whiteboard, open to all by default, so a team with no whiteboard file is a meeting room — and that is all of v0.1. **[v0.3]** `whiteboard.yaml` adds the rest: seal the reviewers from each other, or make the team a relay where each person hears only who spoke before them, with a `read_by` line for what was said — one line each.
-
-Information asymmetry is not a feature we had to invent; it is a narrow `read_by`. Incentives are numeric items on the whiteboard. Private briefs are items only one party can read.
-
-And one thing that is emphatically *not* a layer: the run log. It is the researcher's camera, outside the simulation. **No agent can ever read or write it** — a hard guarantee, without which every asymmetry design leaks.
-
-**5. Experiments are overlays.** **[v0.2]** Your package stays clean and runnable. An `experiment.yaml` lives *outside* it, names it with `base:`, and declares factors as *patches* against it, plus replications and a seed. Single runs and 200-run factorials go through the same engine. When a variant wins, `teamrunner promote` copies the exact version that ran back into the package — same agent, new version — and `export` hands you a standalone copy for production.
+Two more ideas are designed but not built yet — a whiteboard for who sees what, and experiments as overlays — and are described in [PREVIEW.md](PREVIEW.md).
 
 ---
 
 ## Tutorial: your first debate in 10 minutes
 
-We'll build a three-agent debate, run it, give it rounds, a fact checker and the web, and then (**[v0.2]**) turn it into a 40-run experiment. Zero code throughout.
+We'll build a three-agent debate, run it, give it rounds, a fact checker and the web. Zero code throughout. Turning it into a 40-run experiment comes with 0.2: see [PREVIEW.md](PREVIEW.md#experiments-v02).
 
-> Everything in this tutorial not marked **[v0.2]** or **[v0.3]** works in the preview. See [Status](#status-and-roadmap).
+> Every step works in a terminal, and from 0.0.4 also in your browser: see [Use TeamRunner in your browser](#use-teamrunner-in-your-browser).
 
 ### Step 0 — install
 
 ```bash
-pip install teamrunner
+uv tool install teamrunner      # uv fetches the right Python for you: https://docs.astral.sh/uv/
+pip install teamrunner          # or this, if you already have Python 3.10 or later
 ```
 
-Put your provider keys in TeamRunner's key file, `~/.teamrunner/.env` (in your home folder, outside every team):
+Put your key in TeamRunner's key file, `~/.teamrunner/.env` (in your home folder, outside every team). One key is enough: the one for the provider your team's model uses. This tutorial's team runs on OpenAI:
 
 ```
 OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
 ```
 
+A team on another provider takes that provider's key instead (`ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, …). The shipped examples run on OpenRouter, so they need only `OPENROUTER_API_KEY`. If a key is missing, the run stops before spending anything and says which one. You can try every step without a key: `teamrunner run --rehearse` runs the whole team with no model, for free.
+
 Keys stay with you, never with your teams: team folders get copied, zipped and sent to people, and a key inside one goes with it. If you already have a key set in your shell, TeamRunner offers to save it to the key file the first time it needs it (or to use it just this once). If it finds a `.env` inside a team folder, it offers to move the key out and delete it there. And it will **refuse to run** if it finds something that looks like an API key inside a spec file.
 
-Models on your own machine work too, free: install [Ollama](https://ollama.com), pull a model (`ollama pull llama3.2`), and write `model: ollama/llama3.2`. If Ollama runs somewhere other than this computer, put its address in the key file as `OLLAMA_API_BASE`. A word of warning: the smallest models often fail at exactly what teams need most — answering in a fixed form and asking toolkeepers properly — so they test the wiring better than they stand in for a real team. Before the first turn of every run, TeamRunner checks that each model your team names is available and lists every problem it finds in one table, so you never pay for half a run. `teamrunner validate --online` runs the same check without a run.
+Models on your own machine work too, free: install [Ollama](https://ollama.com), pull a model (`ollama pull gpt-oss:20b`), and write `default_model: ollama/gpt-oss:20b` in `team.yaml`. If Ollama runs somewhere other than this computer, put its address in the key file as `OLLAMA_API_BASE`. Choose one of about 20 billion parameters or more: the smallest models often fail at exactly what teams need most — answering in a fixed form and asking toolkeepers properly — so they test the wiring better than they stand in for a real team. Before the first turn of every run, TeamRunner checks that each model your team names is available and lists every problem it finds in one table, so you never pay for half a run. `teamrunner validate --online` runs the same check without a run.
+
+Or open `teamrunner ui` and choose **Set up keys** after selecting a team. It saves keys to the same key file and shows whether each key is present, never its saved value. **Check keys and models online** is a separate check.
 
 ### Step 1 — make a team
 
@@ -206,14 +202,18 @@ Two other ways to start, when you'd rather not begin from nothing:
 - `teamrunner new my_debate --from fact_checked` copies one of the examples that ship with TeamRunner (or any team folder you name), with fresh ids; each file remembers what it was copied from.
 - `teamrunner new my_debate --describe "two debaters argue a topic, a fact checker checks each speech, and a judge decides"` asks a model to write the team for you. It checks its own work with `validate`, never overwrites files, tells you what it cost, and ends by printing `teamrunner explain`, so you can read what it made before you run it. (If you work with an AI coding assistant, `teamrunner skill` gives it the same instructions: it installs a skill for Claude Code and Codex, and `teamrunner skill --agents-md <folder>` writes an `AGENTS.md` for other assistants that read one.)
 
+Or run `teamrunner ui` in the folder where you want to keep your teams. Choose **New team**, enter `debate`, and select an empty team or a shipped example. Select `team.yaml` on the left to edit it.
+
 This tutorial starts from nothing, so you see every file.
 
-`team.yaml` is the only required file. It marks the folder as a team and says what the team does:
+`team.yaml` is the only required file. It marks the folder as a team, says what the team does, and names the model its agents run on:
 
 ```yaml
 # team.yaml
 name: debate
 description: Two debaters argue a topic; a judge decides
+
+default_model: openai/gpt-6-luna
 ```
 
 Two things worth knowing now:
@@ -225,11 +225,12 @@ Two things worth knowing now:
 
 An agent file is Markdown. Frontmatter configures, body prompts.
 
+In the browser, select the team, choose **New member** for each Markdown file below, and paste its contents into the editor. **Save** (Ctrl/Cmd+S), then use **Show as it will run** to read the instructions with inputs filled in.
+
 ```markdown
 <!-- advocate.md -->
 ---
 description: Argues in favor of the topic
-model: openai/gpt-6-luna
 ---
 You are debating in favor of this topic:
 
@@ -244,7 +245,6 @@ recent point before adding your own. Be persuasive but honest.
 <!-- critic.md -->
 ---
 description: Argues against the topic
-model: openai/gpt-6-luna
 ---
 You are debating against this topic:
 
@@ -259,7 +259,6 @@ Be persuasive but honest.
 <!-- judge.md -->
 ---
 description: Decides who argued better
-model: openai/gpt-6-luna
 output:
   winner: [advocate, critic]
   reasoning: ""
@@ -275,7 +274,7 @@ explain your decision in one paragraph.
 
 Four things just happened:
 
-**Every agent names its model.** The model is part of the agent — it's who you hired. When a whole team uses the same one, `team.yaml` can say it once (`default_model: openai/gpt-6-luna`), and a model with its settings can live in a profile, `models/careful.yaml`, that agents name as `model: careful.yaml`. `teamrunner show judge` prints exactly which model and settings the judge will run with. `examples/orchestrators_lite` does both: its five engineers share one profile, `models/engineer.yaml`, named once as the team's `default_model:`.
+**The team names the model once.** No agent above names a model, so all three run on `default_model:` from `team.yaml`. An agent that should run on a different one says so itself (`model: anthropic/…`), and its own line wins. A model with its settings can live in a profile, `models/careful.yaml`, named as `default_model: careful.yaml` or `model: careful.yaml`. `teamrunner show judge` prints exactly which model and settings the judge will run with, and where each came from. `examples/orchestrators_lite` does both: its five engineers share one profile, `models/engineer.yaml`, named once as the team's `default_model:`. Models churn, so either line can name backups in order of preference, separated by commas: `default_model: openai/gpt-6-luna, anthropic/claude-sonnet-4-5`. Before the first turn TeamRunner picks the first one available, keeps it for the whole run, and says so whenever it isn't the first (`↪ judge runs on anthropic/claude-sonnet-4-5, its 2nd choice — …`); the run's record says so too.
 
 **Alphabetical order is the flow.** With no `chair.md`, members act in alphabetical filename order, one turn each — here `advocate → critic → judge`. That is also why the files above have no `name:` line: an agent's name is its filename. The folder listing *is* the running order, visible in any file browser. Rename to reorder.
 
@@ -322,6 +321,8 @@ teamrunner run . --message "Four-day weeks make teams more productive"
 
 The first runs the default topic; the second replaces it. Either way, the run log records the topic and whether it was given or the default.
 
+Or do the editing, validation and running in `teamrunner ui .`: **Validate** checks the same files, and clicking a problem opens its file at the line to fix. Choose **Run…**, keep **Rehearse (free, no model)** checked for a free test, and start. To use a model, clear that checkbox; choose team defaults, a message, a file or a task file. The page shows the conversation as it happens and a **Stop run** button.
+
 What you see while it runs (the words are invented; the layout is the real one):
 
 ```
@@ -349,6 +350,8 @@ Each turn shows who spoke, what they decided, how long it took, what it cost and
 
 Later, `teamrunner runs` lists every run of this package — when, which team, the input, the result (`winner = advocate`), status, time and cost — and `teamrunner runs latest` (or `teamrunner runs 14:32`) shows one again exactly as it looked while it ran.
 
+In the browser, choose **Runs** to reopen the conversation, output, path or record. Select two runs with the checkboxes and choose **Compare selected runs** to see member versions, outputs, cost and paths side by side.
+
 That's a working multi-agent system: four text files, one command.
 
 ### Step 5 — take control of the flow
@@ -372,7 +375,7 @@ The flow grammar is deliberately tiny — it is a whiteboard sketch that happens
 - **[v0.3]** `[a, b]` — **at the same time**: `editor -> [reviewer_1, reviewer_2] -> editor` sends the paper to both reviewers at once, and the editor waits for both reports. Neither sees the other's work in progress.
 - `done` ends the flow — or, inside a named block, just that block; `stop` ends the whole run immediately.
 
-Now the debate runs `advocate → critic → advocate → critic → advocate → critic → judge`. To see it as a picture, `teamrunner explain --diagram` opens the flow as a flowchart in your browser.
+Now the debate runs `advocate → critic → advocate → critic → advocate → critic → judge`. To see it as a picture, `teamrunner explain --diagram` opens the flow as a flowchart in your browser. Or, in the local interface, refresh the file tree after adding `chair.md`, select it, and choose **Flow diagram**. Save an edit to redraw the diagram and plain-words summary.
 
 ### Step 6 — add a fact checker and a decision
 
@@ -382,7 +385,6 @@ Suppose we want each speech fact-checked before it stands. Write a fact checker
 <!-- fact_checker.md -->
 ---
 description: Checks the factual claims in the latest speech
-model: openai/gpt-6-luna
 output:
   verdict: [pass, fail]
   reasons: ""
@@ -468,114 +470,36 @@ A toolkeeper step means the member just before it must end its turn with a reque
 
 `teamrunner explain .` prints, in plain English, who may use which toolkeeper and on what terms.
 
-TeamRunner 0.1 has four built-in tools: `web_search_brave` (Brave Search), `read_page` (a link in, the page's text out), `read_file` (a file the run was given with `--file`, its text out) and `run_code` (Python in a sandbox: no internet unless the toolkeeper allows it, and files written only in the run's own work folder). The sandbox is Python running in WebAssembly, and it installs with TeamRunner — nothing else to set up; it can use packages built for it (numpy, pandas, scipy, sympy and many more), but not every package. `examples/fact_checked` gives the fact checker a second toolkeeper, `sandbox.md`, so it can check the sums in a claim by running them. A toolkeeper holds one tool in 0.1, so its limits always mean one thing; a member who needs two tools asks two toolkeepers, as the fact checker does here. `examples/reference_check` uses `read_page` and `read_file`: it checks every reference in a paper.
-
-### Step 8 — private information and shared records **[v0.3]**
-
-The debate doesn't need this, but the moment you study organizations you will. `whiteboard.yaml` is the team's whiteboard: declared, typed items, each with who may read and write it. Everything anyone says is posted there too, open to all unless a `read_by` line says otherwise.
-
-```yaml
-# whiteboard.yaml
-
-# Bare list = a choice, starting at the first option.
-# Read by everyone, written by the chair — those are the defaults.
-stage: [opening, rebuttal, counter, closing, done]
-
-# A bare value = a starting value, read and written by the defaults.
-rounds_left: 3
-
-# Spell it out only when you change who reads or writes it.
-score:
-  starts_as: 0
-  written_by: [judge]
-
-# Information asymmetry IS a read permission.
-buyer_ceiling:
-  starts_as: 850
-  read_by: [buyer]
-```
-
-Every field is declared up front — no ad-hoc keys appearing mid-run. Every write is harness-mediated and logged as a `state_write` event: an agent listed in `written_by` returns the new value as a declared output field; nothing pokes state directly. Agents reference readable fields in their prompts as `{{whiteboard.buyer_ceiling}}`, and the validator checks that permission before you spend a cent.
-
-This one file is doing a surprising amount of work. Private valuations, confidential negotiating briefs, payoffs and incentives, task inputs, an artifact handed from one department to the next — all of them are just whiteboard items with the right permissions.
+TeamRunner 0.1 has six built-in tools: `web_search_brave` (Brave Search), `read_page` (a link in, the page's text out), `read_file` (a file the run was given with `--file`, its text out), `run_code` (Python in a sandbox: no internet unless the toolkeeper allows it, and files written only in the run's own work folder), `read_email` (one email from a folder of `.eml` files in the package) and `save_draft` (a reply saved in the run's `work/outbox/`, never sent, addressed only to the email's sender unless `reply_only: false`). The sandbox is Python running in WebAssembly, and it installs with TeamRunner — nothing else to set up; it can use packages built for it (numpy, pandas, scipy, sympy and many more), but not every package. `examples/fact_checked` gives the fact checker a second toolkeeper, `sandbox.md`, so it can check the sums in a claim by running them. A toolkeeper holds one tool in 0.1, so its limits always mean one thing; a member who needs two tools asks two toolkeepers, as the fact checker does here. `examples/reference_check` uses `read_page` and `read_file`: it checks every reference in a paper.
 
 ---
 
-## Tutorial part 2: your first experiment **[v0.2]**
+## Use TeamRunner in your browser
 
-Here's the question that motivated the whole project: **does it matter which model plays the advocate?**
-
-Don't touch the debate. Make a folder next to it with one file:
-
-> **[v0.2]** Experiments are built after the package is right. The file below is the agreed shape: it lives *outside* the package (`experiments/advocate_model/experiment.yaml`) and names it with `base:`.
-
-```yaml
-# experiments/advocate_model/experiment.yaml
-name: advocate-model-ab
-base: ../../debate
-task: tasks/remote_work
-
-factors:
-  advocate_model:
-    - label: gpt
-      patch: {advocate.model: "openai/gpt-6-luna"}
-    - label: claude
-      patch: {advocate.model: "anthropic/claude-sonnet-4-5"}
-
-replications: 20        # 2 conditions × 20 = 40 runs
-seed: 42
-
-limits:
-  max_concurrent: 4
-  max_cost_usd: 40.00
-```
+From 0.0.4, open a team folder with:
 
 ```bash
-teamrunner experiment .
+teamrunner ui debate
 ```
 
-What just became possible:
-
-**Factors are patches, so the base spec stays clean.** `advocate.model` means "the `model` field of the component `advocate`". Patch paths address any field of any component, including the prompt body (the field is called `prompt`), and any value can be `file:<path>` to swap in a whole file. `patch: {}` is the *unmodified base spec* — the control condition, written honestly as a level rather than smuggled in as "the normal run."
-
-**Anything in a file is a factor.** That's not a slogan, it's the mechanism. A few real examples from our worked recasts:
+`teamrunner ui` opens the current folder when you leave out `debate`; `teamrunner gui` is an alias. To create teams, open their parent folder instead. The command opens a browser tab and prints its local address. Keep that terminal running while you work; press Ctrl+C there to stop the server. If the tab does not open, paste the full printed address, including its token, into your browser.
 
-```yaml
-# A prompt/strategy A/B — same agent, two personalities
-- {label: tough, patch: {buyer.prompt: file:variants/buyer_tough.md}}
-
-# A treatment: one member is secretly self-interested
-- {label: saboteur, patch: {council.prompt: file:variants/saboteur.md}}
+The page works on the same files as the CLI. Choose a team or file on the left. You can create an empty team or copy a shipped example, add members, edit and save, rename members, or move files to the system trash. The editor warns about unsaved edits and files changed by another editor. Validation points to the file, line and suggested fix. **Show as it will run** fills in a member's instructions; **Flow diagram** shows the team's flow and summary. For a ready-made flow to edit, start from the `fact_checked` example.
 
-# The communication structure ITSELF as the factor:
-# same reviewers, same paper — only who can read whose review changes
-- label: public
-  patch:
-    whiteboard.said.reviewer_1.read_by: everyone
-    whiteboard.said.reviewer_2.read_by: everyone
-    whiteboard.said.reviewer_3.read_by: everyone
-```
+**Run…** accepts team defaults, a message, a file or a YAML task file. Rehearsal is selected by default for a team with no prior run; it uses placeholder words and random answers, needs no key and costs nothing. A model run uses your configured provider and its normal charges. The interface validates before starting, allows one active run at a time, streams the recorded events, and can stop the run cleanly. Key setup uses `~/.teamrunner/.env`; stored key values are never displayed.
 
-That last one is the founding claim of the product. Studying whether peer reviewers herd when they can see each other's reviews is, in TeamRunner, a two-level factor on who may read what each reviewer says.
+**Runs** is the archive. Filter by team or status, search the message and output, then open a run:
 
-**`replications` has a minimum of 2.** Writing `replications: 1` requires an explicit `allow_single_run: true`. LLMs are stochastic; single runs are anecdotes; we made the anecdote the awkward thing to write.
+- **Conversation:** member messages, decisions, tool calls, retries, tokens, models and cost, with a toggle for what each member could read.
+- **Path:** the saved flow with taken arrows highlighted and transition counts. Older logs without a saved engine path show only observed completed-turn transitions, labelled accordingly.
+- **Output:** the rendered `output.md`.
+- **Record:** inputs, numbered member versions, recorded settings and files. Version numbers come from the available run history.
 
-**One master `seed` fixes everything the harness controls** — condition assignment, ordering, per-run seed derivation. It does not, and cannot, make the model deterministic. See [Why we built it](#3-almost-nothing-published-about-multi-agent-systems-is-reproducible).
+Select two runs to compare their outputs, cost, time, paths and member versions. Exact member source diffs are available for new logs that record the source and its fingerprint; older logs show their recorded prompts, which may include substituted inputs.
 
-**`limits` is a real budget ceiling.** `max_cost_usd` stops the experiment; `max_concurrent` keeps you inside your rate limits.
+**Re-run with these inputs…** uses the current team with the old run's input values and copied input files. It does not restore old member versions. **Edit a copy of the saved team…** appears only when a run contains `resolved/team.yaml`; it creates an independent team with fresh IDs and lineage. Open the teams' parent folder to give that copy a place outside the original team. Ordinary runs do not yet save a complete resolved team, so their original files cannot be reconstructed from prompts alone.
 
-Then get the data out:
-
-```bash
-teamrunner runs                     # browse what you've run
-teamrunner export --experiment advocate-model-ab --format csv
-```
-
-Long format, one row per observation, straight into R, Stata, or pandas. Your analysis never lives inside our dashboard — that's a promise, not an oversight.
-
-The declarative metrics layer (ground truth, LLM-as-judge with a separately pinned judge model, cost and time) is specified but its file format is still open. Today's `metrics:` references in the examples are placeholders.
-
----
+Every run has **Open folder** and raw-file download links. The editor stays inside the folder you opened, and run records remain read-only. The server listens only on this computer at `127.0.0.1`, with a random access token. Editor, Markdown and diagram assets are bundled for offline use; model calls and online checks still need their usual services. The page adds no database or separate project format, and shows equivalent CLI commands alongside actions.
 
 ## What lands in a run folder
 
@@ -597,12 +521,12 @@ runs/01JZXG7T3M9QKWP5RVB2C8HD6N/
 
 | Event | What it records |
 |---|---|
-| `run_started` | the inputs, and every member exactly as it will run — model, settings, prompt |
+| `run_started` | the inputs, and every member exactly as it will run — model, settings, prompt; from 0.0.4, also each member's source text, content fingerprints and the declared flow graph |
 | `agent_message` | from, **to** (the *realized* topology), stage, attempt, **what it could read**, everything it said, typed outputs, the model actually used, tokens, cost, time |
 | `route_decision` | who decided, which option, which arrow — the audit trail for "no hidden if-statements" |
 | `tool_call` | who asked, which toolkeeper, the toolkeeper's yes or no, tool, arguments, the full result (for a search, how many results came back, unless `keep_results: true`) |
 | `state_write` **[v0.3]** | item, old → new, writer |
-| `check`, `retry`, `warning`, `error`, `run_finished` | the pre-run check, retries, warnings, failures, and the totals |
+| `check`, `retry`, `warning`, `error`, `run_finished` | the pre-run check, retries, warnings, failures, and the totals; from 0.0.4, `run_finished` also saves the path taken, for arrow counts |
 
 A field never changes its meaning between versions — later versions only add — so an analysis script you write today keeps working.
 
@@ -634,7 +558,17 @@ replays that exact spec. Every run folder is a self-contained replication packag
 
 ## Going further: the worked examples
 
-Six examples ship with TeamRunner, in `examples/`, simplest first — each adds something the one before it doesn't have. Copy one by name to start from it: `teamrunner new my_team --from orchestrators_lite`. Most are published multi-agent papers or projects, recast as TeamRunner files.
+Six examples ship with TeamRunner, in `examples/`, simplest first — each adds something the one before it doesn't have. Copy one by name to start from it: `teamrunner new my_team --from orchestrators_lite`. Most are published multi-agent papers or projects, recast as TeamRunner files. All six use `openrouter/google/gemma-4-31b-it` and need only an OpenRouter API key, with credits for model usage. They do not require OpenAI, Anthropic, Brave or catalogue keys.
+
+Set the key outside the team folder (never commit it):
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-key"
+teamrunner new my_debate --from round_robin
+teamrunner run my_debate
+```
+
+On PowerShell, set `$env:OPENROUTER_API_KEY="your-openrouter-key"` instead. You can also keep `OPENROUTER_API_KEY` in `~/.teamrunner/.env`. Add `--rehearse` to check a flow without calling a model; a rehearsal does not verify live model or tool behavior. The two source-checking examples read public pages and Crossref without extra keys; access restrictions, rate limits and missing abstracts or PDFs can still limit their evidence. The fact checker's Python sandbox downloads its runtime on first use. The code-review example uses demo model settings rather than the source paper's model.
 
 | Example | Recast of | What it adds |
 |---|---|---|
@@ -642,7 +576,7 @@ Six examples ship with TeamRunner, in `examples/`, simplest first — each adds
 | **`multi_agent_debate/`** | muthuspark/multi-agent-debate | A chair: the debate as a script, with a repeated block of rounds. |
 | **`hiring_committee/`** | Stasser & Titus 1985 (hidden profile) | A committee picks a candidate when the key facts are spread across its members: facts only one member knows, kept in that member's own file; a stage in the chair; a clerk who records the decision; and both meeting formats in one `chair.md`, one commented out. |
 | **`orchestrators_lite/`** | Fukui 2026 (lite) | Five engineers review code against planted bugs: a model profile the whole team shares, and two inputs. |
-| **`fact_checked/`** | — | The debate with a fact checker: decisions that send a speech back, counted tries, and toolkeepers — a web search with different terms for different members, a required search step, and a Python sandbox. |
+| **`fact_checked/`** | — | The debate with a fact checker: decisions that send a speech back, counted tries, and toolkeepers — a public-source reader with different terms for different members, a required source-reading step, and a Python sandbox. |
 | **`reference_check/`** | sciwrite-lint (Samsonau 2026) | Checks every reference in a paper: that it exists, that its details are right, and that the cited paper says what the citing sentence claims. A paper given as a link or a file (`--file`), toolkeepers holding `read_page` and `read_file`, the same tool under two toolkeepers with different `domains`, a decision that can stop the run, and batches of ten as a loop with a counted exit. |
 
 **Coming with 0.3**, recast on paper and waiting for the features they need: **Deb8flow** (subteams — each side a debater plus its own fact checker), **NegotiationGym** (private valuations, a loop either side can end), **LLM-Deliberation** (four parties, confidential briefs, one secretly given a hidden agenda), **AgentReview** (three reviewers at once, sealed reviews — do reviewers herd when reviews are public?), **ChatDev** (a three-level company, each department on its own whiteboard), and the full **Invisible Orchestrators** study (a hidden orchestrator whose words reach the team only as unsigned "policy updates").
@@ -665,15 +599,16 @@ The recasting campaign is the point, not decoration: each one is run *before* th
 
 ## Status and roadmap
 
-**Preview.** What the roadmap calls 0.1 is out as a soft launch, numbered 0.0.x: every command in the tutorial not marked **[v0.2]** or **[v0.3]** works. It may still change in ways that break earlier teams and runs until 0.1.0 is announced. What changed in each version is in the [changelog](https://github.com/teamrunner/teamrunner/blob/main/CHANGELOG.md).
+**Preview.** What the roadmap calls 0.1 is out as a soft launch, numbered 0.0.x: every command in the tutorial works; what is designed but not built yet is in [PREVIEW.md](PREVIEW.md). It may still change in ways that break earlier teams and runs until 0.1.0 is announced. What changed in each version is in the [changelog](https://github.com/teamrunner/teamrunner/blob/main/CHANGELOG.md).
 
 | Version | |
 |---|---|
 | **Design** | Spec drafted; paper recasts written as pure text ✅ |
 | **0.1 · The org package** ← now: in preview as 0.0.x | A folder that gets a job done: validation with friendly errors, its own runner, the event log, toolkeepers and four built-in tools, rehearsals, `run`, `runs`, `explain`, `new`, the authoring skill ✅ |
+| **Before 0.2 · Local browser interface** | In 0.0.4 ✅ `teamrunner ui` / `gui`: edit, validate, rehearse or run, browse recorded conversations and paths, compare two runs |
 | **0.2 · Experiments** | Experiments outside the package (`base:`), factorial designs, seeded replications, manifests, response cache, the answer-key metric, `teamrunner experiment`, export; `promote` / `export`. First real result: leader vs. flat |
 | **0.3 · Richer organizations** | Managers and rules-table chairs, `whiteboard.yaml` (private information, sealed and conditional visibility, addressed messages), subteams, parallel work, announcers; the recasts run for real, and the Invisible Orchestrators replication |
-| **0.4+ · Later** | LLM-as-judge metrics, `teamrunner ui` (run browser, cross-run comparison, communication-graph visualization), template library of canonical org structures, human-in-the-loop, automated improvement, running packages in production |
+| **0.4+ · Later** | LLM-as-judge metrics, communication-network statistics and visualization, template library of canonical org structures, human-in-the-loop, automated improvement, running packages in production |
 
 Human-in-the-loop nodes (`kind: human` — the runner pauses and asks a person) are for mixed human–agent studies.
 
@@ -701,7 +636,7 @@ Inside a package, these names are reserved. **Every one of them is optional exce
 | `chair.md` | How a protocol team is run: the script, as the file's body, or a `kind: rules` table **[v0.3]** | Everyone may talk to everyone; members act in alphabetical filename order, one turn each |
 | `manager.md` **[v0.3]** | How a managed team is run: an LLM that decides who acts next; only it may use input placeholders. A team has at most one of `chair.md` and `manager.md` | — |
 | `whiteboard.yaml` **[v0.3]** | Who sees what: declared items with `read_by` / `written_by`, and who can read what each member says (`said`) | Everyone reads everything said; built-in items only (e.g. `stage`) |
-| `tools/` | Reserved for a package's own tools, which come after 0.1. In 0.1 toolkeepers use the built-ins: `web_search_brave`, `read_page`, `read_file`, `run_code` | Built-ins only |
+| `tools/` | Reserved for a package's own tools, which come after 0.1. In 0.1 toolkeepers use the built-ins: `web_search_brave`, `read_page`, `read_file`, `run_code`, `read_email`, `save_draft` | Built-ins only |
 | `models/` | Model profiles: a model and its settings in one `.yaml`, named by agents as `model: careful.yaml` or by `team.yaml` as `default_model:` | Agents name provider models directly |
 | `runs/` | Where every run of this package is logged, whichever team you started; git-ignored | Created on the first run |
 | *subfolder with `team.yaml`* **[v0.3]** | A subteam — a node in the parent flow, with its own whiteboard; the parent hears only its report (`report_from:`) | — |