pathnote 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 shinehyeuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# Pathnote
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+See which notes your AI searched, read and wrote, live on your note graph.
+
+Pathnote is an MCP server for a folder of markdown notes (an Obsidian vault works as is) plus a local viewer page. While Claude, Cursor or another MCP client works in your notes, the viewer draws the path: search hits, the notes it read in order, and the notes it wrote, linked to the notes they came from. Every note the AI creates or edits can be undone from the viewer.
+
+Free, MIT licensed. Runs entirely on your computer; nothing is sent anywhere by Pathnote.
+
+## Try it
+
+You need Node.js 20 or later.
+
+Start with the sample notes so nothing of yours is touched:
+
+```bash
+npx -y pathnote --sample ~/pathnote-sample
+```
+
+### Claude Desktop
+
+Settings → Developer → Edit Config, and add Pathnote to `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "pathnote": {
+      "command": "npx",
+      "args": ["-y", "pathnote", "/Users/you/pathnote-sample"]
+    }
+  }
+}
+```
+
+Restart Claude Desktop, open http://127.0.0.1:4747 in your browser, and ask Claude something like:
+
+> Go through the meeting notes and customer interviews and write next quarter's priorities as a new note.
+
+### Claude Code
+
+```bash
+claude mcp add pathnote -- npx -y pathnote ~/pathnote-sample
+```
+
+### Cursor and other MCP clients
+
+Use the same command: `npx -y pathnote <your notes folder>`.
+
+## The viewer
+
+- http://127.0.0.1:4747 (the next free port if 4747 is taken; the address is printed to the client's MCP log).
+- Several AI sessions on the same folder all report to one viewer.
+- To keep the viewer open while clients come and go: `npx pathnote <folder> --viewer`.
+- **Undo** puts a note back the way it was before the AI changed it. If you edited the note yourself afterwards, Pathnote leaves it alone and says so.
+- **Clear path** clears the drawing, not your notes.
+
+## Tools the AI gets
+
+| Tool | What it does |
+|---|---|
+| `list_notes` | Every note path in the folder |
+| `search_vault` | Notes matching some words, with a snippet each |
+| `read_note` | Full text of one note |
+| `write_note` | Create a note or replace its text (undoable) |
+| `edit_note` | Replace one exact piece of text in a note (undoable) |
+
+Each tool takes an optional `reason`, a short sentence the viewer shows next to the step.
+
+## What Pathnote touches
+
+- Only `.md` files inside the folder you give it. Paths outside it, and `.obsidian`, `.git` and `.trash`, are refused.
+- The text of each note before the AI changed it is kept in `~/.pathnote/` so it can be undone. Delete that folder to clear the history.
+- The viewer only listens on 127.0.0.1 and refuses requests from other websites.
+
+## Development
+
+```bash
+npm install
+npm test
+node bin/pathnote.js examples/sample-vault --viewer
+```

package/bin/pathnote.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// pathnote <vault folder> [--port 4747] [--viewer]
+// pathnote --sample <new folder>   copies the sample notes there, to try Pathnote safely
+//   Started by an MCP client: MCP over stdin/stdout, plus the viewer at http://127.0.0.1:4747
+//   --viewer: only the viewer, for keeping it open while MCP clients come and go
+// stdout belongs to MCP, so every message for people goes to stderr.
+import fs from 'node:fs';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Vault } from '../src/vault.js';
+import { History } from '../src/history.js';
+import { Hub } from '../src/hub.js';
+import { createServer } from '../src/mcp.js';
+
+const pkg = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url)));
+const args = process.argv.slice(2);
+const flag = name => args.includes(name);
+const opt = name => { const i = args.indexOf(name); return i >= 0 ? args[i + 1] : undefined; };
+const folder = args.find((a, i) => !a.startsWith('--') && args[i - 1] !== '--port');
+
+if (flag('--sample')) {
+  if (!folder) { console.error('Usage: pathnote --sample <new folder>'); process.exit(1); }
+  if (fs.existsSync(folder)) { console.error(`Pathnote: "${folder}" already exists. Pick a new folder.`); process.exit(1); }
+  fs.cpSync(new URL('../examples/sample-vault', import.meta.url), folder, { recursive: true });
+  console.error(`Sample notes copied to ${fs.realpathSync(folder)}`);
+  process.exit(0);
+}
+if (!folder || flag('--help')) {
+  console.error(`Pathnote ${pkg.version}\n\nUsage: pathnote <vault folder> [--port 4747] [--viewer]\n       pathnote --sample <new folder>`);
+  process.exit(folder ? 0 : 1);
+}
+if (!fs.existsSync(folder) || !fs.statSync(folder).isDirectory()) {
+  console.error(`Pathnote: "${folder}" is not a folder.`);
+  process.exit(1);
+}
+
+const vault = new Vault(folder);
+const history = new History(vault);
+const hub = new Hub(vault, history, Number(opt('--port')) || 4747);
+const url = await hub.start();
+console.error(`Pathnote ${pkg.version}: vault ${vault.root}\nViewer: ${url}`);
+
+if (!flag('--viewer')) {
+  await createServer({ vault, history, hub, version: pkg.version }).connect(new StdioServerTransport());
+  // The viewer server would keep the process alive after the MCP client quits
+  process.stdin.on('close', () => process.exit(0));
+}

package/examples/sample-vault/Ideas.md

@@ -0,0 +1,5 @@
+# Ideas
+
+- Keyboard-first capture
+- Weekly digest email
+- Templates gallery

package/examples/sample-vault/Meetings/Oct team meeting.md

@@ -0,0 +1,7 @@
+# Oct team meeting
+
+- Onboarding: still no decision. Several people think setup takes too long.
+- Pricing: proposal to drop the monthly-only plan. Parked until we hear from customers.
+- Action: read through [[Customer interviews]] before the next planning session.
+
+Related: [[Weekly review]], [[Budget plan]]

package/examples/sample-vault/Meetings/Weekly review.md

@@ -0,0 +1,3 @@
+# Weekly review
+
+Shipped the new search. Next week: start on onboarding research with [[Oct team meeting]] notes.

package/examples/sample-vault/Product/Budget plan.md

@@ -0,0 +1,3 @@
+# Budget plan
+
+Q1 budget allows one extra contractor for 8 weeks. See [[Product roadmap]].

package/examples/sample-vault/Product/Product roadmap.md

@@ -0,0 +1,8 @@
+# Product roadmap
+
+Next quarter candidates:
+1. Guided onboarding (first-run checklist, import wizard)
+2. Annual pricing
+3. Team spaces
+
+Inputs: [[Customer interviews]], [[Signup metrics]], [[Competitor comparison]]

package/examples/sample-vault/README.md

@@ -0,0 +1,5 @@
+# Sample vault
+
+Example notes for trying Pathnote safely. Ask your AI something like:
+
+"Go through the meeting notes and customer interviews and write next quarter's priorities as a new note."

package/examples/sample-vault/Research/Competitor comparison.md

@@ -0,0 +1,5 @@
+# Competitor comparison
+
+Two competitors ship an import wizard. Both offer annual plans at about 20% off.
+
+See [[Product roadmap]].

package/examples/sample-vault/Research/Customer interviews.md

@@ -0,0 +1,9 @@
+# Customer interviews
+
+Seven interviews in September.
+
+- 5 of 7 said first-time setup was the hardest part.
+- 3 of 7 asked for an annual plan.
+- 2 of 7 compared us with the tools in [[Competitor comparison]].
+
+Raw quotes are collected in [[User feedback]].

package/examples/sample-vault/Research/Signup metrics.md

@@ -0,0 +1,7 @@
+# Signup metrics
+
+- Visit to signup: 4.1%
+- Signup to first note: 38% (this is where most people leave)
+- First note to week-2 active: 61%
+
+Linked from [[Product roadmap]].

package/examples/sample-vault/Research/User feedback.md

@@ -0,0 +1,7 @@
+# User feedback
+
+> "I gave up on importing my notes the first day."
+> "Once it was set up, I used it every day."
+> "I'd pay yearly if it were cheaper than monthly."
+
+Themes: setup friction, price per year. See [[Signup metrics]] for the drop-off numbers.

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "pathnote",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "See which notes your AI searched, read and wrote, live on your note graph. MCP server + local viewer for a markdown folder.",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "obsidian",
+    "markdown",
+    "notes",
+    "claude",
+    "ai",
+    "knowledge-graph"
+  ],
+  "homepage": "https://pathnote.pages.dev",
+  "type": "module",
+  "bin": {
+    "pathnote": "bin/pathnote.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "viewer",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  }
+}

package/src/history.js

@@ -0,0 +1,50 @@
+// Keeps the text a note had before the AI changed it, so each change can be undone.
+// Stored outside the vault (~/.pathnote/<vault id>/history.jsonl) to keep the vault clean.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+
+export class History {
+  constructor(vault) {
+    this.vault = vault;
+    const id = crypto.createHash('sha1').update(vault.root).digest('hex').slice(0, 12);
+    this.file = path.join(os.homedir(), '.pathnote', id, 'history.jsonl');
+  }
+
+  async all() {
+    try {
+      return (await fs.readFile(this.file, 'utf8')).split('\n').filter(Boolean).map(l => JSON.parse(l));
+    } catch (e) {
+      if (e.code === 'ENOENT') return [];
+      throw e;
+    }
+  }
+
+  async append(entry) {
+    await fs.mkdir(path.dirname(this.file), { recursive: true });
+    await fs.appendFile(this.file, JSON.stringify(entry) + '\n');
+  }
+
+  // Call before changing a note. `before` is null for a note that didn't exist.
+  async record(rel, before, after, kind) {
+    const entry = { id: crypto.randomUUID(), t: Date.now(), path: rel, kind, before, after };
+    await this.append(entry);
+    return entry;
+  }
+
+  // Put the note back the way it was before change `id`. Refuses if someone edited it since,
+  // so a user's own later edits are never thrown away.
+  async undo(id) {
+    const all = await this.all();
+    const entry = all.find(e => e.id === id);
+    if (!entry) throw new Error('No such change.');
+    if (all.some(e => e.undoes === id)) throw new Error('Already undone.');
+    const now = await this.vault.readOrNull(entry.path);
+    if (now !== entry.after) throw new Error(`"${entry.path}" changed after the AI wrote it, so it was left as is.`);
+    if (entry.before === null) await this.vault.remove(entry.path);
+    else await this.vault.write(entry.path, entry.before);
+    await this.append({ id: crypto.randomUUID(), t: Date.now(), path: entry.path, kind: 'undo', undoes: id });
+    return entry;
+  }
+}

package/src/hub.js

@@ -0,0 +1,137 @@
+// Local viewer server: serves the graph page and streams what the AI does to it.
+// Claude Desktop may start several Pathnote processes; the first one for a vault owns the
+// viewer port and the others forward their events to it.
+import http from 'node:http';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PAGE = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'viewer', 'index.html');
+const KEEP = 500;
+
+export class Hub {
+  constructor(vault, history, port) {
+    this.vault = vault;
+    this.history = history;
+    this.port = port;
+    this.events = [];
+    this.clients = new Set();
+    this.forwardTo = null; // port of another process that owns the viewer
+    this.boot = Date.now().toString(36); // with seq, lets the page skip events it already has
+    this.seq = 0;
+  }
+
+  // Own a port for this vault, or find the process that already does. Returns the viewer URL.
+  async start() {
+    for (let port = this.port; port < this.port + 10; port++) {
+      const other = await this.info(port);
+      if (other?.vault === this.vault.root) { this.forwardTo = port; return `http://127.0.0.1:${port}`; }
+      if (other) continue;
+      try {
+        await this.listen(port);
+        this.port = port;
+        return `http://127.0.0.1:${port}`;
+      } catch (e) {
+        if (e.code !== 'EADDRINUSE') throw e;
+      }
+    }
+    throw new Error(`No free port between ${this.port} and ${this.port + 9}.`);
+  }
+
+  async info(port) {
+    try {
+      const res = await fetch(`http://127.0.0.1:${port}/api/info`, { signal: AbortSignal.timeout(500) });
+      const body = await res.json();
+      return body.app === 'pathnote' ? body : null;
+    } catch {
+      return null;
+    }
+  }
+
+  listen(port) {
+    return new Promise((resolve, reject) => {
+      const server = http.createServer((req, res) => this.handle(req, res).catch(e => send(res, 500, { error: e.message })));
+      server.once('error', reject);
+      server.listen(port, '127.0.0.1', () => { this.server = server; resolve(); });
+    });
+  }
+
+  async emit(event, retried = false) {
+    const e = { t: Date.now(), ...event };
+    if (this.forwardTo) {
+      try {
+        await fetch(`http://127.0.0.1:${this.forwardTo}/api/event`, {
+          method: 'POST', headers: { 'Content-Type': 'application/json', Origin: `http://127.0.0.1:${this.forwardTo}` },
+          body: JSON.stringify(e), signal: AbortSignal.timeout(1000)
+        });
+        return;
+      } catch {
+        // The process that owned the viewer has quit: take the port over and keep showing events
+        this.forwardTo = null;
+        if (retried) return;
+        try { await this.start(); } catch { return; }
+        if (this.forwardTo) return this.emit(event, true);
+      }
+    }
+    this.broadcast(e);
+  }
+
+  broadcast(event) {
+    const e = { ...event, key: `${this.boot}:${++this.seq}` };
+    this.events.push(e);
+    if (this.events.length > KEEP) this.events.shift();
+    for (const res of this.clients) res.write(`data: ${JSON.stringify(e)}\n\n`);
+  }
+
+  // Only pages served from this port may call the API, so other websites can't trigger undo.
+  allowed(req) {
+    const hosts = [`127.0.0.1:${this.port}`, `localhost:${this.port}`];
+    if (!hosts.includes(req.headers.host)) return false;
+    const origin = req.headers.origin;
+    return req.method === 'GET' ? !origin || hosts.some(h => origin === `http://${h}`) : hosts.some(h => origin === `http://${h}`);
+  }
+
+  async handle(req, res) {
+    if (!this.allowed(req)) return send(res, 403, { error: 'forbidden' });
+    const url = new URL(req.url, 'http://x');
+    if (req.method === 'GET' && url.pathname === '/') {
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' });
+      return res.end(await fs.readFile(PAGE));
+    }
+    if (req.method === 'GET' && url.pathname === '/api/info') return send(res, 200, { app: 'pathnote', vault: this.vault.root });
+    if (req.method === 'GET' && url.pathname === '/api/graph') return send(res, 200, await this.vault.graph());
+    if (req.method === 'GET' && url.pathname === '/api/events') {
+      res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-store', Connection: 'keep-alive' });
+      for (const e of this.events) res.write(`data: ${JSON.stringify(e)}\n\n`);
+      this.clients.add(res);
+      req.on('close', () => this.clients.delete(res));
+      return;
+    }
+    if (req.method === 'POST' && url.pathname === '/api/event') {
+      this.broadcast(await body(req));
+      return send(res, 200, { ok: true });
+    }
+    if (req.method === 'POST' && url.pathname === '/api/undo') {
+      const { id } = await body(req);
+      try {
+        const entry = await this.history.undo(id);
+        this.broadcast({ t: Date.now(), type: 'undo', path: entry.path, changeId: id, created: entry.before === null });
+        return send(res, 200, { ok: true });
+      } catch (e) {
+        return send(res, 409, { error: e.message });
+      }
+    }
+    send(res, 404, { error: 'not found' });
+  }
+}
+
+function send(res, status, data) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(data));
+}
+
+async function body(req) {
+  let s = '';
+  for await (const chunk of req) { s += chunk; if (s.length > 1e6) throw new Error('too large'); }
+  return JSON.parse(s || '{}');
+}

package/src/mcp.js

@@ -0,0 +1,78 @@
+// The MCP tools the AI uses. Each call does its work and tells the viewer what happened.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+const reason = z.string().optional().describe('One short sentence on why you are doing this. Shown to the user in the Pathnote viewer.');
+const text = s => ({ content: [{ type: 'text', text: s }] });
+const fail = e => ({ content: [{ type: 'text', text: `Error: ${e.message}` }], isError: true });
+
+export function createServer({ vault, history, hub, version }) {
+  const server = new McpServer({ name: 'pathnote', version });
+
+  server.registerTool('list_notes', {
+    title: 'List notes',
+    description: 'List every markdown note in the vault, as paths relative to the vault root.',
+    inputSchema: {}
+  }, async () => {
+    try { return text((await vault.list()).join('\n') || '(no notes)'); } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('search_vault', {
+    title: 'Search notes',
+    description: 'Search the notes for words. Returns the best matching note paths with a snippet each.',
+    inputSchema: { query: z.string().describe('Words to look for'), reason }
+  }, async ({ query, reason }) => {
+    try {
+      const hits = await vault.search(query);
+      await hub.emit({ type: 'search', query, hits: hits.map(h => h.path), reason });
+      return text(hits.length ? hits.map(h => `${h.path}\n  ${h.snippet}`).join('\n') : 'No matches.');
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('read_note', {
+    title: 'Read a note',
+    description: 'Read the full text of a note. Path is relative to the vault root; ".md" is optional.',
+    inputSchema: { path: z.string(), reason }
+  }, async ({ path, reason }) => {
+    try {
+      const body = await vault.read(path);
+      await hub.emit({ type: 'read', path: vault.rel(vault.resolve(path)), reason });
+      return text(body);
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('write_note', {
+    title: 'Write a note',
+    description: 'Create a note, or replace a note\'s whole text. The user can undo this from the Pathnote viewer. Link the notes you used with [[Note name]].',
+    inputSchema: { path: z.string(), content: z.string(), reason }
+  }, async ({ path, content, reason }) => {
+    try {
+      const rel = vault.rel(vault.resolve(path));
+      const before = await vault.readOrNull(rel);
+      const change = await history.record(rel, before, content, before === null ? 'create' : 'write');
+      await vault.write(rel, content);
+      await hub.emit({ type: 'write', path: rel, created: before === null, changeId: change.id, reason });
+      return text(`${before === null ? 'Created' : 'Replaced'} ${rel}.`);
+    } catch (e) { return fail(e); }
+  });
+
+  server.registerTool('edit_note', {
+    title: 'Edit a note',
+    description: 'Replace one exact piece of text in a note. `find` must appear exactly once. The user can undo this from the Pathnote viewer.',
+    inputSchema: { path: z.string(), find: z.string().min(1), replace: z.string(), reason }
+  }, async ({ path, find, replace, reason }) => {
+    try {
+      const rel = vault.rel(vault.resolve(path));
+      const before = await vault.read(rel);
+      const count = before.split(find).length - 1;
+      if (count !== 1) throw new Error(count ? `The text appears ${count} times; include more of it so it is unique.` : 'The text was not found.');
+      const after = before.replace(find, () => replace);
+      const change = await history.record(rel, before, after, 'edit');
+      await vault.write(rel, after);
+      await hub.emit({ type: 'edit', path: rel, changeId: change.id, reason });
+      return text(`Edited ${rel}.`);
+    } catch (e) { return fail(e); }
+  });
+
+  return server;
+}

package/src/vault.js

@@ -0,0 +1,109 @@
+// Read and write markdown notes inside one folder. Every path that comes from the AI is
+// resolved against the vault root and refused if it points outside it or isn't a .md file.
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const SKIP = new Set(['.git', '.obsidian', '.trash', 'node_modules']);
+const LINK = /\[\[([^\]|#]+)(?:#[^\]|]*)?(?:\|[^\]]*)?\]\]/g;
+
+export class Vault {
+  constructor(root) {
+    this.root = path.resolve(root);
+  }
+
+  // "Notes/Plan" or "Notes/Plan.md" -> absolute path, or throw if it escapes the vault
+  resolve(rel) {
+    let p = String(rel || '').trim().replace(/\\/g, '/');
+    if (!p) throw new Error('Note path is empty.');
+    if (!p.toLowerCase().endsWith('.md')) p += '.md';
+    const abs = path.resolve(this.root, p);
+    if (abs !== this.root && !abs.startsWith(this.root + path.sep)) throw new Error(`"${rel}" is outside the vault.`);
+    if (abs.split(path.sep).some(part => SKIP.has(part))) throw new Error(`"${rel}" is in a folder Pathnote does not touch.`);
+    return abs;
+  }
+
+  // Same check after following symlinks, so a link inside the vault can't lead outside it
+  async real(rel) {
+    const abs = this.resolve(rel);
+    const root = await fs.realpath(this.root);
+    let dir = abs;
+    for (;;) {
+      try { dir = await fs.realpath(dir); break; } catch (e) { if (e.code !== 'ENOENT') throw e; dir = path.dirname(dir); }
+    }
+    if (dir !== root && !dir.startsWith(root + path.sep)) throw new Error(`"${rel}" is outside the vault.`);
+    return abs;
+  }
+
+  rel(abs) {
+    return path.relative(this.root, abs).split(path.sep).join('/');
+  }
+
+  async list() {
+    const out = [];
+    const walk = async dir => {
+      for (const e of await fs.readdir(dir, { withFileTypes: true })) {
+        if (e.name.startsWith('.') || SKIP.has(e.name)) continue;
+        const abs = path.join(dir, e.name);
+        if (e.isDirectory()) await walk(abs);
+        else if (e.name.toLowerCase().endsWith('.md')) out.push(this.rel(abs));
+      }
+    };
+    await walk(this.root);
+    return out.sort();
+  }
+
+  async read(rel) {
+    return fs.readFile(await this.real(rel), 'utf8');
+  }
+
+  // Current text, or null when the note doesn't exist yet
+  async readOrNull(rel) {
+    try { return await this.read(rel); } catch (e) { if (e.code === 'ENOENT') return null; throw e; }
+  }
+
+  async write(rel, text) {
+    const abs = await this.real(rel);
+    await fs.mkdir(path.dirname(abs), { recursive: true });
+    await fs.writeFile(abs, text, 'utf8');
+  }
+
+  async remove(rel) {
+    await fs.rm(await this.real(rel), { force: true });
+  }
+
+  // Notes ranked by how often the query's words appear, title matches counted extra
+  async search(query, limit = 10) {
+    const words = String(query).toLowerCase().split(/\s+/).filter(Boolean);
+    if (!words.length) return [];
+    const hits = [];
+    for (const rel of await this.list()) {
+      const text = await this.read(rel);
+      const lower = text.toLowerCase(), name = rel.toLowerCase();
+      let score = 0;
+      for (const w of words) {
+        score += lower.split(w).length - 1;
+        if (name.includes(w)) score += 5;
+      }
+      if (!score) continue;
+      const at = Math.max(0, lower.indexOf(words.find(w => lower.includes(w)) ?? words[0]));
+      const snippet = text.slice(Math.max(0, at - 60), at + 140).replace(/\s+/g, ' ').trim();
+      hits.push({ path: rel, score, snippet });
+    }
+    return hits.sort((a, b) => b.score - a.score).slice(0, limit);
+  }
+
+  // Nodes and [[wikilink]] edges for the viewer. Links resolve by file name, like Obsidian.
+  async graph() {
+    const notes = await this.list();
+    const byName = new Map(notes.map(n => [path.posix.basename(n, '.md').toLowerCase(), n]));
+    const edges = [];
+    for (const n of notes) {
+      const text = await this.read(n);
+      for (const m of text.matchAll(LINK)) {
+        const target = byName.get(path.posix.basename(m[1].trim()).toLowerCase());
+        if (target && target !== n) edges.push([n, target]);
+      }
+    }
+    return { nodes: notes, edges };
+  }
+}

package/viewer/index.html

@@ -0,0 +1,318 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Pathnote</title>
+<style>
+:root {
+  --bg: #ffffff; --surface: #f5f5f7; --ink: #1d1d1f; --muted: #6e6e73; --line: #d2d2d7; --node: #c7c7cc;
+  --accent: #0066cc; --accent-soft: rgba(0, 102, 204, 0.12); --warn: #b3261e;
+  --font: "SF Pro Text", system-ui, -apple-system, BlinkMacSystemFont, "Apple SD Gothic Neo", Inter, sans-serif;
+  --mono: ui-monospace, "SF Mono", Menlo, monospace;
+  color-scheme: light;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --bg: #000; --surface: #1d1d1f; --ink: #f5f5f7; --muted: #a1a1a6; --line: #3a3a3c; --node: #48484a;
+    --accent: #2997ff; --accent-soft: rgba(41, 151, 255, 0.16); --warn: #ff6b5b; color-scheme: dark; }
+}
+* { box-sizing: border-box; }
+[hidden] { display: none !important; }
+html, body { height: 100%; margin: 0; }
+body { background: var(--bg); color: var(--ink); font: 400 14px/1.43 var(--font); display: flex; flex-direction: column; }
+.bar { display: flex; align-items: center; gap: 12px; padding: 10px 16px; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
+.bar strong { font-weight: 600; }
+.vault { color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; flex: 1; }
+.chip { display: inline-flex; align-items: center; gap: 6px; font-size: 12px; padding: 4px 10px; border-radius: 9999px; background: var(--surface); color: var(--muted); }
+.chip i { width: 6px; height: 6px; border-radius: 50%; background: var(--muted); }
+.chip.on { background: var(--accent-soft); color: var(--accent); }
+.chip.on i { background: var(--accent); }
+.main { flex: 1; min-height: 0; display: grid; grid-template-columns: minmax(0, 1fr) 340px; }
+.graph { position: relative; min-width: 0; min-height: 0; border-right: 1px solid var(--line); }
+svg { display: block; width: 100%; height: 100%; cursor: grab; touch-action: none; }
+svg.drag { cursor: grabbing; }
+.empty { position: absolute; inset: 0; display: grid; place-items: center; color: var(--muted); padding: 24px; text-align: center; pointer-events: none; }
+.log { display: flex; flex-direction: column; min-height: 0; }
+.log h2 { font-size: 14px; font-weight: 600; margin: 0; padding: 10px 16px; border-bottom: 1px solid var(--line); display: flex; justify-content: space-between; align-items: center; }
+ol { list-style: none; margin: 0; padding: 8px 0; flex: 1; min-height: 0; overflow-y: auto; }
+li { padding: 8px 16px; display: grid; grid-template-columns: 1fr auto; gap: 2px 8px; }
+li.now { background: var(--accent-soft); }
+.tool { font: 500 12px var(--mono); color: var(--accent); }
+.undo .tool { color: var(--muted); }
+time { font-size: 12px; color: var(--muted); font-variant-numeric: tabular-nums; }
+.text { grid-column: 1 / -1; overflow-wrap: anywhere; }
+.why { grid-column: 1 / -1; color: var(--muted); }
+.err { grid-column: 1 / -1; color: var(--warn); font-size: 12px; }
+li .btn { grid-column: 1 / -1; justify-self: start; margin-top: 4px; }
+.btn { font: 400 13px/1 var(--font); min-height: 30px; padding: 0 14px; border-radius: 9999px; border: 1px solid var(--accent); background: transparent; color: var(--accent); cursor: pointer; }
+.btn:active { transform: scale(0.95); }
+.btn:focus-visible { outline: 2px solid #0071e3; outline-offset: 2px; }
+.btn:disabled { opacity: .4; cursor: default; }
+.hint { padding: 16px; color: var(--muted); }
+
+.link { stroke: var(--line); stroke-width: 1; }
+.trail { stroke: var(--accent); stroke-width: 2.5; stroke-linecap: round; transition: stroke-dashoffset .6s ease-in-out, opacity .4s; }
+.src { stroke: var(--accent); stroke-width: 1.5; opacity: .6; }
+.node .dot { fill: var(--node); transition: fill .3s; }
+.node text { font: 400 11px var(--font); fill: var(--muted); paint-order: stroke; stroke: var(--bg); stroke-width: 4px; stroke-linejoin: round; pointer-events: none; }
+.node .ring { fill: none; stroke: var(--accent); stroke-width: 1.5; stroke-dasharray: 3 3; opacity: 0; }
+.node.hit .ring { opacity: 1; }
+.node.visited .dot, .node.written .dot { fill: var(--accent); }
+.node.visited text, .node.written text { fill: var(--ink); font-weight: 600; }
+.node.current .pulse { fill: var(--accent); animation: pulse 1.2s ease-out infinite; transform-box: fill-box; transform-origin: center; }
+.node .pulse { opacity: 0; }
+.node.gone { opacity: .25; }
+.node.gone text { text-decoration: line-through; }
+@keyframes pulse { from { transform: scale(1); opacity: .35; } to { transform: scale(3.2); opacity: 0; } }
+@media (max-width: 760px) {
+  .main { grid-template-columns: 1fr; grid-template-rows: 55% 45%; }
+  .graph { border-right: 0; border-bottom: 1px solid var(--line); }
+}
+@media (prefers-reduced-motion: reduce) { * { animation: none !important; transition: none !important; } }
+</style>
+</head>
+<body>
+<div class="bar">
+  <strong>Pathnote</strong>
+  <span class="vault" id="vault"></span>
+  <span class="chip" id="status"><i></i><span id="statusText"></span></span>
+</div>
+<div class="main">
+  <div class="graph">
+    <svg id="g" role="img"></svg>
+    <div class="empty" id="empty" hidden></div>
+  </div>
+  <div class="log">
+    <h2><span id="logTitle"></span><button class="btn" id="clear" type="button"></button></h2>
+    <ol id="log" aria-live="polite"></ol>
+    <p class="hint" id="hint"></p>
+  </div>
+</div>
+<script>
+const ko = (navigator.language || '').toLowerCase().startsWith('ko');
+const L = ko ? {
+  live: '연결됨', off: '연결 끊김', activity: '작업 기록', clear: '경로 지우기', undo: '되돌리기', undone: '되돌림',
+  wait: 'AI가 노트를 검색하거나 읽으면 여기에 기록이 쌓입니다.', empty: '이 폴더에 .md 노트가 없습니다.',
+  hits: n => `${n}개 찾음`, created: '새 노트', graph: '노트 그래프와 AI가 지나간 경로'
+} : {
+  live: 'Live', off: 'Disconnected', activity: 'Activity', clear: 'Clear path', undo: 'Undo', undone: 'undone',
+  wait: 'When the AI searches or reads your notes, it shows up here.', empty: 'No .md notes in this folder.',
+  hits: n => `${n} found`, created: 'new note', graph: 'Note graph with the path the AI took'
+};
+document.documentElement.lang = ko ? 'ko' : 'en';
+document.getElementById('logTitle').textContent = L.activity;
+document.getElementById('clear').textContent = L.clear;
+document.getElementById('hint').textContent = L.wait;
+
+const NS = 'http://www.w3.org/2000/svg';
+const svg = document.getElementById('g');
+svg.setAttribute('aria-label', L.graph);
+const view = el('g'), gLinks = el('g'), gTrail = el('g'), gNodes = el('g');
+view.append(gLinks, gTrail, gNodes);
+svg.append(view);
+const pos = new Map(), nodeEl = new Map();
+let current = null, sources = new Set(), vb = { x: 0, y: 0, w: 1000, h: 700 };
+
+function el(tag, attrs = {}) {
+  const e = document.createElementNS(NS, tag);
+  for (const k in attrs) e.setAttribute(k, attrs[k]);
+  return e;
+}
+const name = p => p.split('/').pop().replace(/\.md$/i, '');
+
+// Small force layout: nodes push apart, links pull together, everything drifts to the middle
+function layout(nodes, edges) {
+  const n = nodes.length, P = nodes.map((_, i) => {
+    const a = i * 2.39996, r = 30 * Math.sqrt(i + 1);
+    return { x: r * Math.cos(a), y: r * Math.sin(a), vx: 0, vy: 0 };
+  });
+  const idx = new Map(nodes.map((id, i) => [id, i]));
+  const E = edges.map(([a, b]) => [idx.get(a), idx.get(b)]);
+  const steps = n > 600 ? 80 : 250;
+  for (let s = 0; s < steps; s++) {
+    const cool = 1 - s / steps;
+    for (let i = 0; i < n; i++) for (let j = i + 1; j < n; j++) {
+      const dx = P[i].x - P[j].x, dy = P[i].y - P[j].y, d2 = dx * dx + dy * dy + 0.01;
+      if (d2 > 90000) continue;
+      const f = 1800 / d2;
+      P[i].vx += dx * f; P[i].vy += dy * f; P[j].vx -= dx * f; P[j].vy -= dy * f;
+    }
+    for (const [a, b] of E) {
+      const dx = P[b].x - P[a].x, dy = P[b].y - P[a].y, d = Math.hypot(dx, dy) + 0.01, f = (d - 90) * 0.02 / d;
+      P[a].vx += dx * f; P[a].vy += dy * f; P[b].vx -= dx * f; P[b].vy -= dy * f;
+    }
+    for (const p of P) {
+      p.vx -= p.x * 0.004; p.vy -= p.y * 0.004;
+      p.x += Math.max(-20, Math.min(20, p.vx)) * cool; p.y += Math.max(-20, Math.min(20, p.vy)) * cool;
+      p.vx *= 0.5; p.vy *= 0.5;
+    }
+  }
+  nodes.forEach((id, i) => pos.set(id, [P[i].x, P[i].y]));
+}
+
+function fit() {
+  const pts = [...pos.values()];
+  if (!pts.length) return;
+  const xs = pts.map(p => p[0]), ys = pts.map(p => p[1]);
+  const pad = 60, x0 = Math.min(...xs) - pad, y0 = Math.min(...ys) - pad;
+  vb = { x: x0, y: y0, w: Math.max(...xs) + pad - x0, h: Math.max(...ys) + pad - y0 };
+  svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+}
+
+function addNode(id) {
+  const [x, y] = pos.get(id);
+  const g = el('g', { class: 'node' });
+  g.append(el('circle', { class: 'pulse', cx: x, cy: y, r: 7 }), el('circle', { class: 'ring', cx: x, cy: y, r: 13 }),
+    el('circle', { class: 'dot', cx: x, cy: y, r: 6 }));
+  const t = el('text', { x, y: y + 22, 'text-anchor': 'middle' });
+  t.textContent = name(id);
+  const title = el('title'); title.textContent = id;
+  g.append(t, title);
+  gNodes.append(g);
+  nodeEl.set(id, g);
+}
+
+async function loadGraph() {
+  const { nodes, edges } = await (await fetch('/api/graph')).json();
+  document.getElementById('empty').hidden = nodes.length > 0;
+  document.getElementById('empty').textContent = L.empty;
+  layout(nodes, edges);
+  for (const [a, b] of edges) {
+    const [x1, y1] = pos.get(a), [x2, y2] = pos.get(b);
+    gLinks.append(el('line', { class: 'link', x1, y1, x2, y2 }));
+  }
+  nodes.forEach(addNode);
+  fit();
+}
+
+function line(cls, a, b, animate) {
+  const [x1, y1] = pos.get(a), [x2, y2] = pos.get(b);
+  const l = el('line', { class: cls, x1, y1, x2, y2 });
+  l.dataset.to = b;
+  if (animate) {
+    const len = Math.hypot(x2 - x1, y2 - y1);
+    l.style.strokeDasharray = len; l.style.strokeDashoffset = len;
+    gTrail.append(l); l.getBoundingClientRect(); l.style.strokeDashoffset = 0;
+  } else gTrail.append(l);
+}
+
+function setCurrent(id) {
+  if (current) nodeEl.get(current)?.classList.remove('current');
+  current = id;
+  nodeEl.get(id)?.classList.add('current');
+}
+
+// A note the AI created: place it next to the notes it read
+function ensureNode(id) {
+  if (pos.has(id)) return;
+  const src = [...sources].map(s => pos.get(s)).filter(Boolean);
+  const cx = src.length ? src.reduce((a, p) => a + p[0], 0) / src.length : vb.x + vb.w / 2;
+  const cy = src.length ? src.reduce((a, p) => a + p[1], 0) / src.length : vb.y + vb.h / 2;
+  pos.set(id, [cx + 50, cy - 40]);
+  addNode(id);
+  document.getElementById('empty').hidden = true;
+}
+
+const logEl = document.getElementById('log');
+function addLog(e, tool, text, live) {
+  document.getElementById('hint').hidden = true;
+  for (const li of logEl.children) li.classList.remove('now');
+  const li = document.createElement('li');
+  if (live) li.classList.add('now');
+  if (e.type === 'undo') li.classList.add('undo');
+  const a = document.createElement('span'); a.className = 'tool'; a.textContent = tool;
+  const tm = document.createElement('time'); tm.textContent = new Date(e.t).toLocaleTimeString();
+  const b = document.createElement('span'); b.className = 'text'; b.textContent = text;
+  li.append(a, tm, b);
+  if (e.reason) { const w = document.createElement('span'); w.className = 'why'; w.textContent = e.reason; li.append(w); }
+  if (e.changeId && e.type !== 'undo') {
+    const btn = document.createElement('button');
+    btn.className = 'btn'; btn.type = 'button'; btn.textContent = L.undo; btn.dataset.change = e.changeId;
+    btn.onclick = async () => {
+      btn.disabled = true;
+      const res = await fetch('/api/undo', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ id: e.changeId }) });
+      if (!res.ok) {
+        const err = document.createElement('span'); err.className = 'err';
+        err.textContent = (await res.json()).error; li.append(err); btn.disabled = false;
+      }
+    };
+    li.append(btn);
+  }
+  logEl.append(li);
+  logEl.scrollTop = logEl.scrollHeight;
+}
+
+function onEvent(e, live) {
+  if (e.type === 'search') {
+    for (const h of e.hits) nodeEl.get(h)?.classList.add('hit');
+    addLog(e, 'search_vault', `"${e.query}" · ${L.hits(e.hits.length)}`, live);
+  } else if (e.type === 'read') {
+    const g = nodeEl.get(e.path);
+    if (g) {
+      if (current && current !== e.path) line('trail', current, e.path, live);
+      g.classList.remove('hit'); g.classList.add('visited');
+      sources.add(e.path); setCurrent(e.path);
+    }
+    addLog(e, 'read_note', e.path, live);
+  } else if (e.type === 'write' || e.type === 'edit') {
+    ensureNode(e.path);
+    for (const s of sources) if (s !== e.path) line('src', s, e.path, live);
+    const g = nodeEl.get(e.path);
+    g.classList.remove('gone'); g.classList.add('written');
+    setCurrent(e.path);
+    addLog(e, e.type === 'write' ? 'write_note' : 'edit_note', e.created ? `${e.path} (${L.created})` : e.path, live);
+  } else if (e.type === 'undo') {
+    if (e.created) {
+      nodeEl.get(e.path)?.classList.add('gone');
+      gTrail.querySelectorAll(`[data-to="${CSS.escape(e.path)}"]`).forEach(l => l.style.opacity = 0);
+    }
+    logEl.querySelectorAll(`[data-change="${e.changeId}"]`).forEach(b => { b.disabled = true; b.textContent = L.undone; });
+    addLog(e, 'undo', e.path, live);
+  }
+}
+
+document.getElementById('clear').onclick = () => {
+  gTrail.textContent = '';
+  for (const g of nodeEl.values()) g.classList.remove('hit', 'visited', 'current', 'written');
+  current = null; sources = new Set();
+};
+
+// Drag to pan, wheel to zoom
+let drag = null;
+svg.addEventListener('pointerdown', e => { drag = { x: e.clientX, y: e.clientY, vb: { ...vb } }; svg.classList.add('drag'); svg.setPointerCapture(e.pointerId); });
+svg.addEventListener('pointermove', e => {
+  if (!drag) return;
+  const k = vb.w / svg.clientWidth;
+  vb.x = drag.vb.x - (e.clientX - drag.x) * k; vb.y = drag.vb.y - (e.clientY - drag.y) * k;
+  svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+});
+svg.addEventListener('pointerup', () => { drag = null; svg.classList.remove('drag'); });
+svg.addEventListener('wheel', e => {
+  e.preventDefault();
+  const k = Math.exp(e.deltaY * 0.0015), r = svg.getBoundingClientRect();
+  const mx = vb.x + (e.clientX - r.left) / r.width * vb.w, my = vb.y + (e.clientY - r.top) / r.height * vb.h;
+  vb = { x: mx - (mx - vb.x) * k, y: my - (my - vb.y) * k, w: vb.w * k, h: vb.h * k };
+  svg.setAttribute('viewBox', `${vb.x} ${vb.y} ${vb.w} ${vb.h}`);
+}, { passive: false });
+
+(async () => {
+  const info = await (await fetch('/api/info')).json();
+  document.getElementById('vault').textContent = info.vault;
+  await loadGraph();
+  const status = document.getElementById('status'), statusText = document.getElementById('statusText');
+  let replay = true;
+  const es = new EventSource('/api/events');
+  es.onopen = () => { status.classList.add('on'); statusText.textContent = L.live; setTimeout(() => { replay = false; }, 300); };
+  es.onerror = () => { status.classList.remove('on'); statusText.textContent = L.off; };
+  const seen = new Set(); // a reconnect replays events the page already showed
+  es.onmessage = m => {
+    const e = JSON.parse(m.data);
+    if (seen.has(e.key)) return;
+    seen.add(e.key);
+    onEvent(e, !replay);
+  };
+  statusText.textContent = L.off;
+})();
+</script>
+</body>
+</html>