isorite 0.8.1 → 0.10.0

package/docs/setup-for-agents.md

@@ -22,7 +22,7 @@ turn off certificate checking (`NODE_TLS_REJECT_UNAUTHORIZED=0`).
 | `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 model [--from <folder>]` | Optional: the model for search by meaning. Says which is installed and where, else fetches it (53 MB) from npm, a GitHub release, then Hugging Face, saying why each failed. `--from`: granite's files, or any compatible model (below). |
+| `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. |
 
 ## Files
@@ -54,6 +54,7 @@ name = "work"                         # optional; what isorite calls the provide
 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)
@@ -149,16 +150,18 @@ Rules:
 | `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 where it's sent, isn't accepted. | Check the key, `key_header`, and any header the gateway wants. The gateway's own message usually names it. |
+| `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]`. |
-| `! search by meaning: no model …` | Not installed (optional). | `isorite model`. Its failures name each source; offline, `isorite model --from <folder>` with a copy. |
-| `The model could not be fetched:` and a line for npm, GitHub, Hugging Face | None reachable from here. | Copy the model's folder from a machine that has it (`isorite model` there says where), then `isorite model --from <folder>`; or any compatible model. |
+| `! 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. |
-| `isorite term needs OpenCode 2` | OpenCode 1, or none. | `npm i -g @opencode/cli`, or `ISORITE_OPENCODE=…`. |
+| 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 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. |

package/docs/setup.md

@@ -5,9 +5,32 @@ run `isorite doctor`: it checks each step and says what to change.
 
 ## 1. Install
 
+Either one file, with Node inside it:
+
+- **isorite**, as one executable for Linux, macOS or Windows, checked against the release's SHA256SUMS:
+  ```sh
+  curl -fsSL https://github.com/lachlanjs/isorite/releases/latest/download/install.sh | sh
+  ```
+  It goes in `~/.local/bin` (`--dir` for another folder). Each address it fetches is printed, so a machine that
+  can't reach GitHub can fetch the same files another way, or from a mirror with `--url <the executable's address>`.
+  It unpacks itself into `~/.cache/isorite/<version>/` the first time it runs. Run the installer again to update.
+
+  On Windows, in PowerShell:
+  ```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.
+
+Or from npm:
+
 - **Node 24** or later (`node --version`).
 - **isorite**: `npm i -g isorite`.
-- For the terminal, **OpenCode 2**: `npm i -g @opencode/cli`.
+
+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.
 
@@ -58,6 +81,8 @@ Gateways inside companies often want more than a key. Each of these is optional:
 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
 
@@ -145,9 +170,11 @@ 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. Where none of those can be reached,
-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,
+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).
 

package/docs/terminal.md

@@ -10,8 +10,10 @@ Setting isorite up the first time, or at work behind a company's gateway, is in
 
 - **Node 24** or later.
 - **isorite**: `npm i -g isorite`.
-- **OpenCode 2**: `npm i -g @opencode/cli`. It installs as `opencode2` and `opencode`. If an older OpenCode is your
-  `opencode`, isorite finds `opencode2`; or name one with `ISORITE_OPENCODE=/path/to/opencode`.
+- **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.
 
@@ -58,7 +60,11 @@ works (`-L 9000:localhost:4767`, then `http://localhost:9000/`).
 
 ## In the browser
 
-Open the link. While the terminal runs, Iso's pane header has two more switches beside *Iso may edit the notes*:
+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.
+
+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:
 

package/notes/algorithms/the-quadtree/subdivision.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 260 260" width="260" height="260" font-family="sans-serif">
+  <rect x="2" y="2" width="256" height="256" fill="none" stroke="#7a8794" stroke-width="2"/>
+  <g fill="none" stroke="#7a8794" stroke-width="1.5">
+    <path d="M130 2V258M2 130H258"/>
+    <path d="M66 2V130M2 66H130"/>
+    <path d="M194 130V258M130 194H258"/>
+    <path d="M34 2V66M2 34H66"/>
+  </g>
+  <g fill="#3f7fbf">
+    <circle cx="16" cy="18" r="5"/><circle cx="50" cy="48" r="5"/><circle cx="20" cy="52" r="5"/>
+    <circle cx="98" cy="40" r="5"/><circle cx="96" cy="104" r="5"/><circle cx="200" cy="70" r="5"/>
+    <circle cx="40" cy="190" r="5"/><circle cx="160" cy="160" r="5"/><circle cx="226" cy="168" r="5"/>
+    <circle cx="170" cy="226" r="5"/>
+  </g>
+</svg>

package/notes/algorithms/the-quadtree.md

@@ -6,4 +6,6 @@ description: The plane split into squares, and each square into four, until each
 
 A tree over the bodies in 2D. The root is a square holding them all; a square with more than one body is split into four. Each node also keeps its [centre of mass](/algorithms/centre-of-mass.md "requires"). In 3D it is an octree, with eight children.
 
+![Ten bodies: the square split until each square holds at most one](the-quadtree/subdivision.svg)
+
 How is a body inserted, and what does each node keep? I don't have this straight yet.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isorite",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "An agentic harness for understanding: your notes as a knowledge base, an Atlas of them, an agent that reads them, and study.",
   "license": "MIT",
   "type": "module",

package/plugin/server.ts

@@ -45,7 +45,7 @@ export default Plugin.define({
       await ctx.session.hook("context", (request) => {
         request.system.push({
           type: "text",
-          text: `The person's knowledge base is the folder ${notes}: notes in Markdown with YAML frontmatter, linked to each other. Look things up in it with brief_base, search_notes, outline_note and read_note rather than reading its files. Never edit or write its files directly: change a note with edit_note or write_note, which write it at once and mark your words as yours for the person to see. Your edits to code and other files are yours to make as usual. In a note, and in what you say, a fenced block in the language mermaid is drawn as a diagram in isorite, and code fenced with its language is coloured: draw a diagram where it helps or when asked.${lent}\n\n${CITING}`,
+          text: `The person's knowledge base is the folder ${notes}: notes in Markdown with YAML frontmatter, linked to each other. Look things up in it with brief_base, search_notes, outline_note and read_note rather than reading its files. Never edit or write its files directly: change a note with edit_note or write_note, which write it at once and mark your words as yours for the person to see. Your edits to code and other files are yours to make as usual. In a note, and in what you say, a fenced block in the language mermaid is drawn as a diagram in isorite, and code fenced with its language is coloured: draw a diagram where it helps or when asked. A picture in a note is ![what it shows](path), drawn in isorite: you have only its words, so keep its line when you edit around it.${lent}\n\n${CITING}`,
         });
       });
       // A write or an edit to a note anyway is made the same change through isorite, so it is entered and marked.

package/plugin/tui.tsx

@@ -446,6 +446,12 @@ export default Plugin.define({
               if (words && !id) { ctx.ui.toast?.show?.({ message: `no note matches “${words}”`, variant: "warning" }); return; }
               openAtlas(id ?? "");
             },
+          }, {
+            // OpenCode's own /web pairs a browser with its page, by a link that works once; opened again, that page asks
+            // for a password nobody was given (M21). isorite's /web, listed before it, opens isorite's page; OpenCode's
+            // pairing is still /pair.
+            id: "isorite.web", title: "isorite in the browser (OpenCode's pairing: /pair)", palette: true, slash: { name: "web" },
+            run: () => openInBrowser(Isorite.url + "/"),
           }, {
             id: "isorite.note.open", title: "Open a note of the knowledge base", palette: true, slash: { name: "note", arguments: true },
             run: async (input) => {