@noesis-brain/mcp-server 2.0.0

package/scripts/noesis-sync.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+/**
+ * noesis-sync.mjs — Standalone sync script for Noesis cloud API.
+ * Zero dependencies (Node.js 18+ built-ins only).
+ *
+ * Usage:
+ *   node noesis-sync.mjs                        # auto-detect from CWD
+ *   node noesis-sync.mjs --files a.md b.md      # sync specific files
+ *   node noesis-sync.mjs --root my-notes         # sync a named root
+ *   node noesis-sync.mjs --dry-run               # preview only
+ *
+ * Credentials: reads from ~/.claude/.mcp.json → mcpServers.noesis.env
+ * or env vars NOESIS_API_TOKEN / NOESIS_API_URL.
+ */
+
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync, existsSync, readdirSync } from 'node:fs';
+import { resolve, dirname, basename, relative, join, sep } from 'node:path';
+import { homedir } from 'node:os';
+
+// ── Path helpers ────────────────────────────────────────────────────
+
+/**
+ * Tilde-expand `~/Noesis/...` against this machine's home directory.
+ * Cloud-flow roots store `~` in the DB because the cloud doesn't know each
+ * machine's $HOME — we expand here at sync time. No-op for already-
+ * absolute paths.
+ */
+function expandHome(p) {
+  if (!p) return '';
+  if (p === '~') return homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    return join(homedir(), p.slice(2));
+  }
+  return p;
+}
+
+// ── Config ──────────────────────────────────────────────────────────
+
+function loadCredentials() {
+  // Env vars take priority
+  let token = process.env.NOESIS_API_TOKEN;
+  let url = process.env.NOESIS_API_URL;
+
+  if (token && url) return { token, url };
+
+  // Fall back to ~/.claude/.mcp.json
+  const mcpPath = join(homedir(), '.claude', '.mcp.json');
+  if (!existsSync(mcpPath)) {
+    console.error(`ERROR: No credentials. Set NOESIS_API_TOKEN + NOESIS_API_URL or configure ${mcpPath}`);
+    process.exit(1);
+  }
+  const mcp = JSON.parse(readFileSync(mcpPath, 'utf-8'));
+  const env = mcp?.mcpServers?.noesis?.env;
+  if (!env?.NOESIS_API_TOKEN || !env?.NOESIS_API_URL) {
+    console.error('ERROR: mcpServers.noesis.env missing NOESIS_API_TOKEN or NOESIS_API_URL in', mcpPath);
+    process.exit(1);
+  }
+  return { token: env.NOESIS_API_TOKEN, url: env.NOESIS_API_URL };
+}
+
+// ── HTTP helpers ────────────────────────────────────────────────────
+
+async function api(method, path, body, { token, url }) {
+  const res = await fetch(`${url.replace(/\/$/, '')}${path}`, {
+    method,
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(`API ${method} ${path} → ${res.status}: ${err.error || res.statusText}`);
+  }
+  return res.json();
+}
+
+// ── Hashing (matches NoesisClient.computeHash) ─────────────────────
+
+function computeHash(content) {
+  const normalized = content.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  return createHash('sha256').update(normalized, 'utf8').digest('hex');
+}
+
+// ── Git/root detection (mirrors tools/index.ts) ─────────────────────
+
+function findGitRoot(startPath) {
+  let current = resolve(startPath);
+  while (current !== dirname(current)) {
+    if (existsSync(join(current, '.git'))) return current;
+    current = dirname(current);
+  }
+  return null;
+}
+
+function detectRootFromCwd() {
+  const gitRoot = findGitRoot(process.cwd());
+  if (!gitRoot) return null;
+  return { rootPath: dirname(gitRoot), projectName: basename(gitRoot) };
+}
+
+function detectProjectForFile(filePath, rootPath) {
+  const rel = relative(rootPath, filePath);
+  const parts = rel.split(sep).filter(Boolean);
+  // Walk up from file to find .git
+  let current = resolve(filePath);
+  while (current !== resolve(rootPath) && current !== dirname(current)) {
+    current = dirname(current);
+    if (existsSync(join(current, '.git'))) return basename(current);
+  }
+  return parts[0] || basename(dirname(filePath));
+}
+
+// ── Path normalization ───────────────────────────────────────────────
+
+/**
+ * Normalize a file path: forward slashes + lowercase drive letter on Windows.
+ */
+function normalizePath(p) {
+  let normalized = p.replace(/\\/g, '/');
+  if (normalized.length >= 2 && normalized[1] === ':') {
+    normalized = normalized[0].toLowerCase() + normalized.slice(1);
+  }
+  return normalized;
+}
+
+// ── File scanning ───────────────────────────────────────────────────
+
+function scanMarkdownFiles(rootPath) {
+  const files = [];
+  function walk(dir) {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const full = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (e.name.startsWith('.') && e.name !== '.noesis' && e.name !== '.claude-notes') continue;
+        if (e.name === 'node_modules' || e.name === 'dist' || e.name === '.git') continue;
+        walk(full);
+      } else if (e.name.endsWith('.md')) {
+        files.push(full);
+      }
+    }
+  }
+  walk(rootPath);
+  return files;
+}
+
+// ── Parse YAML frontmatter ──────────────────────────────────────────
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!match) return {};
+  const meta = {};
+  const lines = match[1].split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const keyMatch = lines[i].match(/^(\w[\w-]*):\s*(.*)/);
+    if (!keyMatch) { i++; continue; }
+    const key = keyMatch[1];
+    const inline = keyMatch[2].trim();
+
+    // Block scalar: >-, >, |-, |
+    if (/^[>|]-?$/.test(inline)) {
+      const parts = [];
+      i++;
+      while (i < lines.length && /^\s+/.test(lines[i])) {
+        parts.push(lines[i].trim());
+        i++;
+      }
+      meta[key] = parts.join(inline.startsWith('>') ? ' ' : '\n');
+      continue;
+    }
+
+    // Array: key with no inline value, followed by "  - item" lines
+    if (inline === '') {
+      const items = [];
+      let j = i + 1;
+      while (j < lines.length && /^\s+-\s+/.test(lines[j])) {
+        items.push(lines[j].replace(/^\s+-\s+/, '').trim());
+        j++;
+      }
+      if (items.length > 0) {
+        meta[key] = items;
+        i = j;
+        continue;
+      }
+    }
+
+    // Simple key: value
+    if (inline) {
+      meta[key] = inline.replace(/^["']|["']$/g, '');
+    }
+    i++;
+  }
+  return meta;
+}
+
+// ── Main sync logic ─────────────────────────────────────────────────
+
+async function syncFiles(filePaths, { creds, dryRun, force, rootFilter }) {
+  // Get roots
+  const { roots } = await api('GET', '/api/mcp/roots?forSync=true', null, creds);
+  let targetRoots = roots;
+
+  // Auto-detect or create root if none match
+  const detected = detectRootFromCwd();
+
+  if (rootFilter) {
+    targetRoots = roots.filter(r => r.name.toLowerCase().includes(rootFilter.toLowerCase()));
+    if (targetRoots.length === 0) {
+      console.error(`No root matching "${rootFilter}". Available: ${roots.map(r => r.name).join(', ')}`);
+      process.exit(1);
+    }
+  }
+
+  // If syncing specific files, resolve their roots
+  if (filePaths.length > 0) {
+    return await syncSpecificFiles(filePaths, targetRoots, detected, creds, dryRun, force);
+  }
+
+  // Full root sync — auto-detect from CWD
+  if (!rootFilter && detected) {
+    const match = targetRoots.find(r =>
+      resolve(r.path).toLowerCase() === resolve(detected.rootPath).toLowerCase()
+    );
+    if (match) {
+      targetRoots = [match];
+    } else if (!dryRun) {
+      // Auto-create root
+      console.log(`Creating new root: ${basename(detected.rootPath)} → ${detected.rootPath}`);
+      const { root } = await api('POST', '/api/mcp/roots', {
+        name: basename(detected.rootPath),
+        path: detected.rootPath,
+      }, creds);
+      targetRoots = [{ ...root, last_scanned_at: null }];
+    } else {
+      console.log(`[dry-run] Would create root: ${detected.rootPath}`);
+      return;
+    }
+  }
+
+  if (targetRoots.length === 0) {
+    console.error('No roots to sync. Run from a git repo or specify --root.');
+    process.exit(1);
+  }
+
+  let totalAdded = 0, totalUpdated = 0, totalSkipped = 0;
+
+  for (const root of targetRoots) {
+    // Tilde-expand cloud-flow paths (~/Noesis/...) once at the top of the
+    // loop so all downstream uses see the absolute on-disk path.
+    const rootPath = expandHome(root.path);
+    if (!rootPath) {
+      console.log(`\nSkipping root '${root.name}': no path configured for this OS`);
+      continue;
+    }
+    console.log(`\nSyncing root: ${root.name} (${rootPath})`);
+
+    const mdFiles = scanMarkdownFiles(rootPath);
+    console.log(`  Found ${mdFiles.length} markdown files`);
+
+    // Get existing hashes from cloud
+    const { hashes } = await api('GET', `/api/mcp/roots/${root.id}/hashes`, null, creds);
+
+    let added = 0, updated = 0, skipped = 0;
+
+    for (const filePath of mdFiles) {
+      const content = readFileSync(filePath, 'utf-8');
+      const hash = computeHash(content);
+      const stats = statSync(filePath);
+      const relativePath = normalizePath(relative(rootPath, filePath));
+      const existingHash = hashes[relativePath];
+
+      if (existingHash === hash && !force) { skipped++; continue; }
+      const action = existingHash ? 'update' : 'create';
+
+      if (dryRun) {
+        console.log(`  [dry-run] Would ${action}: ${relativePath}`);
+        action === 'create' ? added++ : updated++;
+        continue;
+      }
+
+      const project = detectProjectForFile(filePath, rootPath);
+      const metadata = parseFrontmatter(content);
+
+      await api('POST', '/api/mcp/notes/upsert', {
+        file: {
+          path: normalizePath(filePath),
+          relativePath,
+          content,
+          hash,
+          mtime: stats.mtime,
+          size: stats.size,
+          rootId: root.id,
+          rootName: root.name,
+          project,
+        },
+        metadata,
+        force,
+      }, creds);
+
+      console.log(`  ${action === 'create' ? '+' : '~'} ${relativePath}`);
+      action === 'create' ? added++ : updated++;
+    }
+
+    console.log(`  Done: +${added} ~${updated} =${skipped}`);
+    totalAdded += added; totalUpdated += updated; totalSkipped += skipped;
+
+    if (!dryRun && (added > 0 || updated > 0)) {
+      await api('POST', '/api/mcp/sync/log', {
+        rootId: root.id,
+        filesScanned: mdFiles.length,
+        filesAdded: added,
+        filesUpdated: updated,
+        filesDeleted: 0,
+        source: 'noesis-sync-script',
+      }, creds);
+    }
+  }
+
+  console.log(`\nTotal: +${totalAdded} ~${totalUpdated} =${totalSkipped}`);
+}
+
+async function syncSpecificFiles(filePaths, roots, detected, creds, dryRun, force) {
+  let added = 0, updated = 0, errors = 0;
+  const affectedRoots = new Map();
+
+  for (const filePath of filePaths) {
+    const absPath = normalizePath(resolve(filePath));
+
+    if (!absPath.endsWith('.md')) {
+      console.error(`  SKIP (not .md): ${filePath}`);
+      errors++; continue;
+    }
+    if (!existsSync(absPath)) {
+      console.error(`  SKIP (not found): ${filePath}`);
+      errors++; continue;
+    }
+
+    // Find matching root (case-insensitive path comparison for Windows)
+    let matchingRoot = roots.find(r => absPath.startsWith(normalizePath(resolve(r.path))));
+
+    if (!matchingRoot && detected) {
+      // Try auto-creating root from CWD detection
+      const existingByPath = roots.find(r =>
+        normalizePath(resolve(r.path)) === normalizePath(resolve(detected.rootPath))
+      );
+      if (existingByPath) {
+        matchingRoot = existingByPath;
+      } else if (!dryRun) {
+        console.log(`Creating root: ${basename(detected.rootPath)} → ${detected.rootPath}`);
+        const { root } = await api('POST', '/api/mcp/roots', {
+          name: basename(detected.rootPath),
+          path: normalizePath(detected.rootPath),
+        }, creds);
+        matchingRoot = root;
+        roots.push(root);
+      }
+    }
+
+    if (!matchingRoot) {
+      console.error(`  SKIP (no root): ${filePath}`);
+      errors++; continue;
+    }
+
+    const content = readFileSync(absPath, 'utf-8');
+    const hash = computeHash(content);
+    const stats = statSync(absPath);
+    const relativePath = normalizePath(relative(matchingRoot.path, absPath));
+    const project = detectProjectForFile(absPath, matchingRoot.path);
+    const metadata = parseFrontmatter(content);
+
+    if (dryRun) {
+      console.log(`  [dry-run] Would sync: ${relativePath} → root "${matchingRoot.name}"`);
+      added++; continue;
+    }
+
+    const result = await api('POST', '/api/mcp/notes/upsert', {
+      file: {
+        path: absPath,
+        relativePath,
+        content,
+        hash,
+        mtime: stats.mtime,
+        size: stats.size,
+        rootId: matchingRoot.id,
+        rootName: matchingRoot.name,
+        project,
+      },
+      metadata,
+      force,
+    }, creds);
+
+    const action = result.action || 'synced';
+    console.log(`  ${action}: ${relativePath}`);
+    action === 'created' ? added++ : updated++;
+
+    // Track for sync log
+    if (!affectedRoots.has(matchingRoot.id)) {
+      affectedRoots.set(matchingRoot.id, { root: matchingRoot, added: 0, updated: 0, scanned: 0 });
+    }
+    const rInfo = affectedRoots.get(matchingRoot.id);
+    rInfo.scanned++;
+    action === 'created' ? rInfo.added++ : rInfo.updated++;
+  }
+
+  // Log sync for each affected root
+  if (!dryRun) {
+    for (const [rootId, info] of affectedRoots) {
+      if (info.added > 0 || info.updated > 0) {
+        await api('POST', '/api/mcp/sync/log', {
+          rootId,
+          filesScanned: info.scanned,
+          filesAdded: info.added,
+          filesUpdated: info.updated,
+          filesDeleted: 0,
+          source: 'noesis-sync-script',
+        }, creds);
+      }
+    }
+  }
+
+  console.log(`\nDone: +${added} ~${updated}${errors ? ` errors:${errors}` : ''}`);
+}
+
+// ── CLI ─────────────────────────────────────────────────────────────
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const force = args.includes('--force');
+const filesIdx = args.indexOf('--files');
+const rootIdx = args.indexOf('--root');
+
+let files = [];
+let rootFilter = null;
+
+if (filesIdx !== -1) {
+  // Collect all args after --files until next flag or end
+  for (let i = filesIdx + 1; i < args.length; i++) {
+    if (args[i].startsWith('--')) break;
+    files.push(args[i]);
+  }
+}
+
+if (rootIdx !== -1 && args[rootIdx + 1]) {
+  rootFilter = args[rootIdx + 1];
+}
+
+// Positional arg that isn't a flag — treat as root name or file
+if (files.length === 0 && !rootFilter) {
+  for (const a of args) {
+    if (a.startsWith('--')) continue;
+    if (a.endsWith('.md')) files.push(a);
+    else rootFilter = a;
+  }
+}
+
+const creds = loadCredentials();
+console.log(`Noesis sync → ${creds.url}`);
+if (dryRun) console.log('[DRY RUN MODE]');
+if (force) console.log('[FORCE MODE]');
+
+syncFiles(files, { creds, dryRun, force, rootFilter }).catch(err => {
+  console.error('Sync failed:', err.message);
+  process.exit(1);
+});

package/skill-templates/noesis-refine-note.md

@@ -0,0 +1,92 @@
+---
+description: Polish a Noesis note's metadata and structure. Use a scope (today/session/catalog/cascade) or pass a specific note to iterate over multiple notes.
+---
+
+Refine Noesis notes: fill missing metadata (title, description, keywords, aliases), tighten structure (heading hierarchy, frontmatter completeness), refresh AI-rated quality and importance scores. Works on a single note or a batch discovered by scope.
+
+## Arguments
+
+$ARGUMENTS
+
+Accepted forms:
+
+- (no args) — ask the user to pick a scope via `AskUserQuestion`.
+- `<path-or-filename>.md` — refine this specific note.
+- `<topic-or-query>` — search for matching notes and offer them to the user.
+- `today` — discover and refine notes referenced in today's conversation logs.
+- `session [id]` — discover and refine notes referenced in a specific session (or the latest).
+- `catalog <name>` — refine all notes in a named Noesis catalog.
+- `cascade <anchor>` — refine the anchor note plus its semantically-similar neighbors.
+- `--limit <N>` — cap how many notes a batch mode processes (default: 15).
+- `--dry-run` — show what would change without writing.
+
+## Workflow
+
+### Step 1 — Parse mode
+
+From `$ARGUMENTS`, determine `MODE` using the first matching rule:
+
+| Priority | Pattern | Mode |
+|---|---|---|
+| 1 | `cascade <anchor>` | CASCADE |
+| 2 | `today` (anywhere) | TODAY |
+| 3 | `catalog <name>` | CATALOG |
+| 4 | `session [<id>]` | SESSION |
+| 5 | Ends in `.md` (path or filename) | SINGLE |
+| 6 | Non-empty string (treated as search query) | SEARCH |
+| 7 | Empty | ASK |
+
+For `ASK`, prompt the user via `AskUserQuestion` with options for each mode and proceed once they pick.
+
+### Step 2 — Discover candidate notes
+
+Cap the candidate list per mode:
+
+- **SINGLE**: just the one note. Resolve filename to a path via `mcp__noesis__search_notes` if needed.
+- **SEARCH**: call `mcp__noesis__search_notes(query)` with the user's query; show the top 10, ask the user to pick one or more.
+- **TODAY**: read `~/.claude/logs/console_*.clog` files dated today, extract note paths and search terms mentioned, deduplicate, cap at `--limit` (default 15).
+- **SESSION**: same as TODAY but scoped to the chosen session UUID (or the latest if unspecified).
+- **CATALOG**: call `mcp__noesis__list_notes(catalog: <name>)`, cap at `--limit` (default 25).
+- **CASCADE**: resolve the anchor note's ID via `mcp__noesis__get_note(path)`, then call `mcp__noesis__find_similar_notes(note_id, limit: --limit ?? 10)`. Include the anchor itself.
+
+Show the discovered list to the user and ask them to confirm or trim before refining. Sort by ascending `quality_score` (worst first) so the most-needed refinement happens first.
+
+### Step 3 — Refine each note sequentially
+
+For each candidate note:
+
+1. **Read current state:** `mcp__noesis__get_note(path|id)` to get the full metadata + content.
+2. **Fill missing metadata:** call `mcp__noesis__enhance_note_metadata(note_id)` with the relevant fields requested (`title`, `description`, `keywords`, `aliases`). The MCP tool uses AI to derive values from the note content. Apply with user approval if the change looks substantial; auto-apply if filling pure gaps (e.g., empty `keywords`).
+3. **Structural suggestions** (light touch — skip if `--dry-run`):
+   - Frontmatter completeness: title / description / keywords / aliases / date / updated / status / importance_score / quality_score.
+   - Heading hierarchy: surface any H3+ without parent H2, or duplicate H1s.
+   - Suggest and apply with `Edit` after user approval per file.
+4. **Refresh scores:** call `mcp__noesis__rate_quality(note_id)` and `mcp__noesis__rate_importance(note_id)` — these run an AI rating pass; track the delta vs the prior values.
+5. **Push:** if anything changed locally, call `mcp__noesis__sync_notes(files: [<absolute path>])` to push.
+
+### Step 4 — Report
+
+Per-note line:
+
+- `refined <path>: metadata filled (Δ desc / kw / aliases), quality <old> → <new>, importance <old> → <new>`
+- `refined <path>: no changes needed`
+- `skipped <path> (<reason>)`
+
+Final tally:
+
+- `Total: T. Refined: R. Score delta: avg +X quality / +Y importance. Skipped: S. Errors: E.`
+
+## Constraints
+
+- Never overwrite a user-authored description with an AI-generated one without confirmation. The MCP tool returns suggestions; you apply them only after the user OKs substantial replacements.
+- Never touch note `content` body text in refinement — only frontmatter and structural markers (headings, list normalization). Body rewrites are out of scope; that's an editing task, not a refinement.
+- One note at a time — sequential, not parallel. Each push uses `sync_notes(files:[...])` so conflicts surface per-note.
+- If a sync push returns conflict, hand off to `/noesis-sync` (which has the conflict-resolution flow embedded) or stop the batch and report.
+
+## Examples
+
+- `/noesis-refine-note c:/path/to/note.md` — refine a single note.
+- `/noesis-refine-note today` — refine notes touched today.
+- `/noesis-refine-note catalog Work` — refine the Work catalog.
+- `/noesis-refine-note cascade c:/path/to/anchor.md` — refine the anchor and its semantic neighbors.
+- `/noesis-refine-note today --dry-run` — preview only.

package/skill-templates/noesis-sync.md

@@ -0,0 +1,110 @@
+---
+description: Sync local Noesis notes with the cloud — pulls web-UI edits, pushes local changes, resolves conflicts inline.
+---
+
+The one-stop sync command for Noesis notes. Discovers notes edited via the Noesis web UI (Quick Fix), pulls them locally first, pushes your local changes, and resolves any conflicts inline with your input.
+
+## Arguments
+
+$ARGUMENTS
+
+Accepted forms:
+- (no args) — auto-scope: sync files edited in this conversation, else the current project root.
+- `--files <absolute-paths>` — push these specific files (still pulls web-UI edits first for the matching root).
+- `<root-name>` — bulk sync the named root (full scan).
+- `--dry-run` — preview all actions without writing anything.
+- `--skip-online-edits` — skip the web-UI-edit pull step (advanced; rarely needed).
+
+## Workflow
+
+CRITICAL: never start backend servers, write temporary scripts, or improvise HTTP calls. The cloud API at noesis-notes.vercel.app is always available through the MCP tool or the bundled script.
+
+### Step 1 — Discover web-UI edits (unless `--skip-online-edits`)
+
+Call `mcp__noesis__list_edited_online_notes` (filter by `root_id` if `$ARGUMENTS` names a root). For each returned note inspect the `localStatus`:
+
+- `unchanged` — local file matches the last sync baseline; pull is safe and silent.
+- `not_on_disk` — file does not exist locally; pull creates it (auto-pull, no conflict possible).
+- `also_modified` — local file has diverged from the baseline. Tell the user the conflict cascade will run for those entries and ask `AskUserQuestion` to confirm before proceeding. If they decline, skip Step 2 for the `also_modified` entries and continue to Step 3 for the rest.
+
+If `list_edited_online_notes` returns an empty list, skip to Step 3.
+
+### Step 2 — Pull web-UI edits
+
+For each pending note from Step 1 (excluding any the user declined), call:
+
+```
+mcp__noesis__sync_notes(files: ["<absolute path = root_path + '/' + relative_path>"])
+```
+
+Process one file at a time so per-file conflicts surface immediately. Track each result for the Step 5 summary.
+
+### Step 3 — Push local changes
+
+Apply scoping:
+
+1. **Specific files just edited in this conversation** → pass `files: [<paths>]` (do NOT sync everything else).
+2. **User passed `--files <paths>`** → use those paths.
+3. **User passed a root name** → pass `root: "<name>"` (slow full scan).
+4. **No context, no args** → pass `root` matching the current project directory if it maps to a registered root; otherwise fall back to `files` of the files edited in this conversation.
+
+Choose the tier:
+
+- **Tier 1 (preferred):** call `mcp__noesis__sync_notes` with the resolved scope (and `dryRun: true` if `--dry-run`).
+- **Tier 2 (MCP unavailable):** run `node "{{NOESIS_MCP_SCRIPT_PATH}}" [args]` — the bundled script reads its token from `~/.claude.json` → `mcpServers.noesis.env.NOESIS_API_TOKEN` and talks to the cloud API directly. Pass the same CLI args (`--files`, `--root`, `--dry-run`).
+- **Tier 3 (no Node.js):** call the cloud HTTPS endpoints directly via `curl`. Read the token from `~/.claude.json` as above.
+  ```bash
+  curl -H "Authorization: Bearer $TOKEN" https://noesis-notes.vercel.app/api/mcp/roots?forSync=true
+  curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
+    https://noesis-notes.vercel.app/api/mcp/notes/upsert \
+    -d '{"file":{"path":"...","relativePath":"...","content":"...","hash":"...","rootId":N,"rootName":"...","project":"..."},"metadata":{}}'
+  ```
+
+### Step 4 — Resolve conflicts inline (if any)
+
+If Step 2 or Step 3 reported `conflicts.length > 0` (Tier C of the bidirectional sync — overlapping hunks that anchor reapply and `node-diff3` could not auto-merge), do this PER conflicting file rather than reporting "run another skill":
+
+1. **Gather three sides:**
+   - **CLOUD** — `mcp__noesis__get_note(id)` (id is in the conflict payload, or resolve via `mcp__noesis__list_notes` filtered to the relative path).
+   - **LOCAL** — `Read` the local file at the resolved absolute path.
+   - **BASE** — read `.noesis/baseline/<relative_path>` under the root. If the baseline file is missing (legacy sync state), tell the user and ask whether to treat as a two-way merge or skip the file.
+
+2. **Classify each pair of overlapping hunks:**
+   - **Trivial overlap** (one side adds, other doesn't touch; or one side is a strict superset) → auto-merge silently with the inclusive result.
+   - **Mixed overlap** → resolve the trivial parts automatically; STOP and ask only about the irreconcilable parts.
+   - **Semantic overlap** (opposing edits, contradictory rewrites) → present the diff and ask via `AskUserQuestion`: `keep-local` / `keep-cloud` / paste merged text. NEVER silently overwrite.
+
+3. **Apply the merge:**
+   - `Write` the merged content to the local file.
+   - Call `mcp__noesis__sync_notes(files: [<absolute path>])` to push the resolved version.
+   - If the push returns 409 (cloud changed since this step started), the cloud was updated concurrently — repeat Step 4 for that file from the top.
+   - After a clean push, call `POST /api/mcp/notes/:id/clear-conflict` (via `Bash` + `curl` with the API token) to clear the cloud `conflict_marker`.
+
+Process one file at a time. Do NOT batch a chosen-text response across multiple files.
+
+### Step 5 — Report
+
+Print one line per file processed:
+
+- `pulled (web-UI edit applied locally)` — Step 2 succeeded with no conflict.
+- `pushed (local change applied to cloud)` — Step 3 succeeded with no conflict.
+- `merged auto for <path>` — Step 4 resolved trivial overlap without user input.
+- `merged by user for <path>` — Step 4 resolved with explicit user choice.
+- `skipped <path> (<reason>)` — user declined, baseline missing, or other.
+
+End with a final tally: `Pulled: N. Pushed: M. Merged: K (auto X / by-user Y). Skipped: Z. Errors: E.`
+
+## Constraints
+
+- Never silently overwrite opposing edits — always present the diff and ask.
+- Never modify cloud-side content directly via `PUT /api/notes/:id` — go through `sync_notes` so the optimistic-concurrency 409 catches concurrent changes.
+- Never strip frontmatter or H1 from either side during merge — preserve verbatim from whichever side wrote them.
+- One file at a time for conflict resolution.
+
+## Examples
+
+- `/noesis-sync` — auto-scope to recent conversation edits or current project root.
+- `/noesis-sync --dry-run` — preview the full flow without writing.
+- `/noesis-sync --files <absolute-path>` — push a specific file (still pulls web-UI edits first).
+- `/noesis-sync <root-name>` — bulk sync a named root.
+- `/noesis-sync --skip-online-edits` — push only, skip the web-UI pull step.