@nesso-how/mcp 0.1.0-alpha.37 → 0.1.0-alpha.38

package/README.md

@@ -21,7 +21,7 @@ Add to your MCP client (Cursor, Claude Desktop, etc.):
 }
 ```
 
-Tools: `get_relation_types`, `get_nesso_docs`.
+Tools: `get_relation_types`, `get_nesso_docs`, `validate_graph`, `build_graph`.
 
 Full guide: [MCP integration](https://nesso.how/docs/guides/mcp-integration/).
 

package/dist/index.js

@@ -2,8 +2,10 @@
 // SPDX-License-Identifier: MIT
 import { readFileSync } from 'node:fs';
 import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server';
+import { registerBuildGraph } from './tools/build-graph.js';
 import { registerGetRelationTypes } from './tools/get-relation-types.js';
 import { registerGetDocs } from './tools/get-docs.js';
+import { registerValidateGraph } from './tools/validate-graph.js';
 const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
 const server = new McpServer({
     name: 'nesso',
@@ -11,6 +13,8 @@ const server = new McpServer({
 });
 registerGetRelationTypes(server);
 registerGetDocs(server);
+registerValidateGraph(server);
+registerBuildGraph(server);
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/lib/graph-tools.d.ts

@@ -0,0 +1,147 @@
+import * as z from 'zod/v4';
+import { type NessoGraphDocumentInput } from '@nesso-how/vocab-learning';
+export interface GraphValidationIssue {
+    path: string;
+    message: string;
+}
+export interface GraphValidationResult {
+    valid: boolean;
+    errors: GraphValidationIssue[];
+    warnings: GraphValidationIssue[];
+}
+export declare const relationTypeEnum: z.ZodEnum<{
+    "subtype-of": "subtype-of";
+    "has-subtype": "has-subtype";
+    "instance-of": "instance-of";
+    "has-instance": "has-instance";
+    "part-of": "part-of";
+    contains: "contains";
+    "made-of": "made-of";
+    composes: "composes";
+    causes: "causes";
+    "caused-by": "caused-by";
+    produces: "produces";
+    "produced-by": "produced-by";
+    enables: "enables";
+    "enabled-by": "enabled-by";
+    prevents: "prevents";
+    "prevented-by": "prevented-by";
+    triggers: "triggers";
+    "triggered-by": "triggered-by";
+    inhibits: "inhibits";
+    "inhibited-by": "inhibited-by";
+    disables: "disables";
+    "disabled-by": "disabled-by";
+    consumes: "consumes";
+    "consumed-by": "consumed-by";
+    delays: "delays";
+    "delayed-by": "delayed-by";
+    requires: "requires";
+    "required-by": "required-by";
+    uses: "uses";
+    "used-by": "used-by";
+    "used-for": "used-for";
+    "purpose-of": "purpose-of";
+    precedes: "precedes";
+    follows: "follows";
+    "occurs-in": "occurs-in";
+    "has-occurrence": "has-occurrence";
+    during: "during";
+    spans: "spans";
+    "overlaps-with": "overlaps-with";
+    "derives-from": "derives-from";
+    "gives-rise-to": "gives-rise-to";
+    "contrasts-with": "contrasts-with";
+    "opposite-of": "opposite-of";
+    "similar-to": "similar-to";
+    "analogous-to": "analogous-to";
+    supports: "supports";
+    "supported-by": "supported-by";
+    contradicts: "contradicts";
+    explains: "explains";
+    "explained-by": "explained-by";
+    defines: "defines";
+    "defined-by": "defined-by";
+}>;
+export declare const buildGraphInputSchema: z.ZodObject<{
+    name: z.ZodString;
+    concepts: z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        text: z.ZodString;
+        elaboration: z.ZodOptional<z.ZodObject<{
+            definition: z.ZodString;
+            examples: z.ZodString;
+            notes: z.ZodString;
+            imageUrl: z.ZodOptional<z.ZodString>;
+            imageTitle: z.ZodOptional<z.ZodString>;
+            imageDescriptionUrl: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>;
+    relations: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+        relation: z.ZodEnum<{
+            "subtype-of": "subtype-of";
+            "has-subtype": "has-subtype";
+            "instance-of": "instance-of";
+            "has-instance": "has-instance";
+            "part-of": "part-of";
+            contains: "contains";
+            "made-of": "made-of";
+            composes: "composes";
+            causes: "causes";
+            "caused-by": "caused-by";
+            produces: "produces";
+            "produced-by": "produced-by";
+            enables: "enables";
+            "enabled-by": "enabled-by";
+            prevents: "prevents";
+            "prevented-by": "prevented-by";
+            triggers: "triggers";
+            "triggered-by": "triggered-by";
+            inhibits: "inhibits";
+            "inhibited-by": "inhibited-by";
+            disables: "disables";
+            "disabled-by": "disabled-by";
+            consumes: "consumes";
+            "consumed-by": "consumed-by";
+            delays: "delays";
+            "delayed-by": "delayed-by";
+            requires: "requires";
+            "required-by": "required-by";
+            uses: "uses";
+            "used-by": "used-by";
+            "used-for": "used-for";
+            "purpose-of": "purpose-of";
+            precedes: "precedes";
+            follows: "follows";
+            "occurs-in": "occurs-in";
+            "has-occurrence": "has-occurrence";
+            during: "during";
+            spans: "spans";
+            "overlaps-with": "overlaps-with";
+            "derives-from": "derives-from";
+            "gives-rise-to": "gives-rise-to";
+            "contrasts-with": "contrasts-with";
+            "opposite-of": "opposite-of";
+            "similar-to": "similar-to";
+            "analogous-to": "analogous-to";
+            supports: "supports";
+            "supported-by": "supported-by";
+            contradicts: "contradicts";
+            explains: "explains";
+            "explained-by": "explained-by";
+            defines: "defines";
+            "defined-by": "defined-by";
+        }>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BuildGraphInput = z.infer<typeof buildGraphInputSchema>;
+/** Short element id (`n`/`e` + 5 base36 chars), retried until unique within `used`. */
+export declare function newElementId(prefix: 'n' | 'e', used: ReadonlySet<string>): string;
+/** Non-throwing validation for Nesso graph document JSON strings. */
+export declare function validateGraphJson(graph: string): GraphValidationResult;
+/** Build a valid Nesso graph document from structured agent input. */
+export declare function buildGraphDocument(input: BuildGraphInput): NessoGraphDocumentInput;
+/** Serialize a built graph document to importable JSON. */
+export declare function buildGraphJson(input: BuildGraphInput): string;

package/dist/lib/graph-tools.js

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: MIT
+import dagre from 'dagre';
+import * as z from 'zod/v4';
+import { deserialize, serialize, VOCABULARY, RELATION_TYPE_VALUES, } from '@nesso-how/vocab-learning';
+const elaborationSchema = z.object({
+    definition: z.string(),
+    examples: z.string(),
+    notes: z.string(),
+    imageUrl: z.string().optional(),
+    imageTitle: z.string().optional(),
+    imageDescriptionUrl: z.string().optional(),
+});
+export const relationTypeEnum = z.enum(RELATION_TYPE_VALUES);
+const conceptInputSchema = z.union([
+    z.string().describe('Concept label text'),
+    z.object({
+        id: z.string().optional().describe('Optional stable concept id (n-prefix recommended)'),
+        text: z.string().describe('Concept label'),
+        elaboration: elaborationSchema.optional(),
+    }),
+]);
+export const buildGraphInputSchema = z.object({
+    name: z.string().describe('Graph display name'),
+    concepts: z
+        .array(conceptInputSchema)
+        .min(1)
+        .describe('Concept labels or objects with optional id and elaboration'),
+    relations: z
+        .array(z.object({
+        from: z.string().describe('Source concept id or label text'),
+        to: z.string().describe('Target concept id or label text'),
+        relation: relationTypeEnum.describe('Semantic relation type id'),
+    }))
+        .describe('Directed relations between concepts'),
+});
+const NODE_WIDTH = 180;
+const NODE_HEIGHT = 60;
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+/** Short element id (`n`/`e` + 5 base36 chars), retried until unique within `used`. */
+export function newElementId(prefix, used) {
+    for (;;) {
+        const id = prefix + Math.random().toString(36).slice(2, 7);
+        if (!used.has(id))
+            return id;
+    }
+}
+function issue(path, message) {
+    return { path, message };
+}
+function detectRuntimeFormat(root) {
+    const hasDocumentShape = Array.isArray(root.concepts) && Array.isArray(root.relations);
+    const hasRuntimeShape = Array.isArray(root.nodes) || Array.isArray(root.edges);
+    if (hasRuntimeShape && !hasDocumentShape) {
+        return issue('$', 'Expected graph document format with concepts[] and relations[], not runtime nodes/edges');
+    }
+    return null;
+}
+function collectStructuralIssues(doc) {
+    const errors = [];
+    const warnings = [];
+    if (doc.vocabulary === undefined) {
+        warnings.push(issue('vocabulary', 'Missing vocabulary reference; import works but metadata is incomplete'));
+    }
+    const conceptIds = new Set();
+    for (let i = 0; i < doc.concepts.length; i++) {
+        const id = doc.concepts[i].id;
+        if (conceptIds.has(id)) {
+            errors.push(issue(`concepts[${i}].id`, `Duplicate concept id "${id}"`));
+        }
+        conceptIds.add(id);
+    }
+    const relationIds = new Set();
+    for (let i = 0; i < doc.relations.length; i++) {
+        const rel = doc.relations[i];
+        if (relationIds.has(rel.id)) {
+            errors.push(issue(`relations[${i}].id`, `Duplicate relation id "${rel.id}"`));
+        }
+        relationIds.add(rel.id);
+        if (!conceptIds.has(rel.source)) {
+            errors.push(issue(`relations[${i}].source`, `Source "${rel.source}" does not reference an existing concept id`));
+        }
+        if (!conceptIds.has(rel.target)) {
+            errors.push(issue(`relations[${i}].target`, `Target "${rel.target}" does not reference an existing concept id`));
+        }
+        if (rel.type === undefined) {
+            warnings.push(issue(`relations[${i}].type`, 'Missing relation type; the app falls back to "causes" at render time'));
+        }
+    }
+    return { errors, warnings };
+}
+/** Non-throwing validation for Nesso graph document JSON strings. */
+export function validateGraphJson(graph) {
+    const errors = [];
+    const warnings = [];
+    let parsed;
+    try {
+        parsed = JSON.parse(graph);
+    }
+    catch {
+        return {
+            valid: false,
+            errors: [issue('$', 'Invalid JSON')],
+            warnings,
+        };
+    }
+    const root = asRecord(parsed);
+    if (!root) {
+        return {
+            valid: false,
+            errors: [issue('$', 'Graph document root must be a JSON object')],
+            warnings,
+        };
+    }
+    const runtimeIssue = detectRuntimeFormat(root);
+    if (runtimeIssue) {
+        return { valid: false, errors: [runtimeIssue], warnings };
+    }
+    try {
+        const doc = deserialize(graph);
+        const structural = collectStructuralIssues(doc);
+        errors.push(...structural.errors);
+        warnings.push(...structural.warnings);
+    }
+    catch (err) {
+        errors.push(issue('$', err instanceof Error ? err.message : 'Graph document failed validation'));
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+    };
+}
+function normalizeConceptInputs(input) {
+    const usedIds = new Set();
+    return input.map((item) => {
+        if (typeof item === 'string') {
+            const id = newElementId('n', usedIds);
+            usedIds.add(id);
+            return { id, label: item };
+        }
+        const id = item.id ?? newElementId('n', usedIds);
+        if (usedIds.has(id)) {
+            throw new Error(`Duplicate concept id "${id}" in build_graph input`);
+        }
+        usedIds.add(id);
+        return { id, label: item.text, elaboration: item.elaboration };
+    });
+}
+function resolveConceptRef(ref, concepts) {
+    const byId = concepts.find((c) => c.id === ref);
+    if (byId)
+        return byId.id;
+    const byLabel = concepts.filter((c) => c.label === ref);
+    if (byLabel.length === 1)
+        return byLabel[0].id;
+    if (byLabel.length > 1) {
+        throw new Error(`Ambiguous concept reference "${ref}" — multiple concepts share that label`);
+    }
+    throw new Error(`Unknown concept reference "${ref}" — use an id or unique label`);
+}
+function buildDagreGraph(concepts, relations) {
+    const g = new dagre.graphlib.Graph();
+    g.setDefaultEdgeLabel(() => ({}));
+    g.setGraph({ rankdir: 'LR', nodesep: 80, ranksep: 120 });
+    for (const concept of concepts) {
+        g.setNode(concept.id, { width: NODE_WIDTH, height: NODE_HEIGHT });
+    }
+    for (const rel of relations) {
+        if (g.hasNode(rel.source) && g.hasNode(rel.target)) {
+            g.setEdge(rel.source, rel.target);
+        }
+    }
+    dagre.layout(g);
+    return g;
+}
+function dagreNodePosition(layout) {
+    if (layout?.x === undefined || layout?.y === undefined)
+        return null;
+    return { x: layout.x - NODE_WIDTH / 2, y: layout.y - NODE_HEIGHT / 2 };
+}
+function gridFallbackPosition(index) {
+    const col = index % 4;
+    const row = Math.floor(index / 4);
+    return { x: col * 250, y: row * 120 };
+}
+function layoutConceptPositions(concepts, relations) {
+    const positions = new Map();
+    const g = buildDagreGraph(concepts, relations);
+    for (const concept of concepts) {
+        const pos = dagreNodePosition(g.node(concept.id));
+        if (pos)
+            positions.set(concept.id, pos);
+    }
+    let fallbackIndex = 0;
+    for (const concept of concepts) {
+        if (positions.has(concept.id))
+            continue;
+        positions.set(concept.id, gridFallbackPosition(fallbackIndex));
+        fallbackIndex += 1;
+    }
+    return positions;
+}
+/** Build a valid Nesso graph document from structured agent input. */
+export function buildGraphDocument(input) {
+    const resolvedConcepts = normalizeConceptInputs(input.concepts);
+    const relations = input.relations.map((rel) => ({
+        source: resolveConceptRef(rel.from, resolvedConcepts),
+        target: resolveConceptRef(rel.to, resolvedConcepts),
+        type: rel.relation,
+    }));
+    const usedEdgeIds = new Set();
+    const documentRelations = relations.map((rel) => ({
+        id: newElementId('e', usedEdgeIds),
+        source: rel.source,
+        target: rel.target,
+        type: rel.type,
+    }));
+    const positions = layoutConceptPositions(resolvedConcepts, relations);
+    const concepts = resolvedConcepts.map((concept) => {
+        const pos = positions.get(concept.id) ?? { x: 0, y: 0 };
+        return {
+            id: concept.id,
+            label: concept.label,
+            x: pos.x,
+            y: pos.y,
+            ...(concept.elaboration !== undefined ? { data: { elaboration: concept.elaboration } } : {}),
+        };
+    });
+    return {
+        vocabulary: { id: VOCABULARY.id, version: VOCABULARY.version },
+        name: input.name,
+        concepts,
+        relations: documentRelations,
+    };
+}
+/** Serialize a built graph document to importable JSON. */
+export function buildGraphJson(input) {
+    return serialize(buildGraphDocument(input));
+}

package/dist/lib/graph-tools.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib/graph-tools.test.js

@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: MIT
+import { describe, expect, it } from 'vitest';
+import { serialize } from '@nesso-how/vocab-learning';
+import { buildGraphDocument, buildGraphJson, newElementId, validateGraphJson, } from './graph-tools.js';
+const validDoc = {
+    vocabulary: { id: '@nesso-how/vocab-learning', version: '0.1.0' },
+    name: 'Demo',
+    concepts: [
+        { id: 'n1', label: 'Cause', x: 0, y: 0 },
+        { id: 'n2', label: 'Effect', x: 250, y: 0 },
+    ],
+    relations: [{ id: 'e1', source: 'n1', target: 'n2', type: 'causes' }],
+};
+describe('validateGraphJson', () => {
+    it('accepts a valid graph document', () => {
+        const result = validateGraphJson(serialize(validDoc));
+        expect(result.valid).toBe(true);
+        expect(result.errors).toEqual([]);
+    });
+    it('rejects invalid JSON', () => {
+        const result = validateGraphJson('{not json');
+        expect(result.valid).toBe(false);
+        expect(result.errors[0]?.message).toMatch(/Invalid JSON/);
+    });
+    it('rejects runtime nodes/edges shape', () => {
+        const result = validateGraphJson(JSON.stringify({
+            nodes: [{ id: 'n1' }],
+            edges: [{ id: 'e1', source: 'n1', target: 'n2' }],
+        }));
+        expect(result.valid).toBe(false);
+        expect(result.errors[0]?.message).toMatch(/concepts\[\] and relations\[\]/);
+    });
+    it('rejects unknown relation types', () => {
+        const result = validateGraphJson(JSON.stringify({
+            name: 'X',
+            concepts: [{ id: 'n1', label: 'A', x: 0, y: 0 }],
+            relations: [{ id: 'e1', source: 'n1', target: 'n1', type: 'not-real' }],
+        }));
+        expect(result.valid).toBe(false);
+        expect(result.errors[0]?.message).toMatch(/unknown relation type/);
+    });
+    it('rejects duplicate concept ids', () => {
+        const result = validateGraphJson(JSON.stringify({
+            name: 'X',
+            concepts: [
+                { id: 'n1', label: 'A', x: 0, y: 0 },
+                { id: 'n1', label: 'B', x: 100, y: 0 },
+            ],
+            relations: [],
+        }));
+        expect(result.valid).toBe(false);
+        expect(result.errors.some((e) => e.message.includes('Duplicate concept id'))).toBe(true);
+    });
+    it('rejects dangling relation endpoints', () => {
+        const result = validateGraphJson(JSON.stringify({
+            name: 'X',
+            concepts: [{ id: 'n1', label: 'A', x: 0, y: 0 }],
+            relations: [{ id: 'e1', source: 'n1', target: 'missing', type: 'causes' }],
+        }));
+        expect(result.valid).toBe(false);
+        expect(result.errors.some((e) => e.path.includes('target'))).toBe(true);
+    });
+    it('warns when relation type is omitted', () => {
+        const result = validateGraphJson(JSON.stringify({
+            name: 'X',
+            concepts: [
+                { id: 'n1', label: 'A', x: 0, y: 0 },
+                { id: 'n2', label: 'B', x: 100, y: 0 },
+            ],
+            relations: [{ id: 'e1', source: 'n1', target: 'n2' }],
+        }));
+        expect(result.valid).toBe(true);
+        expect(result.warnings.some((w) => w.path.includes('type'))).toBe(true);
+    });
+    it('warns when vocabulary is missing', () => {
+        const result = validateGraphJson(JSON.stringify({
+            name: 'X',
+            concepts: [{ id: 'n1', label: 'A', x: 0, y: 0 }],
+            relations: [],
+        }));
+        expect(result.valid).toBe(true);
+        expect(result.warnings.some((w) => w.path === 'vocabulary')).toBe(true);
+    });
+});
+describe('buildGraphDocument', () => {
+    it('builds a document that passes validation', () => {
+        const json = buildGraphJson({
+            name: 'Built',
+            concepts: ['Cause', 'Effect'],
+            relations: [{ from: 'Cause', to: 'Effect', relation: 'causes' }],
+        });
+        const result = validateGraphJson(json);
+        expect(result.valid).toBe(true);
+    });
+    it('resolves from/to by concept id', () => {
+        const doc = buildGraphDocument({
+            name: 'Refs',
+            concepts: [{ id: 'n_alpha', text: 'Alpha' }, 'Beta'],
+            relations: [{ from: 'n_alpha', to: 'Beta', relation: 'enables' }],
+        });
+        expect(doc.relations[0]?.source).toBe('n_alpha');
+        expect(doc.relations[0]?.type).toBe('enables');
+    });
+    it('assigns finite layout coordinates', () => {
+        const doc = buildGraphDocument({
+            name: 'Layout',
+            concepts: ['A', 'B', 'C', 'D'],
+            relations: [
+                { from: 'A', to: 'B', relation: 'causes' },
+                { from: 'B', to: 'C', relation: 'causes' },
+                { from: 'C', to: 'D', relation: 'causes' },
+            ],
+        });
+        for (const concept of doc.concepts) {
+            expect(Number.isFinite(concept.x)).toBe(true);
+            expect(Number.isFinite(concept.y)).toBe(true);
+        }
+        const xs = doc.concepts.map((c) => c.x);
+        expect(new Set(xs).size).toBeGreaterThan(1);
+    });
+    it('includes vocabulary metadata', () => {
+        const doc = buildGraphDocument({
+            name: 'Meta',
+            concepts: ['Only'],
+            relations: [],
+        });
+        expect(doc.vocabulary).toEqual({ id: '@nesso-how/vocab-learning', version: '0.1.0' });
+    });
+    it('rejects ambiguous label references', () => {
+        expect(() => buildGraphDocument({
+            name: 'Ambiguous',
+            concepts: ['Same', 'Same'],
+            relations: [{ from: 'Same', to: 'Same', relation: 'causes' }],
+        })).toThrow(/Ambiguous concept reference/);
+    });
+    it('rejects unknown references', () => {
+        expect(() => buildGraphDocument({
+            name: 'Missing',
+            concepts: ['A'],
+            relations: [{ from: 'A', to: 'Z', relation: 'causes' }],
+        })).toThrow(/Unknown concept reference/);
+    });
+});
+describe('newElementId', () => {
+    it('generates unique ids with the expected prefix', () => {
+        const used = new Set();
+        const id = newElementId('n', used);
+        expect(id.startsWith('n')).toBe(true);
+        expect(id.length).toBe(6);
+        used.add(id);
+        const next = newElementId('n', used);
+        expect(next).not.toBe(id);
+    });
+});

package/dist/starlight-docs.pages.json

@@ -4,13 +4,13 @@
       "slug": "guides/ai-mentor",
       "title": "AI mentor (Socrates)",
       "description": "How the Socratic mentor works, connecting a model, persona, and graph-aware context.",
-      "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** entry in the **status bar** (bottom-left) 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## Connecting a model\n\nThe mentor is **experimental** and runs against any OpenAI-compatible `chat/completions` endpoint. Configure it under **Settings -> AI**: base URL, model, and an optional API key.\n\nThe default targets a local [Ollama](https://ollama.com/) instance (`http://localhost:11434/v1`, model `gemma3:4b`). Install Ollama, pull a model, and the mentor works with nothing leaving your machine. Any hosted OpenAI-compatible endpoint works too; set the API key it expects.\n\nThere is **no built-in in-browser model**. Nesso previously bundled a small WebGPU model, but it was too small and slow to be useful and has been removed. Until a reachable endpoint is configured, the chat input stays disabled and the mentor shows a short setup hint.\n\n### Reaching local Ollama from the hosted app\n\nIf you use the hosted web app over HTTPS, requests to `http://localhost:11434` are allowed (localhost is exempt from mixed-content blocking), but Ollama still rejects the cross-origin request unless you allow the app's origin: start it with `OLLAMA_ORIGINS=https://app.nesso.how` (or run the desktop build, where this does not apply).\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.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 [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`.\n\n## Privacy\n\n- **Local Ollama:** prompts and responses go only to your own machine; nothing leaves the device.\n- **Hosted endpoint:** the system prompt (graph snapshot) and chat history are sent to whichever endpoint you configured, each turn. The usual provider-side logging applies.\n\nYour graph itself always stays on your device regardless of the endpoint."
+      "markdown": "The Socratic mentor is **experimental** and **off by default**. Enable it under **Settings → AI** with the **Mentor** toggle (marked _Experimental_). While off, **Socrates** is hidden from the status bar.\n\nWhen enabled, click **Socrates** in the **status bar** (bottom-left) 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## Connecting a model\n\nConfigure any OpenAI-compatible `chat/completions` endpoint under **Settings → AI**: base URL, model, and an optional API key. Endpoint fields appear only while the mentor toggle is on.\n\nThe default targets a local [Ollama](https://ollama.com/) instance (`http://localhost:11434/v1`, model `gemma3:4b`). Install Ollama, pull a model, and the mentor works with nothing leaving your machine. Any hosted OpenAI-compatible endpoint works too; set the API key it expects.\n\nUntil a reachable endpoint is configured, the chat input stays disabled and the mentor shows a short setup hint.\n\n### Reaching local Ollama from the hosted app\n\nIf you use the hosted web app over HTTPS, requests to `http://localhost:11434` are allowed (localhost is exempt from mixed-content blocking), but Ollama still rejects the cross-origin request unless you allow the app's origin: start it with `OLLAMA_ORIGINS=https://app.nesso.how` (or run the desktop build, where this does not apply).\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.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 [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`.\n\n## Privacy\n\n- **Local Ollama:** prompts and responses go only to your own machine; nothing leaves the device.\n- **Hosted endpoint:** the system prompt (graph snapshot) and chat history are sent to whichever endpoint you configured, each turn. The usual provider-side logging applies.\n\nYour graph itself always stays on your device regardless of the endpoint."
     },
     {
       "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- **Double-click** empty canvas to add a concept at the pointer.\n- **`N`** adds a concept at the viewport centre.\n- **Right-click** empty canvas and choose **Add concept here** to add one at the cursor.\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\nAn empty graph shows a centered **\"Your first concept\"** hint; the double-click still works through it.\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 type properties. Per-type line style and glyph come from `@nesso-how/vocab-learning`; 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- **`⌘A` / `Ctrl+A`** selects every concept and relation in the graph.\n- **Right-click** a concept, relation, or empty canvas for a context menu of the relevant actions (copy/cut/duplicate/delete a concept; flip / delete a relation; paste / add concept / center·fit on the canvas). To change a relation's type, select the edge and pick a new type in the Inspector.\n- **`Del`** or **`Backspace`** deletes the selection (one relation, one concept, or every concept in a marquee). Edges attached to a deleted concept go with it. Delete is also on the right-click menu and the Inspector's action toolbar.\n- **`⌘C` / `Ctrl+C`** copies the selection. Copying concepts also copies relations between them; copying a relation includes its two endpoints. **`⌘X` / `Ctrl+X`** cuts: it copies the selection and removes it in one step. **`⌘V` / `Ctrl+V`** pastes the clipboard with a small offset (right-click **Paste** drops it at the cursor instead). **`⌘D` / `Ctrl+D`** duplicates the selection in place without touching the clipboard. These also live on the right-click menu and the Inspector toolbar.\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\nThe Inspector docks on the **right**, full height between the top bar and the status bar. Its header has a **collapse** control that shrinks it to a slim **rail** (keeping the selection plus a vertical action toolbar) and a **close** control; a docked bottom **action toolbar** offers copy / cut / duplicate / delete for a concept, or flip / delete for a relation.\n\nWhen a concept is selected it shows, top to bottom:\n\n- **Image + title:** the title edits inline (`Enter` commits, `Esc` reverts); the image button opens Commons search (see below).\n- **Memory** _(collapsible):_ the FSRS schedule, read-only — when due, stability (in days), last self-rating, review count (with lapses), and time since the last review.\n- **Definition**, **Examples**, **Notes** — see below.\n- **Relations** _(collapsible):_ outgoing and incoming edges, each connected concept shown with the relation glyph in a chip and the type on the right (incoming dimmed). Click a row to jump to that concept; change a relation's type by selecting the edge.\n\n### Notes fields\n\nThree free-text fields that travel with the concept and feed both the AI mentor and [Review](./review-mode/):\n\n- **Definition:** a one-sentence-ish explanation in your own words.\n- **Examples:** one per line. Press `Shift+Enter` or use the **Add** button to add a new line; press `Backspace` in an empty example to remove that line (unless it's the only one).\n- **Notes:** anything else: caveats, sources, mnemonics.\n\nIn Review, definition and examples appear when you **Reveal** a card so you can check your recall. The AI mentor uses the same fields in its graph snapshot and focal-neighbour context when a concept is selected.\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, on reveal 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## Status bar and search\n\n- The **status bar** along the bottom shows the concept and relation counts. Its right side carries undo / redo, zoom out / in, and center·fit; the **Socrates** entry sits on the left.\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- **Double-click** empty canvas to add a concept at the pointer.\n- **`N`** adds a concept at the viewport centre.\n- **Right-click** empty canvas and choose **Add concept here** to add one at the cursor.\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\nAn empty graph shows a centered **\"Your first concept\"** hint; the double-click still works through it.\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 type properties. Per-type line style and glyph come from `@nesso-how/vocab-learning`; 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- **`⌘A` / `Ctrl+A`** selects every concept and relation in the graph.\n- **Right-click** a concept, relation, or empty canvas for a context menu of the relevant actions (copy/cut/duplicate/delete a concept; flip / delete a relation; paste / add concept / center·fit on the canvas). To change a relation's type, select the edge and pick a new type in the Inspector.\n- **`Del`** or **`Backspace`** deletes the selection (one relation, one concept, or every concept in a marquee). Edges attached to a deleted concept go with it. Delete is also on the right-click menu and the Inspector's action toolbar.\n- **`⌘C` / `Ctrl+C`** copies the selection. Copying concepts also copies relations between them; copying a relation includes its two endpoints. **`⌘X` / `Ctrl+X`** cuts: it copies the selection and removes it in one step. **`⌘V` / `Ctrl+V`** pastes the clipboard with a small offset (right-click **Paste** drops it at the cursor instead). **`⌘D` / `Ctrl+D`** duplicates the selection in place without touching the clipboard. These also live on the right-click menu and the Inspector toolbar.\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\nThe Inspector docks on the **right**, full height between the top bar and the status bar. Its header has a **collapse** control that shrinks it to a slim **rail** (keeping the selection plus a vertical action toolbar) and a **close** control; a docked bottom **action toolbar** offers copy / cut / duplicate / delete for a concept, or flip / delete for a relation.\n\nWhen a concept is selected it shows, top to bottom:\n\n- **Image + title:** the title edits inline (`Enter` commits, `Esc` reverts); the image button opens Commons search (see below).\n- **Memory** _(collapsible):_ the FSRS schedule, read-only — when due, stability (in days), last self-rating, review count (with lapses), and time since the last review.\n- **Definition**, **Examples**, **Notes** — see below.\n- **Relations** _(collapsible):_ outgoing and incoming edges, each connected concept shown with the relation glyph in a chip and the type on the right (incoming dimmed). Click a row to jump to that concept; change a relation's type by selecting the edge.\n\n### Notes fields\n\nThree free-text fields that travel with the concept and feed both the AI mentor and [Review](./review-mode/):\n\n- **Definition:** a one-sentence-ish explanation in your own words.\n- **Examples:** one per line. Press `Shift+Enter` or use the **Add** button to add a new line; press `Backspace` in an empty example to remove that line (unless it's the only one).\n- **Notes:** anything else: caveats, sources, mnemonics.\n\nIn Review, definition and examples appear when you **Reveal** a card so you can check your recall. The AI mentor uses the same fields in its graph snapshot and focal-neighbour context when a concept is selected.\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, on reveal 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## Status bar and search\n\n- The **status bar** along the bottom shows the concept and relation counts. Its right side carries undo / redo, zoom out / in, and center·fit. When the mentor is enabled in **Settings → AI**, the **Socrates** entry appears on the left (see [AI mentor](./ai-mentor/)).\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/embedding-graphs",
@@ -22,13 +22,13 @@
       "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 and runs in any modern browser. The AI mentor is optional and needs an OpenAI-compatible endpoint (see [Picking an AI backend](#picking-an-ai-backend)).\n\n## Desktop app (macOS)\n\nA pre-built alpha installer is published on [GitHub Releases](https://github.com/nesso-how/nesso/releases). Download the universal `.dmg` — it runs on both Apple silicon and Intel Macs — 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\nThe desktop app **updates itself**: on launch it checks GitHub Releases and, when a newer build is available, offers to install it and relaunch. Auto-updates begin once you are on a build that ships the updater (`v0.1.0-alpha.25` or later), so that first version still needs a one-time manual download.\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 is **experimental** and uses any OpenAI-compatible `chat/completions` endpoint: a local [Ollama](https://ollama.com/) instance, an OpenAI-compatible proxy, or a hosted provider. There is no built-in in-browser model, so configure an endpoint under **Settings -> AI** (`⌘,` / `Ctrl+,`) or the mentor stays disabled.\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 setup with Ollama\n\nRun [Ollama](https://ollama.com/) locally, then pull a small instruction-tuned model:\n\n```sh\nollama pull gemma3:4b\n```\n\nIn **Settings -> AI**, set:\n\n- Base URL: `http://localhost:11434/v1`\n- Model: `gemma3:4b` (or `llama3.2:3b`, `qwen3:8b`; 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. Prompts and responses stay on your machine.\n\nWhen using the hosted web app over HTTPS, allow its origin in Ollama so the browser request is not blocked by CORS: start Ollama with `OLLAMA_ORIGINS=https://app.nesso.how`. (Requests to `localhost` are exempt from mixed-content blocking, so only CORS needs configuring.)\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| `⌘A` / `Ctrl+A`        | Select all                     |\n| `⌘X` / `Ctrl+X`        | Cut 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. Graphs are stored in your browser or on your machine (local-first, no account). Optional telemetry and desktop update checks may contact external services; using the AI mentor with a remote endpoint sends prompts to that provider.\n\n## Web app\n\nOpen [app.nesso.how](https://app.nesso.how) in your browser. The app works offline after the first load and runs in any modern browser.\n\n## First run\n\nOn a fresh install, Nesso opens with an empty **Tutorial** graph and walks you through the essentials:\n\n1. **Welcome**: a short overview of typed knowledge graphs and spaced repetition.\n2. **Guided tour**: coachmarks on the real UI that walk you through adding and naming concepts, adding a definition in the inspector, connecting two ideas with a typed relation, then opening **Review**.\n3. **Telemetry** (optional): a one-time banner in the top-right asks whether to share anonymous usage events. Declining is remembered; you can change the choice anytime under **Settings → Privacy**.\n\nYou can skip the welcome screen or the tour at any step. Skipping removes the Tutorial graph and opens a demo seed map instead. Completing the tour keeps your Tutorial graph and also opens a demo seed map.\n\nDemo seed graphs are no longer loaded automatically on first launch; you build your first graph during the tour.\n\n## Desktop app (macOS)\n\nA pre-built alpha installer is published on [GitHub Releases](https://github.com/nesso-how/nesso/releases). Download the universal `.dmg` — it runs on both Apple silicon and Intel Macs — 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\nThe desktop app **updates itself**: on launch it checks GitHub Releases and, when a newer build is available, offers to install it and relaunch. Auto-updates begin once you are on a build that ships the updater (`v0.1.0-alpha.25` or later), so that first version still needs a one-time manual download.\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\nSee [AI mentor (Socrates)](./ai-mentor/) for setup, persona, context, and privacy. Quick path with local Ollama:\n\nRun [Ollama](https://ollama.com/) locally, then pull a small instruction-tuned model:\n\n```sh\nollama pull gemma3:4b\n```\n\nIn **Settings → AI**, turn on **Mentor**, then set:\n\n- Base URL: `http://localhost:11434/v1`\n- Model: `gemma3:4b` (or `llama3.2:3b`, `qwen3:8b`; 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. Prompts and responses stay on your machine.\n\nWhen using the hosted web app over HTTPS, allow its origin in Ollama so the browser request is not blocked by CORS: start Ollama with `OLLAMA_ORIGINS=https://app.nesso.how`. (Requests to `localhost` are exempt from mixed-content blocking, so only CORS needs configuring.)\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## 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| `⌘A` / `Ctrl+A`        | Select all                     |\n| `⌘X` / `Ctrl+X`        | Cut 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 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 grouped by category id (`taxonomic`, `structural`, … from `RELATION_CATEGORIES` in `@nesso-how/vocab-learning`), with line style, symmetry, and type properties (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner."
+      "markdown": "The `@nesso-how/mcp` package is a [Model Context Protocol](https://modelcontextprotocol.io/) server that gives AI clients access to Nesso documentation, the full relation-type vocabulary, and tools to **build** and **validate** graph documents. Once connected, models can answer questions about how Nesso works, produce importable graph JSON, and check files before writing them back to disk.\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- \"Build a graph about photosynthesis with causes and enables relations\" (uses `build_graph`)\n- \"Validate this graph JSON before I save it\" (uses `validate_graph`)\n\nThe MCP server is **stateless** and does not read or write files. Your client uses its own filesystem tools to read `.json` graph files, passes the contents inline to `validate_graph` or `build_graph`, and writes the result back. Nesso picks up external edits through its normal workspace sync.\n\n### Agent workflow for graph files\n\nA typical end-to-end flow when the client has filesystem access:\n\n1. **Read** the target graph `.json` from the project folder (client filesystem tool).\n2. **Validate** with `validate_graph` — fix any `errors` before saving; review `warnings` (e.g. missing `vocabulary` or relation `type`).\n3. **Build or extend** with `build_graph` when creating a new graph from structured concepts and relations — the tool assigns ids, vocabulary metadata, valid relation types, and layout positions.\n4. **Re-validate** the output with `validate_graph` if the client edited the JSON by hand.\n5. **Write** the JSON back to disk (client filesystem tool). Open or sync the graph in Nesso.\n\nExample prompt:\n\n> Read `graphs/biology.json` in this workspace, validate it with Nesso MCP, then use `build_graph` to add concepts \"Chloroplast\" and \"Glucose\" linked by `produces`, merge the result, re-validate, and write the file back.\n\nYou can also build graphs directly in [app.nesso.how](https://app.nesso.how) or import JSON via **Graph menu → Import JSON**.\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 grouped by category id (`taxonomic`, `structural`, … from `RELATION_CATEGORIES` in `@nesso-how/vocab-learning`), with line style, symmetry, and type properties (transitive, inverse, strength, polarity, cardinality). Use this whenever you need valid type names for graph JSON or explanations for the learner.\n\n### `validate_graph`\n\n**Input:** `{ \"graph\": \"<json string>\" }` — a Nesso graph **document** (`concepts[]`, `relations[]`), not runtime React Flow `nodes`/`edges`.\n\n**Output:** `{ \"valid\": boolean, \"errors\": [{ \"path\", \"message\" }], \"warnings\": [{ \"path\", \"message\" }] }`\n\nRuns envelope and vocabulary validation plus structural checks the deserializer does not cover today: duplicate ids, dangling relation endpoints, unknown relation types. Warnings flag missing `vocabulary` or relation `type` (the app falls back to `causes` at render time).\n\n`valid` is `true` only when `errors` is empty.\n\n### `build_graph`\n\n**Input:**\n\n```json\n{\n  \"name\": \"Photosynthesis\",\n  \"concepts\": [\n    \"Sunlight\",\n    {\n      \"text\": \"Chloroplast\",\n      \"elaboration\": { \"definition\": \"...\", \"examples\": \"...\", \"notes\": \"\" }\n    }\n  ],\n  \"relations\": [{ \"from\": \"Sunlight\", \"to\": \"Chloroplast\", \"relation\": \"enables\" }]\n}\n```\n\n- `concepts` — label strings or objects with optional `id`, `text`, and `elaboration`.\n- `relations` — `from` / `to` match concept `id` or label (must be unambiguous); `relation` must be a valid type id from `get_relation_types`.\n\n**Output:** Pretty-printed graph document JSON ready to write to disk (includes `vocabulary`, generated ids, and dagre layout positions). FSRS review fields and React Flow edge shape (`type: \"nesso\"`, handles) are applied by the app on import, not stored in the file."
     },
     {
       "slug": "guides/review-mode",
@@ -40,7 +40,7 @@
       "slug": "introduction",
       "title": "Introduction",
       "description": "What Nesso is, why it exists, and the principles it is built on.",
-      "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 app for building typed, AI-assisted knowledge graphs 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. Your graph content, definitions, and Socrates conversations never leave your device unless you connect a remote AI endpoint yourself. Optional telemetry (anonymous crash reports and aggregated usage events) is off by default and opt-in from Settings, Privacy; it never includes graph content, chat, or keys. 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."
+      "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 app for building typed, AI-assisted knowledge graphs 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\nAn optional AI mentor, Socrates, can probe what you have built. It asks questions calibrated to your current graph rather than delivering answers. See [AI mentor (Socrates)](./guides/ai-mentor/) for setup and behaviour.\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. Your graph content and definitions stay on your device. Mentor chat is session-only in the app; if you enable the mentor and use a remote AI endpoint, prompts are sent to that provider each turn. Optional telemetry (anonymous crash reports and aggregated usage events) is off by default and opt-in from **Settings → Privacy**; it never includes graph content, chat, or keys. 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.** The mentor talks to any OpenAI-compatible `chat/completions` endpoint. You 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",

package/dist/tools/build-graph.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+export declare function registerBuildGraph(server: McpServer): void;

package/dist/tools/build-graph.js

@@ -0,0 +1,27 @@
+import { buildGraphInputSchema, buildGraphJson } from '../lib/graph-tools.js';
+export function registerBuildGraph(server) {
+    server.registerTool('build_graph', {
+        description: 'Build a valid Nesso graph document JSON from structured concepts and relations. ' +
+            'Assigns ids, vocabulary metadata, relation types, and dagre layout positions. ' +
+            'Returns importable JSON for the client to write to disk.',
+        inputSchema: buildGraphInputSchema,
+    }, async (input) => {
+        try {
+            const json = buildGraphJson(input);
+            return {
+                content: [{ type: 'text', text: json }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: err instanceof Error ? err.message : String(err),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/validate-graph.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from '@modelcontextprotocol/server';
+export declare function registerValidateGraph(server: McpServer): void;

package/dist/tools/validate-graph.js

@@ -0,0 +1,17 @@
+import * as z from 'zod/v4';
+import { validateGraphJson } from '../lib/graph-tools.js';
+export function registerValidateGraph(server) {
+    server.registerTool('validate_graph', {
+        description: 'Validate a Nesso graph document JSON string. Returns valid, errors, and warnings. ' +
+            'Checks envelope shape, vocabulary rules, duplicate ids, dangling relation endpoints, ' +
+            'and known relation types. Use after reading a graph file or before writing one back.',
+        inputSchema: z.object({
+            graph: z.string().describe('Nesso graph document as a JSON string'),
+        }),
+    }, async ({ graph }) => {
+        const result = validateGraphJson(graph);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nesso-how/mcp",
-  "version": "0.1.0-alpha.37",
+  "version": "0.1.0-alpha.38",
   "description": "MCP server exposing Nesso knowledge graph tools to LLM clients",
   "license": "MIT",
   "repository": {
@@ -20,11 +20,13 @@
     "dist"
   ],
   "dependencies": {
+    "dagre": "^0.8.5",
     "zod": "^4.4.3",
     "@modelcontextprotocol/server": "^2.0.0-alpha.2",
-    "@nesso-how/vocab-learning": "0.1.0-alpha.37"
+    "@nesso-how/vocab-learning": "0.1.0-alpha.38"
   },
   "devDependencies": {
+    "@types/dagre": "^0.7.53",
     "@types/node": "^22.0.0",
     "typescript": "~5.8.3"
   },