isorite 0.3.1 → 0.6.0

package/docs/setup-for-agents.md

@@ -19,7 +19,7 @@ turn off certificate checking (`NODE_TLS_REJECT_UNAUTHORIZED=0`).
 | `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 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 help setup` | Prints this. |
 
@@ -30,6 +30,7 @@ turn off certificate checking (`NODE_TLS_REJECT_UNAUTHORIZED=0`).
 | `~/.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>/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. |
 | `~/.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. |
@@ -40,11 +41,15 @@ isorite never reads or changes the person's own OpenCode settings (`~/.config/op
 
 ## 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 the browser (behind the logo)
+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
 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

package/docs/setup.md

@@ -9,23 +9,37 @@ run `isorite doctor`: it checks each step and says what to change.
 - **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.
+`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, and set the key behind the logo (or sign in there with
-OpenRouter, which makes one). Nothing else is needed.
+**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 named under `[provider]`, with its models under `[tiers]`:
+**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 behind the logo in the browser
+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
@@ -88,6 +102,10 @@ 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`.
 
+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.
+
 It prints a link to click: `http://localhost:4767/`. isorite keeps what it needs in the folder's `.isorite/`.
 
 ## 4. The terminal

package/docs/terminal.md

@@ -72,7 +72,12 @@ terminal's session:
 - **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.
+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.
 
 ## The models
 
@@ -89,6 +94,9 @@ OpenCode doesn't know a gateway's prices, so Iso's pane shows the session's toke
 
 ## OpenCode's settings
 
+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.
+
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "isorite",
-  "version": "0.3.1",
+  "version": "0.6.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/tui.tsx

@@ -5,7 +5,7 @@
 import { spawn } from "node:child_process";
 import { BoxRenderable, fg, ImageRenderable, RGBA, StyledText, TextAttributes, TextRenderable, type Renderable, type TextChunk } from "@opentui/core";
 import { Plugin } from "@opencode/plugin/tui";
-import { createEffect, createResource, createSignal, For, onCleanup, Show, untrack } from "solid-js";
+import { createEffect, createResource, createSignal, For, onCleanup, Show } from "solid-js";
 import type { ScrollBoxRenderable } from "@opentui/core";
 import { ago, anchorOf, blocks, describe, momentKey, moments, reach, type Entry, type MapModel } from "../dist/core.js";
 import { drawAtlas, runsOf, type Role } from "./oneatlas.ts";
@@ -15,7 +15,6 @@ import * as Isorite from "./isorite.ts";
 import * as Logo from "./logo.ts";
 import { lapis, quartz, routeColours } from "./palette.ts";
 import { Play, type Step } from "./play.ts";
-import { TOUR, type TourState } from "./tour.ts";
 import { parseSources } from "./sources.ts";
 import * as Wordmark from "./wordmark.ts";
 
@@ -265,9 +264,6 @@ export default Plugin.define({
         </text>
       ),
     });
-    // What the tour (isorite --tutorial) waits on that nothing else counts: the agent's turns ended, Iso's answers,
-    // and notes sent from here.
-    const [turns, setTurns] = createSignal(0), [isoAnswers, setIsoAnswers] = createSignal(0), [sent, setSent] = createSignal(0);
 
     /** [s]: a note, or a passage of it, sent to the agent from the terminal, as from the browser: under "from you". */
     const sendToAgent = async (note: string, passage?: string) => {
@@ -275,7 +271,7 @@ export default Plugin.define({
       const said = await ctx.ui.dialog.prompt({ title: "Send to the agent", description: passage ? "the passage the cursor is on" : `the note “${(titles().get(note) ?? note).toLowerCase()}”`, placeholder: "what you want of it (optional)" });
       if (said === undefined) return;
       await Isorite.post("/api/agent/send", { note, ...(passage ? { passage } : {}), said: said.trim() })
-        .then(() => setSent((n) => n + 1), (e: Error) => ctx.ui.toast?.show?.({ message: e.message, variant: "error" }));
+        .catch((e: Error) => ctx.ui.toast?.show?.({ message: e.message, variant: "error" }));
     };
 
     const stop = new AbortController();
@@ -293,8 +289,7 @@ export default Plugin.define({
         if (sessionID) void deliver(sessionID);
         return;
       }
-      if (type === "agent-done" && typeof data.session === "string") { reading.delete(data.session); hear((n) => n + 1); setTurns((n) => n + 1); }
-      if (type === "iso-done") setIsoAnswers((n) => n + 1);
+      if (type === "agent-done" && typeof data.session === "string") { reading.delete(data.session); hear((n) => n + 1); }
       if (type === "note-changed") bumpMap((n) => n + 1);
       if (type !== "agent-step" || data.agent !== Isorite.AGENT || typeof data.session !== "string") return;
       const play = plays.get(data.session) ?? new Play();
@@ -324,75 +319,6 @@ export default Plugin.define({
       return new TextRenderable(ctx.renderer, { content: new StyledText(chunks) });
     });
 
-    // ------------------------------------------------------------ the tour (isorite --tutorial)
-    const TUTORIAL = process.env.ISORITE_TUTORIAL === "1";
-    const [stepAt, setStepAt] = createSignal(TUTORIAL ? 0 : TOUR.length);
-    const [cardShown, setCardShown] = createSignal(true);
-    const tourState = (): TourState => {
-      heard();
-      const route = ctx.ui.router.current(), shown = note();
-      return {
-        page: route.type === "plugin" ? (route.name === SPLASH ? "splash" : route.name === NOTE ? "note" : route.name) : route.type,
-        turns: turns(),
-        inPlay: route.type === "session" ? plays.get(route.sessionID)?.size ?? 0 : 0,
-        atlasOpen: ctx.ui.panel.current()?.name === ATLAS,
-        note: shownNote(),
-        // Not known until the note is read: no step moves on for a note still opening.
-        waiting: shown && shown.id === shownNote() ? shown.items.filter((i) => i.type === "change").length : -1,
-        past: moment() !== null,
-        isoAnswers: isoAnswers(),
-        sent: sent(),
-      };
-    };
-    /** Puts the step's prompt in the prompt being typed in, once it has focus and while it is empty. */
-    const fillPrompt = (text: string) => {
-      let tries = 0;
-      const timer = setInterval(() => {
-        const editor = ctx.renderer.currentFocusedEditor;
-        if (editor && !editor.plainText.trim()) editor.insertText(text);
-        if (editor || ++tries > 50) clearInterval(timer);
-      }, 100);
-    };
-    ctx.ui.slot({
-      append: "app",
-      render() {
-        if (!TUTORIAL) return null;
-        // A step moves on when what it waits for holds, judged against what held when it began.
-        let at = -1, began = untrack(tourState);
-        createEffect(() => {
-          const i = stepAt(), now = tourState(), step = TOUR[i];
-          if (i !== at) { at = i; began = now; if (step?.fill) fillPrompt(step.fill); return; }
-          if (step?.until?.(now, began)) setStepAt(i + 1);
-        });
-        ctx.keymap.layer(() => ({
-          mode: "global",
-          commands: [
-            { id: "isorite.tour.next", title: "Tour: the next step", palette: true, slash: { name: "next" }, run: () => { setStepAt((i) => Math.min(i + 1, TOUR.length)); } },
-            { id: "isorite.tour.card", title: "Tour: hide or show the card", palette: true, slash: { name: "tour" }, run: () => { setCardShown((v) => !v); } },
-          ],
-        }));
-        return (
-          <Show when={cardShown() && TOUR[stepAt()]}>
-            {(step) => (
-              <box position="absolute" right={2} bottom={4} width={48} zIndex={3000} flexDirection="column" paddingLeft={1} paddingRight={1}
-                border borderStyle="rounded" borderColor={ground().growth} backgroundColor={ground().g0} title={` tour · ${stepAt() + 1} of ${TOUR.length} `}>
-                <text fg={ground().text} wrapMode="word"><b>{step().title}</b></text>
-                <text fg={ground().soft} wrapMode="word">{step().text}</text>
-                <text> </text>
-                <box flexDirection="row">
-                  <text wrapMode="none">
-                    <For each={TOUR}>{(_, k) => <span style={{ fg: k() <= stepAt() ? ground().growth : ground().line }}>{k() <= stepAt() ? "■" : "□"}</span>}</For>
-                  </text>
-                  <box flexGrow={1} />
-                  <text fg={ground().faint} wrapMode="none">{step().until ? "/tour hides" : "/next   /tour hides"}</text>
-                </box>
-              </box>
-            )}
-          </Show>
-        );
-      },
-    });
-
     ctx.ui.slot({
       append: "sidebar.content",
       render: (input) => {