isorite 0.2.0 → 0.3.1

package/docs/setup-for-agents.md

@@ -0,0 +1,166 @@
+# 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.
+
+**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`).
+
+## Commands
+
+| 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 --tutorial` | A tour on an example base with a scripted model: no key or network needed. Good to check the install alone. |
+| `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 help setup` | Prints this. |
+
+## 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/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>/.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. |
+| `~/.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
+
+```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 the browser (behind the logo)
+key_header = "api-key"                # send the key in this header, as it is, instead of Authorization: Bearer
+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.
+
+## 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. |
+| `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_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. |
+| `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. |
+
+## 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.
+
+## What working looks like
+
+`isorite doctor` 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
+✓ 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, …
+```
+
+`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 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 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. |
+| `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 term needs OpenCode 2` | OpenCode 1, or none. | `npm i -g @opencode/cli`, or `ISORITE_OPENCODE=…`. |
+| `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. |
+
+## 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

@@ -0,0 +1,133 @@
+# 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.
+
+## 1. Install
+
+- **Node 24** or later (`node --version`).
+- **isorite**: `npm i -g isorite`.
+- For the terminal, **OpenCode 2**: `npm i -g @opencode/cli`.
+
+`isorite --tutorial` now shows you around, on an example base, with a scripted model: 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, and set the key behind the logo (or sign in there with
+OpenRouter, which makes one). Nothing else is needed.
+
+**Any other provider or gateway** is named under `[provider]`, with its 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 behind the logo 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
+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.
+
+### 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`.
+
+## 3. Your notes
+
+A folder of Markdown files. To start from nothing:
+
+```sh
+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`.
+
+It prints a link to click: `http://localhost:4767/`. isorite keeps what it needs in the folder's `.isorite/`.
+
+## 4. The terminal
+
+```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).
+
+## Search by meaning (optional)
+
+```sh
+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,
+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.
+
+`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.

package/docs/terminal.md

@@ -0,0 +1,119 @@
+# isorite beside your code: the terminal
+
+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.
+
+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**: `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`.
+- A model provider, set once in `~/.config/isorite/config.toml`: see [setup.md](setup.md). `isorite doctor` checks
+  all of this.
+
+## 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
+
+```sh
+cd ~/code/my-project
+isorite term ~/notes/my-project
+```
+
+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.
+
+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
+```
+
+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.
+
+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.
+
+### Over SSH
+
+`localhost` is the machine `isorite term` runs on. To open isorite from your own machine, forward the port:
+
+```sh
+ssh -L 4767:localhost:4767 <the machine>
+```
+
+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/`).
+
+## In the browser
+
+Open the link. 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:
+
+- **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.
+
+With both off, the pane is Iso's own again.
+
+## The models
+
+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.
+
+`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.
+
+OpenCode doesn't know a gateway's prices, so Iso's pane shows the session's tokens rather than its cost.
+
+## OpenCode's settings
+
+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):
+
+```json
+{ "permissions": [{ "action": "shell", "resource": "*", "effect": "ask" }] }
+```
+
+## Without the internet
+
+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:
+
+- 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).
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isorite",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "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",
@@ -28,6 +28,7 @@
     "web",
     "notes",
     "plugin",
+    "docs",
     "README.md",
     "LICENSE"
   ],

package/plugin/isorite.ts

@@ -35,10 +35,10 @@ export async function post<T>(path: string, body: unknown): Promise<T> {
 /** A tool the server offers an agent, as OpenAI's API describes one. */
 export interface ToolDef { type: "function"; function: { name: string; description: string; parameters: Record<string, unknown> } }
 
-/** What the splash says of the base: its name, how many notes, whether it has a study base. */
-export async function base(): Promise<{ name: string; notes: number; study: boolean }> {
+/** What the splash says of the base: its name and how many notes. */
+export async function base(): Promise<{ name: string; notes: number }> {
   const [session, listing] = await Promise.all([get<Session>("/api/session"), get<Listing>("/api/notes")]);
-  return { name: session.name, notes: listing.notes.length, study: session.study };
+  return { name: session.name, notes: listing.notes.length };
 }
 
 /** The server's events, as the browser hears them, until the signal aborts; heard again after a dropped stream. */

package/plugin/notepage.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource @opentui/solid */
 // A note in the terminal (`Terminal-Note`): its blocks behind a gutter of who wrote them, links underlined, maths as
 // source, code on its own ground, a figure offered in the browser; the changes waiting to be kept between dotted
-// rules, one of them current, with its keys; the step and squares at the top right.
+// rules, one of them current, with its keys.
 
 import { TextAttributes, type ScrollBoxRenderable } from "@opentui/core";
 import type { Entry } from "../dist/core.js";
@@ -20,12 +20,8 @@ export interface NoteData {
   /** At a moment of the timeline: what it was, and how long ago. Read only. */
   at?: { said: string; ago: string };
   entries: Entry[];
-  /** What the study record says of it: 0 not reached … 3 understood, and its squares of 6. */
-  step: number;
-  squares: number;
 }
 
-export const STEPS = ["not reached", "opened", "worked through", "understood"];
 const DOTS = "· ".repeat(38).trim();
 /** The widest a note's column is: its gutter, rail and about 76 characters of text. */
 const MEASURE = 84;
@@ -112,10 +108,6 @@ export function NotePage(props: { note: Accessor<NoteData | undefined>; current:
               <text fg={g().text} wrapMode="none" flexShrink={1} minWidth={0}>{pathOf(note().id, note().title)}</text>
               <Show when={note().at}>{(at) => <text fg={g().growth} wrapMode="none" flexShrink={1} minWidth={0}>{`   as it was ${at().ago}: ${at().said}`}</text>}</Show>
               <box flexGrow={1} />
-              <text fg={g().soft} wrapMode="none" flexShrink={0}>{`${STEPS[note().step] ?? ""}   `}</text>
-              <text wrapMode="none" flexShrink={0}>
-                <For each={[0, 1, 2, 3, 4, 5]}>{(k) => <span style={{ fg: k < note().squares ? g().mal : g().line }}>{k < note().squares ? "■" : "□"}</span>}</For>
-              </text>
             </box>
             <scrollbox ref={props.scroll} flexGrow={1} paddingLeft={4} paddingRight={4} paddingTop={1} scrollbarOptions={{ visible: false }}>
               {/* As the board: the text in a column of reading width, not the terminal's. */}

package/plugin/tui.tsx

@@ -7,7 +7,7 @@ import { BoxRenderable, fg, ImageRenderable, RGBA, StyledText, TextAttributes, T
 import { Plugin } from "@opencode/plugin/tui";
 import { createEffect, createResource, createSignal, For, onCleanup, Show, untrack } from "solid-js";
 import type { ScrollBoxRenderable } from "@opentui/core";
-import { ago, anchorOf, blocks, describe, isStudyId, momentKey, moments, reach, type Entry, type MapModel } from "../dist/core.js";
+import { ago, anchorOf, blocks, describe, momentKey, moments, reach, type Entry, type MapModel } from "../dist/core.js";
 import { drawAtlas, runsOf, type Role } from "./oneatlas.ts";
 import { noteView, type ViewChange } from "./noteview.ts";
 import { NotePage, fromWhom, type NoteData } from "./notepage.tsx";
@@ -107,12 +107,9 @@ export default Plugin.define({
     };
     const loadNote = async (id: string, at: { key: string; said: string; ago: string } | null): Promise<NoteData> => {
       const q = `?id=${encodeURIComponent(id)}`;
-      const [note, entries, study] = await Promise.all([
-        Isorite.get<{ text: string }>(`/api/note${q}`), Isorite.get<Entry[]>(`/api/journal${q}`),
-        Isorite.get<{ notes: Record<string, { step: number; squares: number }> }>("/api/study").catch(() => null),
-      ]);
-      const reading = study?.notes[id], title = titles().get(id) ?? id.split("/").at(-1)!;
-      const common = { id, title, entries, step: reading?.step ?? 0, squares: reading?.squares ?? 0 };
+      const [note, entries] = await Promise.all([Isorite.get<{ text: string }>(`/api/note${q}`), Isorite.get<Entry[]>(`/api/journal${q}`)]);
+      const title = titles().get(id) ?? id.split("/").at(-1)!;
+      const common = { id, title, entries };
       if (!at) return { ...common, text: note.text, items: noteView(note.text, entries) };
       // At a moment of the timeline: the note as it was then, read only, its changes then waiting left out.
       const then = await Isorite.get<{ text: string }>(`/api/version${q}&entry=${encodeURIComponent(at.key)}`);
@@ -198,7 +195,7 @@ export default Plugin.define({
           const model = map(), id = focal();
           if (!model || !id) return null;
           const r = reach(model, id), direct = r.requires.filter((n) => r.depth[n] === 1);
-          return { direct, further: r.requires.length - direct.length, builds: r.builds.filter((n) => !isStudyId(n)) };
+          return { direct, further: r.requires.length - direct.length, builds: r.builds };
         };
         const grid = () => {
           const n = near(), id = focal();
@@ -449,7 +446,7 @@ export default Plugin.define({
           const b = base();
           if (!b) return " ";
           if ("error" in b) return `isorite is not answering at ${Isorite.url}`;
-          return `${b.name} · ${b.notes} ${b.notes === 1 ? "note" : "notes"} · ${b.study ? "study base found" : "no study base"}`;
+          return `${b.name} · ${b.notes} ${b.notes === 1 ? "note" : "notes"}`;
         };
         return (
           <box flexDirection="column" alignItems="center" justifyContent="center" width="100%" height="100%">
@@ -517,7 +514,9 @@ export default Plugin.define({
             id: "isorite.atlas.show", title: "One note's atlas, beside the chat", palette: true, slash: { name: "atlas", arguments: true },
             run: async (input) => {
               const words = input?.trim();
-              const id = words ? (await Isorite.get<{ id: string }[]>(`/api/search?q=${encodeURIComponent(words)}`).catch(() => []))[0]?.id : "";
+              // A note titled with exactly these words comes before the search's first hit, which may only mention them.
+              const hits = words ? await Isorite.get<{ id: string; title: string }[]>(`/api/search?q=${encodeURIComponent(words)}`).catch(() => []) : [];
+              const id = words ? (hits.find((h) => h.title.toLowerCase() === words.toLowerCase()) ?? hits[0])?.id : "";
               if (words && !id) { ctx.ui.toast?.show?.({ message: `no note matches “${words}”`, variant: "warning" }); return; }
               openAtlas(id ?? "");
             },