@noesis-brain/mcp-server 2.0.1 → 2.1.0

package/dist/tools/index.js

@@ -7,9 +7,12 @@ import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'js-yaml';
 import { NoesisClient, CLIENT_OS, getActivePathFromMap, expandHome } from '../api/NoesisClient.js';
+import { parseNoteReference, resolvePathReference, rootLocalBase } from '../resolve/noteRef.js';
+import { formatRootsList } from '../resolve/rootsFormat.js';
 import { initEmbeddingService, generateEmbedding, generateEmbeddingsBatch } from '../services/embedding.js';
 import { SyncStateManager, determineSyncDirection } from './SyncStateManager.js';
 import { registerNaviTools } from './navis.js';
+import { registerBacklogTools } from './backlog.js';
 import { suggestOtherOsPath } from '../utils/suggestPath.js';
 import { diff3Merge, diffPatch } from 'node-diff3';
 // ============================================
@@ -115,6 +118,37 @@ function detectProjectForFile(filePath, rootPath) {
     const parts = relativePath.split(path.sep);
     return parts[0] || 'Uncategorized';
 }
+/**
+ * Resolve a user-supplied file path to a registered root + relative path,
+ * mirroring the sync resolver (see sync_notes): expand `~` / `%USERPROFILE%`
+ * against this machine's home, resolve to absolute, then prefix-match the input
+ * against each root's active path, preferring the longest (most specific) match.
+ * Returns null if the path isn't inside any known root.
+ *
+ * This is what lets get_note resolve an absolute clipboard path
+ * (e.g. C:\Users\me\Noesis\foo.md) against a tilde-stored cloud root (~/Noesis):
+ * the backend /notes/by-path route does a literal prefix compare and never
+ * expands `~`, so absolute paths can't match cloud roots there — resolving
+ * client-side and calling /notes/by-relative instead sidesteps that.
+ */
+export function resolvePathToRoot(filePath, roots) {
+    const normalizedInput = normalizePath(path.resolve(expandHome(filePath)));
+    let best = null;
+    for (const r of roots) {
+        const rawPath = expandHome(r.path || '');
+        if (!rawPath)
+            continue;
+        const rootPath = normalizePath(path.resolve(rawPath));
+        if (normalizedInput === rootPath || normalizedInput.startsWith(rootPath + '/')) {
+            if (!best || rootPath.length > best.rootPath.length) {
+                best = { id: r.id, rootPath };
+            }
+        }
+    }
+    if (!best)
+        return null;
+    return { rootId: best.id, relativePath: normalizePath(path.relative(best.rootPath, normalizedInput)) };
+}
 /**
  * Get a unique file path by appending -1, -2, etc. if file already exists
  */
@@ -150,6 +184,7 @@ export function registerTools(server, services) {
     }
     // Register Navi management tools
     registerNaviTools(server, client);
+    registerBacklogTools(server, client);
     // Register search_notes tool
     server.tool('search_notes', 'Search your knowledge base using full-text search. Returns relevant notes ranked by BM25 relevance.', {
         query: z.string().describe('Search query (natural language or keywords)'),
@@ -222,7 +257,7 @@ export function registerTools(server, services) {
         };
     });
     // Register get_note tool
-    server.tool('get_note', 'PRIMARY READ TOOL FOR NOESIS NOTES — USE THIS INSTEAD OF the `Read` filesystem tool for ANY path inside a registered Noesis root (paths containing `/.noesis/`, or any path under a directory returned by `list_roots`). The path is a Noesis identifier, not just a filesystem coordinate; the file may not exist on this machine\'s disk but the content always exists in the Noesis cloud and works across machines. This tool is READ-ONLY (no disk write) and is SAFE TO CALL IN PLAN MODE. RECOVERY RULE: if you already called `Read` on a path inside a Noesis-watched root and got "File does not exist", YOUR IMMEDIATE NEXT ACTION IS THIS TOOL with the same path — DO NOT use Glob or Grep to hunt for similar filenames, DO NOT ask the user to disambiguate the path, DO NOT suggest the user typed it wrong. Trigger phrases: "read this note", "summarize this file", "what does X say", "open this", "check this bug report", "review this doc" — when the referenced path is Noesis-tracked, use THIS tool. For a writable local copy (e.g., `Edit`/`Write` operations, git diffs, or any task that needs the file on local disk), use `sync_notes(files: [path])` instead, which materializes the file onto disk at the canonical path. Accepts either a Note ID (`id`) or a file path (`path`).', {
+    server.tool('get_note', 'PRIMARY READ TOOL FOR NOESIS NOTES — USE THIS INSTEAD OF the `Read` filesystem tool for ANY path inside a registered Noesis root. A path is Noesis-tracked if it contains `/.noesis/`, OR sits under a folder named `Noesis` (the cloud root — e.g. `~/Noesis/…`, `%USERPROFILE%\\Noesis\\…`, or `C:\\Users\\<you>\\Noesis\\…`), OR is under any directory returned by `list_roots`. The path is a Noesis identifier, not just a filesystem coordinate; the file may not exist on this machine\'s disk but the content always exists in the Noesis cloud and works across machines — and an ABSOLUTE path resolves here even when the cloud stored the root in tilde form. This tool is READ-ONLY (no disk write) and is SAFE TO CALL IN PLAN MODE. RECOVERY RULE: if `Read` returned "File does not exist" for a `.md` path that looks like a note — especially one under a `.noesis`/`Noesis` folder — YOUR IMMEDIATE NEXT ACTION IS THIS TOOL with the same path. DO NOT use Glob or Grep to hunt for similar filenames, DO NOT ask the user to disambiguate the path, DO NOT suggest the user typed it wrong, and DO NOT conclude the note is missing or on another machine until THIS lookup also fails. Trigger phrases: "read this note", "summarize this file", "what does X say", "open this", "check this bug report", "review this doc" — when the referenced path is Noesis-tracked, use THIS tool. For a writable local copy (e.g., `Edit`/`Write` operations, git diffs, or any task that needs the file on local disk), use `sync_notes(files: [path])` instead, which materializes the file onto disk at the canonical path. Accepts either a Note ID (`id`) or a file path (`path`).', {
         id: z.number().optional().describe('Note ID'),
         path: z.string().optional().describe('File path of the note')
     }, async (args) => {
@@ -236,7 +271,36 @@ export function registerTools(server, services) {
                 isError: true
             };
         }
-        const note = id ? await client.getNote(id) : await client.getNoteByPath(path);
+        let note;
+        if (id) {
+            note = await client.getNote(id);
+        }
+        else {
+            // Unified resolution (M2): the `path` arg also accepts note URLs
+            // (https://…/notes/{id}), noesis://note/{id}, and bare numeric ids.
+            // Real paths resolve locally against ACTIVE + ARCHIVED roots (tilde/
+            // home expansion on both sides, longest prefix, legacy translation
+            // into the vault) — the server by-path route stays as the final
+            // fallback for anything the local context can't place.
+            const ref = parseNoteReference(path);
+            if (ref.kind === 'id') {
+                note = await client.getNote(ref.id);
+            }
+            else {
+                const ctx = await client.getResolverContext();
+                const resolved = resolvePathReference(ctx, ref.path);
+                if (resolved) {
+                    for (const rel of resolved.candidates) {
+                        note = await client.getNoteByRelativePath(resolved.rootId, rel);
+                        if (note)
+                            break;
+                    }
+                }
+                if (!note) {
+                    note = await client.getNoteByPath(path);
+                }
+            }
+        }
         if (!note) {
             return {
                 content: [{
@@ -305,6 +369,170 @@ export function registerTools(server, services) {
                 }]
         };
     });
+    // Register get_note_skim_read tool
+    server.tool('get_note_skim_read', "Read a note's SKIM-READ KEY PARTS — the spans the app's Skim-Read feature surfaces as the gist a reader should focus on. READ-ONLY: it computes the key parts on demand and writes NO marks to the note. Accepts a Note ID (`id`) or a file path (`path`). Use this to inspect what Skim-Read extracts for a note, or when iterating on the Skim-Read feature itself (set `fresh:true` to bypass the 30-min server cache after changing extraction logic). Cost: ~1 LLM call per (content+style+intensity), cached 30 min unless `fresh`. Knobs: `style` (gist|balanced|thorough|structure|keyword|question|inverse), `intensity` (light|normal|heavy), `granularities` (section|paragraph|sentence|keyword), `focusQuestion` (with style='question'), `language`. Returns key parts grouped by granularity with each part's importance (0..1) and a short reason. A note with no skimmable gist (a list/tracker/changelog) may correctly return zero parts. NOTE: this tool calls the in-app AI; if it fails with a quota/503/'AI not configured' error, use `apply_note_skim_read` instead — YOU generate the key parts and the server just persists them (no in-app AI needed).", {
+        id: z.number().optional().describe('Note ID'),
+        path: z.string().optional().describe('File path of the note'),
+        style: z.enum(['gist', 'balanced', 'thorough', 'structure', 'keyword', 'question', 'inverse']).optional()
+            .describe("Reading strategy (default: balanced)"),
+        intensity: z.enum(['light', 'normal', 'heavy']).optional().describe('How many parts to surface (default: normal)'),
+        granularities: z.array(z.enum(['section', 'paragraph', 'sentence', 'keyword'])).optional()
+            .describe('Which granularities to allow (default: all)'),
+        focusQuestion: z.string().optional().describe("Only with style='question': surface only spans relevant to this question"),
+        language: z.string().optional().describe("Note language hint (e.g. 'en', 'zh')"),
+        fresh: z.boolean().optional().describe('Bypass the 30-min server cache and recompute (use when iterating on extraction logic)')
+    }, async (args) => {
+        const { id, path, style, intensity, granularities, focusQuestion, language, fresh } = args;
+        if (!id && !path) {
+            return {
+                content: [{ type: 'text', text: 'Error: Please provide either an id or a path.' }],
+                isError: true
+            };
+        }
+        // Resolve a path to a note id locally first (mirrors get_note) so tilde-stored
+        // roots resolve; then skim-read by id. Fall back to sending the path through.
+        let noteId = id;
+        if (!noteId && path) {
+            const roots = await client.getRoots();
+            const resolved = resolvePathToRoot(path, roots);
+            const note = resolved
+                ? await client.getNoteByRelativePath(resolved.rootId, resolved.relativePath)
+                : await client.getNoteByPath(path);
+            if (note)
+                noteId = note.id;
+        }
+        let result;
+        try {
+            result = await client.getNoteSkimRead(noteId
+                ? { id: noteId, style, intensity, granularities, focusQuestion, language, fresh }
+                : { path, style, intensity, granularities, focusQuestion, language, fresh });
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Skim-Read failed: ${e.message}` }],
+                isError: true
+            };
+        }
+        const meta = `**Note ID:** ${result.noteId} · **kind:** ${result.noteKind} · **parts:** ${result.keyPartCount} · **model:** ${result.model ?? 'n/a'}${result.cached ? ' · cached' : ' · fresh'}`;
+        if (!result.keyParts || result.keyParts.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `# Skim-Read — ${result.title}\n\n${meta}\n\nNo key parts surfaced — this note has no skimmable gist (kind: ${result.noteKind}). For a list / tracker / changelog this is the expected result.`
+                    }]
+            };
+        }
+        const ORDER = ['section', 'paragraph', 'sentence', 'keyword'];
+        const byGran = new Map();
+        for (const kp of result.keyParts) {
+            if (!byGran.has(kp.granularity))
+                byGran.set(kp.granularity, []);
+            byGran.get(kp.granularity).push(kp);
+        }
+        let body = '';
+        for (const g of ORDER) {
+            const items = byGran.get(g);
+            if (!items || items.length === 0)
+                continue;
+            items.sort((a, b) => b.importance - a.importance);
+            body += `\n## ${g.charAt(0).toUpperCase() + g.slice(1)} (${items.length})\n`;
+            for (const kp of items) {
+                const reason = kp.reason ? ` — ${kp.reason}` : '';
+                body += `- [${kp.importance.toFixed(2)}] ${JSON.stringify(kp.quote)}${reason}\n`;
+            }
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Skim-Read — ${result.title}\n\n${meta}\n${body}`
+                }]
+        };
+    });
+    server.tool('apply_note_skim_read', [
+        "Persist Skim-Read KEY PARTS that YOU generate for a note — the Gemini-free fallback for the app's Skim-Read feature when the in-app AI is rate-limited/503/unconfigured. WRITES marks: the server anchors each verbatim quote against the note's authoritative content and persists the matches as `suggested` ai_skim marks (the same marks the Skim-Read panel renders). The server does NO LLM call — it only anchors + persists what you provide.",
+        "",
+        "WORKFLOW: (1) read the note's content (get_note); (2) pick the key parts a reader should focus on to get the gist; (3) call this tool with `id` (or `path`) and `keyParts`; (4) if the result lists `unmatchedQuotes`, FIX those quotes (they weren't found verbatim) and call again.",
+        "",
+        "Each keyPart: { granularity, quote, headingPath?, importance?, reason? }.",
+        "- quote: MUST be copied CHARACTER-FOR-CHARACTER (verbatim) from the note — do NOT paraphrase, fix typos, translate, summarize, or add ellipses. Make it long enough to occur exactly once; if a short phrase repeats, include enough surrounding words to be unique. For a 'section' quote the heading line text; 'sentence' the full sentence; 'paragraph' its first ~12 words; 'keyword' the exact token(s).",
+        "- granularity: section | paragraph | sentence | keyword.",
+        "- importance: 0..1; reserve > 0.8 for the few genuinely load-bearing parts.",
+        "- reason: <= 12 words, plainly what the span says (no hype words).",
+        "- Only quote VISIBLE prose. Never quote inside code fences (```), YAML frontmatter, HTML tags, or a COLLAPSED `<details>` block (one without the `open` attribute).",
+        "- headingPath: ancestor heading texts (top-most first) to disambiguate a repeated quote; [] if unknown.",
+        "Knobs (optional): `style`, `intensity` (light|normal|heavy — bounds how many parts persist), `granularities`, `language`, `model` (provenance label). Re-applying replaces prior un-accepted suggestions; accepted/dismissed marks are preserved.",
+    ].join('\n'), {
+        id: z.number().optional().describe('Note ID'),
+        path: z.string().optional().describe('File path of the note'),
+        keyParts: z.array(z.object({
+            granularity: z.enum(['section', 'paragraph', 'sentence', 'keyword']),
+            quote: z.string().describe('Verbatim slice of the note content (character-for-character)'),
+            headingPath: z.array(z.string()).optional().describe('Ancestor heading texts, top-most first; [] if unknown'),
+            importance: z.number().min(0).max(1).optional().describe('0..1; > 0.8 only for load-bearing parts'),
+            reason: z.string().optional().describe('<= 12 words: plainly what the span says'),
+        })).min(1).describe('The key parts you generated (verbatim quotes from the note)'),
+        style: z.enum(['gist', 'balanced', 'thorough', 'structure', 'keyword', 'question', 'inverse']).optional()
+            .describe('Reading strategy hint (default: balanced)'),
+        intensity: z.enum(['light', 'normal', 'heavy']).optional().describe('Bounds how many parts persist (default: normal)'),
+        granularities: z.array(z.enum(['section', 'paragraph', 'sentence', 'keyword'])).optional()
+            .describe('Which granularities to allow (default: all)'),
+        language: z.string().optional().describe("Note language hint (e.g. 'en', 'zh')"),
+        model: z.string().optional().describe("Provenance label stored on the run (default: 'claude-code')"),
+    }, async (args) => {
+        const { id, path, keyParts, style, intensity, granularities, language, model } = args;
+        if (!id && !path) {
+            return {
+                content: [{ type: 'text', text: 'Error: Please provide either an id or a path.' }],
+                isError: true
+            };
+        }
+        // Resolve a path to a note id locally first (mirrors get_note_skim_read).
+        let noteId = id;
+        if (!noteId && path) {
+            const roots = await client.getRoots();
+            const resolved = resolvePathToRoot(path, roots);
+            const note = resolved
+                ? await client.getNoteByRelativePath(resolved.rootId, resolved.relativePath)
+                : await client.getNoteByPath(path);
+            if (note)
+                noteId = note.id;
+        }
+        let result;
+        try {
+            result = await client.applyNoteSkimRead(noteId
+                ? { id: noteId, keyParts, style, intensity, granularities, language, model }
+                : { path, keyParts, style, intensity, granularities, language, model });
+        }
+        catch (e) {
+            return {
+                content: [{ type: 'text', text: `Apply Skim-Read failed: ${e.message}` }],
+                isError: true
+            };
+        }
+        const lines = [
+            `**Note ID:** ${result.noteId} · **applied:** ${result.keyPartCount}/${result.providedCount} provided · **anchored:** ${result.anchoredCount} · **model:** ${result.model ?? 'n/a'}`,
+        ];
+        if (result.unmatchedQuotes && result.unmatchedQuotes.length > 0) {
+            lines.push('');
+            lines.push(`**${result.unmatchedQuotes.length} quote(s) did NOT anchor (not found verbatim in the note). Fix the exact text and re-apply:**`);
+            for (const q of result.unmatchedQuotes)
+                lines.push(`- ${JSON.stringify(q)}`);
+        }
+        else if (result.keyPartCount > 0) {
+            lines.push('');
+            lines.push('All provided quotes anchored. Open the note in Noesis — the Skim-Read panel now shows these key parts.');
+        }
+        if (result.declined) {
+            lines.push('');
+            lines.push('(Nothing anchored — no suggestions were persisted.)');
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Skim-Read applied — ${result.title}\n\n${lines.join('\n')}`
+                }]
+        };
+    });
     server.tool('get_bookmark_context', 'Read the note content surrounding a specific bookmark/tag. ' +
         'Accepts either a Noesis bookmark URL of the form ' +
         '`https://noesisbrain.com/notes/{id}#bm={uuid}` ' +
@@ -356,7 +584,7 @@ export function registerTools(server, services) {
         return { content: [{ type: 'text', text: lines.join('\n') }] };
     });
     // Register get_chat_session tool
-    server.tool('get_chat_session', 'Get a chat session (conversation) and its main-thread messages by ID. URL pattern: noesisbrain.com/<id>. Scoped to the authenticated user.', {
+    server.tool('get_chat_session', 'Get a chat session (conversation) and its messages by ID. URL pattern: noesisbrain.com/<id>. Includes main-thread messages and Navi Discussion turns (each turn is labeled with the speaker Navi). Scoped to the authenticated user.', {
         id: z.number().describe('Chat session ID'),
         limit: z.number().optional().describe('Max messages to return (default 200, max 500). Returns the latest N messages in chronological order.')
     }, async (args) => {
@@ -381,8 +609,14 @@ export function registerTools(server, services) {
         }
         else {
             for (const m of messages) {
-                const speaker = m.role === 'user' ? 'user' : (navi?.name || 'assistant');
-                out += `\n**${speaker}** · ${m.created_at}\n${m.content}\n`;
+                // Navi Discussion turns carry their own navi_id/navi_name (each
+                // participant speaks under their own persona). Fall back to the
+                // session-level Navi for regular assistant turns.
+                const perTurnName = m.navi_name;
+                const speakerNavi = perTurnName || navi?.name || 'assistant';
+                const speaker = m.role === 'user' ? 'user' : speakerNavi;
+                const tag = m.message_type === 'discussion' ? ' _(discussion)_' : '';
+                out += `\n**${speaker}**${tag} · ${m.created_at}\n${m.content}\n`;
             }
         }
         if (hasMore) {
@@ -457,41 +691,11 @@ export function registerTools(server, services) {
     });
     // Register list_roots tool
     server.tool('list_roots', 'List all watched root directories in the knowledge base.', {}, async () => {
-        const roots = await client.getRoots();
-        if (roots.length === 0) {
-            return {
-                content: [{
-                        type: 'text',
-                        text: 'No root directories configured.'
-                    }]
-            };
-        }
-        // Phase32: each root now has a per-OS path map. Show all configured
-        // entries with an [active] marker on the CLIENT_OS row.
-        const lines = [];
-        let anyMissing = false;
-        roots.forEach((root, index) => {
-            lines.push(`${index + 1}. **${root.name}**`);
-            for (const key of ['win32', 'darwin', 'linux']) {
-                const v = root.local_paths?.[key];
-                const label = key === 'win32' ? 'Windows' : key === 'darwin' ? 'macOS  ' : 'Linux  ';
-                const marker = key === CLIENT_OS ? '  [active]' : '';
-                if (v) {
-                    lines.push(`   ${label}: ${v}${marker}`);
-                }
-                else if (key === CLIENT_OS) {
-                    lines.push(`   ${label}: (not configured for this OS)${marker}`);
-                    anyMissing = true;
-                }
-            }
-            lines.push('');
-        });
-        let text = `Watched directories (${roots.length}):\n\n${lines.join('\n').trimEnd()}`;
-        if (anyMissing) {
-            text += `\n\nTip: roots missing a path for the current OS (${CLIENT_OS}) cannot be used for get_note/sync_notes on this machine. Add the missing path in Noesis Dashboard.`;
-        }
+        // Single-vault (M3): render the vault + any active roots with this
+        // machine's resolved base, plus the archived legacy-translation table.
+        const ctx = await client.getResolverContext();
         return {
-            content: [{ type: 'text', text }]
+            content: [{ type: 'text', text: formatRootsList(ctx) }]
         };
     });
     // Register add_root tool
@@ -799,7 +1003,7 @@ export function registerTools(server, services) {
         };
     });
     // Register sync_notes tool (bidirectional sync)
-    server.tool('sync_notes', 'Bidirectional sync for the listed files. If a `files` path is MISSING LOCALLY but present in the cloud, this materializes the cloud content onto local disk at that path — creating any missing parent directories — and sets a sync baseline so future edits diff correctly. Use this whenever the user references a path inside a registered Noesis root (`list_roots`) and the file is not yet on this machine (e.g., the note was created by Claude Code on another laptop and pushed to Noesis); after the call the file will exist on disk at the canonical path and can be read, edited, and re-pushed normally. If both sides have content and differ, conflicts are detected and reported. Calling without `root` or `files` performs a FULL root scan, which is slow and should only be used for intentional bulk syncs. PLAN-MODE GUIDANCE: This tool writes to disk so plan mode forbids the actual call, but you SHOULD propose calling it as Step 1 of any plan that needs a local file for a Noesis-tracked path that is missing on this machine — DO NOT ask the user "did you mean a different path?" or fall back to filesystem search when the path is inside a registered Noesis root. For read-only intent in plan mode (just reading content), prefer `get_note(path)` instead — it is read-only and plan-safe.', {
+    server.tool('sync_notes', 'Bidirectional sync for the listed files. If a `files` path is MISSING LOCALLY but present in the cloud, this materializes the cloud content onto local disk at that path — creating any missing parent directories — and sets a sync baseline so future edits diff correctly. Use this whenever the user references a path inside a registered Noesis root and the file is not yet on this machine (e.g., the note was created by Claude Code on another laptop and pushed to Noesis); after the call the file will exist on disk at the canonical path and can be read, edited, and re-pushed normally. A path is inside a Noesis root if it contains `/.noesis/`, sits under a folder named `Noesis` (the cloud root — `~/Noesis/…`, `%USERPROFILE%\\Noesis\\…`, `C:\\Users\\<you>\\Noesis\\…`), or is under any directory in `list_roots`; absolute paths work even when the cloud stored the root in tilde form. If both sides have content and differ, conflicts are detected and reported. Calling without `root` or `files` performs a FULL root scan, which is slow and should only be used for intentional bulk syncs. PLAN-MODE GUIDANCE: This tool writes to disk so plan mode forbids the actual call, but you SHOULD propose calling it as Step 1 of any plan that needs a local file for a Noesis-tracked path that is missing on this machine — DO NOT ask the user "did you mean a different path?" or fall back to filesystem search when the path is inside a registered Noesis root. For read-only intent in plan mode (just reading content), prefer `get_note(path)` instead — it is read-only and plan-safe.', {
         root: z.string().optional().describe('Sync only a specific root folder (by name)'),
         files: z.array(z.string()).optional().describe('Sync specific file paths only. IMPORTANT: Use absolute paths (e.g., "C:/projects/docs/file.md"). Relative paths may resolve incorrectly.'),
         dryRun: z.boolean().optional().describe('Preview changes without syncing (default: false)'),
@@ -879,7 +1083,7 @@ export function registerTools(server, services) {
         }
         // Handle specific files sync mode (push-only for specific files)
         if (files && files.length > 0) {
-            return await syncSpecificFiles(files, roots, dryRun, client, force, regenerateMetadata);
+            return await syncSpecificFiles(files, dryRun, client, force, regenerateMetadata);
         }
         // Filter to specific root if requested
         const rootsToSync = root
@@ -904,12 +1108,28 @@ export function registerTools(server, services) {
         };
         // Track files moved to .noesis folder
         const allMovedToNoesis = [];
+        // H4 (F4): the vault IS the notes home, so the "move new files to a
+        // .noesis subfolder" concept is meaningless there — worse, moving files
+        // into dot-folders makes them invisible to future full scans (the
+        // scanner skips dot-dirs) and thus silently clobberable. Identify the
+        // vault so the move-prompt + move-block are skipped for it.
+        const vaultRootId = (await client.getResolverContext()).vaultRootId;
         for (const syncRoot of rootsToSync) {
-            // Check if root path exists
-            if (!fs.existsSync(syncRoot.path)) {
-                result.errors.push(`Root path not found: ${syncRoot.path}`);
+            const isVault = vaultRootId != null && syncRoot.id === vaultRootId;
+            // Fresh-machine bootstrap (M3): a root with a known local path that
+            // doesn't exist on disk yet (e.g. ~/Noesis on a machine that has never
+            // synced) is CREATED, not error-skipped — the sync below then pulls
+            // the cloud notes into it. Roots with NO path for this OS still skip.
+            if (!syncRoot.path || /%[^%/\\]+%/.test(syncRoot.path)) {
+                result.errors.push(!syncRoot.path
+                    ? `Root '${syncRoot.name}' has no local path configured for this OS (${CLIENT_OS}) — skipped.`
+                    : `Root '${syncRoot.name}' has an unexpanded template token in its path (${syncRoot.path}) — fix it in the Noesis Dashboard; skipped.`);
                 continue;
             }
+            if (!fs.existsSync(syncRoot.path)) {
+                fs.mkdirSync(syncRoot.path, { recursive: true });
+                result.details.push({ file: syncRoot.path, action: 'pulled_create', reason: `created local root directory for '${syncRoot.name}' (fresh machine bootstrap)` });
+            }
             // Load sync state for three-way hash comparison
             const stateMgr = new SyncStateManager(syncRoot.path);
             stateMgr.load();
@@ -952,8 +1172,11 @@ export function registerTools(server, services) {
                     }
                 }
             }
-            // If LOCAL ONLY files found and moveNewToNoesis not set, return prompt
-            if (localOnlyFiles.length > 0 && !moveNewToNoesis && !dryRun) {
+            // If LOCAL ONLY files found and moveNewToNoesis not set, return prompt.
+            // H4: NEVER prompt for the vault — new files there just push-create
+            // (falling through to the loop below); moving them into .noesis would
+            // trap them under a dot-dir the scanner can't see.
+            if (localOnlyFiles.length > 0 && !moveNewToNoesis && !dryRun && !isVault) {
                 return {
                     content: [{
                             type: 'text',
@@ -967,9 +1190,10 @@ export function registerTools(server, services) {
                         }]
                 };
             }
-            // If moveNewToNoesis is true and there are LOCAL ONLY files, move them to .noesis
+            // If moveNewToNoesis is true and there are LOCAL ONLY files, move them
+            // to .noesis — but NEVER inside the vault (H4: the dot-folder trap).
             const movedToNoesisFiles = [];
-            if (moveNewToNoesis && localOnlyFiles.length > 0 && !dryRun) {
+            if (moveNewToNoesis && !isVault && localOnlyFiles.length > 0 && !dryRun) {
                 for (const file of localOnlyFiles) {
                     const oldPath = file.path;
                     const fileName = path.basename(oldPath);
@@ -1034,14 +1258,28 @@ export function registerTools(server, services) {
                         }
                     }
                     else if (!localFile && cloudNote) {
-                        // CLOUD ONLY: Pull to local (create)
-                        if (dryRun) {
+                        // CLOUD ONLY (per the local SCAN) — but the scanner skips
+                        // dot-directories, so a note whose rel contains `.noesis/` can be
+                        // absent from localMap while a file DOES exist on disk. H4 (F4):
+                        // never blind-overwrite such a file. Check the real disk state
+                        // first; only a genuinely-absent file is a pure cloud-create.
+                        const localPath = path.join(syncRoot.path, relativePath);
+                        const existsOnDisk = fs.existsSync(localPath);
+                        const diskContent = existsOnDisk ? fs.readFileSync(localPath, 'utf-8') : null;
+                        const diskDiffers = diskContent != null && NoesisClient.computeHash(diskContent) !== cloudNote.hash;
+                        if (existsOnDisk && diskDiffers) {
+                            // Real local edit the scan couldn't see. Preserve it — record a
+                            // conflict instead of clobbering; the user resolves via a
+                            // per-file sync (the resolver reaches dot-rel paths).
+                            result.conflicts.push({ path: relativePath, localModified: '', cloudModified: cloudNote.modified_at });
+                            result.details.push({ file: relativePath, action: 'conflict', reason: 'scan-hidden local edit preserved (under a dot-folder) — sync this file directly to resolve' });
+                        }
+                        else if (dryRun) {
                             result.details.push({ file: relativePath, action: 'pulled_create' });
                             result.pulled.created++;
                         }
                         else {
-                            // Write file locally
-                            const localPath = path.join(syncRoot.path, relativePath);
+                            // Genuinely absent (or byte-identical on disk): safe to write.
                             const localDir = path.dirname(localPath);
                             if (!fs.existsSync(localDir)) {
                                 fs.mkdirSync(localDir, { recursive: true });
@@ -1057,8 +1295,13 @@ export function registerTools(server, services) {
                     }
                     else if (localFile && cloudNote) {
                         // BOTH EXIST: Compare hashes
-                        if (localFile.hash === cloudNote.hash) {
-                            // Same hash: seed baseline and check for metadata enrichment
+                        if (localFile.hash === cloudNote.hash &&
+                            cloudNote.content != null &&
+                            NoesisClient.computeHash(cloudNote.content) === cloudNote.hash) {
+                            // Same hash AND cloud internally consistent: seed baseline + metadata enrichment.
+                            // The computeHash(cloudNote.content) === cloudNote.hash guard defends against a
+                            // "hash-ahead-of-content" divergence (cloud hash matches local but cloud content
+                            // is stale); when detected we fall through to the push/three-way branch below.
                             if (!dryRun && localFile.hash) {
                                 stateMgr.setBaseline(relativePath, { hash: localFile.hash, lastSyncedAt: cloudNote.modified_at }, localFile.content);
                             }
@@ -1098,7 +1341,10 @@ export function registerTools(server, services) {
                             const baselineLastSyncedAt = baselineMeta?.lastSyncedAt;
                             const localMtime = localFile.mtime ? localFile.mtime.getTime() : Date.now();
                             const cloudMtime = new Date(cloudNote.modified_at).getTime();
-                            const direction = force
+                            // Push when forced, OR when we reached this branch with equal hashes (only
+                            // possible via the divergence fall-through above) — determineSyncDirection
+                            // would see equal hashes and skip, so override to repair the stale cloud content.
+                            const direction = (force || localFile.hash === cloudNote.hash)
                                 ? 'push'
                                 : determineSyncDirection(localFile.hash, cloudNote.hash, baselineHash, localMtime, cloudMtime, cloudNote.edited_online_at, baselineLastSyncedAt);
                             if (direction === 'conflict') {
@@ -1734,10 +1980,14 @@ export function registerTools(server, services) {
                 isError: true
             };
         }
-        // 3. If move_file, physically move the file on disk
+        // 3. If move_file, physically move the file on disk.
+        // H5: expandHome first — oldPath is the server-synthesized file_path,
+        // which for the vault is tilde-form (~/Noesis/...), and new_path may be
+        // tilde too. normalizePath does NOT expand ~, so without this the mkdir/
+        // rename would create a literal '~' directory under the process cwd.
         if (move_file) {
-            const normalizedOldPath = normalizePath(oldPath);
-            const normalizedNewPath = normalizePath(new_path);
+            const normalizedOldPath = normalizePath(expandHome(oldPath));
+            const normalizedNewPath = normalizePath(expandHome(new_path));
             try {
                 // Create destination directory
                 fs.mkdirSync(path.dirname(normalizedNewPath), { recursive: true });
@@ -1767,9 +2017,11 @@ export function registerTools(server, services) {
         // 4. Update sync state if applicable
         try {
             const roots = await client.getRootsForSync();
-            // Remove baseline from old root
+            // Remove baseline from old root (expandHome so a tilde-form oldPath
+            // matches an expanded root path — H5).
+            const expandedOld = normalizePath(expandHome(oldPath));
             const oldRoot = roots.find(r => {
-                return normalizePath(oldPath).startsWith(normalizePath(r.path));
+                return expandedOld.startsWith(normalizePath(expandHome(r.path)));
             });
             if (oldRoot && oldRelativePath) {
                 const oldMgr = new SyncStateManager(oldRoot.path);
@@ -1782,8 +2034,8 @@ export function registerTools(server, services) {
             if (newRoot && moveResult.relative_path) {
                 const newMgr = new SyncStateManager(newRoot.path);
                 newMgr.load();
-                // Compute hash from file content if available
-                const filePath = normalizePath(new_path);
+                // Compute hash from file content if available (expandHome for the vault tilde path — H5)
+                const filePath = normalizePath(expandHome(new_path));
                 if (fs.existsSync(filePath)) {
                     const content = fs.readFileSync(filePath, 'utf-8');
                     const hash = NoesisClient.computeHash(content);
@@ -2450,12 +2702,26 @@ function scanMarkdownFiles(rootPath, rootId, rootName, detectProjects = false) {
     scan(rootPath);
     return files;
 }
+/** Adapt a by-relative Note (+ its hash from the root hash map) into CloudNoteRow. */
+export function adaptCloudNote(n, relativePath, hash) {
+    return {
+        id: n.id,
+        relative_path: n.relative_path ?? relativePath,
+        hash,
+        modified_at: n.modified_at ?? new Date(0).toISOString(),
+        content: n.content ?? '',
+        title: n.title ?? null,
+        description: n.description ?? null,
+        keywords: n.keywords ?? null,
+        edited_online_at: n.edited_online_at ?? null,
+    };
+}
 /**
  * Sync specific files by path (single-file or multi-file sync mode)
  * @param force - If true, bypass hash check and always re-sync (useful for metadata regeneration)
  * @param regenerateMetadata - If true, backend AI regenerates all metadata fields, overwriting existing values
  */
-async function syncSpecificFiles(filePaths, roots, dryRun, client, force = false, regenerateMetadata = false) {
+export async function syncSpecificFiles(filePaths, dryRun, client, force = false, regenerateMetadata = false) {
     // Use bidirectional sync result type
     const result = {
         pushed: { created: 0, updated: 0 },
@@ -2469,61 +2735,93 @@ async function syncSpecificFiles(filePaths, roots, dryRun, client, force = false
     const warnings = [];
     // Cache SyncStateManagers per root path
     const syncStateCache = new Map();
-    // Cache cloud notes per root to avoid multiple API calls
-    const cloudNotesCache = new Map();
+    // H3a: hash-first delta sync. Post-migration one root (the vault) holds the
+    // whole corpus (~50MB+), so priming full content per root — the old
+    // getNotesForSync approach — cost the entire corpus on every per-file sync.
+    // Instead cache a lightweight relative_path→hash map per root (KB), and
+    // fetch a single note's full content ONLY for the file being synced, only
+    // when it actually exists in the cloud.
+    const rootHashCache = new Map();
+    const cloudNoteCache = new Map(); // key: `${rootId}::${rel}`
+    // Unified reference resolution (M2): entries may be note URLs, noesis://
+    // ids, bare ids, or paths of ANY OS's shape — including legacy
+    // pre-migration paths translated through archived roots. Materialization
+    // ALWAYS targets the resolver-derived local path for this machine (never
+    // the caller-typed string), which also retires the old empty-root-path →
+    // cwd footgun and the doubled-segment auto-correction heuristic.
+    const resolverCtx = await client.getResolverContext();
     for (const filePath of filePaths) {
-        // Normalize path — with auto-correction for doubled directory segments.
-        // expandHome handles `~/...`, `~\...`, and `%USERPROFILE%\...` (the Windows
-        // display form clients copy from the Noesis frontend) before path.resolve,
-        // which itself doesn't expand `~` or env vars.
-        let normalizedPath = normalizePath(path.resolve(expandHome(filePath)));
-        // Check if resolved path falls inside any known root
-        const inKnownRoot = roots.some(r => normalizedPath.startsWith(normalizePath(path.resolve(r.path))));
-        if (!inKnownRoot) {
-            // Look for consecutive duplicate segments (e.g., md-manager/md-manager)
-            const segments = normalizedPath.split('/');
-            let corrected = false;
-            for (let i = 1; i < segments.length; i++) {
-                if (segments[i] === segments[i - 1]) {
-                    const deduped = [...segments.slice(0, i), ...segments.slice(i + 1)];
-                    const candidate = deduped.join('/');
-                    if (roots.some(r => candidate.startsWith(normalizePath(path.resolve(r.path))))) {
-                        warnings.push(`Auto-corrected doubled path segment "${segments[i]}": ${filePath} -> ${candidate}`);
-                        normalizedPath = candidate;
-                        corrected = true;
-                        break;
-                    }
-                }
+        const ref = parseNoteReference(filePath);
+        let targetRootId = null;
+        let candidates = [];
+        if (ref.kind === 'id') {
+            const idNote = await client.getNote(ref.id).catch(() => undefined);
+            const rel = idNote?.relative_path;
+            const rootId = idNote?.root_id;
+            if (!idNote || rootId == null || !rel) {
+                result.errors.push(`Note not found for id reference: ${filePath}`);
+                result.details.push({ file: filePath, action: 'error', reason: 'Note id not found' });
+                continue;
+            }
+            targetRootId = rootId;
+            candidates = [normalizePath(rel)];
+        }
+        else {
+            const resolved = resolvePathReference(resolverCtx, ref.path);
+            if (resolved) {
+                targetRootId = resolved.rootId;
+                candidates = resolved.candidates.map(c => normalizePath(c));
             }
         }
-        // Check if it's a markdown file (before existence check so cloud-only pulls also validate)
-        if (!normalizedPath.endsWith('.md')) {
+        if (targetRootId === null || candidates.length === 0) {
+            result.errors.push(`Path '${filePath}' is not inside any registered Noesis root (active or archived). Check list_roots, or reference the note by its URL or id instead.`);
+            result.details.push({ file: filePath, action: 'error', reason: 'Not in configured root' });
+            continue;
+        }
+        const ctxRoot = resolverCtx.roots.find(r => r.id === targetRootId);
+        const rootBase = rootLocalBase(resolverCtx, targetRootId);
+        if (!ctxRoot || !rootBase) {
+            result.errors.push(`Root ${targetRootId} has no usable path on this machine (${resolverCtx.clientOs}) — cannot materialize '${filePath}'.`);
+            result.details.push({ file: filePath, action: 'error', reason: 'No local path for root on this OS' });
+            continue;
+        }
+        const matchingRoot = { id: ctxRoot.id, name: ctxRoot.name, path: rootBase };
+        // H3a: fetch the root's lightweight relative_path→hash map (KB), pick the
+        // candidate present in it (collapsed form first; local-only pushes use the
+        // first), then fetch that ONE note's full content lazily — never the whole
+        // corpus. cloudNote===null means the note doesn't exist in the cloud.
+        if (!rootHashCache.has(matchingRoot.id)) {
+            const raw = await client.getNoteHashesByRoot(matchingRoot.id);
+            // Normalize keys the same way candidates are (forward-slash), matching
+            // the pre-H3a cloud-map keying so lookups stay byte-identical.
+            const norm = new Map();
+            for (const [rel, h] of raw)
+                norm.set(normalizePath(rel), h);
+            rootHashCache.set(matchingRoot.id, norm);
+        }
+        const rootHashes = rootHashCache.get(matchingRoot.id);
+        const relativePath = candidates.find(c => rootHashes.has(c)) ?? candidates[0];
+        const normalizedPath = `${matchingRoot.path}/${relativePath}`;
+        // Markdown-only (before existence check so cloud-only pulls also validate)
+        if (!relativePath.endsWith('.md')) {
             result.errors.push(`Not a markdown file: ${filePath}`);
             result.details.push({ file: filePath, action: 'error', reason: 'Not a markdown file' });
             continue;
         }
-        // Check if file exists locally — if not, try pulling from cloud
-        if (!fs.existsSync(normalizedPath)) {
-            const matchingRoot = roots.find(r => normalizedPath.startsWith(normalizePath(path.resolve(r.path))));
-            if (!matchingRoot) {
-                result.errors.push(`File not in any configured root: ${filePath}`);
-                result.details.push({ file: filePath, action: 'error', reason: 'Not in configured root' });
-                continue;
-            }
-            const relativePath = normalizePath(path.relative(matchingRoot.path, normalizedPath));
-            // Fetch cloud notes (cached)
-            if (!cloudNotesCache.has(matchingRoot.id)) {
-                const cloudNotes = await client.getNotesForSync(matchingRoot.id);
-                const cloudMap = new Map();
-                for (const note of cloudNotes) {
-                    if (note.relative_path) {
-                        cloudMap.set(normalizePath(note.relative_path), note);
-                    }
-                }
-                cloudNotesCache.set(matchingRoot.id, cloudMap);
+        // Lazily materialize the single cloud note (content + metadata) only when
+        // the candidate exists in the hash map — the delta-sync payload win.
+        const cloudHash = rootHashes.get(relativePath);
+        let cloudNote = null;
+        if (cloudHash) {
+            const cnKey = `${matchingRoot.id}::${relativePath}`;
+            if (!cloudNoteCache.has(cnKey)) {
+                const n = await client.getNoteByRelativePath(matchingRoot.id, relativePath);
+                cloudNoteCache.set(cnKey, n ? adaptCloudNote(n, relativePath, cloudHash) : null);
             }
-            const cloudNotesMap = cloudNotesCache.get(matchingRoot.id);
-            const cloudNote = cloudNotesMap.get(relativePath);
+            cloudNote = cloudNoteCache.get(cnKey);
+        }
+        // Missing locally — pull from cloud to the VAULT-DERIVED path
+        if (!fs.existsSync(normalizedPath)) {
             if (cloudNote) {
                 // CLOUD ONLY: Pull to local (create)
                 if (dryRun) {
@@ -2531,13 +2829,17 @@ async function syncSpecificFiles(filePaths, roots, dryRun, client, force = false
                     result.pulled.created++;
                 }
                 else {
+                    const rootDirExisted = fs.existsSync(matchingRoot.path);
                     const localDir = path.dirname(normalizedPath);
                     if (!fs.existsSync(localDir)) {
                         fs.mkdirSync(localDir, { recursive: true });
                     }
+                    if (!rootDirExisted) {
+                        warnings.push(`Created local vault/root directory at ${matchingRoot.path} (fresh machine bootstrap).`);
+                    }
                     fs.writeFileSync(normalizedPath, cloudNote.content, 'utf-8');
                     const stats = fs.statSync(normalizedPath);
-                    await client.updateFileMetadata(normalizedPath, stats.size, cloudNote.hash);
+                    await client.updateFileMetadata({ rootId: matchingRoot.id, relativePath }, stats.size, cloudNote.hash);
                     // Set baseline
                     if (!syncStateCache.has(matchingRoot.path)) {
                         const mgr = new SyncStateManager(matchingRoot.path);
@@ -2551,38 +2853,19 @@ async function syncSpecificFiles(filePaths, roots, dryRun, client, force = false
                 }
             }
             else {
-                result.errors.push(`Path '${filePath}' is inside root '${matchingRoot.name}' but no note at relative path '${relativePath}' exists in the cloud. This is a genuinely missing note — not a stale local cache. Try search_notes or list_notes to find similar paths in this root.`);
+                result.errors.push(`'${filePath}' resolved to root '${matchingRoot.name}' but no note exists at '${candidates.join("' or '")}' in the cloud, and there is no local file at ${normalizedPath}. This is a genuinely missing note — try search_notes or list_notes.`);
                 result.details.push({ file: filePath, action: 'error', reason: 'Not found locally or in cloud' });
             }
             continue;
         }
-        // Find which root this file belongs to
-        const matchingRoot = roots.find(r => normalizedPath.startsWith(normalizePath(path.resolve(r.path))));
-        if (!matchingRoot) {
-            result.errors.push(`Path '${filePath}' is not inside any registered Noesis root. Call list_roots to see what's registered, or use add_root to register a parent directory before syncing this path.`);
-            result.details.push({ file: filePath, action: 'error', reason: 'Not in configured root' });
-            continue;
-        }
         try {
-            // Read local file content
+            // Read local file content. relativePath + cloudNote were resolved above
+            // (H3a) — the outer relativePath equals path.relative(root, normalizedPath)
+            // by construction, and cloudNote is the single fetched note (or null).
             const localContent = fs.readFileSync(normalizedPath, 'utf-8');
             const stats = fs.statSync(normalizedPath);
-            const relativePath = normalizePath(path.relative(matchingRoot.path, normalizedPath));
             const localHash = NoesisClient.computeHash(localContent);
             const localMtime = stats.mtime.getTime();
-            // Get cloud notes for this root (cached)
-            if (!cloudNotesCache.has(matchingRoot.id)) {
-                const cloudNotes = await client.getNotesForSync(matchingRoot.id);
-                const cloudMap = new Map();
-                for (const note of cloudNotes) {
-                    if (note.relative_path) {
-                        cloudMap.set(normalizePath(note.relative_path), note);
-                    }
-                }
-                cloudNotesCache.set(matchingRoot.id, cloudMap);
-            }
-            const cloudNotesMap = cloudNotesCache.get(matchingRoot.id);
-            const cloudNote = cloudNotesMap.get(relativePath);
             // Get or create SyncStateManager for this root
             if (!syncStateCache.has(matchingRoot.path)) {
                 const mgr = new SyncStateManager(matchingRoot.path);
@@ -2618,8 +2901,17 @@ async function syncSpecificFiles(filePaths, roots, dryRun, client, force = false
                     affectedRoots.add(matchingRoot.id);
                 }
             }
-            else if (localHash === cloudNote.hash) {
-                // SAME CONTENT HASH: Check if metadata differs
+            else if (localHash === cloudNote.hash &&
+                cloudNote.content != null &&
+                NoesisClient.computeHash(cloudNote.content) === cloudNote.hash) {
+                // SAME CONTENT HASH (and the cloud is internally consistent): metadata-only diff.
+                // The computeHash(cloudNote.content) === cloudNote.hash guard defends against a
+                // "hash-ahead-of-content" divergence — a cloud row whose stored hash matches local
+                // but whose stored *content* is stale. When detected, we fall through to the push
+                // branch below (which force-pushes on equal hashes) instead of trusting hash-equality
+                // and skipping, so a diverged note can always be repaired. (force is intentionally NOT
+                // part of this gate: a forced re-sync of genuinely-identical content should keep the
+                // original same-hash/metadata behavior, not re-upload the whole body.) Metadata diff:
                 const cloudKeywords = parseCloudKeywords(cloudNote.keywords);
                 const metadataDiffers = (cloudNote.title && cloudNote.title !== localMetadata.title) ||
                     (cloudNote.description && cloudNote.description !== localMetadata.description) ||
@@ -2695,7 +2987,11 @@ async function syncSpecificFiles(filePaths, roots, dryRun, client, force = false
                 const baselineHash = baselineMeta?.hash;
                 const baselineLastSyncedAt = baselineMeta?.lastSyncedAt;
                 const cloudMtime = new Date(cloudNote.modified_at).getTime();
-                const direction = force
+                // Push when forced, OR when we reached this branch with matching hashes — which now
+                // only happens via the divergence/force fall-through above (a cloud row whose hash
+                // matches local but whose content is stale). determineSyncDirection would see equal
+                // hashes and return 'skip', so override it to repair the stale cloud content.
+                const direction = (force || localHash === cloudNote.hash)
                     ? 'push'
                     : determineSyncDirection(localHash, cloudNote.hash, baselineHash, localMtime, cloudMtime, cloudNote.edited_online_at, baselineLastSyncedAt);
                 if (direction === 'conflict') {