isorite 0.12.1 → 0.14.0

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.

package/guide/atlas/find-what-it-rests-on.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Find what it rests on
+uses: [atlas/the-atlas]
+---
+
+From the Atlas only, without following a link in a note, find what [what the agent has in hand](/iso/in-hand.md) requires, and open it.
+
+Then switch on Iso's context on the Atlas (Alt+C), and switch it off again.

package/guide/atlas/the-atlas.md

@@ -0,0 +1,21 @@
+---
+type: Concept
+title: The Atlas
+description: The map of the base, drawn from what rests on what.
+---
+
+The Atlas is the base as a map. Each note is a block, each folder a frame, and each [link](/notes/links-and-their-kinds.md "requires") a line. Notes are placed so that what a note requires stands before it, along its folder's way, and the lines between folders run as trunks along the gaps.
+
+- **Click a note** to choose it: it lights with its links, the notes it rests on and the notes that rest on it, and the rest dims. **Click it again** to open it in the Note pane. Click one it rests on to step back to it, the way kept lit; click open ground to let go.
+- **Click a folder** to bring it to the screen, and again to step out to the folder it is in. Folders open as you zoom in on them and close to one block as you zoom out: see [folders](/notes/folders.md "see also").
+- **Shift+click a note**, or hold on it, to give it to [Iso](/iso/iso.md "see also"). On a phone, a long press offers it.
+- **Hold on open ground** to make a note there.
+- Drag the ground to move about, and pinch or scroll to zoom.
+
+The note open in the Note pane has a bar inside its left edge. When it is off the screen, a pip at the Atlas's edge points to it: click the pip to bring it into view. A link under the mouse, in a note or in the agent's answer, is outlined on the map with its line lit, and a note under the mouse on the map marks the open note's links to it.
+
+The layout changes as the base does, but starts from where it was, so the map you know moves as little as it can.
+
+Open [questions](/questions-and-problems/questions.md "see also") and [problems](/questions-and-problems/problems.md "see also") are on the map too, each beside the notes it is about, and a solved problem shows it.
+
+What it shows besides is chosen by [the switches](/atlas/the-switches.md "see also").

package/guide/atlas/the-switches/satellites.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 360 132" width="360" height="132" font-family="ui-monospace, Menlo, monospace" font-size="11">
+  <rect x="0.5" y="0.5" width="359" height="131" fill="#f1efe9" stroke="#b9b4a8"/>
+  <text x="14" y="20" fill="#6d6a63">combat</text>
+  <rect x="14" y="30" width="150" height="64" fill="#f7f6f2" stroke="#7a7770"/>
+  <text x="24" y="50" fill="#2b2a27" font-family="Georgia, serif" font-size="13">Hitboxes</text>
+  <g fill="#f7f6f2" stroke="#9d998f">
+    <rect x="176" y="30" width="26" height="26"/><rect x="210" y="30" width="26" height="26"/><rect x="244" y="30" width="26" height="26"/><rect x="278" y="30" width="26" height="26"/>
+  </g>
+  <g fill="none" stroke="#3a6fb0" stroke-width="1.3" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="189" cy="43" r="7"/><path d="M182 43h14M189 36c-2.6 3.6-2.6 10.4 0 14M189 36c2.6 3.6 2.6 10.4 0 14"/>
+    <path d="M220 38.5l-4.5 4.5 4.5 4.5M226 38.5l4.5 4.5-4.5 4.5M224.5 37l-3 12"/>
+  </g>
+  <rect x="245" y="31" width="24" height="24" fill="#c9824f"/><path d="M245 50l7-7 5 5 4-4 8 8v3h-24z" fill="#5d7f4a"/><circle cx="262" cy="37" r="2.5" fill="#f3e3b5"/>
+  <rect x="279" y="31" width="24" height="24" fill="#8fb3d9"/><path d="M283 52l6-14 6 14z M292 52l5-9 5 9z" fill="#48678f"/>
+  <text x="176" y="74" fill="#6d6a63">web code pictures</text>
+  <text x="14" y="116" fill="#6d6a63">its links out, and the pictures it shows, beside it</text>
+</svg>

package/guide/atlas/the-switches.md

@@ -0,0 +1,27 @@
+---
+type: Concept
+title: The switches
+description: Each pane's header switches choose what it shows, and what an attached agent may do.
+---
+
+Each pane's header has a row of small icons. Each is a switch: it says what it is when you hover on it, and when on it takes its colour, with a bar under it. Each has a key.
+
+**The note:**
+- Provenance, whose words are whose (Alt+P).
+- The timeline (Alt+T). Both are in [every change is kept](/notes/every-change-is-kept.md "uses").
+
+**The Atlas:**
+- Open questions (Alt+Q) and problems (Alt+B), on the map.
+- Links to the web (Alt+W) and to code (Alt+K): see [links out of the base](/out-of-the-base/web-and-code-links.md "see also").
+- Files beside the notes (Alt+I): pictures, [artifacts](/iso/artifacts.md "see also"), data and documents, each in its folder with its kind's mark, joined to the notes that cite them. A note's pasted pictures are one item.
+- Iso's context (Alt+C): what the agent's session was given, what it read and what it changed, marked on the map.
+
+**Iso:**
+- May agents edit the notes (Alt+N). On unless you switch it off, and kept with the base rather than in the browser, so it holds for an agent in its own terminal too: its tools for writing notes and artifacts are refused, and so is asking to edit a note's file. An agent whose own tools change a file without asking can't be stopped; the change is still kept, under its name, to put back.
+- With an agent attached, may it edit the project's files (Alt+F) and run commands (Alt+R): what it asks to do that is switched off is refused. See [your own agent](/terminal/your-own-agent.md "see also").
+
+![A note on the Atlas with a link to the web, one to code and two pictures beside it](the-switches/satellites.svg)
+
+At the right of each header, its settings: for the note, the layout of the panes and which are shown.
+
+The switches show; they never change the notes. [The Atlas](/atlas/the-atlas.md "requires") is where most of them show.

package/guide/iso/agents-md.md

@@ -0,0 +1,13 @@
+---
+type: Concept
+title: AGENTS.md
+description: Your base's instructions, for every agent you attach.
+---
+
+A file named `AGENTS.md` at the top of the base holds what any agent should know about working in it: your notation, the level you write at, the language, how you name notes. It is a file and not a note: it is not on the Atlas.
+
+Every agent you attach is given it, with isorite's brief of the base, the first thing it reads. The name is the one other agents use.
+
+Edit it in Iso's settings. An agent may offer lines for it, when it notices a way of working worth keeping; you choose whether to take them.
+
+This guide has one: it asks the agent to answer from the guide and to point you to the problems.

package/guide/iso/artifacts/the-guide.csv

@@ -0,0 +1,8 @@
+folder,notes,questions_and_problems
+atlas,3,0
+iso,10,0
+notes,10,0
+out-of-the-base,1,0
+questions-and-problems,6,3
+terminal,4,0
+your-own-base,2,0

package/guide/iso/artifacts/the-guide.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>The guide in numbers</title>
+<meta name="description" content="How many notes each of the guide's folders holds: an artifact on the kit, from one data file, in markup only.">
+<meta name="author" content="Iso">
+<meta name="date" content="2026-10-28">
+<meta name="isorite:kit" content="1">
+<meta name="isorite:uses" content="the-guide.csv">
+</head>
+<body>
+<iso-page>
+  <header>
+    <h1>The guide in numbers</h1>
+    <p>Where the guide spends its notes.</p>
+  </header>
+  <iso-grid>
+    <iso-panel class="wide">
+      <h2>In all</h2>
+      <iso-stats>
+        <iso-stat data="the-guide.csv" column="notes" of="sum" label="notes" tone="blue"></iso-stat>
+        <iso-stat data="the-guide.csv" column="folder" of="count" label="folders"></iso-stat>
+        <iso-stat data="the-guide.csv" column="notes" of="max" label="the most in one folder" tone="gold"></iso-stat>
+      </iso-stats>
+    </iso-panel>
+    <iso-panel class="wide">
+      <h2>Notes by folder</h2>
+      <iso-chart data="the-guide.csv" type="bar" x="folder" y="notes" y-label="notes" height="220"></iso-chart>
+      <p>The notes and Iso take the most explaining; the base itself, the least.</p>
+    </iso-panel>
+  </iso-grid>
+</iso-page>
+</body>
+</html>

package/guide/iso/artifacts.md

@@ -0,0 +1,15 @@
+---
+type: Concept
+title: Artifacts
+description: A page beside your notes that works, such as a dashboard of your data or a simulation.
+---
+
+An artifact is an HTML file beside your notes that isorite shows working: a dashboard of a data file, two runs compared, a simulation you can play, an explanation you can change and watch, a 3D model you can turn. It is a file like any other in the base, on the Atlas with the [files beside the notes](/atlas/the-switches.md "see also"), and opened in the Note pane.
+
+Shown in a note, with the picture's syntax, it works in place:
+
+![The guide in numbers](/iso/artifacts/the-guide.html)
+
+Ask your agent in [Iso](/iso/iso.md "uses")'s pane for one: "a dashboard of runs.csv", "a simulation of this note's model". It builds it with isorite's tools, on isorite's kit, which gives it its look, so it reads as the rest of isorite does, and the plain look is a press away. It reaches nothing outside itself: no network, only the data files it names. And "standalone" saves it as one file, with its data inside, that opens anywhere.
+
+Its artifacts are checked and run before they are written, and [marked](/iso/iso-writes-marked.md "see also") and put back as its notes are: [every change is kept](/notes/every-change-is-kept.md "see also").

package/guide/iso/ask-iso.md

@@ -0,0 +1,7 @@
+---
+type: Problem
+title: Ask in Iso's pane
+uses: [iso/iso]
+---
+
+Ask in Iso's pane what a problem note is for. Open a note it links in its answer, and find the notes it drew on under its reply.

package/guide/iso/give-it-notes.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Give it notes
+uses: [iso/in-hand]
+---
+
+Give the agent a note from the Atlas (shift+click it, or hold on it, or drag it to Iso's pane), and a passage from a note (select it, and send it to Iso). Open the Context view and find both in the tray, and take one out.
+
+Then ask something about the other.

package/guide/iso/in-hand.md

@@ -0,0 +1,18 @@
+---
+type: Concept
+title: What the agent has in hand
+description: The Context view, as far as isorite can see into the agent's session.
+---
+
+The gauge in Iso's header shows how full the agent's context is, as the agent says. Click it for the Context view: a column in layers, as wide as each part's share of what the model takes.
+
+- **isorite's**: its instructions and its tools, as isorite gives them to every session.
+- **Notes**: those you gave the session, and those it read, listed under the column.
+- **The rest**: the harness's own instructions and the conversation.
+- **Room**: what is left.
+
+Below it is the tray: what goes before the next prompt, asked here or in the agent's front end. Take a part out with ✕.
+
+What the agent dropped when it compacted its conversation can't be seen from here, and the view says so. It needs [Iso](/iso/iso.md "requires")'s pane to be showing a session.
+
+On the Atlas, the context switch (Alt+C) marks what the session gave, read and changed.

package/guide/iso/iso-writes-marked.md

@@ -0,0 +1,15 @@
+---
+type: Concept
+title: The agent writes, marked
+description: An agent's changes are made, marked as its own, with what you asked, and put back from the timeline.
+---
+
+An agent attached to your base changes your notes when you ask it to, without asking you to accept each change first, whether it writes through isorite's tools or edits the file with its own. It is safe because [every change is kept](/notes/every-change-is-kept.md "requires"):
+
+- Each change is entered in the note's history under the agent's name, with what you had asked it.
+- Its words are marked as its own, with provenance on (Alt+P), until you edit them.
+- The note's timeline puts back any version: a change undone is a change of its own.
+
+An agent can also offer words rather than write them: "insert" puts them in the note as your own, since you chose them. And it can ask a question back, which you keep as a question note, or not.
+
+isorite asks it not to put words in your notes you did not ask for, and to suggest splitting or merging notes rather than doing it.

package/guide/iso/iso.md

@@ -0,0 +1,17 @@
+---
+type: Concept
+title: Iso
+description: The pane where your own agent works in your base, and the way of working isorite asks of it.
+---
+
+isorite does not bring an agent of its own: it attaches to the one you already use (Claude, Codex, OpenCode, omp, Hermes, or any that speaks ACP). Iso is the pane where that agent's session shows, beside your notes and the Atlas, and the way of working isorite asks of it: cite the notes in the sentence, ask a question back rather than supply what you don't know, offer your own words rather than write over them.
+
+The agent has your knowledge base as tools: it searches the notes, reads them, follows their links, and answers from them, with links to the notes it used. What it reads lights on the Atlas, and once a turn is over, the notes it drew on stand under its reply. How to attach one is in [your own agent](/terminal/your-own-agent.md "uses").
+
+Ask in the box at the foot of the pane, or in the agent's own front end: the session is the same. Notes you give it go in [the tray](/iso/give-it-notes.md "see also"), before your next prompt. What it has in hand is in [the Context view](/iso/in-hand.md "see also").
+
+It may change your notes through isorite, and [its words are marked](/iso/iso-writes-marked.md "see also"). It can build [artifacts](/iso/artifacts.md "see also"): pages that work, from your data. How it should work in your base is [AGENTS.md](/iso/agents-md.md "see also"). What it may do in the project around the base (edit its files, run commands) is set by the pane's [switches](/atlas/the-switches.md "uses").
+
+isorite asks it to help you understand rather than understand for you: to read [where you stand](/questions-and-problems/how-iso-reads-you.md "see also") from your notes, to check a [problem](/questions-and-problems/problems.md "see also")'s solution rather than solve it, and to keep your notes in your words.
+
+On the guide's own site no agent can be attached, and the guide's finder stands in for one, and says so: it answers with the notes that match what you ask.

package/guide/iso/let-it-write.md

@@ -0,0 +1,11 @@
+---
+type: Problem
+title: Let it write
+uses: [iso/iso-writes-marked]
+---
+
+With your own agent attached, give it [your notes](/your-notes.md) and ask it to add a link to a guide note that suits them.
+
+See its words marked in your notes, with provenance on. Then put the note back as it was, from its timeline.
+
+This needs isorite of your own, not the guide's site: see [starting a base](/your-own-base/starting-a-base.md).

package/guide/iso/write-agents-md.md

@@ -0,0 +1,11 @@
+---
+type: Problem
+title: Write an AGENTS.md
+uses: [iso/agents-md]
+---
+
+In a base of your own, write an AGENTS.md of three lines or so: your notation, your level, and one thing you want the agent to do or not do.
+
+Then ask your agent something, and see whether it follows it.
+
+This needs isorite of your own, not the guide's site: see [starting a base](/your-own-base/starting-a-base.md).

package/guide/notes/a-note-is-markdown.md

@@ -0,0 +1,17 @@
+---
+type: Concept
+title: A note is Markdown
+description: A note is a Markdown file, written as you read it.
+---
+
+Every note is a Markdown file in the base's folder, and the folder is the base: you can open it in any editor, keep it in git, or copy it away. isorite keeps its own records beside the notes, in `.isorite/`.
+
+The Note pane shows Markdown as it reads, and shows its marks only on the line you are writing in:
+
+- `**bold**` and `*italic*`, `# headings`, lists and `> quotes`.
+- Maths between dollars, `$E = mc^2$` in a line or `$$…$$` on its own, as $\int_0^1 x\,dx = \tfrac12$.
+- Code in backticks, and in fenced blocks, coloured by its language; and [diagrams](/notes/diagrams-and-code.md "see also") written in Mermaid.
+
+There is nothing to save: what you type is kept as you type it, and [every change is kept](/notes/every-change-is-kept.md "see also").
+
+Notes are joined by [links](/notes/links-and-their-kinds.md "see also"), and say what they are in [their details](/notes/a-notes-details.md "see also").

package/guide/notes/a-notes-details.md

@@ -0,0 +1,23 @@
+---
+type: Concept
+title: A note's details
+description: A note's type, title, description and tags, at its top.
+---
+
+A note starts with its details, between two lines of `---`:
+
+```markdown
+---
+type: Concept
+title: Leapfrog
+description: A step that keeps energy bounded.
+tags: [integrators]
+---
+```
+
+- **type** is what the note is: a `Concept`, the usual; a `Question` (see [questions](/questions-and-problems/questions.md "see also")); or a `Problem` (see [problems](/questions-and-problems/problems.md "see also")).
+- **title** is its name, on the Atlas and in links. The file's name is apart from it.
+- **description** says the idea in a line. An agent reads it first, when it looks through the base, so a good one helps it find the note.
+- **tags**, if you want them.
+
+The Note pane shows them in its label, under the title, and changes them there: the description is the italic line, the kind is one of three, the tags are in brackets, and pressing the folder or the name moves or renames the file. Deleting a note is in the Note pane's menu.

package/guide/notes/diagrams-and-code.md

@@ -0,0 +1,43 @@
+---
+type: Concept
+title: Diagrams and code
+description: A fenced block of code is coloured by its language, one written in Mermaid is drawn as a diagram, and a picture is shown in place.
+---
+
+Name a fenced block's language after its opening fence, and its code is coloured by it:
+
+```python
+def leapfrog(x, v, a, dt):
+    """One step: half a kick, a drift, half a kick."""
+    v = v + 0.5 * dt * a(x)
+    x = x + dt * v
+    return x, v + 0.5 * dt * a(x)  # the second half kick
+```
+
+In the Note pane's settings, *the code* chooses colour, or ink as in print: keywords bold and comments faint.
+
+A block whose language is `mermaid` is drawn as a diagram, and stays Mermaid in the file:
+
+```mermaid
+flowchart LR
+  note[A note] -->|requires| other[The notes it rests on]
+  note -->|uses| tool[What it uses]
+  other --> atlas[(The Atlas)]
+```
+
+Put the cursor in it to change it: its source shows, and the diagram beneath it is drawn again as you type. A diagram that can't be drawn says why, in the line and column of its source. Maths in a label goes between double dollars, as Mermaid has it:
+
+```mermaid
+flowchart TB
+  m["$$\mathcal{M}$$, a manifold"] -->|"$$T_p\mathcal{M}$$ at each point"| t["$$T\mathcal{M}$$, its tangent bundle"]
+```
+
+Every kind of diagram Mermaid draws is drawn: [flowcharts, sequences, states, classes, timelines and more](https://mermaid.js.org/intro/ "see also"). [Iso](/iso/iso.md "see also") draws one where a picture helps, or when you ask it for one.
+
+## Pictures
+
+Paste a picture into a note, or drop one on it. isorite asks for its name, and what it shows, then saves it in a folder named for the note and shows it where you pasted it: `![the player at rest](hitboxes/player-idle.png)`. What it shows is what [Iso](/iso/iso.md "see also") reads of it, since Iso can't see the picture. The same picture pasted twice is one file.
+
+To show a picture that's in the notes already, type `[[!` and choose it: each is listed with a small copy of itself. Any number of notes can show the same picture. `"left"` after its path sets it at the left, with the text beside it: `![a map](map.png "left")`.
+
+A picture from your code's repository is shown with `code:`, as a [code link](/out-of-the-base/web-and-code-links.md "see also") is: `![the player](code:assets/player.png)`. One whose file is gone is struck through.

package/guide/notes/every-change-is-kept.md

@@ -0,0 +1,14 @@
+---
+type: Concept
+title: Every change is kept
+description: Every change to a note is kept, with who made it.
+---
+
+isorite keeps every change to every note in a journal, in `.isorite/`, with who made it: you, or an agent you attached (or Iso, before isorite attached your own).
+
+Two switches in the Note pane's header show it:
+
+- **The timeline** (Alt+T): the note's history as layers in its margin, the newest on top, each as thick as the change was large: yours blue, an agent's gold. Click one to see the note as it was then, and restore it to there if you want it back. Restoring is itself a change, so nothing is lost.
+- **Provenance** (Alt+P): whose words are whose. Words you wrote are plain; words an agent wrote, and you have not touched, are marked. Edit them, and they become yours.
+
+This is why [Iso writes, marked](/iso/iso-writes-marked.md "see also"), and why letting it write is safe.

package/guide/notes/folders.md

@@ -0,0 +1,11 @@
+---
+type: Concept
+title: Folders
+description: A base's folders are its parts, and frames on the Atlas.
+---
+
+A base is a folder of notes, and may hold folders, as this guide does: one for notes, one for [the Atlas](/atlas/the-atlas.md "see also"), one for Iso, and so on.
+
+A folder is a frame on the Atlas, open when it is big enough on the screen to show its notes, and one block when not. Click it to bring it to the screen; click it again to step out. Links between notes in different folders are drawn between the folders, along the gaps of the map.
+
+To make a note, hold still on open ground on the Atlas, inside the folder it belongs in, and let go: "Untitled note" is made where you held, open to type its title over. Hold and drag a little way to make a folder instead. A note can also be moved by changing its folder in its details.

package/guide/notes/go-back-a-version.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Go back a version
+uses: [notes/every-change-is-kept]
+---
+
+In [your notes](/your-notes.md), switch the timeline on, look at the note as it was before your last change, and restore it to there.
+
+Then look at the timeline again: the restoring is a change of its own.

package/guide/notes/link-your-notes.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Link your notes
+uses: [notes/links-and-their-kinds]
+---
+
+In [your notes](/your-notes.md), link a note of the guide you have read, as one your notes require: its link ends in `"requires"`.
+
+Then find the new line on the Atlas, between your notes and that note.

package/guide/notes/links-and-their-kinds.md

@@ -0,0 +1,23 @@
+---
+type: Concept
+title: Links and their kinds
+description: A link joins two notes, and says how one stands on the other.
+---
+
+A link is a Markdown link to another note's file, from the base's top:
+
+```markdown
+[Leapfrog](/integrators/leapfrog.md "requires")
+```
+
+The word in quotes is the link's kind, and says how this note stands on the other:
+
+- **requires**: this note cannot be understood without that one. Read that one first.
+- **uses**: this note draws on that one, but stands without it.
+- **see also**: related, no more. A link with no kind is one of these.
+
+The kinds are what [the Atlas](/atlas/the-atlas.md "see also") is drawn from: notes are placed so that what a note requires stands before it, and the links are lines between them. So a link's kind is worth choosing: it is how the map, and your agent, know what rests on what.
+
+Type `[[` and the start of a note's title to link it, and choose the kind with the button that comes beside the link (or Alt+1, 2, 3). Ctrl+click a link (⌘+click on a Mac) to follow it. A link to a note that is not there is shown struck through.
+
+Links to the web and to code are [links out of the base](/out-of-the-base/web-and-code-links.md "see also").

package/guide/notes/make-move-delete.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Make, move and delete a note
+uses: [notes/folders]
+---
+
+On the Atlas, make a note, and give it a title. Move it into a folder of its own. Then delete it.
+
+[Every change is kept](/notes/every-change-is-kept.md), so it can be found again in its folder's history.

package/guide/notes/write-in-your-notes.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Write in your notes
+uses: [notes/a-note-is-markdown]
+---
+
+Open [your notes](/your-notes.md) and write a line of your own in it, with one word in **bold** and a formula between dollars.
+
+Click away from the line, and see it as it reads.

package/guide/out-of-the-base/web-and-code-links.md

@@ -0,0 +1,13 @@
+---
+type: Concept
+title: Web and code links
+description: Links from a note to the web, and to a project's code.
+---
+
+A note can link out of the base: to a page on the web, `[The paper](https://arxiv.org/abs/…)`, or to a file of a project's code, by a path from the project's top, `[the step](code:sim/step.py#L40-L52)`, lines and all.
+
+Code links are read against the project's folder, named in the base's `.isorite/settings.toml`, (`repository = "../code"`). A link to a file no longer there is shown struck through, and the agent is told once, with its next prompt from the pane.
+
+On the Atlas, the web and code switches (Alt+W, Alt+K) show them, beside the notes that hold them.
+
+They are [links](/notes/links-and-their-kinds.md "requires"), with no kind: they say where to look, not what rests on what.

package/guide/questions-and-problems/ask-a-question.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Write a question
+uses: [questions-and-problems/questions]
+---
+
+Write a question about a guide note you found unclear, about that note, and embed it in [your notes](/your-notes.md).
+
+Find it on the Atlas, beside the note it is about.

package/guide/questions-and-problems/how-iso-reads-you.md

@@ -0,0 +1,9 @@
+---
+type: Concept
+title: How the agent reads you
+description: Your agent reads where you stand from your own notes, questions and problems.
+---
+
+isorite keeps no score and no record of you apart from your notes, and [your agent](/iso/iso.md "requires") is asked to read you from them. Where you stand is in what you wrote: your words in a note, your [questions](/questions-and-problems/questions.md "uses") open and resolved, the [problems](/questions-and-problems/problems.md "uses") you have solved and not.
+
+Asked to explain, it is to read those first, and ask where you stand before it explains. Where it finds your understanding stops, it offers that to you as a question to keep, or a problem to try, so the place is marked in your base and not only in the conversation.

package/guide/questions-and-problems/problems.md

@@ -0,0 +1,15 @@
+---
+type: Concept
+title: Problems
+description: A problem is something to do, and you say when it is solved.
+---
+
+A problem is a note of its own, `type: Problem`, that uses the notes it names in its label: an exercise to try, a calculation to do, a thing to build. Like [a question](/questions-and-problems/questions.md "uses"), it stands beside those notes on the Atlas.
+
+You mark it solved, with the mark at the end of its label (◇ unsolved, ◆ solved), which adds `solved:` and the date. Nothing checks it but you. Write your solution in the problem's note, under a heading, if you want it kept.
+
+A problem has no steps inside it. One that takes several is several problems, each linking to the one before it as "requires" ([Write a link](/notes/links-and-their-kinds.md "see also") says how), in a folder of their own if they belong together: the Atlas then draws the chain, and each is solved in turn.
+
+Given a problem, [Iso](/iso/iso.md "see also") checks your working rather than solving it: it says where a step goes wrong, and leaves the next step to you.
+
+The things to do in this guide are problems, and [Start here](/start-here.md "see also") holds the first.

package/guide/questions-and-problems/questions.md

@@ -0,0 +1,27 @@
+---
+type: Concept
+title: Questions
+description: An open question marks where your understanding stops.
+---
+
+A question is a note of its own, `type: Question`, about the notes it names in its label:
+
+```markdown
+---
+type: Question
+title: Why does leapfrog not drift?
+about: [integrators/leapfrog]
+---
+```
+
+It is where your understanding stops, written down, so that it is not lost: on the Atlas beside the notes it is about, until you resolve it, by writing what you found and adding `resolved:` with the date. Then it leaves the map.
+
+A note can hold a question in place, on a line of its own, by the question's file name:
+
+```markdown
+[[!why-does-leapfrog-not-drift]]
+```
+
+Make one from the Atlas, holding on ground and choosing a question, or from the note's settings. [Iso](/iso/iso.md "see also") may ask you one back, and you choose whether to keep it; until you do, it shows on the Atlas in a dotted outline, where it would go.
+
+A question is the start of [a problem](/questions-and-problems/problems.md "see also"), sometimes.

package/guide/questions-and-problems/resolve-a-question.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Resolve a question
+uses: [questions-and-problems/questions]
+---
+
+Resolve [why are links Markdown links?](/questions-and-problems/why-markdown-links.md): write an answer in your own words in the question's note, and mark it resolved.
+
+A hint: what does a link need to carry, beside its target? And where else must the notes be read?

package/guide/questions-and-problems/why-markdown-links.md

@@ -0,0 +1,7 @@
+---
+type: Question
+title: Why are links Markdown links?
+about: [notes/links-and-their-kinds]
+---
+
+Other note apps link with `[[wikilinks]]`. isorite links with Markdown links to the file, `[Title](/folder/note.md "requires")`. Why?

package/guide/solve-this-one.md

@@ -0,0 +1,11 @@
+---
+type: Problem
+title: Solve this one
+uses: [start-here]
+---
+
+Mark this problem solved: open it, and click ◇ unsolved at the end of its label.
+
+Then go back to [Start here](/start-here.md) and find its tick, and find it on the Atlas, where a solved problem is marked as one.
+
+To unmark it, click it again.

package/guide/start-here.md

@@ -0,0 +1,39 @@
+---
+type: Concept
+title: Start here
+description: What isorite is, its three panes, and how this guide works.
+---
+
+isorite is a home for what you are coming to understand: notes in Markdown, a map of what rests on what, and Iso, the pane where the agent you already use reads your notes with you.
+
+This guide is a knowledge base like any other, and its subject is isorite. Read it in isorite, and use isorite to read it.
+
+## The three panes
+
+- **The note**, open to read and write. This one is open there now.
+- **The Atlas**, the map of the notes: each folder a frame, each note a block, each line a link. It starts from [the Atlas](/atlas/the-atlas.md "uses").
+- **Iso**, your agent's session: [Iso](/iso/iso.md "uses").
+
+Each pane's header has its switches: [the switches](/atlas/the-switches.md "uses") says what they are.
+
+## How to read the guide
+
+Start with [a note is Markdown](/notes/a-note-is-markdown.md "requires"), then follow the links that interest you. The Atlas shows which notes rest on which.
+
+Beside the notes are problems: things to do in isorite, one each. You mark a problem solved yourself, when you have done it, and its tick shows here and on the Atlas. Try the first:
+
+[[!solve-this-one]]
+
+Then these, in any order:
+
+[[!write-in-your-notes]]
+
+[[!link-your-notes]]
+
+[[!find-what-it-rests-on]]
+
+[[!ask-iso]]
+
+[[!give-it-notes]]
+
+Write what you like in [your notes](/your-notes.md "see also"): the guide is yours to change. When you are ready for your own base, see [starting a base](/your-own-base/starting-a-base.md "see also").

package/guide/terminal/let-the-agent-remember.md

@@ -0,0 +1,9 @@
+---
+type: Problem
+title: Let the agent remember
+uses: [terminal/memory]
+---
+
+Run `isorite memory`, then attach your agent to a project's base. Tell it something about how you work that it should remember, and watch it appear in the memory's tab: switch to `memory` from the base's name in the first pane's header.
+
+This needs isorite of your own, not the guide's site: see [starting a base](/your-own-base/starting-a-base.md).