namidb-vault 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NamiDB, Inc.
+
+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

@@ -0,0 +1,226 @@
+# namidb-vault — sync a markdown vault to NamiDB Cloud
+
+A self-contained AI-tool skill that pushes your **local** Obsidian/markdown
+vault to your **NamiDB Cloud** namespace as a real graph, then lets your AI
+tool query it back over MCP. The vault on disk stays the source of truth; the
+cloud graph is a rebuildable index.
+
+Why this beats a plain graph view: because the index lives in a real graph
+database with semantic vector search, you get backlinks, multi-hop neighbor
+traversal, orphan detection, shared-tag clustering, and (with a server-side
+embedder) semantic "find related notes" — all as queries, from any AI tool.
+
+## Install & run
+
+Zero-install with `npx` (recommended) — works in any terminal and inside
+Claude Code / Cursor / Codex:
+
+```bash
+# Get an API key in your NamiDB dashboard (API keys) and export it.
+# NEVER paste the key into chat — keep it in the environment.
+export NAMIDB_API_KEY='nk_live_...'
+
+npx namidb-vault@latest \
+  --vault ./my-notes \
+  --api-url https://api.namidb.com \
+  --namespace my-vault
+```
+
+- `--dry-run` — parse + diff, print the plan, write nothing.
+- `--no-prune` — additive push; never delete cloud notes whose files are gone.
+- `--watch` — live re-sync on file changes (debounced).
+
+**As a Claude Code skill** (so the agent runs it for you, proactively): drop
+this folder into `~/.claude/skills/namidb-vault/` and Claude Code auto-loads
+it — then just say *"sync my vault to namidb"*. See `SKILL.md`.
+
+## What lands in the graph
+
+Faithful to the NamiDB markdown mapping:
+
+| Vault thing | Graph thing |
+| --- | --- |
+| every `.md` / `.markdown` file | a `Note` node (`title`, `path`, `body`, `key`, `body_hash`, + your frontmatter) |
+| `[[wikilink]]`, `[text](note.md)` | `LINKS_TO` edge |
+| `![[embed]]` | `EMBEDS` edge |
+| `#tag`, frontmatter `tags:` | shared `:Tag` node + `:TAGGED` edge |
+| nested tag `area/db` | ancestor `:Tag` + `:SUBTAG_OF` edge |
+| a link to a note that doesn't exist | placeholder `:Note` (`placeholder: true`) |
+
+Name resolution matches the engine: links resolve by **normalized basename**
+with Latin diacritic folding, so `[[User Role]]`, `[[user-role]]` and
+`user_role.md` collapse to one note, and `[[Matías]]` resolves to `matias.md`.
+Links inside fenced/inline code are ignored.
+
+**Embeddings are computed server-side.** This skill pushes note *text* only —
+it never sends vectors and never reads or transmits an embedder API key. After
+each successful sync it **auto-triggers a server-side embed** of the changed
+notes (`POST /v1/embed`), so `vault_search` stays current with no extra step.
+That trigger is best-effort: a missing embedder or an embed error never fails
+the sync (the next sync re-triggers it). Semantic search lights up once you
+configure an embedder on the namespace (in the dashboard → namespace detail →
+**Semantic search**); links/tags/graph lenses work without one. When no embedder
+is configured the sync prints `semantic search off (no embedder configured)`.
+
+## Requirements
+
+- Node.js >= 18 (uses built-in `fetch`, `crypto`, `fs/promises` — **zero npm deps**).
+- A NamiDB project API key with write access to the target namespace.
+
+## Config
+
+Routing config lives in `namidb-vault.config.json` at your vault/repo root
+(copy `namidb-vault.config.example.json`). It holds only non-secret values:
+
+```json
+{
+  "vaultDir": "./vault",
+  "apiUrl": "https://api.namidb.com",
+  "namespace": "my-vault"
+}
+```
+
+The **API key is never stored in the file**. Export it as an environment
+variable:
+
+```bash
+export NAMIDB_API_KEY='your-project-api-key'
+```
+
+The script reads `NAMIDB_API_URL`, `NAMIDB_API_KEY`, and `NAMIDB_NAMESPACE`
+from the environment; CLI flags (`--api-url`, `--namespace`) override them.
+
+## Run it
+
+```bash
+# Dry run — parse + diff, print the plan, write nothing
+node sync.mjs --vault ./vault --dry-run
+
+# Incremental sync (default): upsert notes, prune notes deleted from disk
+node sync.mjs --vault ./vault --api-url https://api.namidb.com --namespace my-vault
+
+# Additive only — never delete cloud notes
+node sync.mjs --vault ./vault --no-prune
+```
+
+Ids are stable per note path (`uuid5` of the relative path), so re-running
+upserts in place — sync is idempotent. A default sync **prunes**: cloud notes
+whose files are gone from disk are `DETACH DELETE`d, and orphaned placeholder
+stubs + unused tags are cleaned up, so the graph stays a faithful mirror.
+Point `--vault` at the right directory before the first run against a
+populated namespace; use `--no-prune` for a purely additive push.
+
+## Live folder sync (`--watch`)
+
+```bash
+node sync.mjs --vault ./vault --watch
+```
+
+Watches the vault recursively and re-syncs on any `.md` change, debounced
+(`--watch-debounce`, default 1500ms) and serialized so overlapping edits
+coalesce into one pass. Each pass is the same incremental + prune sync, so the
+graph tracks the folder live. Leave it running in a terminal while you write.
+
+## Install in your AI tool
+
+All four tools run the **same** `sync.mjs`. Drop this folder somewhere stable
+(e.g. `~/.namidb/skills/namidb-vault/`) and reference it.
+
+### Claude Code
+
+This directory **is** a Claude Code skill — it ships `SKILL.md`. Install it:
+
+```bash
+mkdir -p ~/.claude/skills
+cp -R ./namidb-vault ~/.claude/skills/
+```
+
+Then just ask: "sync my vault" / "push my notes to NamiDB". Claude reads
+`SKILL.md`, finds your config, and runs the sync. (Set `NAMIDB_API_KEY` in
+your shell first.)
+
+### Cursor
+
+Add a project rule that points the agent at the script. In
+`.cursor/rules/namidb-vault.md`:
+
+```md
+When I ask to sync / push / index my vault, run:
+  node ~/.namidb/skills/namidb-vault/sync.mjs --vault <vaultDir> \
+    --api-url <apiUrl> --namespace <namespace>
+The API key is in $NAMIDB_API_KEY — never print it or ask me to paste it.
+Read namidb-vault.config.json for vaultDir/apiUrl/namespace.
+```
+
+### Codex CLI
+
+Add to your `AGENTS.md` (or run directly):
+
+```md
+## Vault sync
+To sync the markdown vault to NamiDB Cloud:
+  node ~/.namidb/skills/namidb-vault/sync.mjs --vault ./vault \
+    --api-url https://api.namidb.com --namespace my-vault
+Key: $NAMIDB_API_KEY (env only, never echoed).
+```
+
+### Kimi (and other agent CLIs)
+
+Any agent that can run a shell command works the same way — there is nothing
+tool-specific in the script:
+
+```bash
+NAMIDB_API_KEY=… node ~/.namidb/skills/namidb-vault/sync.mjs \
+  --vault ./vault --api-url https://api.namidb.com --namespace my-vault
+```
+
+## Query the graph back (hosted MCP)
+
+NamiDB Cloud hosts an MCP server in the gateway, authed by the **same project
+API key**. Point your AI tool's MCP config at it to query the notes you just
+synced — no extra service to run. Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "namidb": {
+      "type": "http",
+      "url": "https://api.namidb.com/v1/mcp",
+      "headers": {
+        "Authorization": "Bearer ${NAMIDB_API_KEY}",
+        "X-NamiDB-Namespace": "my-vault"
+      }
+    }
+  }
+}
+```
+
+Exposed tools (read-only over your namespace): `vault_search` (semantic; needs
+a configured embedder), `backlinks`, `neighbors`, `orphans`, `shared_tags`,
+and `get_note`, plus a raw `cypher` escape hatch. The same lenses the Obsidian
+graph view can draw but cannot query:
+
+```cypher
+-- backlinks of a note (links + embeds)
+MATCH (src:Note)-[:LINKS_TO|:EMBEDS]->(:Note {path: $path}) RETURN DISTINCT src
+
+-- orphans: nothing references them and they reference nothing
+MATCH (n:Note) WHERE NOT EXISTS((n)-[:LINKS_TO|:EMBEDS]-()) RETURN n
+
+-- notes that share a tag
+MATCH (:Note {path: $path})-[:TAGGED]->(:Tag)<-[:TAGGED]-(o:Note) RETURN DISTINCT o
+```
+
+## Notes & limits
+
+- The frontmatter parser handles the shapes vaults actually use (scalars,
+  flow/block lists, one-level maps, last-wins duplicate keys). Deeply nested
+  YAML is JSON-stringified onto the note property (the `:Tag`/`LINKS_TO`
+  relationships carry the structure that matters for queries).
+- List/map frontmatter values are stored as a JSON string on the `Note` (the
+  bulk endpoint rejects nested objects); scalars pass through typed.
+- `body_hash` is a stable per-note change marker (blake2b512 over the file
+  bytes). The server-side embedder compares it to decide which notes to
+  re-embed, so only changed notes are re-embedded. This skill always pushes the
+  full current vault (cheap: a vault is small, and bulk upsert is one commit
+  per chunk).

package/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: namidb-vault
+description: >-
+  Sync a local Obsidian/markdown vault to a NamiDB Cloud namespace as a
+  queryable graph (Note nodes; LINKS_TO/EMBEDS/TAGGED/SUBTAG_OF edges).
+  Use this whenever the user asks to "sync my vault", "push my notes",
+  "index my markdown", "rebuild the note graph", or after they add,
+  edit, rename, or delete `.md` files and want the cloud graph to match.
+  The vault on disk stays the source of truth; the cloud graph is a
+  rebuildable index that powers backlinks, neighbor traversal, orphan
+  detection, shared-tag queries, and (when an embedder is configured
+  server-side) semantic search over the same notes.
+version: 1.0.0
+allowed-tools: Bash(node:*), Read, Glob
+---
+
+# NamiDB vault sync
+
+Push a local markdown vault to a NamiDB Cloud namespace. The cloud graph
+mirrors the vault: every `.md` file is a `Note`, every `[[wikilink]]` /
+`[text](note.md)` is a `LINKS_TO` edge, every `![[embed]]` is an `EMBEDS`
+edge, and `#tags` + frontmatter `tags` become shared `:Tag` nodes joined by
+`:TAGGED` (nested tags add a `:SUBTAG_OF` tree). Embeddings are computed
+server-side, so this skill never sends vectors and never touches an embedder
+key — it pushes note text only, then **auto-triggers a server-side embed** of
+the changed notes after a successful sync. Semantic search (`vault_search`)
+lights up only once an embedder is configured for the namespace in the
+dashboard; if none is, the sync still succeeds and reports that semantic search
+is off.
+
+## When to run this
+
+Run a sync when the user:
+
+- asks to "sync", "push", "upload", "index", or "rebuild" their vault / notes,
+- has just created, edited, renamed, moved, or deleted `.md` files and wants
+  the graph to reflect disk,
+- asks a graph/semantic question about their notes and the graph looks stale
+  (when in doubt, sync first — it is incremental and idempotent).
+
+Do NOT run it on every file save unless the user explicitly asks for live
+sync; for that, point them at `--watch` (see the README) rather than looping
+the tool yourself.
+
+## How to run it
+
+1. Find the config. Look for `namidb-vault.config.json` at the vault root (or
+   the repo root). If present, read it for `vaultDir`, `apiUrl`, and
+   `namespace`. The API key is **only** ever read from the `NAMIDB_API_KEY`
+   environment variable — never from the config file, never from chat, and
+   never echoed back.
+2. Resolve config -> env. The script reads `NAMIDB_API_URL`,
+   `NAMIDB_API_KEY`, and `NAMIDB_NAMESPACE` from the environment; CLI flags
+   override them. Prefer flags sourced from the config file for URL +
+   namespace, and leave the key in the environment.
+3. Run the sync from the directory that holds this skill's `sync.mjs`:
+
+   ```bash
+   node sync.mjs --vault "<vaultDir>" --api-url "<apiUrl>" --namespace "<ns>"
+   ```
+
+   The key is taken from `NAMIDB_API_KEY` in the environment. If it is unset,
+   tell the user to export it (give them the variable name, not a value) and
+   stop — do not ask them to paste the key into the conversation.
+4. Report the printed summary (notes added/modified/unchanged/deleted, edges,
+   tags, placeholders). After a successful sync the script auto-triggers a
+   server-side embed and prints either `embedded N, skipped M` or, when no
+   embedder is configured, `semantic search off (no embedder configured)` —
+   relay that line too. On a non-zero exit, surface the error message; the
+   script prints the failing note path / chunk, not secrets.
+
+## Hard rules
+
+- NEVER print, log, echo, or store `NAMIDB_API_KEY` (or any value that looks
+  like an API key). If the user pastes a key into chat, treat it as
+  compromised: tell them to rotate it and set it as an env var instead.
+- NEVER hardcode the API URL, namespace, or bucket — always read them from
+  config/flags/env.
+- The vault is the source of truth. This skill only writes to the cloud
+  graph; it never edits `.md` files.
+- A `--prune` sync (the default) deletes cloud notes whose files are gone
+  from disk. If the user points it at the wrong/empty directory it will
+  prune the namespace; confirm the `--vault` path before a first run against
+  a populated namespace, and offer `--no-prune` for an additive push.
+
+## Quick reference
+
+```bash
+# Dry run — parse + diff, print the plan, write nothing
+node sync.mjs --vault ./vault --dry-run
+
+# Incremental sync (default): upsert changed notes, prune deleted ones
+node sync.mjs --vault ./vault
+
+# Additive only — never delete cloud notes
+node sync.mjs --vault ./vault --no-prune
+
+# Live sync — re-sync on file changes (debounced)
+node sync.mjs --vault ./vault --watch
+```
+
+After a sync, query the graph through the hosted NamiDB MCP server (see
+`README.md` -> "Query the graph back"): `vault_search`, `backlinks`,
+`neighbors`, `orphans`, `shared_tags`, `get_note`, and `cypher` are exposed as
+MCP tools authed by the same project API key.

package/namidb-vault.config.example.json

@@ -0,0 +1,6 @@
+{
+  "vaultDir": "./vault",
+  "apiUrl": "https://api.namidb.com",
+  "namespace": "my-vault",
+  "_note": "The API key is NOT stored here. Set NAMIDB_API_KEY in your environment. This file holds only non-secret routing config and is safe to commit."
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "namidb-vault",
+  "version": "1.0.0",
+  "description": "Sync a local Obsidian/markdown vault to NamiDB Cloud as a queryable graph for AI coding agents (Claude Code, Cursor, Codex). Note nodes + LINKS_TO/EMBEDS/TAGGED edges; backlinks, n-hop, orphans, shared-tags and semantic search over MCP. Zero-dependency.",
+  "type": "module",
+  "bin": {
+    "namidb-vault": "sync.mjs"
+  },
+  "files": [
+    "sync.mjs",
+    "SKILL.md",
+    "README.md",
+    "namidb-vault.config.example.json",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "namidb",
+    "obsidian",
+    "markdown",
+    "vault",
+    "knowledge-graph",
+    "graph-database",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "codex",
+    "semantic-search",
+    "rag",
+    "notes"
+  ],
+  "homepage": "https://namidb.com",
+  "bugs": {
+    "url": "https://namidb.com/contact"
+  },
+  "license": "MIT",
+  "author": "NamiDB, Inc.",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/sync.mjs

@@ -0,0 +1,933 @@
+#!/usr/bin/env node
+/**
+ * namidb vault sync — push a local Obsidian/markdown vault to a NamiDB Cloud
+ * namespace as a queryable graph. Zero dependencies (Node >= 18 built-ins).
+ *
+ * The cloud graph mirrors the vault, faithful to the engine's namidb-markdown
+ * mapping:
+ *   - every `.md`/`.markdown` file  -> a `Note` node
+ *       props: title, path, body, key, body_hash, + typed frontmatter
+ *   - `[[wikilink]]` / `[text](note.md)` -> `LINKS_TO` edge
+ *   - `![[embed]]`                       -> `EMBEDS` edge
+ *   - `#tag` + frontmatter `tags`         -> shared `:Tag` node + `:TAGGED` edge
+ *   - nested tag `area/db`                -> ancestor `:Tag` + `:SUBTAG_OF` edge
+ *   - dangling reference                  -> placeholder `:Note` (placeholder=true)
+ *
+ * Node identity is STABLE per note path: uuid5(DNS, "namidb-note:" + relPath).
+ * Tags/placeholders get uuid5("namidb-tag:" + name) / uuid5("namidb-note-key:"
+ * + key). These ids are owned by THIS skill (the engine loader is not on this
+ * path); re-running upserts in place. Link/embed resolution is by normalized
+ * basename key (diacritic-folded), exactly like the engine, so a `[[User Role]]`
+ * resolves to `user-role.md` regardless of folder.
+ *
+ * Embeddings are computed SERVER-SIDE: this script pushes note TEXT only. It
+ * never sends vectors and never reads or transmits an embedder API key. After a
+ * successful push (+ prune), it triggers the gateway to (re-)embed the changed
+ * Notes via POST /v1/embed (best-effort; a missing embedder or embed error never
+ * fails the sync). Semantic search needs an embedder configured in the dashboard.
+ *
+ * Config (env; flags override):
+ *   NAMIDB_API_URL    e.g. https://api.namidb.com   (--api-url)
+ *   NAMIDB_API_KEY    the project API key, Bearer    (env only; never a flag)
+ *   NAMIDB_NAMESPACE  the target namespace name       (--namespace)
+ *
+ * Usage:
+ *   export NAMIDB_API_KEY='nk_live_...'
+ *   node sync.mjs --vault ./vault --api-url https://api.namidb.com --namespace my-vault
+ *   node sync.mjs --vault ./vault --dry-run
+ *   node sync.mjs --vault ./vault --no-prune
+ *   node sync.mjs --vault ./vault --watch
+ */
+import { createHash } from "node:crypto";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { watch } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+
+// ─── CLI / config ────────────────────────────────────────────────────────
+const args = parseArgs(process.argv.slice(2));
+if (args.help || args.h) {
+  printUsage();
+  process.exit(0);
+}
+
+const VAULT = path.resolve(args.vault || process.env.NAMIDB_VAULT || ".");
+const API_URL = String(
+  args["api-url"] || process.env.NAMIDB_API_URL || "",
+).replace(/\/+$/, "");
+const NAMESPACE = String(args.namespace || process.env.NAMIDB_NAMESPACE || "");
+const API_KEY = process.env.NAMIDB_API_KEY || "";
+const CHUNK = Math.max(50, Math.min(20_000, Number(args.chunk ?? 2000)));
+const DRY_RUN = Boolean(args["dry-run"]);
+const PRUNE = args["no-prune"] ? false : true;
+const WATCH = Boolean(args.watch);
+const REQ_TIMEOUT_MS = Math.max(5000, Number(args.timeout ?? 120_000));
+const DEBOUNCE_MS = Math.max(200, Number(args["watch-debounce"] ?? 1500));
+
+if (!API_URL || !NAMESPACE) {
+  fail(
+    "missing config: set --api-url/NAMIDB_API_URL and --namespace/NAMIDB_NAMESPACE\n" +
+      "  (the API key is read from the NAMIDB_API_KEY environment variable)",
+  );
+}
+if (!DRY_RUN && !API_KEY) {
+  fail(
+    "NAMIDB_API_KEY is not set in the environment (do not pass it as a flag or paste it in chat)",
+  );
+}
+
+// ─── Graph constants (must match the engine's namidb-markdown shapes) ─────
+const NOTE_LABEL = "Note";
+const TAG_LABEL = "Tag";
+const LINKS_TO = "LINKS_TO";
+const EMBEDS = "EMBEDS";
+const TAGGED = "TAGGED";
+const SUBTAG_OF = "SUBTAG_OF";
+// Engine-owned property names an author may not override (stem-derived `key`,
+// byte-derived `body_hash`) plus the engine-reserved set. Dropped from
+// frontmatter so they cannot shadow a managed column. The server-side embed
+// change-detection compares against `body_hash`, so this skill writes a stable
+// hash under that exact name; every Note carries one so the server re-embeds
+// only the notes whose `body_hash` changed.
+const RESERVED_PROPS = new Set([
+  "key",
+  "body_hash",
+  "node_id",
+  "tombstone",
+  "lsn",
+]);
+function isReservedProp(name) {
+  return (
+    RESERVED_PROPS.has(name) ||
+    name.startsWith("__") ||
+    name.startsWith("prop_")
+  );
+}
+
+// ─── Stable ids: RFC-4122 v5 (SHA-1) over the DNS namespace ───────────────
+const NS_DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+function uuid5(name) {
+  const nsBytes = Buffer.from(NS_DNS.replace(/-/g, ""), "hex");
+  const hash = createHash("sha1")
+    .update(nsBytes)
+    .update(Buffer.from(name, "utf8"))
+    .digest();
+  const b = Buffer.from(hash.subarray(0, 16));
+  b[6] = (b[6] & 0x0f) | 0x50; // version 5
+  b[8] = (b[8] & 0x3f) | 0x80; // RFC-4122 variant
+  const h = b.toString("hex");
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(
+    16,
+    20,
+  )}-${h.slice(20, 32)}`;
+}
+const noteId = (relPath) => uuid5(`namidb-note:${relPath}`);
+const noteKeyId = (key) => uuid5(`namidb-note-key:${key}`); // placeholders resolve here
+const tagId = (name) => uuid5(`namidb-tag:${name}`);
+
+// ─── Key normalization + diacritic fold (mirror crates/.../src/id.rs) ─────
+const FOLD = {
+  À: "A", Á: "A", Â: "A", Ã: "A", Ä: "A", Å: "A",
+  à: "a", á: "a", â: "a", ã: "a", ä: "a", å: "a",
+  Ç: "C", ç: "c",
+  È: "E", É: "E", Ê: "E", Ë: "E", è: "e", é: "e", ê: "e", ë: "e",
+  Ì: "I", Í: "I", Î: "I", Ï: "I", ì: "i", í: "i", î: "i", ï: "i",
+  Ñ: "N", ñ: "n",
+  Ò: "O", Ó: "O", Ô: "O", Õ: "O", Ö: "O", ò: "o", ó: "o", ô: "o", õ: "o", ö: "o",
+  Ù: "U", Ú: "U", Û: "U", Ü: "U", ù: "u", ú: "u", û: "u", ü: "u",
+  Ý: "Y", ý: "y", ÿ: "y",
+};
+function normalizeKey(name) {
+  let out = "";
+  let prevSep = false;
+  for (const ch of name.trim()) {
+    if (ch === "-" || ch === "_" || /\s/u.test(ch)) {
+      if (out.length && !prevSep) {
+        out += "-";
+        prevSep = true;
+      }
+    } else {
+      out += (FOLD[ch] ?? ch).toLowerCase();
+      prevSep = false;
+    }
+  }
+  return out.replace(/-+$/u, "");
+}
+
+// ─── Code-fence + inline-code masking (so links inside code don't count) ──
+// Replace fenced blocks (``` / ~~~) and inline `code` spans with spaces of the
+// same length, preserving offsets like the engine's pulldown-cmark masker.
+function maskCode(body) {
+  const lines = body.split("\n");
+  let fence = null; // current fence marker char-run, or null
+  const out = [];
+  for (const line of lines) {
+    const fm = line.match(/^\s*(```+|~~~+)/);
+    if (fence) {
+      out.push(" ".repeat(line.length));
+      if (fm && line.trim().startsWith(fence[0]) && line.trim().length >= fence.length)
+        fence = null;
+      continue;
+    }
+    if (fm) {
+      fence = fm[1];
+      out.push(" ".repeat(line.length));
+      continue;
+    }
+    // Inline code spans: blank out backtick-delimited runs.
+    out.push(line.replace(/`+[^`]*`+/g, (m) => " ".repeat(m.length)));
+  }
+  return out.join("\n");
+}
+
+// ─── Frontmatter (minimal YAML: scalars, flow/block lists, one-level maps) ─
+function splitFrontmatter(raw) {
+  const m = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!m) return [null, raw];
+  return [m[1], raw.slice(m[0].length)];
+}
+function parseScalar(s) {
+  const t = s.trim();
+  if (t === "") return null;
+  if (
+    (t.startsWith('"') && t.endsWith('"')) ||
+    (t.startsWith("'") && t.endsWith("'"))
+  )
+    return t.slice(1, -1);
+  if (t === "true") return true;
+  if (t === "false") return false;
+  if (t === "null" || t === "~") return null;
+  if (/^-?\d+$/.test(t)) return Number.parseInt(t, 10);
+  if (/^-?\d*\.\d+$/.test(t)) return Number.parseFloat(t);
+  return t;
+}
+function parseFlowList(s) {
+  return s
+    .slice(1, -1)
+    .split(",")
+    .map((x) => parseScalar(x))
+    .filter((x) => x !== null || x === 0 || x === false);
+}
+// Best-effort YAML for the shapes vaults actually use. Top-level keys only;
+// `key:` then either an inline scalar/flow-list or a block list of `- item`.
+function parseFrontmatter(yaml) {
+  if (yaml == null) return {};
+  const props = {};
+  const lines = yaml.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!line.trim() || line.trim().startsWith("#")) continue;
+    if (/^\s/.test(line)) continue; // belongs to a block value handled below
+    const cm = line.match(/^([^:#][^:]*):(.*)$/);
+    if (!cm) continue;
+    const key = cm[1].trim();
+    const rest = cm[2].trim();
+    if (!key) continue;
+    let value;
+    if (rest === "") {
+      // Block list: consume following `- item` / indented lines.
+      const items = [];
+      let isList = false;
+      while (i + 1 < lines.length && /^\s+\S/.test(lines[i + 1])) {
+        const next = lines[++i].trim();
+        if (next.startsWith("- ")) {
+          isList = true;
+          items.push(parseScalar(next.slice(2)));
+        }
+      }
+      value = isList ? items : null;
+    } else if (rest.startsWith("[") && rest.endsWith("]")) {
+      value = parseFlowList(rest);
+    } else {
+      value = parseScalar(rest);
+    }
+    if (value === null && rest !== "") continue;
+    if (value === null && rest === "") continue;
+    props[key] = value; // last-wins on duplicate top-level keys, like Obsidian
+  }
+  return props;
+}
+
+// ─── Wikilink / embed / markdown-link / tag extraction ───────────────────
+const WIKILINK_RE = /(!?)\[\[([^[\]\r\n]+?)\]\]/g;
+const MD_LINK_RE = /(!?)\[[^\]]*\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const TAG_RE = /(?:^|\s)#([\p{L}\p{N}_/-]*[\p{L}_/-][\p{L}\p{N}_/-]*)/gu;
+
+function linkTargetKey(inner) {
+  const beforeAlias = inner.split("|")[0];
+  const beforeAnchor = beforeAlias.split("#")[0].trim();
+  if (!beforeAnchor) return null;
+  const base = beforeAnchor.split("/").pop();
+  const k = normalizeKey(base);
+  return k || null;
+}
+function classifyWikilinks(masked) {
+  const links = [];
+  const embeds = [];
+  const sl = new Set();
+  const se = new Set();
+  for (const m of masked.matchAll(WIKILINK_RE)) {
+    const k = linkTargetKey(m[2]);
+    if (!k) continue;
+    if (m[1] === "!") {
+      if (!se.has(k)) {
+        se.add(k);
+        embeds.push(k);
+      }
+    } else if (!sl.has(k)) {
+      sl.add(k);
+      links.push(k);
+    }
+  }
+  return { links, embeds };
+}
+function mdLinkTargetKey(dest) {
+  const d = dest.trim();
+  if (!d || d.startsWith("#") || d.startsWith("//") || d.includes("://"))
+    return null;
+  const colon = d.indexOf(":");
+  if (colon > 0) {
+    const scheme = d.slice(0, colon);
+    if (/^[A-Za-z][A-Za-z0-9+.-]*$/.test(scheme)) return null; // mailto:, tel:, ...
+  }
+  const noFrag = d.split(/[#?]/)[0];
+  const base = noFrag.split(/[/\\]/).pop();
+  const decoded = decodeURIComponentSafe(base);
+  const lower = decoded.toLowerCase();
+  let stem;
+  if (lower.endsWith(".md")) stem = decoded.slice(0, -3);
+  else if (lower.endsWith(".markdown")) stem = decoded.slice(0, -9);
+  else return null;
+  if (/[:/\\#?]/.test(stem)) return null;
+  const k = normalizeKey(stem);
+  return k || null;
+}
+function decodeURIComponentSafe(s) {
+  try {
+    return decodeURIComponent(s);
+  } catch {
+    return s;
+  }
+}
+function extractMarkdownLinks(masked) {
+  const out = [];
+  const seen = new Set();
+  for (const m of masked.matchAll(MD_LINK_RE)) {
+    if (m[1] === "!") continue; // image embed, not a note link
+    const k = mdLinkTargetKey(m[2]);
+    if (k && !seen.has(k)) {
+      seen.add(k);
+      out.push(k);
+    }
+  }
+  return out;
+}
+function extractTags(masked) {
+  const out = [];
+  const seen = new Set();
+  for (const m of masked.matchAll(TAG_RE)) {
+    if (!seen.has(m[1])) {
+      seen.add(m[1]);
+      out.push(m[1]);
+    }
+  }
+  return out;
+}
+// A frontmatter value that IS a single whole `[[wikilink]]` (a link field).
+function frontmatterLinkTarget(value) {
+  if (typeof value !== "string") return null;
+  const t = value.trim();
+  if (!t.startsWith("[[") || !t.endsWith("]]")) return null;
+  const inner = t.slice(2, -2);
+  if (inner.includes("[[") || inner.includes("]]") || /[\r\n]/.test(inner))
+    return null;
+  return linkTargetKey(inner);
+}
+
+// ─── Parse one note ──────────────────────────────────────────────────────
+function noteTitle(relPath) {
+  const base = relPath.split("/").pop();
+  return base.replace(/\.(md|markdown)$/i, "");
+}
+function parseNote(relPath, raw) {
+  const [yaml, body] = splitFrontmatter(raw);
+  const fm = parseFrontmatter(yaml);
+
+  const title = noteTitle(relPath);
+  const key = normalizeKey(title);
+  const masked = maskCode(body);
+
+  // Properties: typed frontmatter (reserved dropped) + engine-owned fields.
+  const properties = {};
+  for (const [k, v] of Object.entries(fm)) {
+    if (isReservedProp(k)) continue;
+    properties[k] = v;
+  }
+  // `title` defers to a STRING frontmatter title; else the file stem.
+  if (typeof properties.title !== "string") properties.title = title;
+  properties.path = relPath;
+  properties.body = body;
+  properties.key = key;
+  // Stable per-note change marker. The server-side embed change-detection
+  // copies whatever value is in `body_hash`, so the PROPERTY NAME must match;
+  // the algorithm only needs to be stable (Node stdlib blake2b512 over the raw
+  // file bytes is fine). A changed hash is what tells the server to re-embed.
+  properties.body_hash = createHash("blake2b512")
+    .update(raw, "utf8")
+    .digest("hex");
+
+  // Merge inline #tags into the `tags` property (frontmatter first, dedup).
+  const inlineTags = extractTags(masked);
+  let tagList = [];
+  if (Array.isArray(properties.tags))
+    tagList = properties.tags.filter((t) => typeof t === "string");
+  else if (typeof properties.tags === "string") tagList = [properties.tags];
+  if (inlineTags.length) {
+    const present = new Set(tagList);
+    for (const t of inlineTags)
+      if (!present.has(t)) {
+        present.add(t);
+        tagList.push(t);
+      }
+    if (
+      properties.tags === undefined ||
+      Array.isArray(properties.tags) ||
+      typeof properties.tags === "string"
+    )
+      properties.tags = tagList.slice();
+  }
+  const tags = dedup(tagList);
+
+  // Links: body wikilinks (doc order) + markdown links, then whole-value
+  // frontmatter wikilinks; embeds kept separate.
+  const { links: bodyLinks, embeds } = classifyWikilinks(masked);
+  const links = dedup([...bodyLinks, ...extractMarkdownLinks(masked)]);
+  for (const [name, value] of Object.entries(fm)) {
+    if (["tags", "aliases", "title", "path", "body"].includes(name)) continue;
+    const vals = Array.isArray(value) ? value : [value];
+    for (const v of vals) {
+      const k = frontmatterLinkTarget(v);
+      if (k && !links.includes(k)) links.push(k);
+    }
+  }
+
+  // Aliases (frontmatter `aliases`), normalized like link targets.
+  const aliases = [];
+  const aliasSeen = new Set();
+  const aliasSrc = Array.isArray(fm.aliases)
+    ? fm.aliases
+    : fm.aliases != null
+      ? [fm.aliases]
+      : [];
+  for (const a of aliasSrc) {
+    if (typeof a !== "string") continue;
+    const k = normalizeKey(a);
+    if (k && !aliasSeen.has(k)) {
+      aliasSeen.add(k);
+      aliases.push(k);
+    }
+  }
+
+  return {
+    id: noteId(relPath),
+    key,
+    title,
+    relPath,
+    properties,
+    links,
+    embeds,
+    tags,
+    aliases,
+  };
+}
+
+function dedup(arr) {
+  const seen = new Set();
+  const out = [];
+  for (const x of arr)
+    if (!seen.has(x)) {
+      seen.add(x);
+      out.push(x);
+    }
+  return out;
+}
+
+// ─── Walk the vault ──────────────────────────────────────────────────────
+async function walkVault(root) {
+  const files = [];
+  async function rec(dir) {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch (e) {
+      throw new Error(`cannot read ${dir}: ${e.message}`);
+    }
+    for (const ent of entries) {
+      const full = path.join(dir, ent.name);
+      if (ent.isDirectory()) {
+        if (ent.name.startsWith(".") || ent.name === "_templates") continue;
+        await rec(full);
+      } else if (/\.(md|markdown)$/i.test(ent.name)) {
+        const rel = path.relative(root, full).split(path.sep).join("/");
+        files.push(rel);
+      }
+    }
+  }
+  await rec(root);
+  files.sort();
+  return files;
+}
+
+// ─── Build the desired graph (notes + resolved edges + tags + placeholders) ─
+function buildGraph(notes) {
+  const known = new Set(notes.map((n) => n.key));
+  // key -> note id (first note in path order wins a duplicate basename key).
+  const keyToId = new Map();
+  for (const n of notes) if (!keyToId.has(n.key)) keyToId.set(n.key, n.id);
+  // Alias map: first note (path order) to declare an alias wins; a real note
+  // key always shadows an alias.
+  const aliasMap = new Map();
+  for (const n of notes)
+    for (const a of n.aliases)
+      if (!known.has(a) && !aliasMap.has(a)) aliasMap.set(a, n.id);
+
+  const linkEdges = [];
+  const embedEdges = [];
+  const placeholders = new Map(); // key -> placeholder node id
+
+  const pushEdge = (arr, srcId, target) => {
+    let dst = null;
+    if (known.has(target)) dst = keyToId.get(target);
+    else if (aliasMap.has(target)) dst = aliasMap.get(target);
+    if (dst != null) {
+      arr.push([srcId, dst]);
+    } else {
+      // Dangling -> placeholder Note, keyed by the normalized target so a real
+      // note created later upserts over the stub.
+      const pid = noteKeyId(target);
+      if (!placeholders.has(target)) placeholders.set(target, pid);
+      arr.push([srcId, pid]);
+    }
+  };
+  for (const n of notes) {
+    for (const t of n.links) pushEdge(linkEdges, n.id, t);
+    for (const t of n.embeds) pushEdge(embedEdges, n.id, t);
+  }
+  dedupPairs(linkEdges);
+  dedupPairs(embedEdges);
+
+  // Tags + nested SUBTAG_OF tree.
+  const tagNodes = new Map(); // id -> name
+  const tagged = [];
+  const subtags = new Set(); // "childIdparentId"
+  for (const n of notes) {
+    for (const tag of n.tags) {
+      const tid = tagId(tag);
+      tagNodes.set(tid, tag);
+      tagged.push([n.id, tid]);
+      let child = tag;
+      let slash;
+      while ((slash = child.lastIndexOf("/")) !== -1) {
+        const parent = child.slice(0, slash);
+        if (!parent) break;
+        const cid = tagId(child);
+        const pid = tagId(parent);
+        tagNodes.set(pid, parent);
+        subtags.add(`${cid}${pid}`);
+        child = parent;
+      }
+    }
+  }
+  return {
+    notes,
+    linkEdges,
+    embedEdges,
+    placeholders,
+    tagNodes,
+    tagged,
+    subtags,
+  };
+}
+function dedupPairs(pairs) {
+  const seen = new Set();
+  for (let i = pairs.length - 1; i >= 0; i--) {
+    const k = pairs[i][0] + "" + pairs[i][1];
+    if (seen.has(k)) pairs.splice(i, 1);
+    else seen.add(k);
+  }
+  pairs.reverse(); // restore first-seen order after reverse-walk
+}
+
+// ─── Property encoding for /v1/bulk ──────────────────────────────────────
+// Scalars (null/bool/number/string) pass through. Homogeneous numeric arrays
+// become vectors (we never emit those here). Lists of strings (tags/aliases)
+// and one-level maps are JSON-stringified where the engine rejects nesting.
+function encodeProps(properties) {
+  const out = {};
+  for (const [k, v] of Object.entries(properties)) {
+    if (
+      v === null ||
+      typeof v === "boolean" ||
+      typeof v === "number" ||
+      typeof v === "string"
+    ) {
+      out[k] = v;
+    } else if (Array.isArray(v) && v.every((x) => typeof x === "number")) {
+      out[k] = v; // homogeneous numeric array -> vector (not used by notes)
+    } else {
+      // Lists/maps: the bulk endpoint rejects nested objects, so flatten to a
+      // JSON string. The graph relationships (:Tag, LINKS_TO) carry structure;
+      // this is just a faithful display copy of the frontmatter.
+      out[k] = JSON.stringify(v);
+    }
+  }
+  return out;
+}
+
+// ─── HTTP ────────────────────────────────────────────────────────────────
+async function postBulk(payload) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQ_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${API_URL}/v1/bulk`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        "X-NamiDB-Namespace": NAMESPACE,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify(payload),
+      signal: ctrl.signal,
+    });
+    if (!res.ok)
+      throw new Error(
+        `bulk HTTP ${res.status}: ${(await res.text().catch(() => "")).slice(
+          0,
+          300,
+        )}`,
+      );
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function postCypher(query, params = {}) {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQ_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${API_URL}/v1/cypher`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        "X-NamiDB-Namespace": NAMESPACE,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ query, params }),
+      signal: ctrl.signal,
+    });
+    if (!res.ok)
+      throw new Error(
+        `cypher HTTP ${res.status}: ${(await res.text().catch(() => "")).slice(
+          0,
+          300,
+        )}`,
+      );
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+// Trigger the gateway to (re-)embed this namespace's changed Notes. Authed the
+// same way as /v1/bulk and /v1/cypher (Bearer + X-NamiDB-Namespace); the body
+// is empty JSON. Returns the parsed { embedded, skipped, status } envelope —
+// status "no_embedder" is a 200 (not an error) when no embedder is configured,
+// so a missing embedder never fails a sync. Never sends or reads an embedder
+// key; the gateway holds the encrypted key control-plane-side.
+async function postEmbed() {
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), REQ_TIMEOUT_MS);
+  try {
+    const res = await fetch(`${API_URL}/v1/embed`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${API_KEY}`,
+        "X-NamiDB-Namespace": NAMESPACE,
+        "Content-Type": "application/json",
+      },
+      body: "{}",
+      signal: ctrl.signal,
+    });
+    if (!res.ok)
+      throw new Error(
+        `embed HTTP ${res.status}: ${(await res.text().catch(() => "")).slice(
+          0,
+          300,
+        )}`,
+      );
+    return res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+// Best-effort embed trigger: log a one-line status, never throw. A failed embed
+// must not fail an otherwise-successful sync — the vault is already pushed and
+// the server re-embeds idempotently on the next sync.
+async function triggerEmbed() {
+  try {
+    const r = await postEmbed();
+    if (r && r.status === "no_embedder") {
+      console.log(
+        "semantic search off (no embedder configured) — configure one in the dashboard to enable vault_search",
+      );
+    } else {
+      const embedded = Number(r?.embedded ?? 0);
+      const skipped = Number(r?.skipped ?? 0);
+      console.log(`embedded ${embedded}, skipped ${skipped}`);
+    }
+  } catch (e) {
+    console.warn(`embed trigger skipped (sync still succeeded): ${e.message}`);
+  }
+}
+
+// ─── Bulk push in chunks ─────────────────────────────────────────────────
+async function pushNodes(nodes) {
+  let written = 0;
+  for (let i = 0; i < nodes.length; i += CHUNK) {
+    const slice = nodes.slice(i, i + CHUNK);
+    const r = await postBulk({ nodes: slice, edges: [] });
+    written += r.nodes_written ?? 0;
+  }
+  return written;
+}
+async function pushEdges(edges) {
+  let written = 0;
+  for (let i = 0; i < edges.length; i += CHUNK) {
+    const slice = edges.slice(i, i + CHUNK);
+    const r = await postBulk({ nodes: [], edges: slice });
+    written += r.edges_written ?? 0;
+  }
+  return written;
+}
+
+// ─── Diff-prune: delete cloud notes/tags removed locally ─────────────────
+async function pruneRemoved(graph) {
+  // Current real-note paths in the cloud (placeholders have no path).
+  const resp = await postCypher(
+    `MATCH (n:${NOTE_LABEL}) WHERE n.path IS NOT NULL RETURN n.path AS path`,
+  );
+  const cloudPaths = new Set(
+    (resp.rows || []).map((r) => r.path).filter(Boolean),
+  );
+  const localPaths = new Set(graph.notes.map((n) => n.relPath));
+  const removed = [...cloudPaths].filter((p) => !localPaths.has(p));
+  let deleted = 0;
+  for (const p of removed) {
+    await postCypher(`MATCH (n:${NOTE_LABEL} {path: $path}) DETACH DELETE n`, {
+      path: p,
+    });
+    deleted++;
+  }
+  // Drop placeholder stubs that nothing references any more, and now-orphaned
+  // tags (no :TAGGED edge left). Cheap idempotent cleanup so the graph stays a
+  // faithful index after deletions.
+  await postCypher(
+    `MATCH (n:${NOTE_LABEL}) WHERE n.placeholder = true AND NOT EXISTS((n)<-[:${LINKS_TO}|:${EMBEDS}]-()) DETACH DELETE n`,
+  );
+  await postCypher(
+    `MATCH (t:${TAG_LABEL}) WHERE NOT EXISTS((t)<-[:${TAGGED}]-()) AND NOT EXISTS((t)<-[:${SUBTAG_OF}]-()) DETACH DELETE t`,
+  );
+  return deleted;
+}
+
+// ─── One sync pass ───────────────────────────────────────────────────────
+async function syncOnce() {
+  const t0 = performance.now();
+  const relPaths = await walkVault(VAULT);
+  const notes = [];
+  for (const rel of relPaths) {
+    const raw = await readFile(path.join(VAULT, rel), "utf8");
+    notes.push(parseNote(rel, raw));
+  }
+  const graph = buildGraph(notes);
+
+  // Assemble bulk payloads.
+  const noteNodes = graph.notes.map((n) => ({
+    id: n.id,
+    label: NOTE_LABEL,
+    properties: encodeProps(n.properties),
+  }));
+  const placeholderNodes = [...graph.placeholders.entries()].map(
+    ([key, id]) => ({
+      id,
+      label: NOTE_LABEL,
+      properties: { key, title: key, placeholder: true },
+    }),
+  );
+  const tagNodeList = [...graph.tagNodes.entries()].map(([id, name]) => ({
+    id,
+    label: TAG_LABEL,
+    properties: { name },
+  }));
+  const linkEdges = graph.linkEdges.map(([src, dst]) => ({
+    type: LINKS_TO,
+    src,
+    dst,
+    properties: {},
+  }));
+  const embedEdges = graph.embedEdges.map(([src, dst]) => ({
+    type: EMBEDS,
+    src,
+    dst,
+    properties: {},
+  }));
+  const taggedEdges = graph.tagged.map(([src, dst]) => ({
+    type: TAGGED,
+    src,
+    dst,
+    properties: {},
+  }));
+  const subtagEdges = [...graph.subtags].map((s) => {
+    const [child, parent] = s.split("");
+    return { type: SUBTAG_OF, src: child, dst: parent, properties: {} };
+  });
+
+  const plan = {
+    notes: noteNodes.length,
+    placeholders: placeholderNodes.length,
+    tags: tagNodeList.length,
+    links: linkEdges.length,
+    embeds: embedEdges.length,
+    tagged: taggedEdges.length,
+    subtags: subtagEdges.length,
+  };
+
+  if (DRY_RUN) {
+    console.log(`[dry-run] vault=${VAULT} ns=${NAMESPACE}`);
+    console.log(`[dry-run] plan: ${JSON.stringify(plan)}`);
+    console.log(`[dry-run] no writes performed.`);
+    return plan;
+  }
+
+  // Order: nodes first (notes, placeholders, tags), then edges. The bulk
+  // endpoint does not require endpoints in-batch, but creating nodes first
+  // keeps a partial failure from leaving dangling edges.
+  const nodesWritten = await pushNodes([
+    ...noteNodes,
+    ...placeholderNodes,
+    ...tagNodeList,
+  ]);
+  const edgesWritten = await pushEdges([
+    ...linkEdges,
+    ...embedEdges,
+    ...taggedEdges,
+    ...subtagEdges,
+  ]);
+
+  let deleted = 0;
+  if (PRUNE) deleted = await pruneRemoved(graph);
+
+  const secs = ((performance.now() - t0) / 1000).toFixed(1);
+  console.log(
+    `synced ${plan.notes} notes (${nodesWritten} nodes, ${edgesWritten} edges, ` +
+      `${deleted} deleted) to ns=${NAMESPACE} in ${secs}s` +
+      (PRUNE ? "" : "  [additive, no prune]"),
+  );
+
+  // Sync succeeded: trigger the server-side embed of changed Notes so semantic
+  // search stays current. Best-effort — never fails the sync (see triggerEmbed).
+  await triggerEmbed();
+
+  return { ...plan, deleted, nodesWritten, edgesWritten };
+}
+
+// ─── Watch mode ──────────────────────────────────────────────────────────
+async function runWatch() {
+  console.log(
+    `watching ${VAULT} for changes (debounce ${DEBOUNCE_MS}ms)... Ctrl-C to stop`,
+  );
+  await syncOnce().catch((e) => console.error(`sync error: ${e.message}`));
+  let timer = null;
+  let running = false;
+  let again = false;
+  const trigger = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(async () => {
+      if (running) {
+        again = true;
+        return;
+      }
+      running = true;
+      try {
+        await syncOnce();
+      } catch (e) {
+        console.error(`sync error: ${e.message}`);
+      } finally {
+        running = false;
+        if (again) {
+          again = false;
+          trigger();
+        }
+      }
+    }, DEBOUNCE_MS);
+  };
+  watch(VAULT, { recursive: true }, (_evt, name) => {
+    if (name && /\.(md|markdown)$/i.test(name)) trigger();
+  });
+}
+
+// ─── Entry ───────────────────────────────────────────────────────────────
+try {
+  await stat(VAULT);
+} catch {
+  fail(`vault directory not found: ${VAULT}`);
+}
+if (WATCH) {
+  await runWatch();
+} else {
+  try {
+    await syncOnce();
+  } catch (e) {
+    fail(e.message);
+  }
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith("--")) out[key] = true;
+      else {
+        out[key] = next;
+        i++;
+      }
+    } else if (a.startsWith("-")) {
+      out[a.slice(1)] = true;
+    }
+  }
+  return out;
+}
+function fail(msg) {
+  console.error(`error: ${msg}`);
+  process.exit(1);
+}
+function printUsage() {
+  console.log(
+    `namidb vault sync\n\n` +
+      `usage: node sync.mjs --vault DIR [--api-url URL] [--namespace NS] [options]\n\n` +
+      `config (env; flags override):\n` +
+      `  NAMIDB_API_URL     gateway base URL (--api-url)\n` +
+      `  NAMIDB_API_KEY     project API key, Bearer (env only)\n` +
+      `  NAMIDB_NAMESPACE   target namespace (--namespace)\n\n` +
+      `options:\n` +
+      `  --vault DIR        vault root (default: $NAMIDB_VAULT or .)\n` +
+      `  --dry-run          parse + plan, write nothing\n` +
+      `  --no-prune         additive only (never delete cloud notes)\n` +
+      `  --watch            re-sync on .md changes (debounced)\n` +
+      `  --chunk N          rows per bulk request (default 2000)\n` +
+      `  --timeout MS       per-request timeout (default 120000)\n`,
+  );
+}