@nesso-how/mcp 0.1.0-alpha.22 → 0.1.0-alpha.24

package/dist/starlight-docs.pages.json

@@ -4,25 +4,25 @@
       "slug": "guides/ai-mentor",
       "title": "AI mentor (Socrates)",
       "description": "How the Socratic mentor works, local vs remote, persona, and graph-aware context.",
-      "markdown": "Click the **Socrates** bubble in the bottom-right of the canvas to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/cedoor/nesso/blob/main/src/llm/context.ts))—**FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n## Local vs remote\n\nConfigure under **Settings -> AI**:\n\n- **Local model (default):** Qwen2.5 1.5B (~1.1 GB, q4f16 quantised) runs entirely in the browser via WebGPU using [WebLLM](https://github.com/mlc-ai/web-llm). First run prompts a one-off download; subsequent loads use the cached weights in IndexedDB. Nothing leaves your device.\n- **Remote API:** any OpenAI-compatible `chat/completions` endpoint. Set base URL, model, and (optionally) API key. Defaults work with a local [Ollama](https://ollama.com/) instance at `http://localhost:11434/v1`.\n\nThe toggle is live: switching modes takes effect on the next message.\n\n### When local mode is unavailable\n\nIf your browser does not support WebGPU, or the weights haven't been downloaded yet, the chat input stays disabled and the mentor card shows a short status line. Click **Download & use** in **Settings -> AI** to fetch the model, or switch to Remote API mode.\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorBubble.tsx`](https://github.com/cedoor/nesso/blob/main/src/components/MentorBubble.tsx)) shapes Socrates:\n\n- One short question per turn by default; explain only enough to frame the question.\n- Replies are soft-capped at ~200 words (hard cap via output tokens).\n- No graph edits proposed in dialogue. Socrates probes; the user edits.\n- No emojis, flattery, JSON, or pseudo-graph markup. Sparse `*asterisks*` on key terms.\n- Replies in the active UI language (English or Italian). Snapshot tokens stay **English-shaped** (`s=…d`, `…d since review`, etc.), with the same spelling in the legend for every locale.\n\nIf you want a more permissive coach, fork the persona. It is plain text in the component and easy to swap.\n\n## Opening message\n\nWhen the panel opens, the mentor sends itself a short synthetic **user** turn so its first message reflects what's selected:\n\n- **A concept node selected:** opens on that concept and one of its relations.\n- **An edge selected (no node):** opens on the typed relation between its endpoints.\n- **Nothing selected:** opens on a weak spot in the graph (low stability plus weak **last reviews** — Again/Hard or a long gap; **DUE** is extra scheduler context).\n\nClick **New chat** in the header to reset history and request a fresh opener.\n\n## Context size\n\nLarge graphs are summarised, not truncated abruptly. The weakest-reviewed nodes appear first (`nodeStrength`), so the verbatim slice emphasises instability and risky last ratings; tail nodes are omitted with a short count only. Edges have a ~2x allowance over node count. These limits live in [`MentorBubble.tsx`](https://github.com/cedoor/nesso/blob/main/src/components/MentorBubble.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`.\n\n## Privacy\n\n- **Local mode:** every byte stays in the browser. Graph data, prompts, responses, and model weights are all client-side.\n- **Remote mode:** the system prompt (graph snapshot) and chat history are sent to whichever endpoint you configured, each turn. If that is a hosted provider, the usual provider-side logging applies."
+      "markdown": ":::caution\nThis is the part of Nesso with the most potential and the most room to grow. Small models tend to drift out of the Socratic role and start explaining rather than questioning. A larger remote model works noticeably better. Improving the mentor is where most of the future work is headed.\n:::\n\nClick the **Socrates** bubble in the bottom-right of the canvas to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/nesso-how/nesso/blob/main/src/llm/context.ts)): **FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n## Local vs remote\n\nConfigure under **Settings -> AI**:\n\n- **Local model (default):** Qwen2.5 1.5B (~1.1 GB, q4f16 quantised) runs entirely in the browser via WebGPU using [WebLLM](https://github.com/mlc-ai/web-llm). First run prompts a one-off download; subsequent loads use the cached weights in IndexedDB. Nothing leaves your device.\n- **Remote API:** any OpenAI-compatible `chat/completions` endpoint. Set base URL, model, and (optionally) API key. Defaults work with a local [Ollama](https://ollama.com/) instance at `http://localhost:11434/v1`.\n\nThe toggle is live: switching modes takes effect on the next message.\n\n### When local mode is unavailable\n\nIf your browser does not support WebGPU, or the weights haven't been downloaded yet, the chat input stays disabled and the mentor card shows a short status line. Click **Download & use** in **Settings -> AI** to fetch the model, or switch to Remote API mode.\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorBubble.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/MentorBubble.tsx)) shapes Socrates:\n\n- One short question per turn by default; explain only enough to frame the question.\n- Replies are soft-capped at ~200 words (hard cap via output tokens).\n- No graph edits proposed in dialogue. Socrates probes; the user edits.\n- No emojis, flattery, JSON, or pseudo-graph markup. Sparse `*asterisks*` on key terms.\n- Replies in the active UI language (English or Italian). Snapshot tokens stay **English-shaped** (`s=…d`, `…d since review`, etc.), with the same spelling in the legend for every locale.\n\nIf you want a more permissive coach, fork the persona. It is plain text in the component and easy to swap.\n\n## Opening message\n\nWhen the panel opens, the mentor sends itself a short synthetic **user** turn so its first message reflects what's selected:\n\n- **A concept node selected:** opens on that concept and one of its relations.\n- **An edge selected (no node):** opens on the typed relation between its endpoints.\n- **Nothing selected:** opens on a weak spot in the graph (low stability plus weak **last reviews** (Again/Hard or a long gap); **DUE** is extra scheduler context).\n\nClick **New chat** in the header to reset history and request a fresh opener.\n\n## Context size\n\nLarge graphs are summarised, not truncated abruptly. The weakest-reviewed nodes appear first (`nodeStrength`), so the verbatim slice emphasises instability and risky last ratings; tail nodes are omitted with a short count only. Edges have a ~2x allowance over node count. These limits live in [`MentorBubble.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/MentorBubble.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`.\n\n## Privacy\n\n- **Local mode:** every byte stays in the browser. Graph data, prompts, responses, and model weights are all client-side.\n- **Remote mode:** the system prompt (graph snapshot) and chat history are sent to whichever endpoint you configured, each turn. If that is a hosted provider, the usual provider-side logging applies."
     },
     {
       "slug": "guides/concepts-and-inspector",
       "title": "Concepts & Inspector",
       "description": "Adding concepts, drawing typed relations, and using the Inspector to enrich nodes with definitions, examples, notes, and images.",
-      "markdown": "The canvas is the centre of Nesso. **Concepts** are nodes; **typed relations** are edges. The **Inspector** is the right-hand panel where you enrich whatever you've got selected.\n\n## Adding concepts\n\n- **Bottom dock -> +** adds a new concept near the centre of the viewport.\n- **`N`** adds a concept at the viewport centre (same as the dock `+`).\n- **Double-click** empty canvas to add a concept at the pointer.\n- New concepts open in edit mode. Type the label and press `Enter` to commit, `Esc` to cancel.\n- **Double-click** a concept to rename it inline.\n\nConcepts you add are stored locally in IndexedDB. Switch graphs from the sidebar; create new graphs from the **Graphs** list.\n\n## Drawing relations\n\nDrag from a node's right edge (`out` handle) to another node's left edge (`in` handle). On release, a **relation picker** opens, grouped by category. Pick the relation type and the edge is created.\n\n- Drag-to-self is ignored, so you can't accidentally create self-loops.\n- The connection line previews with the same quadratic geometry the final edge uses.\n- Edge type can be changed any time from the Inspector when an edge is selected.\n\nSee the [relation types reference](../../reference/relation-types/) for the full list and what each one encodes visually.\n\n## Selecting and editing\n\n- **Click** a node or edge to select it. The Inspector reflects the selection.\n- **Hold `⌘` / `Ctrl` and click** to toggle additional items into the selection.\n- **Drag on empty canvas** to marquee-select multiple items.\n- **`Del`** or **`Backspace`** (or the trash icon in the bottom dock) deletes the selection — one relation, one concept, or every concept in a marquee. Edges attached to a deleted concept go with it. Relation delete is only from the dock or keyboard, not from the relation Inspector.\n- **`⌘C` / `Ctrl+C`** (copy icon in the bottom dock) copies the selection. Copying concepts also copies relations between them; copying a relation includes its two endpoints. **`⌘V` / `Ctrl+V`** (paste icon) duplicates the clipboard with a small offset and selects the new items.\n- **Arrow keys** nudge a selected concept; **Shift + arrows** move it in larger steps.\n- **`⌘Z` / `Ctrl+Z`** undoes structural edits; **`⌘⇧Z` / `Ctrl+Shift+Z`** redoes. History has 50 steps and resets when you switch or import a graph.\n\n## The Inspector\n\nWhen a concept is selected, the Inspector shows two tabs.\n\n### Overview\n\n- **Title:** edit inline. Pressing `Enter` commits; `Esc` reverts.\n- **FSRS stats:** when due, stability (in days), and last self-rating. Surfaced read-only.\n- **Relations:** outgoing and incoming edges grouped by category. Click a relation chip to jump to the connected node; click the type to swap relation in place.\n\n### Notes\n\nThree free-text fields that travel with the concept and feed both the AI mentor and Review:\n\n- **Definition:** a one-sentence-ish explanation in your own words.\n- **Examples:** one per line. Press `Shift+Enter` or use the `+` button to add a new line.\n- **Notes:** anything else: caveats, sources, mnemonics.\n\nThese power the [Review](./review-mode/) recall question. The model is told to _aim_ at the topic suggested by your notes without paraphrasing the definition, so active recall still works.\n\n### Concept image\n\nPress the picture icon to open the **Wikimedia Commons search**. The query auto-fills from the concept title and runs immediately; pick any result to attach a 200-px thumbnail to the concept. The image shows in the Inspector, in Review mode, and is included as context for the AI mentor.\n\nThe image link and Commons description URL are persisted with the graph, so attribution is preserved on export.\n\n## Display options (sidebar)\n\n**Sidebar → Display** controls how the **active graph** is rendered: heatmap overlay, edge encoding density, curve style, and auto flip. Choices are saved **with the graph** in IndexedDB (and included in JSON export). New graphs start from the app defaults until you change them.\n\nWhen **Display → Curve** is set to **Arc**, **Auto flip** (on by default) bends relations toward the side that avoids overlapping nodes — flipping when the target is above the source on the right, or below on the left — and updates live while you drag concepts. **Flip curve** in the Inspector is **Off | Auto | On** while auto flip is on: **Auto** follows layout, **Off** / **On** pin a manual bend on that edge. With auto flip off for that graph, the control is **Off | On** only.\n\n## When an edge is selected\n\nThe Inspector shows the relation as a chip with its category colour and a dropdown of every relation type. Picking a new type updates the edge in place; the graph keeps its endpoints and identity.\n\n## Stats and search\n\n- **Sidebar -> Stats** shows concept count, link count, and current zoom (a handy gut-check for graph size).\n- **`⌘K` / `Ctrl+K`** opens a fuzzy search palette over concept titles. `Enter` selects and recenters the viewport; `Esc` closes.\n\n## Edge encoding density\n\nEdges carry three visual channels: colour (category), line style, and glyph. Crank this down for large or printed graphs from **Sidebar → Display → Edges**:\n\n- **Full:** colour + style + glyph (default).\n- **Category:** colour only.\n- **Minimal:** plain line, no encoding.\n\nSymmetric relations (similarity, opposition) never render an arrowhead regardless of encoding."
+      "markdown": "The canvas is the centre of Nesso. **Concepts** are nodes; **typed relations** are edges. The **Inspector** is the right-hand panel where you enrich whatever you've got selected.\n\n## Adding concepts\n\n- **Bottom dock -> +** adds a new concept near the centre of the viewport.\n- **`N`** adds a concept at the viewport centre (same as the dock `+`).\n- **Double-click** empty canvas to add a concept at the pointer.\n- New concepts open in edit mode. Type the label and press `Enter` to commit, `Esc` to cancel.\n- **Double-click** a concept to rename it inline.\n\nConcepts you add are stored locally in IndexedDB. Switch graphs from the sidebar; create new graphs from the **Graphs** list.\n\n## Drawing relations\n\nDrag from a node's right edge (`out` handle) to another node's left edge (`in` handle). On release, a **relation picker** opens, grouped by category. Pick the relation type and the edge is created.\n\n- Drag-to-self is ignored, so you can't accidentally create self-loops.\n- The connection line previews with the same quadratic geometry the final edge uses.\n- Edge type can be changed any time from the Inspector when an edge is selected.\n\nSee the [relation types reference](../../reference/relation-types/) for the full list, semantic meaning, and coefficients. Per-type line style and glyph come from `@nesso-how/relation-types`; edge encoding density is under [Display options](#display-options-sidebar) below.\n\n## Selecting and editing\n\n- **Click** a node or edge to select it. The Inspector reflects the selection.\n- **Hold `⌘` / `Ctrl` and click** to toggle additional items into the selection.\n- **Drag on empty canvas** to marquee-select multiple items.\n- **`Del`** or **`Backspace`** (or the trash icon in the bottom dock) deletes the selection (one relation, one concept, or every concept in a marquee). Edges attached to a deleted concept go with it. Relation delete is only from the dock or keyboard, not from the relation Inspector.\n- **`⌘C` / `Ctrl+C`** (copy icon in the bottom dock) copies the selection. Copying concepts also copies relations between them; copying a relation includes its two endpoints. **`⌘V` / `Ctrl+V`** (paste icon) duplicates the clipboard with a small offset and selects the new items.\n- **Arrow keys** nudge a selected concept; **Shift + arrows** move it in larger steps.\n- **`⌘Z` / `Ctrl+Z`** undoes structural edits; **`⌘⇧Z` / `Ctrl+Shift+Z`** redoes. History has 50 steps and resets when you switch or import a graph.\n\n## The Inspector\n\nWhen a concept is selected, the Inspector shows two tabs.\n\n### Overview\n\n- **Title:** edit inline. Pressing `Enter` commits; `Esc` reverts.\n- **FSRS stats:** when due, stability (in days), and last self-rating. Surfaced read-only.\n- **Relations:** outgoing and incoming edges grouped by category. Click a relation chip to jump to the connected node; click the type to swap relation in place.\n\n### Notes\n\nThree free-text fields that travel with the concept and feed both the AI mentor and Review:\n\n- **Definition:** a one-sentence-ish explanation in your own words.\n- **Examples:** one per line. Press `Shift+Enter` or use the `+` button to add a new line.\n- **Notes:** anything else: caveats, sources, mnemonics.\n\nThese power the [Review](./review-mode/) recall question. The model is told to _aim_ at the topic suggested by your notes without paraphrasing the definition, so active recall still works.\n\n### Concept image\n\nPress the picture icon to open the **Wikimedia Commons search**. The query auto-fills from the concept title and runs immediately; pick any result to attach a 200-px thumbnail to the concept. The image shows in the Inspector, in Review mode, and is included as context for the AI mentor.\n\nThe image link and Commons description URL are persisted with the graph, so attribution is preserved on export.\n\n## Display options (sidebar)\n\n**Sidebar → Display** controls how the **active graph** is rendered: heatmap overlay, edge encoding density, curve style, and auto flip. Choices are saved **with the graph** in IndexedDB (and included in JSON export). New graphs start from the app defaults until you change them.\n\nWhen **Display → Curve** is set to **Arc**, **Auto flip** (on by default) bends relations toward the side that avoids overlapping nodes, flipping when the target is above the source on the right, or below on the left, and updates live while you drag concepts. **Flip curve** in the Inspector is **Off | Auto | On** while auto flip is on: **Auto** follows layout, **Off** / **On** pin a manual bend on that edge. With auto flip off for that graph, the control is **Off | On** only.\n\n## When an edge is selected\n\nThe Inspector shows the relation as a chip with its category colour and a dropdown of every relation type. Picking a new type updates the edge in place; the graph keeps its endpoints and identity.\n\n## Stats and search\n\n- **Sidebar -> Stats** shows concept count, link count, and current zoom (a handy gut-check for graph size).\n- **`⌘K` / `Ctrl+K`** opens a fuzzy search palette over concept titles. `Enter` selects and recenters the viewport; `Esc` closes.\n\n## Edge encoding density\n\nEdges carry three visual channels: colour (category), line style, and glyph. Crank this down for large or printed graphs from **Sidebar → Display → Edges**:\n\n- **Full:** colour + style + glyph (default).\n- **Category:** colour only.\n- **Minimal:** plain line, no encoding.\n\nSymmetric relations (similarity, opposition) never render an arrowhead regardless of encoding."
     },
     {
       "slug": "guides/getting-started",
       "title": "Getting started",
       "description": "How to run Nesso locally or on the web.",
-      "markdown": "Nesso is available as a hosted web app, a macOS desktop app, and as open-source code you can run locally. All data is stored in your browser or on your machine; nothing is sent to external servers unless you configure a remote AI endpoint.\n\n## Web app\n\nOpen [app.nesso.how](https://app.nesso.how) in your browser. The app works offline after the first load. Use Chrome, Edge, Arc, or any other browser with **WebGPU** if you want to run the AI mentor locally; for the remote API mode any modern browser is fine.\n\n## Desktop app (macOS)\n\nPre-built alpha installers for Apple silicon and Intel are published on [GitHub Releases](https://github.com/cedoor/nesso/releases). Download the `.dmg` for your architecture and open it.\n\n## Run from source\n\nRequires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/).\n\n```sh\ngit clone https://github.com/cedoor/nesso.git\ncd nesso\npnpm install\npnpm dev\n```\n\nFor a desktop build, [Rust](https://rustup.rs/) is required as well:\n\n```sh\npnpm build:desktop\n```\n\n## Picking an AI backend\n\nThe Socratic mentor uses an LLM. Choose under **Settings -> AI**:\n\n- **Local model (default):** Qwen2.5 1.5B runs entirely in the browser via WebGPU (powered by [WebLLM](https://github.com/mlc-ai/web-llm)). The first run downloads ~1.1 GB and caches it; subsequent loads are instant. Nothing leaves your machine.\n- **Remote API:** any OpenAI-compatible `chat/completions` endpoint: local [Ollama](https://ollama.com/) at `http://localhost:11434/v1`, an OpenAI-compatible proxy, or a hosted provider. Set base URL, model, and API key if needed.\n\nEither mode can be switched at any time from **Settings** (`⌘,` / `Ctrl+,`).\n\n> API keys are stored client-side in `localStorage`. Do not self-host the web app publicly with secrets baked in.\n\n### Local mode tips\n\n- WebGPU is required. On macOS, recent Chrome / Edge / Arc work out of the box; Safari support is improving but currently limited.\n- The first download streams progress into the Settings panel. Closing the panel does not cancel the download.\n- **Settings -> Data -> Delete** clears graphs and preferences but leaves the cached model untouched. Clearing browser site data removes everything, including the model weights.\n\n### Remote mode with Ollama\n\nRun Ollama locally, then pull a small instruction-tuned model:\n\n```sh\nollama pull gemma3:4b\n```\n\nIn **Settings -> AI**, choose **Remote API** and set:\n\n- Base URL: `http://localhost:11434/v1`\n- Model: `gemma3:4b` (or `llama3.2:3b`, `qwen2.5:7b`; presets are shown in Settings)\n- API key: leave empty\n\nSettings auto-probes the endpoint and offers a **Pull** button if the model is missing.\n\n## Keyboard shortcuts\n\n| Shortcut               | Action                         |\n| ---------------------- | ------------------------------ |\n| `?`                    | Show shortcuts dialog          |\n| `⌘,` / `Ctrl+,`        | Settings                       |\n| `⌘K` / `Ctrl+K`        | Search concepts                |\n| `N`                    | Add concept at viewport centre |\n| `R`                    | Open review mode               |\n| `⌘Z` / `Ctrl+Z`        | Undo                           |\n| `⌘⇧Z` / `Ctrl+Shift+Z` | Redo                           |\n| `Del` / `Backspace`    | Delete selection               |\n| `⌘C` / `Ctrl+C`        | Copy selection                 |\n| `⌘V` / `Ctrl+V`        | Paste                          |\n| `↑` `↓` `←` `→`        | Nudge selected concept         |\n| `Shift` + arrows       | Nudge selected concept (large) |\n| `Esc`                  | Close dialog                   |\n\nHold `⌘` / `Ctrl` to add to a selection; drag on empty canvas to marquee-select."
+      "markdown": "Nesso is available as a hosted web app, a macOS desktop app, and as open-source code you can run locally. All data is stored in your browser or on your machine; nothing is sent to external servers unless you configure a remote AI endpoint.\n\n## Web app\n\nOpen [app.nesso.how](https://app.nesso.how) in your browser. The app works offline after the first load. Use Chrome, Edge, Arc, or any other browser with **WebGPU** if you want to run the AI mentor locally; for the remote API mode any modern browser is fine.\n\n## Desktop app (macOS)\n\nPre-built alpha installers for Apple silicon and Intel are published on [GitHub Releases](https://github.com/nesso-how/nesso/releases). Download the `.dmg` for your architecture and open it.\n\n:::caution\nThe app is not signed with an Apple developer certificate. macOS will block it on first launch. After installing, run this command in the terminal to remove the quarantine flag:\n\n```sh\nxattr -cr /Applications/Nesso.app\n```\n\nThen open the app normally.\n:::\n\n## Run from source\n\nRequires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/).\n\n```sh\ngit clone https://github.com/nesso-how/nesso.git\ncd nesso\npnpm install\npnpm dev\n```\n\nFor a desktop build, [Rust](https://rustup.rs/) is required as well:\n\n```sh\npnpm build:desktop\n```\n\n## Picking an AI backend\n\nThe Socratic mentor uses an LLM. Choose under **Settings -> AI**:\n\n- **Local model (default):** Qwen2.5 1.5B runs entirely in the browser via WebGPU (powered by [WebLLM](https://github.com/mlc-ai/web-llm)). The first run downloads ~1.1 GB and caches it; subsequent loads are instant. Nothing leaves your machine.\n- **Remote API:** any OpenAI-compatible `chat/completions` endpoint: local [Ollama](https://ollama.com/) at `http://localhost:11434/v1`, an OpenAI-compatible proxy, or a hosted provider. Set base URL, model, and API key if needed.\n\nEither mode can be switched at any time from **Settings** (`⌘,` / `Ctrl+,`).\n\n:::caution\nAPI keys are stored client-side in `localStorage`. Do not self-host the web app publicly with secrets baked in.\n:::\n\n### Local mode tips\n\n- WebGPU is required. On macOS, recent Chrome / Edge / Arc work out of the box; Safari support is improving but currently limited.\n- The first download streams progress into the Settings panel. Closing the panel does not cancel the download.\n- To remove the cached model weights, clear the browser site data for the app.\n\n### Remote mode with Ollama\n\nRun Ollama locally, then pull a small instruction-tuned model:\n\n```sh\nollama pull gemma3:4b\n```\n\nIn **Settings -> AI**, choose **Remote API** and set:\n\n- Base URL: `http://localhost:11434/v1`\n- Model: `gemma3:4b` (or `llama3.2:3b`, `qwen2.5:7b`; presets are shown in Settings)\n- API key: leave empty\n\nSettings auto-probes the endpoint and offers a **Pull** button if the model is missing.\n\n## Keyboard shortcuts\n\n| Shortcut               | Action                         |\n| ---------------------- | ------------------------------ |\n| `?`                    | Show shortcuts dialog          |\n| `⌘,` / `Ctrl+,`        | Settings                       |\n| `⌘K` / `Ctrl+K`        | Search concepts                |\n| `N`                    | Add concept at viewport centre |\n| `R`                    | Open review mode               |\n| `⌘Z` / `Ctrl+Z`        | Undo                           |\n| `⌘⇧Z` / `Ctrl+Shift+Z` | Redo                           |\n| `Del` / `Backspace`    | Delete selection               |\n| `⌘C` / `Ctrl+C`        | Copy selection                 |\n| `⌘V` / `Ctrl+V`        | Paste                          |\n| `↑` `↓` `←` `→`        | Nudge selected concept         |\n| `Shift` + arrows       | Nudge selected concept (large) |\n| `Esc`                  | Close dialog                   |\n\nHold `⌘` / `Ctrl` to add to a selection; drag on empty canvas to marquee-select."
     },
     {
       "slug": "guides/mcp-integration",
       "title": "MCP",
       "description": "Connect Nesso to Claude, Cursor, or any MCP-compatible AI client.",
-      "markdown": "The `@nesso-how/mcp` package is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI clients access to Nesso documentation and the full relation-type vocabulary. Once connected, models can answer questions about how Nesso works and use the correct relation names when you build graphs yourself in the app or in JSON.\n\n## Setup\n\n### Claude Desktop\n\nOpen `claude_desktop_config.json`. On macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows at `%APPDATA%\\Claude\\claude_desktop_config.json`.\n\nAdd a `nesso` entry under `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nesso\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nesso-how/mcp\"]\n    }\n  }\n}\n```\n\nSave the file and restart Claude Desktop. The Nesso tools will be available to the model automatically.\n\n### Cursor\n\nOpen **Settings -> MCP** and add a new server with command `npx` and args `[\"-y\", \"@nesso-how/mcp\"]`.\n\n### Other MCP clients\n\nAny client that speaks the stdio MCP transport works. Run `npx -y @nesso-how/mcp` as the server command. No other configuration is required.\n\n## What it can do\n\nOnce connected, you can ask your AI client things like:\n\n- \"What relation types does Nesso support?\" (uses `get_relation_types`)\n- \"Show me the Nesso getting started guide\" (uses `get_nesso_docs`)\n\nYou can build graphs in [app.nesso.how](https://app.nesso.how) yourself, or paste graph JSON from the model via **Graph menu → Import JSON** when it follows the shape below.\n\n## Tools reference\n\n### `get_nesso_docs`\n\nFetches documentation pages from this site. Call it without a `slug` to get a table of contents, or with a slug (e.g. `\"guides/getting-started\"`) to get the full page content.\n\n### `get_relation_types`\n\nReturns the complete list of relation types with their category, line style, symmetry, and semantic coefficients (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner.\n\n### Graph JSON (Import JSON)\n\nPaste this JSON shape into **Graph menu → Import JSON** in the web or desktop app (or construct it elsewhere and import the file). **Import** keeps structure (nodes, edges, display, elaboration) and resets FSRS / review fields to fresh defaults — personal scheduling from another user is not applied. **Export JSON** from the graph menu is share-safe the same way (no review history). Desktop workspace autosave is separate and retains your full progress.\n\n```json\n{\n  \"name\": \"Graph title\",\n  \"nodes\": [\n    {\n      \"id\": \"n1\",\n      \"type\": \"concept\",\n      \"position\": { \"x\": 0, \"y\": 0 },\n      \"data\": {\n        \"text\": \"Concept label\",\n        \"stability\": 0,\n        \"difficulty\": 0,\n        \"reps\": 0,\n        \"lapses\": 0,\n        \"fsrsState\": 0,\n        \"due\": 0,\n        \"lastReview\": 0,\n        \"lastRating\": 0\n      }\n    }\n  ],\n  \"edges\": [\n    {\n      \"id\": \"e1\",\n      \"type\": \"nesso\",\n      \"source\": \"n1\",\n      \"target\": \"n2\",\n      \"sourceHandle\": \"out\",\n      \"targetHandle\": \"in\",\n      \"data\": { \"type\": \"causes\" }\n    }\n  ]\n}\n```\n\nCall `get_relation_types` before inventing **`data.type`** values so they match Nesso."
+      "markdown": "The `@nesso-how/mcp` package is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI clients access to Nesso documentation and the full relation-type vocabulary. Once connected, models can answer questions about how Nesso works and use the correct relation names when you build graphs yourself in the app or in JSON.\n\n## Setup\n\n### Claude Desktop\n\nOpen `claude_desktop_config.json`. On macOS it lives at `~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows at `%APPDATA%\\Claude\\claude_desktop_config.json`.\n\nAdd a `nesso` entry under `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"nesso\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nesso-how/mcp\"]\n    }\n  }\n}\n```\n\nSave the file and restart Claude Desktop. The Nesso tools will be available to the model automatically.\n\n### Cursor\n\nOpen **Settings -> MCP** and add a new server with command `npx` and args `[\"-y\", \"@nesso-how/mcp\"]`.\n\n### Other MCP clients\n\nAny client that speaks the stdio MCP transport works. Run `npx -y @nesso-how/mcp` as the server command. No other configuration is required.\n\n## What it can do\n\nOnce connected, you can ask your AI client things like:\n\n- \"What relation types does Nesso support?\" (uses `get_relation_types`)\n- \"Show me the Nesso getting started guide\" (uses `get_nesso_docs`)\n\nYou can build graphs in [app.nesso.how](https://app.nesso.how) yourself, or ask the model to generate a graph as a JSON file and import it via **Graph menu → Import JSON**. Use `get_relation_types` to make sure the model picks valid relation names.\n\n## Tools reference\n\n### `get_nesso_docs`\n\nFetches documentation pages from this site. Call it without a `slug` to get a table of contents, or with a slug (e.g. `\"guides/getting-started\"`) to get the full page content.\n\n### `get_relation_types`\n\nReturns the complete list of relation types with their category, line style, symmetry, and semantic coefficients (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner."
     },
     {
       "slug": "guides/review-mode",
@@ -34,13 +34,13 @@
       "slug": "introduction",
       "title": "Introduction",
       "description": "What Nesso is, why it exists, and the principles it is built on.",
-      "markdown": "Nesso is an open-source, AI-assisted knowledge graph for active learning. It is built on a specific claim about how understanding works and a specific critique of how most current tools approach it.\n\n## The problem with passive learning tools\n\nThe dominant pattern AI is settling into is passive: hand over a source, receive a summary; ask a question, receive an answer; describe what you want to learn, receive a pre-built map. This is convenient, and pedagogically counterproductive. Decades of cognitive science converge on the same conclusion: deep understanding is not received; it is constructed. When the work of deciding how concepts relate is offloaded to a system, the process that produces comprehension is bypassed.\n\nAlongside this, most learning platforms treat user data as a resource. In the context of learning, this data is uniquely sensitive: it reveals not just what someone has read, but how they reason, where they struggle, and how their understanding evolves over time. Capturing it passively, and often opaquely, is at odds with the interests of the people the tools claim to serve.\n\nFinally, most platforms are proprietary silos: closed standards, locked formats, no way to inspect or extend them. Educators, developers, and learners themselves have no meaningful recourse when a platform makes choices they disagree with or stops serving their needs.\n\n## What Nesso does instead\n\nNesso inverts the flow. The learner constructs their own knowledge structure: a typed concept graph that reflects how _they_ understand, not just what they have consumed. The act of deciding which relation holds between two concepts (does X _cause_ Y, or merely _enable_ it? is A an _instance of_ B, or a _subtype of_ it?) is where elaborative processing happens. The decision is the learning.\n\nAlgorithms work on what the learner has built, not on a generic curriculum. Spaced repetition is driven by graph structure: concepts with low stability or untested connections surface before well-reinforced ones. The review queue is always a function of the learner's own map.\n\nAI is present, but with a constrained role. The AI mentor, Socrates, does not deliver pre-packaged answers. It asks questions calibrated to the learner's current graph, probing understanding, surfacing gaps, and leaving the work of constructing answers to the learner. It is designed to accelerate active thinking, not to replace it.\n\n## Principles\n\n**Constructivist by design.** Every feature is oriented around the learner doing cognitive work: drawing edges, labelling relations, writing definitions in their own words, self-rating recall. The system does not do this work for them.\n\n**Private by architecture.** In the web app, graphs are stored locally in the browser (IndexedDB). In the **desktop app** (Tauri), each graph is also mirrored to a `.json` file in a workspace folder you can open in any editor (default: app data; optional custom folder in **Settings → Data**). The local AI mode runs entirely in-browser via WebGPU; no data leaves the device. Privacy is an implementation detail, not a policy promise.\n\n**Open by default.** The code is MIT-licensed. Data formats are documented and importable/exportable as plain JSON. The MCP server makes the graph vocabulary available to any compatible client. Technical work done here is intended to be useful beyond this application.\n\n**Provider-agnostic AI.** Nesso talks to any OpenAI-compatible `chat/completions` endpoint. Users choose whether to run a model locally or connect a remote provider; no vendor is privileged by the architecture.\n\n## What Nesso is not\n\nNesso is not a note-taking app. It does not replace a text editor, a spaced-repetition deck manager, or a general-purpose LLM interface. It is specifically a tool for the phase of learning where understanding a domain means deciding how its concepts relate to each other, and testing whether you can hold that structure under questioning.\n\nIt is also not a finished product. It is an alpha-stage open-source project. Some features are rough, some planned items are not yet built, and the codebase is publicly available for inspection and contribution.\n\n---\n\nThe remainder of this documentation covers how to use the app and how to integrate with it programmatically. If you want to start immediately, [Getting started](./guides/getting-started/) has everything you need."
+      "markdown": ":::caution\nThis is an early-stage project. Some features are rough, some are not yet built, and this documentation is just getting started too.\n:::\n\nNesso is an open-source, AI-assisted knowledge graph for active learning. It is built on a specific claim about how understanding works and a specific critique of how most current tools approach it.\n\n## The problem with passive learning tools\n\nPassive learning is not a new problem. AI has made it the default and amplified it at scale: You hand over a source and receive a summary, ask a question and receive an answer, or describe what you want to learn and receive a pre-built map. This is convenient, and pedagogically counterproductive. Decades of cognitive science converge on the same conclusion: deep understanding is not received; it is constructed. When the work of deciding how concepts relate is offloaded to a system, the process that produces comprehension is bypassed.\n\nAlongside this, most learning platforms treat user data as a resource. In the context of learning, this data is uniquely sensitive: it reveals not just what someone has read, but how they reason, where they struggle, and how their understanding evolves over time. Capturing it passively, and often opaquely, is at odds with the interests of the people the tools claim to serve.\n\nFinally, most platforms are proprietary silos: closed standards, locked formats, no way to inspect or extend them. Educators, developers, and learners themselves have no meaningful recourse when a platform makes choices they disagree with or stops serving their needs.\n\n## What Nesso does instead\n\nNesso inverts the flow. The learner constructs their own knowledge structure: a typed concept graph that reflects how _they_ understand, not just what they have consumed. The act of deciding which relation holds between two concepts (does X _cause_ Y, or merely _enable_ it? is A an _instance of_ B, or a _subtype of_ it?) is where elaborative processing happens. The decision is the learning.\n\nAlgorithms work on what the learner has built, not on a generic curriculum. Spaced repetition is driven by graph structure: concepts with low stability or untested connections surface before well-reinforced ones. The review queue is always a function of the learner's own map.\n\nAI is present, but with a constrained role. The AI mentor, Socrates, does not deliver pre-packaged answers. It asks questions calibrated to the learner's current graph, probing understanding, surfacing gaps, and leaving the work of constructing answers to the learner. It is designed to accelerate active thinking, not to replace it.\n\n## Principles\n\n**Constructivist by design.** Every feature is oriented around the learner doing cognitive work: drawing edges, labelling relations, writing definitions in their own words, self-rating recall. The system does not do this work for them.\n\n**Private by architecture.** In the web app, graphs are stored locally in your browser. In the desktop app, they are also saved as plain JSON files on your machine. The local AI mode runs entirely on your device; no data leaves it. Privacy is an implementation detail, not a policy promise.\n\n**Open by default.** The code is MIT-licensed. Data formats are documented and importable/exportable as plain JSON. The MCP server makes the graph vocabulary available to any compatible client. Technical work done here is intended to be useful beyond this application.\n\n**Provider-agnostic AI.** Nesso talks to any OpenAI-compatible `chat/completions` endpoint. Users choose whether to run a model locally or connect a remote provider; no vendor is privileged by the architecture.\n\n## What Nesso is not\n\nNesso is not a note-taking app. It does not replace a text editor, a spaced-repetition deck manager, or a general-purpose LLM interface. It is specifically a tool for the phase of learning where understanding a domain means deciding how its concepts relate to each other, and testing whether you can hold that structure under questioning.\n\nIt is also not a finished product. The codebase is publicly available for inspection and contribution.\n\n---\n\nThe remainder of this documentation covers how to use the app and how to integrate with it programmatically. If you want to start immediately, [Getting started](./guides/getting-started/) has everything you need."
     },
     {
       "slug": "reference/relation-types",
       "title": "Relation types",
       "description": "The 52 semantic relation types across 8 categories in Nesso.",
-      "markdown": "Edges in Nesso carry a **semantic type**: a named relation that describes how two concepts are connected. There are 52 types grouped into 8 categories. Each category has a distinct colour; each type has a line style, a glyph, and a set of semantic coefficients used by graph-analysis algorithms.\n\nAsymmetric relations come in **inverse pairs** (e.g. `subtype-of` / `has-subtype`) so traversal in either direction is first-class. Symmetric relations (`contrasts-with`, `opposite-of`, `similar-to`, `analogous-to`, `overlaps-with`, `contradicts`) are self-inverse.\n\n## Coefficients\n\nEach relation type declares:\n\n- **`symmetric`** — `true` when the edge carries the same meaning in both directions (no arrowhead).\n- **`transitive`** — `Y` (strict), `N` (none), or `weak` (transitivity with decay; algorithms may discount per step).\n- **`inverse`** — the canonical inverse type in the set. Self for symmetric relations.\n- **`strength`** — per-type semantic weight in `0..1`. Encodes how \"tight\" the relation is, not per-edge confidence.\n- **`polarity`** — `+1` positive effect, `-1` antagonistic, `0` neutral/structural. From signed-network theory.\n- **`cardinality`** — expected mapping pattern: `1-1`, `1-N`, `N-1`, or `N-N` (no constraint).\n\n## Taxonomic\n\n_What kind of thing is it?_\n\n| Type           | Label        | Inverse        | T   | S    | P   | Card |\n| -------------- | ------------ | -------------- | --- | ---- | --- | ---- |\n| `subtype-of`   | subtype of   | `has-subtype`  | Y   | 0.90 | 0   | N-1  |\n| `has-subtype`  | has subtype  | `subtype-of`   | Y   | 0.90 | 0   | 1-N  |\n| `instance-of`  | instance of  | `has-instance` | N   | 0.95 | 0   | N-1  |\n| `has-instance` | has instance | `instance-of`  | N   | 0.95 | 0   | 1-N  |\n\n## Structural\n\n_What is it made of or composed from?_\n\n| Type       | Label    | Inverse    | T    | S    | P   | Card |\n| ---------- | -------- | ---------- | ---- | ---- | --- | ---- |\n| `part-of`  | part of  | `contains` | Y    | 0.85 | 0   | N-1  |\n| `contains` | contains | `part-of`  | Y    | 0.85 | 0   | 1-N  |\n| `made-of`  | made of  | `composes` | weak | 0.75 | 0   | N-N  |\n| `composes` | composes | `made-of`  | weak | 0.75 | 0   | N-N  |\n\n## Causal\n\n_What does it do or prevent?_\n\n| Type           | Label        | Inverse        | T    | S    | P   | Card |\n| -------------- | ------------ | -------------- | ---- | ---- | --- | ---- |\n| `causes`       | causes       | `caused-by`    | N    | 0.85 | +1  | N-N  |\n| `caused-by`    | caused by    | `causes`       | N    | 0.85 | +1  | N-N  |\n| `produces`     | produces     | `produced-by`  | N    | 0.70 | +1  | N-N  |\n| `produced-by`  | produced by  | `produces`     | N    | 0.70 | +1  | N-N  |\n| `enables`      | enables      | `enabled-by`   | weak | 0.60 | +1  | N-N  |\n| `enabled-by`   | enabled by   | `enables`      | weak | 0.60 | +1  | N-N  |\n| `prevents`     | prevents     | `prevented-by` | N    | 0.85 | −1  | N-N  |\n| `prevented-by` | prevented by | `prevents`     | N    | 0.85 | −1  | N-N  |\n| `triggers`     | triggers     | `triggered-by` | N    | 0.70 | +1  | N-N  |\n| `triggered-by` | triggered by | `triggers`     | N    | 0.70 | +1  | N-N  |\n| `inhibits`     | inhibits     | `inhibited-by` | N    | 0.55 | −1  | N-N  |\n| `inhibited-by` | inhibited by | `inhibits`     | N    | 0.55 | −1  | N-N  |\n| `disables`     | disables     | `disabled-by`  | weak | 0.60 | −1  | N-N  |\n| `disabled-by`  | disabled by  | `disables`     | weak | 0.60 | −1  | N-N  |\n| `consumes`     | consumes     | `consumed-by`  | N    | 0.65 | −1  | N-N  |\n| `consumed-by`  | consumed by  | `consumes`     | N    | 0.65 | −1  | N-N  |\n| `delays`       | delays       | `delayed-by`   | weak | 0.55 | −1  | N-N  |\n| `delayed-by`   | delayed by   | `delays`       | weak | 0.55 | −1  | N-N  |\n\n`prevents` (total blockage), `inhibits` (partial reduction), and `disables` (switches off a capacity or function) are three distinct negative types — intensity and mechanism are semantic properties of the type, not a per-edge value. `disables` is the counterpart to `enables`; use `prevents` when an outcome is fully blocked and `inhibits` when it is only reduced.\n\nThe category also includes `consumes` (resource destruction, distinct from dependency's `uses`) and `delays` (slows or postpones an effect; polarity −1 because delay hinders the outcome).\n\n## Dependency\n\n_What does it need or serve?_\n\n| Type          | Label       | Inverse       | T    | S    | P   | Card |\n| ------------- | ----------- | ------------- | ---- | ---- | --- | ---- |\n| `requires`    | requires    | `required-by` | Y    | 0.85 | 0   | N-N  |\n| `required-by` | required by | `requires`    | Y    | 0.85 | 0   | N-N  |\n| `uses`        | uses        | `used-by`     | weak | 0.50 | 0   | N-N  |\n| `used-by`     | used by     | `uses`        | weak | 0.50 | 0   | N-N  |\n| `used-for`    | used for    | `purpose-of`  | N    | 0.55 | +1  | N-N  |\n| `purpose-of`  | purpose of  | `used-for`    | N    | 0.55 | +1  | N-N  |\n\n## Temporal\n\n_When or where does it happen?_\n\n| Type             | Label          | Inverse          | T   | S    | P   | Card |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | ---- |\n| `precedes`       | precedes       | `follows`        | Y   | 0.50 | 0   | N-N  |\n| `follows`        | follows        | `precedes`       | Y   | 0.50 | 0   | N-N  |\n| `occurs-in`      | occurs in      | `has-occurrence` | Y   | 0.40 | 0   | N-1  |\n| `has-occurrence` | has occurrence | `occurs-in`      | Y   | 0.40 | 0   | 1-N  |\n| `during`         | during         | `spans`          | Y   | 0.55 | 0   | N-1  |\n| `spans`          | spans          | `during`         | Y   | 0.55 | 0   | 1-N  |\n| `overlaps-with`  | overlaps with  | self (symmetric) | N   | 0.45 | 0   | N-N  |\n| `derives-from`   | derives from   | `gives-rise-to`  | Y   | 0.70 | 0   | N-1  |\n| `gives-rise-to`  | gives rise to  | `derives-from`   | Y   | 0.70 | 0   | 1-N  |\n\n`during` / `spans` model Allen's interval-in-interval containment (peer intervals). Distinct from `occurs-in` which localizes a quasi-point event in a period (different scale).\n\n`derives-from` / `gives-rise-to` capture genealogical descent — temporal lineage with transformative continuity (languages, species, ideas), distinct from `caused-by` (direct influence without continuity) and from taxonomic `subtype-of` (class membership at a snapshot in time, not historical descent).\n\n## Opposition\n\n_What does it contrast with?_ Symmetric.\n\n| Type             | Label          | T   | S    | P   | Card |\n| ---------------- | -------------- | --- | ---- | --- | ---- |\n| `contrasts-with` | contrasts with | N   | 0.50 | −1  | N-N  |\n| `opposite-of`    | opposite of    | N   | 0.80 | −1  | 1-1  |\n\n## Similarity\n\n_What is it like?_ Symmetric.\n\n| Type           | Label        | T    | S    | P   | Card |\n| -------------- | ------------ | ---- | ---- | --- | ---- |\n| `similar-to`   | similar to   | weak | 0.40 | +1  | N-N  |\n| `analogous-to` | analogous to | N    | 0.30 | +1  | N-N  |\n\n## Epistemic\n\n_How do we know?_\n\n| Type           | Label        | Inverse          | T    | S    | P   | Card |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | ---- |\n| `supports`     | supports     | `supported-by`   | weak | 0.70 | +1  | N-N  |\n| `supported-by` | supported by | `supports`       | weak | 0.70 | +1  | N-N  |\n| `contradicts`  | contradicts  | self (symmetric) | N    | 0.75 | −1  | N-N  |\n| `explains`     | explains     | `explained-by`   | weak | 0.80 | 0   | N-N  |\n| `explained-by` | explained by | `explains`       | weak | 0.80 | 0   | N-N  |\n| `defines`      | defines      | `defined-by`     | N    | 0.90 | 0   | 1-1  |\n| `defined-by`   | defined by   | `defines`        | N    | 0.90 | 0   | 1-1  |\n\n`defines` goes from the defining expression (definiens) to the term being defined (definiendum) — e.g. \"F = ma defines force\". Cardinality 1-1 enforces one canonical definition per term.\n\n`contradicts` is symmetric (mutual logical incompatibility), unlike `supports` and `explains` which are asymmetric evidence/explanans → claim relations.\n\n---\n\n**Edge encoding** is controlled per-graph via Settings → Appearance → Edge encoding:\n\n- `full`: glyph and line style\n- `category`: colour only\n- `minimal`: plain line"
+      "markdown": "In Nesso, every edge carries a **semantic type**: a named relation describing how two concepts are connected, with semantic coefficients reserved for graph-analysis algorithms (future work, no algorithm currently consumes them). The vocabulary is fixed at 52 types across 8 categories, drawn from prior work in knowledge representation, lexical semantics, temporal logic, and signed-network theory.\n\n:::note\nThis set and its coefficients are a starting point. Both the types and their coefficient values will evolve as real graphs accumulate, edge cases surface, and the analysis algorithms that consume the coefficients get built out. Treat them as a considered first cut, not a final spec.\n:::\n\n## Coefficients\n\nEach relation type declares the coefficients below. They define the contract that graph-analysis algorithms will consume; closing the enum guarantees every type comes with them, where a user-defined type would arrive without and stay analytically opaque.\n\n- **Transitive (T)**: `Y` (strict), `N` (none), or `weak` (transitivity with decay; algorithms may discount per step).\n- **Inverse (I)**: the canonical inverse type in the set; `self` for symmetric relations. Asymmetric relations declare it explicitly so traversal is first-class in both directions. The explicit-inverse design follows knowledge-graph embedding work <a id=\"cite-1\" href=\"#ref-1\">[1]</a>, which lists symmetry, antisymmetry, inversion, and composition as the four properties a good relation set should support.\n- **Strength (S)**: per-type semantic weight in `0..1`. Encodes how \"tight\" the relation is in general (e.g. `defines` 0.90 vs `similar-to` 0.40), not how sure the user is about a specific edge. The idea that different relation types carry different semantic distance comes from lexical-taxonomy weighting schemes <a id=\"cite-2\" href=\"#ref-2\">[2]</a>, <a id=\"cite-3\" href=\"#ref-3\">[3]</a>.\n- **Polarity (P)**: `+1` positive effect, `-1` antagonistic, `0` neutral/structural. From signed-network theory <a id=\"cite-4\" href=\"#ref-4\">[4]</a>: with polarity, the graph becomes a signed network where balance and cycle-sign analyses can apply.\n- **Cardinality (C)**: expected mapping pattern, always declared. One of `1-1`, `1-N`, `N-1`, `N-N` (no a-priori constraint). Setting this consistently lets algorithms flag structural anomalies (e.g. two competing `defines` edges into the same term).\n\n## Categories\n\nEach category answers a specific question about the relation. Grouping the types by question makes the vocabulary easier to navigate when authoring a graph, and lets graph-analysis algorithms compare and aggregate at category level instead of only per individual type.\n\n### Taxonomic\n\n_What kind of thing is it?_\n\n| Type           | Label        | I              | T   | S    | P   | C   |\n| -------------- | ------------ | -------------- | --- | ---- | --- | --- |\n| `subtype-of`   | subtype of   | `has-subtype`  | Y   | 0.90 | 0   | N-1 |\n| `has-subtype`  | has subtype  | `subtype-of`   | Y   | 0.90 | 0   | 1-N |\n| `instance-of`  | instance of  | `has-instance` | N   | 0.95 | 0   | N-1 |\n| `has-instance` | has instance | `instance-of`  | N   | 0.95 | 0   | 1-N |\n\nTaxonomic relations answer the simplest question you can ask about a concept: what kind of thing is it? Nesso splits the answer into two layers that look alike at a glance but behave very differently under reasoning. The class-vs-instance distinction mirrors OWL/RDFS <a id=\"cite-5\" href=\"#ref-5\">[5]</a>: `subtype-of` corresponds to `rdfs:subClassOf` (one class refines another, as a sparrow refines bird), while `instance-of` corresponds to `rdf:type` (an individual belongs to a class, as Tweety belongs to sparrow). Inheritance flows freely through the subtype chain, but instances are leaves: Tweety is a sparrow and through that a bird, yet Tweety is not itself \"a kind of\" anything.\n\n### Structural\n\n_What is it made of or composed from?_\n\n| Type       | Label    | I          | T    | S    | P   | C   |\n| ---------- | -------- | ---------- | ---- | ---- | --- | --- |\n| `part-of`  | part of  | `contains` | Y    | 0.85 | 0   | N-1 |\n| `contains` | contains | `part-of`  | Y    | 0.85 | 0   | 1-N |\n| `made-of`  | made of  | `composes` | weak | 0.75 | 0   | N-N |\n| `composes` | composes | `made-of`  | weak | 0.75 | 0   | N-N |\n\nStructural relations describe how a thing decomposes into its parts. The category covers two patterns. `part-of` and its inverse `contains` capture discrete structural decomposition: an engine is part of a car, a paragraph is part of a chapter, and transitivity flows cleanly through the chain. `made-of` and `composes` capture material or substantive composition instead: water is made of hydrogen and oxygen, a chair is made of wood. Transitivity there is only weak, because what something is made of doesn't always propagate in a meaningful way (a chair made of wood, made of cellulose, made of carbon, made of atoms dilutes the relationship as the chain grows).\n\n### Causal\n\n_What does it do or prevent?_\n\n| Type           | Label        | I              | T    | S    | P   | C   |\n| -------------- | ------------ | -------------- | ---- | ---- | --- | --- |\n| `causes`       | causes       | `caused-by`    | N    | 0.85 | +1  | N-N |\n| `caused-by`    | caused by    | `causes`       | N    | 0.85 | +1  | N-N |\n| `produces`     | produces     | `produced-by`  | N    | 0.70 | +1  | N-N |\n| `produced-by`  | produced by  | `produces`     | N    | 0.70 | +1  | N-N |\n| `enables`      | enables      | `enabled-by`   | weak | 0.60 | +1  | N-N |\n| `enabled-by`   | enabled by   | `enables`      | weak | 0.60 | +1  | N-N |\n| `prevents`     | prevents     | `prevented-by` | N    | 0.85 | −1  | N-N |\n| `prevented-by` | prevented by | `prevents`     | N    | 0.85 | −1  | N-N |\n| `triggers`     | triggers     | `triggered-by` | N    | 0.70 | +1  | N-N |\n| `triggered-by` | triggered by | `triggers`     | N    | 0.70 | +1  | N-N |\n| `inhibits`     | inhibits     | `inhibited-by` | N    | 0.55 | −1  | N-N |\n| `inhibited-by` | inhibited by | `inhibits`     | N    | 0.55 | −1  | N-N |\n| `disables`     | disables     | `disabled-by`  | weak | 0.60 | −1  | N-N |\n| `disabled-by`  | disabled by  | `disables`     | weak | 0.60 | −1  | N-N |\n| `consumes`     | consumes     | `consumed-by`  | N    | 0.65 | −1  | N-N |\n| `consumed-by`  | consumed by  | `consumes`     | N    | 0.65 | −1  | N-N |\n| `delays`       | delays       | `delayed-by`   | weak | 0.55 | −1  | N-N |\n| `delayed-by`   | delayed by   | `delays`       | weak | 0.55 | −1  | N-N |\n\nCausal is the largest category in Nesso, because causation in the real world doesn't come in a single flavor. On the positive side, `causes` describes direct generation of an outcome, `triggers` describes the initiation of something that then plays out on its own (a spark triggers an explosion), and `enables` describes making something possible without forcing it. The negative side mirrors this: `prevents` is total blockage, `inhibits` is partial reduction, and `disables` is switching off a capacity or function. Intensity and mechanism live at the type level rather than as per-edge weights, so choosing between `inhibits` and `prevents` is a semantic decision about what is actually happening, not about how confident the author is.\n\n`consumes` and `delays` round out the category. `consumes` captures resource destruction, which is causal rather than dependency-flavored: it is distinct from `uses`, where the resource survives the interaction. `delays` carries negative polarity because slowing or postponing an outcome hinders it, even though nothing is destroyed.\n\n### Dependency\n\n_What does it need or serve?_\n\n| Type          | Label       | I             | T    | S    | P   | C   |\n| ------------- | ----------- | ------------- | ---- | ---- | --- | --- |\n| `requires`    | requires    | `required-by` | Y    | 0.85 | 0   | N-N |\n| `required-by` | required by | `requires`    | Y    | 0.85 | 0   | N-N |\n| `uses`        | uses        | `used-by`     | weak | 0.50 | 0   | N-N |\n| `used-by`     | used by     | `uses`        | weak | 0.50 | 0   | N-N |\n| `used-for`    | used for    | `purpose-of`  | N    | 0.55 | +1  | N-N |\n| `purpose-of`  | purpose of  | `used-for`    | N    | 0.55 | +1  | N-N |\n\nDependency relations capture what a concept _needs_ rather than what causes it. A car requires an engine to function, but the engine doesn't cause the car, and that difference shows up in how the graph traverses these edges. `requires` and `required-by` are the hard form, where the dependency is essential and transitivity is strict: if A requires B and B requires C, A also requires C. `uses` and `used-by` are softer, capturing a working relationship that doesn't necessarily imply the user can't survive without it, so transitivity decays through the chain. `used-for` and `purpose-of` are teleological: they point at the goal or function a thing serves (a hammer is used for driving nails). Cardinality there stays open at N-N, since one tool can serve many purposes and many tools can share a single purpose.\n\n### Temporal\n\n_When or where does it happen?_\n\n| Type             | Label          | I                | T   | S    | P   | C   |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | --- |\n| `precedes`       | precedes       | `follows`        | Y   | 0.50 | 0   | N-N |\n| `follows`        | follows        | `precedes`       | Y   | 0.50 | 0   | N-N |\n| `occurs-in`      | occurs in      | `has-occurrence` | Y   | 0.40 | 0   | N-1 |\n| `has-occurrence` | has occurrence | `occurs-in`      | Y   | 0.40 | 0   | 1-N |\n| `during`         | during         | `spans`          | Y   | 0.55 | 0   | N-1 |\n| `spans`          | spans          | `during`         | Y   | 0.55 | 0   | 1-N |\n| `overlaps-with`  | overlaps with  | self (symmetric) | N   | 0.45 | 0   | N-N |\n| `derives-from`   | derives from   | `gives-rise-to`  | Y   | 0.70 | 0   | N-1 |\n| `gives-rise-to`  | gives rise to  | `derives-from`   | Y   | 0.70 | 0   | 1-N |\n\nTemporal relations describe when things happen relative to each other and how an event sits inside a larger period. Allen's interval algebra <a id=\"cite-6\" href=\"#ref-6\">[6]</a> inspires the containment pair: `during` and `spans` model intervals nested inside other intervals (the medieval period spans roughly a thousand years, and Charlemagne's reign was during it). `occurs-in` and its inverse work at a different scale, pinning a quasi-point event to the period it falls inside (the moon landing occurs in 1969). `precedes` and `follows` cover plain sequence without nesting, and `overlaps-with` is the symmetric case for two intervals that share a stretch of time without one containing the other.\n\n`derives-from` and `gives-rise-to` are not just about chronology, they capture genealogical descent: a transformative continuity where something becomes something else over time. Languages, species, and ideas all have lineages of this kind. The relation is close to `caused-by` but distinct, because causation is direct influence without requiring the cause to _become_ the effect. It is also distinct from taxonomic `subtype-of`, which is a snapshot of class membership rather than a historical claim. Italian derives from Latin, but Italian is not a subtype of Latin in the modern sense.\n\n### Opposition\n\n_What does it contrast with?_\n\n| Type             | Label          | I                | T   | S    | P   | C   |\n| ---------------- | -------------- | ---------------- | --- | ---- | --- | --- |\n| `contrasts-with` | contrasts with | self (symmetric) | N   | 0.50 | −1  | N-N |\n| `opposite-of`    | opposite of    | self (symmetric) | N   | 0.80 | −1  | 1-1 |\n\nOpposition is the category for concepts that stand against each other. The two types differ in strength. `contrasts-with` is the weaker form, where two concepts highlight each other by sitting at different points on some dimension (warm contrasts with cool, North contrasts with South). `opposite-of` is the canonical, often binary opposite (alive is the opposite of dead, true is the opposite of false), and its cardinality is 1-1 because a canonical opposite is unique. Both are symmetric: if A is the opposite of B, then B is the opposite of A by definition.\n\n### Similarity\n\n_What is it like?_\n\n| Type           | Label        | I                | T    | S    | P   | C   |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | --- |\n| `similar-to`   | similar to   | self (symmetric) | weak | 0.40 | +1  | N-N |\n| `analogous-to` | analogous to | self (symmetric) | N    | 0.30 | +1  | N-N |\n\nThe similarity category includes two related but distinct relations. `similar-to` is the looser one, where two concepts share enough properties to be grouped together (lions are similar to tigers). `analogous-to` is more structural: the two concepts aren't necessarily alike in their properties, but their roles or relationships mirror each other (an electron orbiting an atom is analogous to a planet orbiting the sun). Both are symmetric, and both carry positive polarity because finding similarity or analogy is usually a constructive move in reasoning.\n\n### Epistemic\n\n_How do we know?_\n\n| Type           | Label        | I                | T    | S    | P   | C   |\n| -------------- | ------------ | ---------------- | ---- | ---- | --- | --- |\n| `supports`     | supports     | `supported-by`   | weak | 0.70 | +1  | N-N |\n| `supported-by` | supported by | `supports`       | weak | 0.70 | +1  | N-N |\n| `contradicts`  | contradicts  | self (symmetric) | N    | 0.75 | −1  | N-N |\n| `explains`     | explains     | `explained-by`   | weak | 0.80 | 0   | N-N |\n| `explained-by` | explained by | `explains`       | weak | 0.80 | 0   | N-N |\n| `defines`      | defines      | `defined-by`     | N    | 0.90 | 0   | 1-1 |\n| `defined-by`   | defined by   | `defines`        | N    | 0.90 | 0   | 1-1 |\n\nThe epistemic category is where Nesso models reasoning about claims rather than facts about the world. `supports` and `supported-by` connect a piece of evidence to the claim it bolsters; `explains` and `explained-by` connect an explanans (the explanatory account) to its explanandum (what is being explained). Both pairs are asymmetric, because evidence points to a claim and an explanation is not equivalent to what it explains.\n\n`defines` is the most rigid relation in this category. It goes from the defining expression (the _definiens_) to the term being defined (the _definiendum_): in \"F = ma defines force\", the equation is the definiens and `force` is the definiendum. Cardinality 1-1 enforces a single canonical definition per term, so two competing `defines` edges into the same concept signal a real ambiguity worth resolving.\n\n`contradicts` is the only symmetric relation in the category, because logical incompatibility goes both ways: if A contradicts B, then B equally contradicts A. This distinguishes it from `supports` and `explains`, which always point in a particular direction.\n\n## References\n\n1. <a id=\"ref-1\"></a>Sun, Z., Deng, Z.-H., Nie, J.-Y., and Tang, J. [_RotatE: Knowledge Graph Embedding by Relational Rotation in Complex Space_](https://arxiv.org/abs/1902.10197). ICLR, 2019. [↑](#cite-1)\n2. <a id=\"ref-2\"></a>Sussna, M. [_Word sense disambiguation for free-text indexing using a massive semantic network_](https://doi.org/10.1145/170088.170106). CIKM '93, 1993. [↑](#cite-2)\n3. <a id=\"ref-3\"></a>Jiang, J. J. and Conrath, D. W. [_Semantic similarity based on corpus statistics and lexical taxonomy_](https://arxiv.org/abs/cmp-lg/9709008). ROCLING X, 1997. [↑](#cite-3)\n4. <a id=\"ref-4\"></a>Cartwright, D. and Harary, F. [_Structural balance: A generalization of Heider's theory_](https://doi.org/10.1037/h0046049). Psychological Review, 63(5):277–293, 1956. [↑](#cite-4)\n5. <a id=\"ref-5\"></a>W3C. [_OWL 2 Web Ontology Language Primer (Second Edition)_](https://www.w3.org/TR/owl2-primer/). 2012. [↑](#cite-5)\n6. <a id=\"ref-6\"></a>Allen, J. F. [_Maintaining knowledge about temporal intervals_](https://doi.org/10.1145/182.358434). Communications of the ACM, 26(11):832–843, 1983. [↑](#cite-6)"
     }
   ]
 }

package/dist/tools/get-relation-types.js

@@ -17,7 +17,7 @@ export function registerGetRelationTypes(server) {
                 type: name,
                 label: def.label,
                 line: def.line,
-                symmetric: def.symmetric,
+                symmetric: def.inverse === 'self',
                 transitive: def.transitive,
                 inverse: def.inverse,
                 strength: def.strength,

package/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@nesso-how/mcp",
-  "version": "0.1.0-alpha.22",
+  "version": "0.1.0-alpha.24",
   "description": "MCP server exposing Nesso knowledge graph tools to LLM clients",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nesso-how/nesso",
+    "directory": "packages/mcp"
+  },
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -18,7 +23,7 @@
     "@cfworker/json-schema": "^4.1.1",
     "@modelcontextprotocol/server": "^2.0.0-alpha.2",
     "zod": "^4.4.3",
-    "@nesso-how/relation-types": "0.1.0-alpha.22"
+    "@nesso-how/relation-types": "0.1.0-alpha.24"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",