@zenera/cli 1.1.2 → 1.1.3

package/templates/editor/.github/skills/zen-cli/references/frame.md

@@ -0,0 +1,119 @@
+# The frame
+
+What is true of every command, whichever one is being run.
+
+## Invocation
+
+```
+zen <command> [options]
+```
+
+Three names run the same program: `zen`, `zn` and `zenera`. Help and error
+hints name the binary that was actually invoked, so `zn run` is spelled `zn`
+back at you.
+
+## Global options
+
+| Flag                    | Meaning                                                  |
+| ----------------------- | -------------------------------------------------------- |
+| `-h`, `--help`          | The command list, or a command's own help                |
+| `-v`, `--version`       | The version, and nothing else                            |
+| `--json`                | Machine-readable output on stdout instead of a rendering |
+| `-C`, `--directory <d>` | Act as if run in `<d>`                                   |
+
+These are lifted out of the argument list before a command parses its own
+flags, so they work in any position and a command never declares them itself.
+Everything after the command name belongs to that command.
+
+## Aliases
+
+Not listed in help, but they work.
+
+| Alias                | Command   |
+| -------------------- | --------- |
+| `ls`                 | `list`    |
+| `new`                | `init`    |
+| `keys`               | `key`     |
+| `validate`, `doctor` | `check`   |
+| `report`             | `inspect` |
+| `edit`, `code`       | `open`    |
+| `mock`               | `faker`   |
+
+## stdout is the answer, stderr is the narration
+
+The answer to what was asked goes to stdout: a model's reply, a report, a list.
+Progress, banners, warnings and the spinner go to stderr. So
+`zen run acme "…" > answer.md` captures the answer and nothing else, and
+`2>/dev/null` silences everything but it.
+
+`--json` applies to every command and prints one machine-readable document on
+stdout in place of the rendered form. Under `--json` nothing is asked
+interactively — the questions a run would ask are taken as answered.
+
+The banner is drawn only when stderr is a terminal, so a piped invocation never
+sees it.
+
+## Exit codes
+
+| Code | Name        | Means                                                      |
+| ---- | ----------- | ---------------------------------------------------------- |
+| 0    | ok          | It worked                                                  |
+| 1    | failed      | It ran and did not succeed                                 |
+| 2    | usage       | The command line was wrong                                 |
+| 3    | invalid     | The project is not valid — bad `agents.yaml`, missing file |
+| 4    | credentials | No usable credential for what was asked                    |
+| 5    | sandbox     | No container engine, or the image could not be prepared    |
+
+A wrong invocation and a wrong answer are deliberately not the same code, which
+is what a script needs. Failure messages name the offending key or file; a load
+error names the exact path, as in `agents.yaml: agents[1].skills.discovery — …`.
+Read it rather than guessing: the loader is strict on purpose and an unknown key
+is an error, not a value quietly ignored.
+
+## Which project
+
+Most commands operate on a project directory, resolved in this order:
+
+1. `--project <name|dir>` — a registry name or a path.
+2. The working directory, if it is a project (or is inside one).
+3. For `zen run`, a bare first word that names a registered project.
+
+`zen check` is the exception: its bare argument is a directory if one is there
+and a registered name otherwise, and it needs no `zenera.json`, so an
+unregistered directory can still be validated.
+
+## Environment
+
+| Variable           | Effect                                                |
+| ------------------ | ----------------------------------------------------- |
+| `ZENERA_HOME`      | Moves the whole home tree. Default `~/.zenera/neo`    |
+| `ZENERA_THEME`     | `dark`, `light` or `auto` for the TUI palette         |
+| `ZENERA_EDITOR`    | The editor `zen open` launches                        |
+| `ZENERA_DEBUG`     | Print a stack trace when something unexpected escapes |
+| `VISUAL`, `EDITOR` | Consulted by `zen open` after `ZENERA_EDITOR`         |
+| `COLORFGBG`        | Read as a hint when the palette is being detected     |
+| Provider keys      | `OPENAI_API_KEY` and friends — see [keys.md](keys.md) |
+
+A real environment variable always beats the keyring.
+
+## Where things live
+
+```
+~/.zenera/neo/            the home tree (0700)
+    projects.json         the registry: name -> directory
+    keys.json             credentials (0600)
+    keys/                 key files, for providers that hold a file
+    faker/                generator cache for `zen faker`
+
+<project>/
+    zenera.json           { version, name }
+    INSTRUCTIONS.md       house rules, prepended to every agent's prompt
+    agents.yaml           the configuration
+    agents/prompts/       one .md per agent
+    agents/skills/        one directory per skill, each with SKILL.md
+    sandbox/Dockerfile    the image commands run in, when the project builds one
+    sessions/             run state, memory, blobs, reports — never committed
+```
+
+Credential files are refused if anyone but the owner can read them, the way
+`ssh` refuses a loose private key: `chmod 600` and try again.

package/templates/editor/.github/skills/zen-cli/references/inspect.md

@@ -0,0 +1,61 @@
+# Reports — `zen inspect`
+
+```
+zen inspect [run] [--session <id>] [--open] [--rebuild] [--serve [port]]
+```
+
+Alias: `report`.
+
+Renders the trajectory of a run: every message, tool call, skill activation and
+hand-off, in order, with what each one cost. With no arguments it takes the
+newest run of the newest session.
+
+| Flag             | Meaning                                                 |
+| ---------------- | ------------------------------------------------------- |
+| `[run]`          | A run id. The newest otherwise                          |
+| `--session <id>` | Which session the run belongs to                        |
+| `--open`         | Open the report in a browser                            |
+| `--rebuild`      | Rebuild `report.html` from the recorded state           |
+| `--serve [port]` | Serve it locally, which the report needs for its assets |
+
+Use `--serve` rather than opening the file directly when the report has media in
+it; the page fetches its assets and `file://` will not give them to it.
+
+## Why it is the first thing to look at
+
+It shows what the model was actually given, which is rarely what you assumed. A
+prompt that reads correctly and behaves wrongly is nearly always a prompt that
+was assembled differently from how it looks in the repository: a skill that did
+not activate, a hand-off that fired early, a tool that was withheld, an asset
+that was not attached.
+
+The report also draws the architecture — agents, their tools, their hand-offs —
+and falls back to reconstructing the wiring from the trajectory when the run
+did not record it.
+
+## Where it comes from
+
+```
+<project>/sessions/<session-id>/runs/<run-id>/
+    input.md      what was asked
+    output.md     what came back
+    state.json    the whole trajectory
+    report.html   the rendering, rebuilt from state.json on demand
+    meta.json     when it ran, how long it took
+```
+
+Ids are timestamps: `20260825-143012-a7f3`. Listing them is `zen list --sessions`.
+
+Large images are lifted out of the recorded state and stored alongside it, so a
+photograph re-sent on every turn does not bloat every message. The report
+resolves them back.
+
+## What it prints
+
+The path to `report.html` on stdout — it is the answer, so it pipes. `--json`
+gives `{ session, run, report }` instead. A report that is missing is built
+before either; `--rebuild` builds one that already exists again, which is always
+safe because the report is derived and `state.json` is the truth. That is also
+what makes an old run readable by a newer renderer.
+
+To assert on a run in a script, read `state.json` rather than the report.

package/templates/editor/.github/skills/zen-cli/references/keys.md

@@ -0,0 +1,114 @@
+# Credentials — `zen key`
+
+```
+zen key <ls|add|use|check|rm|show|env> [ref] [options]
+```
+
+Alias: `keys`.
+
+Keys live in `~/.zenera/neo/keys.json`, mode `0600`, and are materialised into
+the environment just before a run. **A real environment variable always wins**,
+so a `.env` or an exported key still decides.
+
+A reference is `provider` or `provider/name`. A provider may hold several named
+keys; one of them is active.
+
+## Subcommands
+
+| Command                           | What it does                            |
+| --------------------------------- | --------------------------------------- |
+| `zen key ls [--check]`            | Everything stored, and its state        |
+| `zen key add <provider>[/name]`   | Read a key from stdin, or ask for it    |
+| `zen key use <provider>/<name>`   | Choose which one a run uses             |
+| `zen key check [provider[/name]]` | Ask the provider whether it still works |
+| `zen key rm <provider>/<name>`    | Forget one                              |
+| `zen key show <ref> [--reveal]`   | Masked by default                       |
+| `zen key env [provider …]`        | Shell exports, for other tools          |
+
+`zen key add` also takes `--project` and `--location`, for a Vertex service
+account.
+
+```
+zen key add openai                    # prompts, echo off
+pbpaste | zen key add openai/work     # or from stdin
+eval "$(zen key env)"                 # hand them to something else
+```
+
+**The secret never comes from argv.** A command line lands in `ps`, in shell
+history and in CI logs, so `zen key add` takes the value from piped stdin or an
+echo-off prompt and from nowhere else.
+
+## Providers
+
+| Name         | Environment variable             | Holds  | Where a key comes from              |
+| ------------ | -------------------------------- | ------ | ----------------------------------- |
+| `openai`     | `OPENAI_API_KEY`                 | secret | platform.openai.com/api-keys        |
+| `anthropic`  | `ANTHROPIC_API_KEY`              | secret | console.anthropic.com/settings/keys |
+| `google`     | `GEMINI_API_KEY`                 | secret | aistudio.google.com/apikey          |
+| `vertex`     | `GOOGLE_APPLICATION_CREDENTIALS` | file   | a service-account JSON key from GCP |
+| `vertex`     | `VERTEX_API_KEY`                 | secret | an express-mode key from GCP        |
+| `openrouter` | `OPENROUTER_API_KEY`             | secret | openrouter.ai/settings/keys         |
+| `exa`        | `EXA_API_KEY`                    | secret | dashboard.exa.ai/api-keys           |
+
+`exa` is a service the tools call, not a model provider.
+
+### Vertex takes either shape
+
+A **service-account file** is absorbed into `~/.zenera/neo/keys/` and
+`GOOGLE_APPLICATION_CREDENTIALS` points at it. It wants a project too, from
+`--project`, or `GOOGLE_CLOUD_PROJECT`, or the `project_id` inside the file, and
+a region from `--location` (`global` otherwise). Application Default
+Credentials from `gcloud auth application-default login` work with no entry at
+all.
+
+An **express-mode key** is an ordinary secret under `VERTEX_API_KEY`, and
+addresses no project: a key and a project are alternatives, and sending both
+gets a `403` that mentions neither. `--project` and `--location` are therefore
+refused alongside a key.
+
+```
+zen key add vertex --project acme-prod --location europe-west4
+# paste a path  → the file shape
+# paste a key   → the express shape
+```
+
+Which one you gave is read off the value: a path that exists is the file, and
+anything else is the key.
+
+## Credentials the keyring does not hold
+
+`zen key ls` also lists what the environment brought and what `gcloud` left
+behind, marked `~` and named for the variable rather than for a key:
+
+```
+~ vertex/$VERTEX_API_KEY   vx-1…9f0z   live   from the environment
+~ vertex/adc               …/application_default_credentials.json
+```
+
+These can be listed and checked, not chosen or forgotten — there is nothing to
+choose between, and nothing of ours to remove. Unset the variable, or
+`gcloud auth application-default revoke`.
+
+## Liveness
+
+`zen key check` and `zen key ls --check` do one round trip per key and record
+the verdict:
+
+- **live** — authenticated. A rate-limited answer counts as live, because it
+  proves the credential.
+- **dead** — the provider rejected it. A verdict.
+- **unknown** — the provider could not be asked. Says nothing about the key;
+  usually the network.
+
+`zen init` uses the same probe to pick which provider to scaffold with, so a
+project is not built around a revoked key.
+
+## When a run says there is no credential
+
+The frame does **not** materialise the keyring for you — each command that needs
+a credential opens the store itself. If `zen key ls` shows a key as live and a
+command still says `provider "openai": no api key — set OPENAI_API_KEY`, the
+credential is fine and the command is at fault. Everything that runs a model
+(`run`, `check`, `models`, `faker`, `rag`) already does this.
+
+Exit code `4` means no usable credential for what was asked.

package/templates/editor/.github/skills/zen-cli/references/projects.md

@@ -0,0 +1,99 @@
+# Projects — `init`, `list`, `open`, `version`
+
+## `zen init`
+
+```
+zen init [dir] [--name <name>] [--model <ref>] [--force]
+```
+
+Creates a project here, or in `<dir>`, and records it in the registry so `zen
+list` and `zen open` can find it by name.
+
+| Flag            | Meaning                                                 |
+| --------------- | ------------------------------------------------------- |
+| `--name <name>` | The registry name. Defaults to the directory's basename |
+| `--model <ref>` | The model to scaffold with, taken as written            |
+| `--force`       | Write into a directory that already holds a project     |
+
+What it writes:
+
+```
+zenera.json                     { version, name }
+INSTRUCTIONS.md                 house rules
+agents.yaml                     the configuration
+agents/prompts/default.md       the default agent's prompt
+agents/skills/                  empty, for skills
+assets/README.md
+sandbox/Dockerfile              the image the sandbox builds
+sessions/                       empty
+.gitignore
+.vscode/settings.json           editor files
+.github/                        copilot instructions, prompts, this skill
+```
+
+The project's own files are never overwritten — `--force` is what allows
+writing into an occupied directory, and the files already there stay. The
+editor files are the exception: `.vscode/settings.json` and the `.github/` tree
+are ours and are replaced on every `init` and every `zen open`, so edits to them
+do not survive.
+
+The default agent gets the file tools and a sandboxed shell, plus `exa:*` when
+the keyring holds an Exa key.
+
+**Choosing the model.** Without `--model`, the keyring is asked — not counted.
+Stored credentials are probed, because holding a key is not the same as holding
+a working one, and the model is picked from a provider that answers. A key from
+the environment is taken at its word. Each provider has its own scaffolded
+default, and every scaffolded ref names its provider: the model shorthand reads
+the first segment as a **provider name**, not a vendor, so a bare
+`gemini-3.5-flash` would be asked of OpenAI.
+
+## `zen list`
+
+```
+zen list [--sessions] [--prune]
+```
+
+Every known project: its sessions, the last run, and whether one is live right
+now.
+
+| Flag         | Meaning                                      |
+| ------------ | -------------------------------------------- |
+| `--sessions` | Expand each project into its sessions        |
+| `--prune`    | Forget entries whose directory has gone away |
+
+The registry is an index, not the truth. An entry pointing at a directory that
+no longer exists is shown dimmed rather than hidden, because a moved project is
+a thing to fix, not a thing to silently lose.
+
+## `zen open`
+
+```
+zen open [project] [--editor <cmd>] [--wait]
+```
+
+Opens the project directory in an editor. This is the only command that locates
+a project for a human rather than for itself.
+
+| Flag             | Meaning                               |
+| ---------------- | ------------------------------------- |
+| `--editor <cmd>` | The command to launch                 |
+| `--wait`         | Do not return until the editor closes |
+
+The editor is chosen in this order: `--editor`, `$ZENERA_EDITOR`, the editor
+this terminal belongs to, `$VISUAL` or `$EDITOR`, a known editor on `PATH` or
+installed, then the platform opener.
+
+Opening refreshes the editor files (`.vscode/settings.json` and the `.github/`
+tree) in the directory being opened. VS Code and its forks are launched with
+`--disable-workspace-trust`, so the settings written there apply to the new
+window immediately rather than after a prompt.
+
+## `zen version`
+
+```
+zen version
+```
+
+The CLI version, the library version and the Node version. `zen --version`
+prints the CLI version alone and returns before anything else loads.

package/templates/editor/.github/skills/zen-cli/references/rag.md

@@ -0,0 +1,159 @@
+# API search — `zen rag`
+
+```
+zen rag schema <index|search|show|stats> [spec...]
+```
+
+Provided by `@zenera/rag` — `npm i -g @zenera/rag` if `zen rag` says it is not
+installed.
+
+Reads an OpenAPI/Swagger document as a **graph** — operations, schemas and the
+fields inside them, joined by the `$ref`s between them — and makes it
+searchable. The answer to a search is not a list of matches but the connected
+piece of the API that matched: the operations, the schemas they carry and the
+fields inside them, printed as text, a diagram, or TypeScript that compiles.
+
+It exists because a large specification does not fit in a context window and
+grepping it returns fragments that name types nobody printed.
+
+## `index`
+
+```
+zen rag schema index <spec...> [--embedding <ref>] [-o <dir>] [--batch <n>]
+```
+
+| Flag                | Default       | Meaning                                                      |
+| ------------------- | ------------- | ------------------------------------------------------------ |
+| `--embedding <ref>` | —             | Which embedder makes the vectors. Omit it to see the choices |
+| `-o`, `--out <dir>` | `./schema-db` | Where the index goes                                         |
+| `--batch <n>`       | `96`          | Texts per embedding request, and how often progress prints   |
+
+```
+zen rag schema index openapi.yaml --embedding openai:text-embedding-3-small
+```
+
+Unlike the faker, `$ref`s are **bundled, not dereferenced**: component names are
+the node ids and the cycles between them are the edges. `discriminator` is kept —
+it is what turns a `oneOf` into a tagged union a compiler can narrow.
+
+What lands in `<out>`:
+
+```
+manifest.json     written last; its presence means the index is complete
+graph.json        the nodes and edges
+schemas.json      the schemas, read lazily
+operations.json   the operations, read lazily
+lance/            the vector and full-text indexes
+```
+
+The manifest records the embedding ref **and** the embedder's own id, so a
+search with a different model is refused rather than quietly returning nonsense.
+
+## `search`
+
+```
+zen rag schema search [terms…] [filters…]
+```
+
+Every argument is validated before an embedder is constructed, so a typo is a
+usage error rather than a credential error.
+
+### Terms — repeatable, and the field is the point
+
+| Term                    | Searches                                 |
+| ----------------------- | ---------------------------------------- |
+| `<text>`                | Everything, the same as `--all`          |
+| `--all <q>`             | Everything, unfiltered                   |
+| `--method <q>`          | Operations                               |
+| `--type <q>`            | Schemas, on the side `--direction` names |
+| `--input-type <q>`      | Schemas a call accepts                   |
+| `--output-type <q>`     | Schemas a call returns                   |
+| `--property <q>`        | Fields and parameters, per `--direction` |
+| `--input-property <q>`  | Fields and parameters a call accepts     |
+| `--output-property <q>` | Fields a call returns                    |
+| `--query <json\|->`     | A whole query object; `-` reads stdin    |
+
+Putting the intent in the field that matches what is wanted is what makes the
+search good. A request field belongs in `--input-property`, a response field in
+`--output-property`; `--all` cannot filter and is the weakest of them.
+
+### Filters and shape
+
+| Flag                        | Default       | Meaning                                                 |
+| --------------------------- | ------------- | ------------------------------------------------------- |
+| `-d`, `--dir <dir>`         | `./schema-db` | Which index                                             |
+| `--embedding <ref>`         | the index's   | Must be the one the index was built with                |
+| `--direction <d>`           | `any`         | `input`, `output` or `any`                              |
+| `--method-type <t>`         | `any`         | `read_only`, `read_write` or `any`                      |
+| `--exclude-id <id>`         | —             | Drop a node. Repeatable                                 |
+| `--exclude-method <name>`   | —             | Drop an operation by name. Repeatable                   |
+| `--exclude-type <name>`     | —             | Drop a schema by name. Repeatable                       |
+| `--exclude-property <name>` | —             | Drop a field by name. Repeatable                        |
+| `--limit <n>`               | `5`           | Seeds kept per term                                     |
+| `--max-hops <n>`            | `3`           | How far apart two hits may be                           |
+| `--max-nodes <n>`           | `200`         | Nodes per result                                        |
+| `--format <f>`              | `text`        | `text`, `mermaid`, `mermaid-flowchart`, `ts`, `openapi` |
+| `--no-docs`                 | —             | Leave the descriptions out                              |
+| `--interactive`             | —             | Prompt, search, refine. Needs a terminal                |
+| `--quiet`                   | —             | No narration                                            |
+
+```
+zen rag schema search --method "reset a user password" --format ts
+zen rag schema search --output-property "invoice total" --direction output
+echo '{"methods":["cancel a subscription"]}' | zen rag schema search --query -
+```
+
+The exclusions are what turn one search into a session: pass back the ids of
+what you have already been shown to be shown something else instead of the same
+thing again.
+
+`--format ts` emits TypeScript closed over its own `$ref`s — everything named is
+also declared, so the output compiles on its own.
+
+### `--interactive`
+
+A prompt that keeps the query between searches:
+
+```
+<text>                  search everything
+all|method|type <text>  search one field
+input-property <text>   also: output-property, property, input-type, output-type
+direction <d>           input | output | any
+method-type <t>         read_only | read_write | any
+format <f>              text | mermaid | mermaid-flowchart | ts | openapi
+show                    the query as it stands
+reset                   forget it, exclusions included
+quit
+```
+
+## `show`
+
+```
+zen rag schema show <id...> [-d <dir>] [--format <f>]
+```
+
+Prints named nodes with no search in between. Needs no embedder and no
+credential — it is a read of the graph.
+
+## `stats`
+
+```
+zen rag schema stats [-d <dir>]
+```
+
+What is in an index and what built it: counts by kind, the embedding model, the
+documents it came from. Also needs no embedder.
+
+## Giving it to an agent
+
+`@zenera/rag/tools` exports the same search as tools an agent can call:
+
+| Tool                       | For                                                                 |
+| -------------------------- | ------------------------------------------------------------------- |
+| `search_api`               | The search above, with the same fields                              |
+| `describe_types`           | Named schemas as TypeScript, closed over what they refer to         |
+| `find_types_with_property` | Every schema with a field of this name — exact lookup, no searching |
+| `list_methods`             | Operations by path, to see the shape of the API before asking       |
+
+They share the group `schema`, so an agent takes them with `schema:*` in its
+`tools:`.

package/templates/editor/.github/skills/zen-cli/references/run.md

@@ -0,0 +1,104 @@
+# Running — `zen run`
+
+```
+zen run [project] [prompt] [options]
+```
+
+On a terminal with no prompt it opens the TUI. With a prompt, or with no tty, it
+answers once on stdout and exits.
+
+## Options
+
+| Flag                    | What it does                                           |
+| ----------------------- | ------------------------------------------------------ |
+| `--project <name\|dir>` | Which project. Inferred from the directory otherwise   |
+| `--session <id>`        | Continue a particular session                          |
+| `--new`                 | Start a fresh one                                      |
+| `--workspace <dir>`     | What the agent may read and write                      |
+| `--model <ref>`         | Override the default model for this run                |
+| `--image <ref>`         | Override the container image commands run in           |
+| `--read-only`           | Withhold every tool that can write                     |
+| `--quiet`               | The answer only; no narration                          |
+| `--plain`               | One shot, even on a terminal                           |
+| `--theme <dark\|light>` | Force the palette. Detected otherwise; `$ZENERA_THEME` |
+| `--out <file>`          | Write the answer to a file as well as to stdout        |
+| `--yes`                 | Accept the questions it would otherwise ask            |
+
+Flags always beat the file: the repository states intent, the invocation
+overrides it.
+
+## Which word is the project
+
+The first positional is read as a project when it names one, and as the first
+word of the prompt when it does not:
+
+```
+zen run acme                     the acme project, TUI
+zen run acme "what changed?"     the acme project, one answer
+zen run "what changed?"          this directory's project, one answer
+zen run --project why "why?"     when the project is called "why"
+```
+
+The prompt comes from the argument, or from stdin, or from the TUI:
+
+```
+git diff | zen run --quiet "summarise this diff"
+```
+
+## What a prompt on the command line implies
+
+A prompt is a request for an answer, not a conversation to pick up, so it
+answers the three questions itself: **a fresh session**, **the directory you are
+in** as the workspace, and **no confirmation**. Every flag still wins —
+`--session`, `--workspace` and `--read-only` override it — and the TUI, where
+there is someone to ask, still asks.
+
+There is no `resume`. A session continues itself, because its state is what it
+is; `--session <id>` picks which one.
+
+## The TUI
+
+Drawn only when there is a terminal on both stdin and stdout, no prompt,
+no `--plain`, no `--quiet` and no `--json`. It streams the answer, shows
+reasoning as it arrives, and reports per-turn and per-session token usage in the
+footer.
+
+Reasoning only _arrives_ if the model was asked for it: OpenAI needs
+`reasoningSummary` on the responses API, Anthropic needs `thinkingBudgetTokens`,
+Gemini has `includeThoughts` on by default. An OpenAI project shows nothing
+until `agents.yaml` asks.
+
+Palette selection: `--theme` > `$ZENERA_THEME` > a query to the terminal >
+`COLORFGBG` > dark.
+
+## Sessions
+
+One session is one continuing conversation, with its own workspace, memory and
+run history. Ids look like `20260825-143012-a7f3`.
+
+```
+<project>/sessions/<id>/
+    workspace/          what the agent sees, unless --workspace said otherwise
+    runs/<run-id>/      input.md, output.md, state.json, report.html, meta.json
+    .data/
+        state.json      the live, resumable state, rewritten after every run
+        session.json    when it was made, and the workspace it is rooted at
+        memory/
+        blobs/
+        sandbox/home/   /home/agent inside the container
+    .lock               held while a run is in flight
+```
+
+The recorded workspace is what makes resuming safe: a session that quietly
+changed what "the workspace" meant between turns would be unexplainable, so it
+is written once and reused.
+
+None of `sessions/` is source and none of it is committed.
+
+A session is locked while it runs, and a lock whose process is gone is stale by
+definition and is taken over.
+
+## Afterwards
+
+Each run writes a `report.html` next to its state; the run prints a
+`file://` link to it. See [inspect.md](inspect.md).