isorite 0.12.1 → 0.13.0

package/docs/setup-for-agents.md

@@ -1,6 +1,6 @@
 # Setting isorite up: for an AI helping someone
 
-You're helping someone set up isorite: a local web app over a folder of Markdown notes (the browser), an agent in it called Iso, and `isorite term`, which runs OpenCode 2 beside the notes. This is everything isorite reads, writes and runs for the setup, and how each failure shows. `isorite help setup` prints this file.
+You're helping someone set up isorite: a local web app over a folder of Markdown notes (the browser), attached to the agent they already use (Claude Code, Codex, OpenCode, omp, Hermes, or any ACP agent) over MCP and ACP. isorite calls no model itself (since M25): the agent's key and model are its own, set up as for its own terminal. This is everything isorite reads, writes and runs for the setup, and how each failure shows. `isorite help setup` prints this file.
 
 **Start here:** ask them to run `isorite doctor --report` (add the notes folder if they have one) and paste what it prints. It shows isorite's and Node's versions, the platform, the configuration with secrets replaced by their lengths, the environment variables isorite reads, and a line for each check, ✓ passed, ✗ failed, ! a warning, – skipped. Most failures say what to change. Never ask them to paste a key or passphrase, and don't ask them to turn off certificate checking (`NODE_TLS_REJECT_UNAUTHORIZED=0`).
 
@@ -9,145 +9,87 @@ You're helping someone set up isorite: a local web app over a folder of Markdown
 | Command | What it does |
 |---|---|
 | `isorite new <folder>` | Makes the folder (and its parents), empty but for `.isorite/`. Refuses one with files in it already: that is opened as it is. |
-| `isorite doctor [<notes>] [--report] [--offline]` | Checks the setup a step at a time (below). Exit 1 if anything failed. `--offline`: asks the provider nothing. |
-| `isorite serve <notes> [--port <n>]` | The browser app at `http://localhost:4767/`, on 127.0.0.1 only. |
-| `isorite term [<notes>] [--port <n>]` | OpenCode 2 in this terminal, in the current folder (the code), with the notes beside it. Starts the isorite server if none answers on the port, and stops it on exit. |
-| `isorite check <notes>` | Lints the notes: frontmatter, links, cycles. |
+| `isorite doctor [<notes>] [--report] [--offline]` | Checks the setup a step at a time (below), and offers the project's MCP config for the notes named, written on a yes at a terminal. Exit 1 if anything failed. `--offline`: fetches nothing. |
+| `isorite serve <notes> [--port <n>]` | The browser app at `http://localhost:4767/`, on 127.0.0.1 only. Starts the agent chosen for the base's pane, if one is. |
+| `isorite acp --agent "<command>" [<notes>] [--port <n>]` | Run by an ACP front end (Toad, Zed) as its agent: starts the real agent behind it, adds isorite's MCP to its sessions, and shows them in Iso's pane. Starts the isorite server if none answers on the port, and lets it go on exit. |
+| `isorite mcp [<notes>] [--port <n>] [--agent <name>]` | isorite's MCP over stdio, a bridge to the server's, for an agent in its own terminal; what the project's config names. Starts the server likewise. |
+| `isorite check <notes>` | Lints the notes: frontmatter, links, cycles, and artifacts' rules. |
 | `isorite memory [<folder>]` | The agent's memory: a base (`~/isorite-memory` unless named), a git repository of its own, with its practice in `AGENTS.md`, listed in `bases.toml` as `memory`, lent. Run again, says where it is and changes nothing. |
 | `isorite bases [lend\|keep <name>]` | The bases this machine knows, as `bases.toml` lists them; `lend` lends one to every session, `keep` stops. |
-| `isorite guide [<folder>]` | The guide, a knowledge base about isorite, written into `~/isorite-guide` (or the folder named) and served. With no provider set up, Iso is the guide's finder: no key or network needed. Good to check the install alone. `isorite --tutorial` is another name for it. |
+| `isorite guide [<folder>]` | The guide, a knowledge base about isorite, written into `~/isorite-guide` (or the folder named) and served. Good to check the install alone. `isorite --tutorial` is another name for it. |
 | `isorite model [--from <folder\|.tgz>] [--url <url>]` | Optional: the model for search by meaning. Says which is installed and where, else fetches it (53 MB) from `ISORITE_MODEL_BASE_URL` (a mirror: the folder `isorite-model-granite-1.0.0.tgz` is in), npm, a GitHub release, then Hugging Face, saying why each failed. `--url`: that address only. `--from`: the release's `.tgz` fetched by hand (checked by its SHA-256), granite's files, or any compatible model (below). |
 | `isorite help setup` | Prints this. |
 
+`isorite term` and `isorite opencode` were retired in M25: OpenCode is attached as any agent (`opencode acp`).
+
 ## Files
 
 | Where | What |
 |---|---|
-| `~/.config/isorite/config.toml` (or `$XDG_CONFIG_HOME/isorite/`) | isorite's settings for this machine: `device`, `[provider]`, `[tiers]`, `[prices]`. Mode 600. Holds the key. |
-| `~/.config/isorite/bases.toml` | The bases this machine knows, a table each: `[<name>] path = "…"`, `lend = true` to lend it to every session. Each base opened is added, under its folder's name. Separate from config.toml, which is never rewritten for it. |
-| `~/.config/isorite/opencode/` | OpenCode's settings as isorite writes them at each `isorite term` start (`opencode.json`, theme, plugin link). Rewritten; don't edit. |
-| `~/.config/isorite/opencode/local.json` | The person's own OpenCode settings, laid over isorite's. Never rewritten. |
-| `<notes>/AGENTS.md` | The base's own instructions (notation, level, how notes are named), sent to Iso with every turn and named in OpenCode's `instructions`. Not a note: not on the Atlas, not linted. |
-| `<notes>/.isorite/` | isorite's own folder in the notes: journals of every change, `settings.toml` (`repository = "<path>"`, where code links point). Made on first open; commit it with the notes. |
+| `~/.config/isorite/config.toml` (or `$XDG_CONFIG_HOME/isorite/`) | This machine's `device` id. Mode 600. A `[provider]` or `[tiers]` from before M25 is left as written and no longer read. |
+| `~/.config/isorite/bases.toml` | The bases this machine knows, a table each: `[<name>] path = "…"`, `lend = true` to lend it to every session, and `agent = "<registry id>"` or `agent_command = "…"` for the agent the pane starts. Each base opened is added, under its folder's name. |
+| `<notes>/AGENTS.md` | The base's own instructions (notation, level, how notes are named), given to every agent in `brief_base`. Not a note: not on the Atlas, not linted. |
+| `<notes>/.isorite/` | isorite's own folder in the notes: journals of every change, the agents' sessions it carried (`conversations/agents/`), Iso's conversations from before M25 (`conversations/`), and `settings.toml` (`repository = "<path>"`, where code links point when it isn't the git repository the notes are in, or for notes outside any, the one an agent was first attached in; `agents_write_notes = false`, the pane's switch). Made on first open; commit it with the notes. |
+| `<repository>/.mcp.json`, `<repository>/opencode.json` | The project's MCP config, naming `isorite mcp <the base's folder>`; written by `doctor` or the pane on a yes. What else they hold is kept. |
+| `~/.cache/isorite/acp-registry.json` | The ACP registry, kept an hour. |
+| `~/.local/share/isorite/agents/<id>/<version>/` | A registry agent's program, fetched once and checked against its SHA-256. |
 | `~/.local/share/isorite/models/` (or `$XDG_DATA_HOME/isorite/models/`) | The models for search by meaning, a folder each: `granite-embedding-small-english-r2/`, and any other installed with `--from`. `use` names the one used, if not granite. |
 | `~/.cache/isorite/vectors-<hash>.json` | Each base's vectors, made by the model; made again when the model changes. |
-| `$TMPDIR/isorite-term-<port>.log` | The isorite server's output, when `isorite term` started it. Look here when "the isorite server did not start". |
-| `$TMPDIR/isorite-opencode-<port>.log` | OpenCode's server's output, under `isorite term`. |
-
-isorite never reads or changes the person's own OpenCode settings (`~/.config/opencode/`).
-
-## config.toml
-
-The person can set all of this from Iso's settings in the browser (M18: on `localhost` only; checked as `doctor` checks it, kept into use without a restart). The page writes the same fields; it drops comments, keeping the file as it was once as `config.toml.bak`. Writing it by hand needs the server restarted.
-
-```toml
-[provider]
-name = "work"                         # optional; what isorite calls the provider in messages
-url = "https://…/v1"                  # OpenAI-compatible; /chat/completions and /models are added. Absent: OpenRouter
-key = "…"                             # the key; also settable in Iso's settings in the browser
-key_header = "api-key"                # send the key in this header, as it is, instead of Authorization: Bearer
-key_prefix = "Bearer "                # what goes before the key in key_header (default: "Bearer " in Authorization, else "")
-stream_usage = false                  # don't send stream_options (some gateways answer 400 to it)
-max_tokens = 16000                    # the least output budget any call gets, for models that think at length
-cache_marks = true                    # send Anthropic cache marks (OpenRouter-style gateways only)
-pfx = "~/certs/me.pfx"                # client certificate (mTLS), PKCS#12; or cert + cert_key (PEM)
-pfx_passphrase = "$PFX_PASS"          # "$NAME": read from that environment variable
-cert = "me.pem"                       # relative paths are from config.toml's folder
-cert_key = "me.key"
-ca = "company-root.pem"               # extra authority for the gateway's certificate (added to the trusted ones)
-
-[provider.headers]                    # sent with every request; values may be "$NAME"
-X-Team = "…"
-
-[provider.query]                      # added to every request's URL
-api-version = "…"
-
-[tiers]                               # the provider's model names
-low = "…"                             # quick
-mid = "…"                             # Iso's default; the terminal's default
-max = "…"                             # most able
-
-[prices]                              # optional: US$ per million tokens in and out, for providers that don't say
-"model-name" = [3.0, 15.0]
-```
-
-Rules:
-
-- With `url` set and no `[tiers]`, OpenRouter's names are used (`anthropic/claude-…`). A gateway usually answers 404 to them. Doctor warns: name the gateway's models under `[tiers]`.
-- `pfx` and `cert` can't both be named. `cert` and `cert_key` go together.
-- A `"$NAME"` value whose variable isn't set is an error naming both.
-- Certificates are used only over https, and only for the provider's own address.
+| `$TMPDIR/isorite-server-<port>.log` | The isorite server's output, when `isorite acp` or `isorite mcp` started it. Look here when "the isorite server did not start". |
 
 ## Environment variables
 
 | Variable | Effect |
 |---|---|
-| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | Used by the `isorite` command: it re-runs itself once with `NODE_USE_ENV_PROXY=1`, and adds `localhost,127.0.0.1,::1` to `NO_PROXY`. OpenCode (Bun) reads them itself. |
+| `HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` | Used by the `isorite` command: it re-runs itself once with `NODE_USE_ENV_PROXY=1`, and adds `localhost,127.0.0.1,::1` to `NO_PROXY`. The agent reads them itself. |
 | `ISORITE_NODE_DEFAULTS=0` | Leave Node as it is: no system authorities, no proxy unless Node is told. |
 | `NODE_EXTRA_CA_CERTS` | A .pem of extra authorities, read by Node at start. |
-| `ISORITE_GATEWAY_URL`, `ISORITE_GATEWAY_MODELS`, `ISORITE_GATEWAY_KEY` | The terminal only: OpenCode asks this OpenAI-compatible address directly, with these models (comma-separated) and key, instead of `config.toml`'s provider. No certificate or headers apply. |
+| `ISORITE_ACP_REGISTRY` | Another ACP registry: an address, or a file. |
 | `ISORITE_EMBED_DIR` | The model for search by meaning is in this folder (and nowhere else is looked). |
 | `ISORITE_EMBED=off` | No search by meaning, whatever is installed. |
-| `ISORITE_OPENCODE` | The OpenCode 2 binary to run. Otherwise `opencode2`, then `opencode`, must be version 2. |
+| `ISORITE_BROWSER` | The Chromium to run artifacts in, unseen, when an agent writes one. |
 | `XDG_CONFIG_HOME` | Where `isorite/config.toml` is looked for. |
-| `SSH_CONNECTION` | Set over SSH: `term`, `serve` and `doctor` print the `ssh -L` command for the browser. |
+| `SSH_CONNECTION` | Set over SSH: `serve` and `doctor` print the `ssh -L` command for the browser. |
 
-## How requests reach the provider
-
-- **Iso** (in the isorite server) posts to `<url>/chat/completions?<query>`, streaming, with the key (in `Authorization: Bearer` or `key_header`), `headers`, and `stream_options` unless `stream_usage = false`. With a certificate or `ca`, it goes by `node:https` with them, through `HTTPS_PROXY` if set. Otherwise it uses Node's fetch.
-- **The terminal**: OpenCode is configured with the provider at `http://127.0.0.1:<port>/api/gateway`, the isorite server's relay, and with the server's token as its key. The relay adds the real key, certificate, headers and query, and passes `/chat/completions` and `/models` on. So whatever works for Iso works for the terminal. The relay answers only on 127.0.0.1, and only that token.
-- **Retries.** A 502, 503 or 504, a dropped connection or a timeout is asked again up to 3 times (after about 1, 2 and 4 s), and a 429 once (after its `Retry-After`, if 10 s or less), but only before any of the reply has come. The relay does the same before it passes anything to OpenCode (which retries on its own as well). 4xx answers and names not found are the settings', and are not asked again.
-- **An empty reply.** A reply cut off at its length limit with nothing written (a reasoning model that spent the budget thinking) is asked once more with three times the room.
-- With no key and no certificate in `config.toml`, and no `ISORITE_GATEWAY_*`, OpenCode uses its own models. `isorite term` prints which models it uses, and from where.
+The agent the pane starts is given the server's environment: its own keys (`ANTHROPIC_API_KEY`, `CODEX_API_KEY`, …) must be set where `isorite serve` runs.
 
 ## What working looks like
 
-`isorite doctor` ends `nothing failed`, with lines like:
+`isorite doctor <notes>` ends `nothing failed`, with lines like:
 
 ```
-✓ config: /home/me/.config/isorite/config.toml: work at https://llm-gateway.corp.example/v1
-✓ key: <48 characters>, sent in api-key
-✓ certificate: /home/me/certs/me.pfx
-✓ models: low small, mid medium, max large
+✓ config: /home/me/.config/isorite/config.toml
 ✓ proxy: http://proxy.corp:8080, used
 ✓ authorities: the system's (146), as well as Node's own
-✓ reached: https://llm-gateway.corp.example/v1/models answered with 12 models
-✓ reply from medium: "ready", 14 tokens in and 2 out
-✓ tools: medium called ping
-✓ opencode: opencode2 2.0.32
-✓ terminal: work's models, through isorite's server at http://127.0.0.1:4767/api/gateway, …
+✓ port: 4767 is free: isorite acp and isorite mcp start a server there
+✓ artifacts: run unseen when an agent writes one, in /usr/bin/chromium
+✓ search by meaning: granite-embedding-small-english-r2 at /home/me/.local/share/isorite/models/granite-embedding-small-english-r2
+✓ notes: /home/me/code/proj/notes, with its .isorite/
+✓ agents: .mcp.json and opencode.json in /home/me/code/proj name this base
 ```
 
-`isorite term` prints `isorite: http://localhost:4767/` and the terminal's models before OpenCode opens.
-
 ## Failures, and what to change
 
 | Seen | Cause | Change |
 |---|---|---|
-| `could not be reached: … SELF_SIGNED_CERT_IN_CHAIN` or `UNABLE_TO_VERIFY_LEAF_SIGNATURE` | The gateway's certificate is signed by an authority not trusted, usually the company's. | Install the company's root on the machine (isorite trusts the system's), or name its .pem as `ca`, or in `NODE_EXTRA_CA_CERTS`. Check `ISORITE_NODE_DEFAULTS` isn't 0. |
-| `… CERTIFICATE_REQUIRED`, `… other side closed (UND_ERR_SOCKET)` on https, `HANDSHAKE_FAILURE`, `BAD_CERTIFICATE` | The gateway wants a client certificate (mTLS), and got none it accepts. | `pfx` + `pfx_passphrase`, or `cert` + `cert_key`. Ask the person where theirs is: often a .pfx or .p12 file. If it's only in the Windows certificate store or the macOS keychain, it must be exported to a file. |
-| `pfx_passphrase does not open …` | Wrong passphrase, or the variable it names holds the wrong one. | Fix the passphrase. |
-| `ENOTFOUND` | The host name isn't found. | Check `url`. The name may resolve only on the company's network or VPN. |
-| `ECONNREFUSED` | Nothing listens there. | Check the URL's port. |
-| `ETIMEDOUT`, `UND_ERR_CONNECT_TIMEOUT` | No answer: often a proxy is needed. | Set `HTTPS_PROXY` (and `NO_PROXY` for internal hosts reached directly). |
-| `said 401` / `said 403` | The key, or how it's sent, isn't accepted. `doctor` says how it was sent (`sent as X-Gateway-Auth: <41 characters>`) and quotes the gateway. | Check the key, `key_header`, and any header the gateway wants. A message like "missing Bearer prefix" means `key_prefix = "Bearer "`. |
-| `Proxy response (407) … The proxy (HTTPS_PROXY), not the provider, refused with 407` | The company's proxy wants credentials of its own. Not the gateway's 401. | Credentials in `HTTPS_PROXY` (`http://user:password@proxy:port`), or the proxy's own sign-in. A proxy that signs in by Kerberos or NTLM can't be answered by isorite. |
-| `said 404 … no model called X, which is OpenRouter's name for it` | No `[tiers]`. | Name the gateway's models under `[tiers]`. `doctor` lists the models `/models` offers. |
-| `… is unavailable (503 …), tried 4 times over N s: it is likely …, not your settings` | The gateway, or the model behind it, is down. | Wait, and send it again (↻ under the turn). If it lasts, the gateway's status page or owner. |
-| `… used its whole output budget (N tokens) thinking, and wrote nothing` | A reasoning model ran out of room before it wrote. | A lower tier, or `max_tokens` under `[provider]`. |
+| `! agents: .mcp.json … doesn't name this base` | The project's MCP config isn't written. | `isorite doctor <notes>` at a terminal, and yes; or the pane's *the project's config*. Commit the files. |
+| The pane says "no agent is attached" | Nothing is attached to this base. | Choose one in the pane, or run `isorite acp` from a front end, or give the agent isorite's MCP. |
+| The pane's chosen agent says `the agent stopped (1)` and a line of its output | The agent's command failed: not installed, no key, no model. | Run the command in a terminal where `isorite serve` runs, and fix what it says; its key must be in that environment. |
+| `… is not offered for <platform>` | The registry has no way to run that agent here. | Install it yourself, and give its command. |
+| `Authentication required` in the pane | The agent wants to be signed in, and has no API key method, or none set. | Sign it in from its own front end or terminal, or set its key (`CODEX_API_KEY` for Codex). |
+| The agent never uses isorite's tools | It reads the Markdown with its own (OpenCode, omp, Hermes do). | Through `isorite acp` that still counts; in its own terminal, ask it to use isorite's tools, or attach it over ACP. |
+| Claude asks before each of isorite's tools | Claude's own permissions. | Answer *always*, or allow `mcp__isorite` in its settings. |
+| `isorite: starting…` and then nothing | The server it starts is stalled. | Read the log the line names (`isorite-server-<port>.log`). |
+| `port 4767 is serving <other>, not <notes>` | An isorite from before M20 serves another base there. | Stop it, or `--port`. |
+| `isorite term and isorite opencode are retired` | A command from before M25. | Attach OpenCode with `opencode acp`, from the pane or a front end. |
 | `! search by meaning: no model …` | Not installed (optional). `doctor` says whether the release (or the mirror) answers from here. | `isorite model`. Its failures name each source; offline, `isorite model --from <the .tgz>` with the file it names. |
-| `The model could not be fetched:` and a line for each source | None reachable from here. | Fetch the file it prints another way, check its SHA-256, and `isorite model --from <the .tgz>`. Or set `ISORITE_MODEL_BASE_URL` to a mirror's folder, or `isorite model --url <address>`. Or copy the model's folder from a machine that has it, then `isorite model --from <folder>`. |
-| `said 400: … stream_options` | The gateway refuses `stream_options`. | `stream_usage = false`. |
-| `✗ tools: … answered without calling the tool` | The model or gateway drops tools. | Choose a model that supports tool calls. Iso and the terminal need them. |
-| `isorite: starting…` and then nothing, or `waiting for OpenCode's server` | Something it starts is stalled. isorite runs no `git` to start (0.8.1); OpenCode may, and a company's `git` wrapper that waits on the network stalls it. | Read the log the line names. Check `git --version` answers at once in that folder; if not, the wrapper is the cause. |
-| The browser asks for a user and password (realm "Secure Area") | That's OpenCode's own web page, on the port `isorite term` names, not isorite's: a pairing link (`/pair`) used twice, or its address opened directly. | Open isorite's page (the link `isorite term` prints, or `/web` in the terminal). |
-| `isorite term needs OpenCode 2` | OpenCode 1, or none. | `isorite opencode` installs OpenCode 2 in `~/.config/isorite/opencode-cli`, leaving the global prefix alone; or `ISORITE_OPENCODE=…` names one. `isorite term` offers to install it when run in a terminal. |
-| `port 4767 is serving <other>, not <notes>` | Another base is served there. | Stop it, or `--port`. |
+| `The model could not be fetched:` and a line for each source | None reachable from here. | Fetch the file it prints another way, check its SHA-256, and `isorite model --from <the .tgz>`. Or set `ISORITE_MODEL_BASE_URL` to a mirror's folder, or `isorite model --url <address>`. |
+| `… SELF_SIGNED_CERT_IN_CHAIN` fetching the model or the registry | A company's authority not trusted. | Install it on the machine (isorite trusts the system's), or `NODE_EXTRA_CA_CERTS`. |
+| `Proxy response (407)` | The company's proxy wants credentials of its own. | Credentials in `HTTPS_PROXY` (`http://user:password@proxy:port`). A proxy that signs in by Kerberos or NTLM can't be answered by isorite. |
 | The link doesn't open, over SSH | `localhost` is the remote machine. | `ssh -L 4767:localhost:4767 <host>` from the person's own machine. |
-| The terminal works but uses an unexpected model | Check the line `isorite term` prints: `config.toml`, `ISORITE_GATEWAY_URL`, or OpenCode's own (no key or certificate). | Fix what it names. |
+
+The agent's own model, gateway or provider failing is the agent's to fix, in its own settings: isorite passes what it said into the pane.
 
 ## Another model for search by meaning
 
 Any ONNX model that gives 384 numbers for a text, with its `tokenizer.json`, can stand in for granite: `isorite model --from <folder>`. It's checked by use (loaded, and asked for one vector), copied into the models folder, and used from then on; each base's vectors are made again with it. An optional `isorite-model.json` beside its files gives `{"name": "…", "pooling": "cls" | "mean"}`: `cls` (the default) takes the first token's state, as granite is used; `mean` averages them all, as sentence-transformers models such as all-MiniLM-L6-v2 are used.
-
-If the gateway isn't OpenAI-compatible (Bedrock's or Vertex's own APIs, for example), isorite can't use it directly. An OpenAI-compatible proxy in front of it, such as LiteLLM, can.

package/docs/setup.md

@@ -1,6 +1,8 @@
 # Setting isorite up
 
-From nothing to Iso answering in the browser and OpenCode working in the terminal. If anything fails on the way, run `isorite doctor`: it checks each step and says what to change.
+From nothing to your notes in the browser, with the agent you already use attached to them. If anything fails on the way, run `isorite doctor`: it checks each step and says what to change.
+
+isorite calls no model itself (since M25). It is the notes, the Atlas and the record of how your understanding changed, attached to your agent: Claude, Codex, OpenCode, omp, Hermes, or any that speaks ACP. The agent's key and model are its own, set up as for its own terminal.
 
 ## 1. Install
 
@@ -16,87 +18,22 @@ Either one file, with Node inside it:
   ```powershell
   irm https://github.com/lachlanjs/isorite/releases/latest/download/install.ps1 | iex
   ```
-  It goes in `%LOCALAPPDATA%\isorite`, which it adds to your PATH (open a new terminal after), and unpacks itself into `%LOCALAPPDATA%\isorite\<version>\` the first time it runs. The executable isn't signed, so Windows may say it's from an unknown publisher. isorite's own settings are in `%USERPROFILE%\.config\isorite\`. Use Windows Terminal for `isorite term`. `isorite opencode` needs npm, so Node 24 as well.
+  It goes in `%LOCALAPPDATA%\isorite`, which it adds to your PATH (open a new terminal after), and unpacks itself into `%LOCALAPPDATA%\isorite\<version>\` the first time it runs. The executable isn't signed, so Windows may say it's from an unknown publisher. isorite's own settings are in `%USERPROFILE%\.config\isorite\`.
 
 Or from npm:
 
 - **Node 24** or later (`node --version`).
 - **isorite**: `npm i -g isorite`.
 
-Then, for the terminal, **OpenCode 2**: `isorite opencode` installs it for isorite alone (in `~/.config/isorite/opencode-cli`), leaving your global npm prefix, and any OpenCode 1 you use, as they are.
-
-`isorite guide` now opens the guide, a knowledge base about isorite with things to do in it. Until a provider is set up, Iso there is the guide's finder: no key, nothing sent anywhere.
-
-## 2. A model provider
-
-Iso and the terminal need an OpenAI-compatible provider. isorite's settings are in `~/.config/isorite/config.toml` (or `$XDG_CONFIG_HOME/isorite/config.toml`), a file only you can read.
-
-**OpenRouter** is the default. Open isorite in the browser, open Iso's settings (the icon at the right of Iso's pane head), and paste a key there, or sign in with OpenRouter, which makes one. Nothing else is needed.
-
-**Any other provider or gateway** is set up in the same place: choose *a gateway of your own*, give its address and key, and open *what else it asks for* for its key's header, headers, query values, client certificate, and whether it reports usage. Each tier's model is picked from the gateway's own list. The pulse icon checks the setup before it is kept, as `isorite doctor` would, and says what to change; the tick keeps it, in use at once, without a restart. The clipboard icon copies `isorite doctor --report` for someone helping.
-
-- The setup is changed only from this machine (`localhost`). From a phone over a tailnet it is shown and checked, and the key can be changed, but not the address it goes to.
-- Keeping a new address forgets the key held for the old one, unless a key is given with it.
-- Secrets (the key, the `.pfx`'s password, a header whose name looks secret) are written and never shown again.
-- The page writes `config.toml` again without its comments; the first time, the file as it was is kept beside it as `config.toml.bak`.
-- A running `isorite term` keeps the models it started with, but asks through the new address at once.
-
-The same setup can be written by hand in `config.toml`, under `[provider]`, with the models under `[tiers]`:
-
-```toml
-[provider]
-name = "work"                              # what isorite calls it
-url = "https://llm.example.com/v1"         # /chat/completions is added to it
-key = "…"                                  # or set it in Iso's settings in the browser
-
-[tiers]                                    # the provider's own names for its models
-low = "small-model"                        # quick replies
-mid = "medium-model"                       # Iso's default, and the terminal's
-max = "large-model"                        # the most able
-```
-
-Without `[tiers]`, OpenRouter's names are used, and another provider usually answers 404 to them.
-
-### A company's gateway
-
-Gateways inside companies often want more than a key. Each of these is optional:
-
-```toml
-[provider]
-url = "https://llm-gateway.corp.example/v1"
-key = "…"
-key_header = "api-key"                     # the header the key goes in, as it is, instead of Authorization: Bearer
-# key_prefix = "Bearer "                   # what goes before the key: for Bearer in another header, as
-#                                          # key_header = "X-Gateway-Auth"; Authorization has Bearer unless key_prefix = ""
-stream_usage = false                       # for a gateway that refuses stream_options; the gauge then counts nothing
-max_tokens = 16000                         # the least room a reply is given, for models that think at length
-
-# A client certificate (mTLS), for a gateway that asks for one: a .pfx (or .p12) ...
-pfx = "~/certs/me.pfx"
-pfx_passphrase = "$MY_PFX_PASSPHRASE"      # "$NAME" is read from the environment, so it isn't written here
-# ... or a certificate and its key, as .pem files:
-# cert = "~/certs/me.pem"
-# cert_key = "~/certs/me.key"
-
-ca = "~/certs/company-root.pem"            # the authority the gateway's own certificate is signed by, if needed
-
-[provider.headers]                         # sent with every request
-X-Team = "research"
-X-Project = "$PROJECT_ID"
-
-[provider.query]                           # added to every request's address
-api-version = "2024-10-21"
-```
-
-Paths may start with `~`, or are taken from `config.toml`'s folder. Any value written `"$NAME"` is read from that environment variable.
+`isorite guide` now opens the guide, a knowledge base about isorite with things to do in it.
 
 ### Proxies and the company's certificates
 
 The `isorite` command uses `HTTPS_PROXY` (and `NO_PROXY`) when they're set, and trusts the system's certificate authorities as well as Node's own, so a company's authority installed on the machine is trusted. Node does neither by itself. Set `ISORITE_NODE_DEFAULTS=0` to leave Node as it is.
 
-If the company's authority isn't installed on the machine, name its certificate as `ca` above, or in `NODE_EXTRA_CA_CERTS`.
+If the company's authority isn't installed on the machine, name its certificate in `NODE_EXTRA_CA_CERTS`.
 
-## 3. Your notes
+## 2. Your notes
 
 A folder of Markdown files. To start from nothing:
 
@@ -105,22 +42,19 @@ isorite new ~/notes/my-project
 isorite serve ~/notes/my-project
 ```
 
-`isorite new` makes the folder, empty but for isorite's own `.isorite/`. A folder of notes you have already is opened as it is, with `isorite serve`.
+`isorite new` makes the folder, empty but for isorite's own `.isorite/`. A folder of notes you have already is opened as it is, with `isorite serve`. It prints a link to click: `http://localhost:4767/`. isorite keeps what it needs in the folder's `.isorite/`.
 
-How you want the base kept (your notation, the level, the language, how notes are named) goes in `AGENTS.md` at the top of the notes, which Iso and the terminal's agent are both given. Edit it in Iso's settings, the icon at the right of its pane's header, or in any editor. Iso may offer a line for it when you say how you want things done.
+How you want the base kept (your notation, the level, the language, how notes are named) goes in `AGENTS.md` at the top of the notes, which every agent you attach is given. Edit it in Iso's settings, the icon at the right of its pane's header, or in any editor. An agent may offer a line for it when you say how you want things done.
 
-It prints a link to click: `http://localhost:4767/`. isorite keeps what it needs in the folder's `.isorite/`.
+## 3. Your agent
 
-## 4. The terminal
+Three ways in; [terminal.md](terminal.md) has each in full.
 
-```sh
-cd ~/code/my-project
-isorite term ~/notes/my-project
-```
-
-It prints the same link, and which models the terminal uses. OpenCode uses the provider above, through isorite. More is in [terminal.md](terminal.md).
+- **In Iso's pane.** With no agent attached, the pane offers one: an agent of the [ACP registry](https://agentclientprotocol.com/get-started/registry) (fetched and run as the registry says: its program checked against its SHA-256, else `npx` or `uvx`), or the command of one it doesn't list (`hermes acp`). isorite starts it for the base, in the base's repository, with the server's environment. Chosen from this machine only, and kept in `bases.toml`.
+- **From an ACP front end** (Toad, Zed, JetBrains): give it `isorite acp --agent "<the agent's command>"` as its agent. The session is live in the front end and in the pane at once.
+- **In the agent's own terminal**: give it isorite's MCP in the project's config. `isorite doctor ~/notes/my-project` shows the lines it would add (`.mcp.json` for Claude Code and others, `opencode.json` for OpenCode) and writes them on a yes; the pane offers the same. Commit them with the project.
 
-## 5. Several bases, and the agent's memory (optional)
+## 4. Several bases, and the agent's memory (optional)
 
 ```sh
 isorite memory              # ~/isorite-memory: a base of its own, a private git repository, lent to every session
@@ -128,7 +62,7 @@ isorite bases               # the bases this machine knows: each one is listed t
 isorite bases lend <name>   # lend one to every session (isorite bases keep <name> stops)
 ```
 
-One isorite server holds every base it is asked for. Each base's page is the same link with `?base=<name>`, and the base's name before the first pane's name switches between them; Ctrl-click opens one in a tab of its own. A base **lent** to every session can be read by every base's agent and Iso, and written by the agent, its words marked as its own. The memory is one: what the agent learns about you and your tools, kept across projects, as its `AGENTS.md` says. The list is in `~/.config/isorite/bases.toml`, beside `config.toml`:
+One isorite server holds every base it is asked for. Each base's page is the same link with `?base=<name>`, and the base's name before the first pane's name switches between them; Ctrl-click opens one in a tab of its own. A base **lent** to every session can be read and written by every base's agent, its words marked as its own. The memory is one: what the agent learns about you and your tools, kept across projects, as its `AGENTS.md` says. The list is in `~/.config/isorite/bases.toml`, beside `config.toml`:
 
 ```toml
 [memory]
@@ -142,16 +76,18 @@ lend = true
 isorite model
 ```
 
-It says which model is installed and where, or fetches it (53 MB, once): from npm, else from a release on GitHub, else from Hugging Face. Without it, Iso searches by words and follows links. A mirror of the release is tried first when `ISORITE_MODEL_BASE_URL` names the folder its `.tgz` is in, and `isorite model --url <address>` fetches from that one address alone. Where none of those can be reached, `isorite model` prints the file's address and SHA-256: fetch it another way, and run `isorite model --from <the .tgz>`. Or copy the model's folder from a machine that has it (`isorite model` there says where it is) and run `isorite model --from <folder>`. Any compatible model works the same way: an ONNX model that gives 384 numbers, with its `tokenizer.json` (for example all-MiniLM-L6-v2, with `{"pooling": "mean"}` in an `isorite-model.json` beside it).
+It says which model is installed and where, or fetches it (53 MB, once): from npm, else from a release on GitHub, else from Hugging Face. Without it, the agent searches by words and follows links. A mirror of the release is tried first when `ISORITE_MODEL_BASE_URL` names the folder its `.tgz` is in, and `isorite model --url <address>` fetches from that one address alone. Where none of those can be reached, `isorite model` prints the file's address and SHA-256: fetch it another way, and run `isorite model --from <the .tgz>`. Or copy the model's folder from a machine that has it (`isorite model` there says where it is) and run `isorite model --from <folder>`. Any compatible model works the same way: an ONNX model that gives 384 numbers, with its `tokenizer.json` (for example all-MiniLM-L6-v2, with `{"pooling": "mean"}` in an `isorite-model.json` beside it).
 
 ## When something fails
 
-If a gateway is down for a moment (it answers 502, 503 or 504, or drops the connection), Iso and the terminal ask it again, up to three times. When it stays down, Iso says it's likely the gateway, not your settings, and the ↻ under the turn sends it again.
-
 ```sh
 isorite doctor ~/notes/my-project
 ```
 
-It checks, in turn: the configuration, how Node reaches the network (the proxy, the authorities), the provider (its list of models, a reply of a few words from each model, and a tool call: a few hundred tokens in all), the terminal (OpenCode 2, the port, the models it will use), and the notes. Each line says what failed, and what to change. `--offline` asks the provider nothing.
+It checks, in turn: the configuration, how Node reaches the network (the proxy, the authorities), the port, a browser to run artifacts in, the model for search by meaning, the notes and their repository, and the project's MCP config. Each line says what failed, and what to change. `--offline` fetches nothing.
+
+`isorite doctor --report` gives all of it as one block, with the configuration and the environment it read, any secret shown only by its length. Paste it to whoever is helping, or to an AI helping you: [setup-for-agents.md](setup-for-agents.md) is written for it, and `isorite help setup` prints it.
+
+Your agent's own failures (its key, its model, its gateway) are its own: its front end, or the pane, says what it said. A refusal is shown in the pane; an agent that asks to be signed in with its API key (Codex) is signed in with it when isorite starts it.
 
-`isorite doctor --report` gives all of it as one block, with the configuration and the environment it read. The key, passphrases and any other secrets are shown only by their length. Paste it to whoever is helping, or to an AI helping you: [setup-for-agents.md](setup-for-agents.md) is written for it, and `isorite help setup` prints it.
+Until M25, `config.toml` also held Iso's provider, under `[provider]` and `[tiers]`. They are left as written, and no longer read.

package/docs/terminal.md

@@ -1,96 +1,95 @@
-# isorite beside your code: the terminal
+# isorite beside your agent
 
-How to use isorite on a project of your own. OpenCode 2 is the coding agent in your terminal; isorite gives it your notes, and shows its session in Iso's pane in the browser. From there you can ask it things, give it notes and passages, stop it, and answer what it asks before it acts.
+How to use isorite with the agent you already use (Claude, Codex, OpenCode, omp, Hermes, or any that speaks ACP) on a project of your own. isorite gives the agent your notes over MCP, and reaches the agent over ACP: the agent gets the notes, the Atlas sees the agent, and Iso's pane shows the session. isorite calls no model itself: the agent's key and model are its own, set up as for its own terminal.
 
-Setting isorite up the first time, or at work behind a company's gateway, is in [setup.md](setup.md).
-
-## What you need
-
-- **Node 24** or later.
-- **isorite**: `npm i -g isorite`.
-- **OpenCode 2**: `isorite opencode` installs the version isorite is tested with in `~/.config/isorite/opencode-cli`, for isorite alone, leaving the global npm prefix (and an OpenCode 1 you use) as it is. `isorite term` offers to when it finds none. One installed yourself (`npm i -g @opencode/cli`, as `opencode2`) is found too, or name one with `ISORITE_OPENCODE=/path/to/opencode`.
-- A model provider, set once in `~/.config/isorite/config.toml`: see [setup.md](setup.md). `isorite doctor` checks all of this.
+Setting isorite up the first time is in [setup.md](setup.md).
 
 ## Your notes for the project
 
-Keep the project's notes in a folder of their own, for example `~/notes/<project>`. It can start empty: `isorite new ~/notes/<project>` makes it. isorite keeps what it needs in the folder's `.isorite/` (the journals of every change, and its settings), made the first time the folder is opened. Commit `.isorite/` with the notes, if they're in git.
-
-## Starting it
+Keep the project's notes in a folder of their own, often inside the project's repository (`notes/`), or beside it (`~/notes/<project>`). It can start empty: `isorite new <folder>` makes it. isorite keeps what it needs in the folder's `.isorite/` (the journals of every change, the sessions it carried, and its settings), made the first time the folder is opened. Commit `.isorite/` with the notes, if they're in git.
 
 ```sh
-cd ~/code/my-project
-isorite term ~/notes/my-project
+isorite serve ~/code/my-project/notes
 ```
 
-This starts the isorite server for the notes (unless one is running on port 4767; `--port <n>` for another), and OpenCode's own server, on this machine, with a password of its own. Then it opens the terminal on that server.
+## Three ways in
 
-Before OpenCode takes the screen, `isorite term` prints:
-
-```
-isorite: http://localhost:4767/
-  the terminal's models: work-large, work-small, as config.toml names them, through the isorite server
-```
+### In Iso's pane
 
-Most terminals let you click the link. It prints the same again when OpenCode exits. Closing the terminal stops both servers, if `isorite term` started them.
+With no agent attached, Iso's pane says how to attach one. *Here, in this pane*: choose an agent of the [ACP registry](https://agentclientprotocol.com/get-started/registry), or give the command of one it doesn't list (`hermes acp`). isorite starts it for the base, behind `isorite acp --pane`, in the repository the base is in, with the server's environment, and starts it again when the base is next opened. It runs a program, so it is chosen from this machine only; the choice is kept in `~/.config/isorite/bases.toml` (`agent`, or `agent_command`). The drawer's *stop it* stops it.
 
-The first time, the folder you started in is named as the notes' repository in `.isorite/settings.toml`, so that code links in the notes point into it.
+A registry agent is run as the registry says: its program for this platform, fetched once into `~/.local/share/isorite/agents/<id>/<version>/` and checked against its SHA-256; else with `npx -y` or `uvx`. `ISORITE_ACP_REGISTRY` names another registry, an address or a file.
 
-### Over SSH
+### From an ACP front end
 
-`localhost` is the machine `isorite term` runs on. To open isorite from your own machine, forward the port:
+Toad in the terminal, Zed, or JetBrains: give it isorite as its agent, with the real agent's command:
 
 ```sh
-ssh -L 4767:localhost:4767 <the machine>
+isorite acp --agent "npx -y @agentclientprotocol/claude-agent-acp" ~/code/my-project/notes
 ```
 
-Then open `http://localhost:4767/` on your own. Over SSH, `isorite term` prints this command too. Any local port works (`-L 9000:localhost:4767`, then `http://localhost:9000/`).
+Run in a folder with a base in it or under it, the notes can be left out. This starts the isorite server for the notes, unless one is running on port 4767 (`--port <n>` for another), and the agent behind it. Every message passes through: the session is live in the front end and in the pane at once, asked from either. isorite's MCP is added to each session the agent opens, so the agent needs no config of its own for it.
 
-## In the browser
+### In the agent's own terminal
 
-Open the link, or type `/web` in the terminal. OpenCode runs a web page of its own as well, on another port. It asks for a password nobody was given, so isorite's `/web` opens isorite's page instead (OpenCode's pairing is `/pair`), and `isorite term` says on which port OpenCode's page is, so that you don't open it.
+Give the agent isorite's MCP in the project's config, and run it as you always do:
 
-While the terminal runs, Iso's pane header has two more switches beside *Iso may edit the notes*: *Iso may edit the project's files* (Alt+F) and *Iso may run commands* (Alt+R). With either on, the pane is the terminal's session:
+```sh
+isorite doctor ~/code/my-project/notes
+```
 
-- **The session:** each prompt (asked in the terminal, or from here), what the agent says, and a line for each thing it does. A command opens on its output, a file on its diff, a look-up in your notes on the note.
-- **Asking from here:** what you type goes to the terminal's session, with what you gave Iso (hold a note on the Atlas, or select a passage and send it to Iso): notes by name, for the agent to read with isorite's tools, and passages as they are. Escape, or the square, stops it.
-- **Permissions:** when OpenCode asks before doing something, the same question is in the pane: allow once, always allow, or don't allow. Answered in either place, it's gone from both.
-- **Notes the agent changes** are written at once, under its name. Turn on provenance in the Note pane's header to see the agent's words marked, and the timeline to put a note back.
+shows the lines it would add to the project's `.mcp.json` (Claude Code's, read by several others) and `opencode.json` (OpenCode's), and writes them on a yes; Iso's pane offers the same. They name `isorite mcp <the base's folder>`, a bridge over stdio to the server, so they hold on every machine whatever the port. Commit them with the project. Only what the agent does through isorite's tools is seen this way: a file it reads with its own tools isn't.
 
-With both off, the pane is Iso's own again. The ≡ in its header, or a click on its gauge, opens what Iso is sent: a row for each part, with its size. These are the notes you gave and the notes Iso read, the conversation's turns, and what is always sent. Iso keeps a note it read in hand, and sets it aside after three turns unused, as a line it can read again. A click switches a row on or off. At the head of the conversation, one icon sums the earlier turns up into a briefing sent instead of them, and another starts a new conversation from that briefing. Iso sums up on its own only when a turn would be more than the model takes.
+## What the agent gets
 
-## The agent's memory, and other bases
+isorite's MCP, at each base's address on the server (`http://localhost:4767/b/<name>/mcp`, on this machine only), or through `isorite mcp`:
 
-`isorite memory` makes a base for the agent's memory, lent to every session (see [setup.md](setup.md), §5). Every tool the agent has takes an optional `base`: one of the bases lent to it, named by `brief_base`. Without it, a tool acts on the base the terminal is for. A note in another base can also be named `memory:tools/opencode`. The agent is told which bases are lent, and each base's `AGENTS.md` says how it is kept; the memory's says what to keep, and how.
+- `brief_base`, the first look: the base's folders, how it is kept, how to cite a note, how to make an artifact, and the base's `AGENTS.md`.
+- `search_notes`, `find_similar` (by meaning, where the model is installed), `outline_note`, `read_note`: each look is a step on the Atlas.
+- `edit_note`, `write_note`: written at once, under the agent's name, with what was asked, its words marked as its own.
+- `ask_question`, `offer_text`: a question back, standing dotted on the Atlas until you keep it as a question note; words offered for a note, inserted as yours, or not.
+- `read_data`, `artifact_recipe`, `write_artifact`, `read_artifact`: artifacts on isorite's kit, checked and run (in a browser found on this machine) before they are written.
+- Notes as resources (`isorite://<base>/<note>`), for agents that offer `@` mentions of them.
 
-A second `isorite term`, for another project, on the same port, adds its base to the server that is running rather than starting another; a server `isorite term` started stops when the last terminal using it is done. Over MCP (`isorite mcp`) the tools are the same.
+Through `isorite acp`, isorite sees more: a Markdown file of the base the agent reads with its own tools is a step on the Atlas, as the note read, and one it changes is journalled under its name, with what was asked. The notes it read or cited stand under its reply; its links to notes are put in isorite's form however it wrote them.
 
-To watch the memory learn, open it beside the project: choose `memory` from the base's name at the left of the first pane's header (Ctrl-click for a tab of its own). What the agent reads there lights on its Atlas; what it writes appears, marked as the agent's.
+## In the browser
 
-## The models
+Iso's pane is the agent's session: each prompt (asked in its front end, or from here), what the agent says, a line for each thing it does (a command opens on its output, a file on its diff, a look-up in your notes on the note), and what it asks before doing. Answered in either place, a question is gone from both.
 
-The terminal uses Iso's provider, as `config.toml` names it ([setup.md](setup.md)): the `[tiers]` models, `mid` its default. OpenCode asks the isorite server, which passes each request on to the provider with the key, the client certificate, the headers and the query `config.toml` names. OpenCode is given none of them, only the isorite server's token.
+- **The tray:** hold a note on the Atlas, or select a passage and send it to Iso, and it goes before the next prompt, from either place, once a session.
+- **The switches:** *agents may edit the notes* (Alt+N), on unless you switch it off, is kept in the base's `.isorite/settings.toml` and enforced by the server: `edit_note`, `write_note` and `write_artifact` are refused, and through `isorite acp` so is an agent's request to edit a note's file, with no page open too. An agent whose own tools change a file without asking can't be stopped; the change is journalled under its name, to put back. *The agent may edit the project's files* (Alt+F) and *may run commands* (Alt+R) are this browser's: what it asks to do that is switched off is refused while the page is open.
+- **The drawer:** the agents' sessions, live, the agents' own (their `session/list`), and those isorite carried, kept in `.isorite/conversations/agents/`. One the agent can carry on is carried on in the pane; one whose agent isn't attached is read. Iso's own conversations, from before M25, are listed under them, to read.
+- **The Context view** (the gauge, or ≡): what the agent has in hand, as far as isorite sees: isorite's part, the notes given and read, the rest, and the room left, from what the agent says it fills.
+- **Notes the agent changes** are written at once. Turn on provenance in the Note pane's header to see its words marked, and the timeline to put a note back.
 
-`ISORITE_GATEWAY_URL`, `ISORITE_GATEWAY_MODELS` (comma-separated) and `ISORITE_GATEWAY_KEY`, when set, are used instead, and OpenCode asks that address itself. With no key and no certificate in `config.toml`, OpenCode uses its own models; `isorite term` says which.
+## How each agent differs
 
-OpenCode doesn't know a gateway's prices, so Iso's pane shows the session's tokens rather than its cost.
+Checked with Claude Agent 0.99.1, Codex 2.5.0 and Hermes 0.15.2 (M25 step 5), and OpenCode 2.2 and omp 18.14 (the spike).
 
-## OpenCode's settings
+- **Claude** (`@agentclientprotocol/claude-agent-acp`): looks through isorite's tools, and cites in isorite's form. It asks before each of isorite's tools until you answer *always*, or allow `mcp__isorite` in its settings.
+- **Codex** (`@agentclientprotocol/codex-acp`): asks to be signed in first; started from the pane, isorite signs it in with its API key (`CODEX_API_KEY` or `OPENAI_API_KEY`). A provider of your own goes in `~/.codex/config.toml`.
+- **OpenCode** (`opencode acp`) and **omp** (`omp acp`): mostly read the Markdown with their own tools, which isorite counts as reading the notes.
+- **Hermes** (`hermes acp`, not in the registry): reads with its own tools too, and is not told how to cite, so it seldom links a note.
 
-OpenCode is given the base's `AGENTS.md` (in its `instructions`), when `isorite term` is named the notes, and the knowledge base's ways through `brief_base`: how a note is written and linked, and how the base is kept.
+## The agent's memory, and other bases
 
-isorite keeps OpenCode's settings in `~/.config/isorite/opencode/`, rewritten at each start, so your own OpenCode settings are never read or changed. Anything of your own goes in `~/.config/isorite/opencode/local.json`, which is never rewritten, and is laid over what isorite writes. For example, to have OpenCode ask before every command (by default it runs them):
+`isorite memory` makes a base for the agent's memory, lent to every session (see [setup.md](setup.md)). Every tool takes an optional `base`: one of the bases lent, named by `brief_base`; a note in another base can also be named `memory:tools/opencode`. The memory's `AGENTS.md` says what to keep, and how.
 
-```json
-{ "permissions": [{ "action": "shell", "resource": "*", "effect": "ask" }] }
-```
+A second `isorite acp` or `isorite mcp`, for another project, on the same port, adds its base to the server that is running rather than starting another; a server one of them started stops when the last using it is done.
+
+To watch the memory learn, open it beside the project: choose `memory` from the base's name at the left of the first pane's header (Ctrl-click for a tab of its own).
 
-## Without the internet
+## Over SSH
 
-Once installed, isorite needs no network, as long as the model's address in `config.toml` is one you can reach (a gateway, or a model served on your own machine). What it fetches, it fetches once:
+`localhost` is the machine isorite runs on. To open it from your own, forward the port:
+
+```sh
+ssh -L 4767:localhost:4767 <the machine>
+```
 
-- isorite and OpenCode, from npm: through your company's npm mirror, if it has one.
-- The model for search by meaning (optional): `isorite model` gets it from npm too (`isorite-model-granite`), so the same mirror serves it; else from its release on GitHub, else from Hugging Face. On a machine with none of them, copy its folder from one that has it (`isorite model` there says where), or download the package from `https://github.com/lachlanjs/isorite/releases/tag/model-granite-1.0.0` and unpack it, then `isorite model --from <folder>`. Granite's files are checked against their SHA-256; any other compatible model is checked by use ([setup-for-agents.md](setup-for-agents.md) says which).
+Over SSH, `isorite serve` prints this command too.
 
 ## Who can reach it
 
-OpenCode's server listens on this machine only (127.0.0.1), and only the isorite server talks to it. The isorite server listens on this machine only too, unless you put it on your tailnet (`tailscale serve`). Then anyone on your tailnet who opens the page can ask the agent to act in your project, as they could already edit your notes. The provider is passed on to OpenCode only on this machine, never over the tailnet.
+The isorite server listens on this machine only (127.0.0.1), unless you put it on your tailnet (`tailscale serve`). Then anyone on your tailnet who opens the page can ask the attached agent to act in your project, as they could already edit your notes. MCP, `isorite acp`'s link, and choosing the pane's agent are answered on this machine only.

package/guide/AGENTS.md

@@ -0,0 +1,4 @@
+These notes are about isorite itself: the app they are read in.
+
+- Answer from them, and link the notes you used. Where they do not say, say so, and answer only what you are sure of.
+- The reader is learning isorite. Point them to the problem that practises what they ask about, rather than doing it for them.