stellavault 0.7.2 → 0.7.4

package/dist/stellavault.js

@@ -4,12 +4,6 @@ const require = createRequire(import.meta.url);
 
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -88,17 +82,33 @@ import { createHash } from "node:crypto";
 import matter from "gray-matter";
 function scanVault(vaultPath) {
   const documents = [];
-  let skippedFiles = 0;
+  const skipped = [];
   const mdFiles = findMdFiles(vaultPath);
   for (const filePath of mdFiles) {
+    const rel = relative(vaultPath, filePath).replace(/\\/g, "/");
     try {
+      const stat = statSync(filePath);
+      if (stat.size === 0) {
+        skipped.push({ path: rel, reason: "empty" });
+        continue;
+      }
+      if (stat.size > MAX_FILE_BYTES) {
+        skipped.push({ path: rel, reason: "too-large", detail: `${stat.size}B` });
+        continue;
+      }
       const doc = parseDocument(vaultPath, filePath);
+      if (!doc.content || doc.content.trim().length === 0) {
+        skipped.push({ path: rel, reason: "empty", detail: "no content after frontmatter" });
+        continue;
+      }
       documents.push(doc);
-    } catch {
-      skippedFiles++;
+    } catch (err) {
+      const msg = err?.message ?? String(err);
+      const reason = /ENOENT|EACCES|EPERM/.test(msg) ? "unreadable" : "parse-error";
+      skipped.push({ path: rel, reason, detail: msg.slice(0, 200) });
     }
   }
-  return { documents, scannedFiles: mdFiles.length, skippedFiles };
+  return { documents, scannedFiles: mdFiles.length, skippedFiles: skipped.length, skipped };
 }
 function findMdFiles(dir, files = []) {
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
@@ -209,9 +219,11 @@ function extractTags(frontmatter, content) {
   }
   return [...tags];
 }
+var MAX_FILE_BYTES;
 var init_scanner = __esm({
   "packages/core/dist/indexer/scanner.js"() {
     "use strict";
+    MAX_FILE_BYTES = 5 * 1024 * 1024;
   }
 });
 
@@ -419,28 +431,60 @@ var init_retry = __esm({
 });
 
 // packages/core/dist/indexer/local-embedder.js
+function getPipeline(modelName) {
+  let p = pipelineCache.get(modelName);
+  if (p)
+    return p;
+  p = (async () => {
+    const { pipeline: createPipeline } = await import("@xenova/transformers");
+    return createPipeline("feature-extraction", `Xenova/${modelName}`, { quantized: true });
+  })();
+  pipelineCache.set(modelName, p);
+  return p;
+}
 function createLocalEmbedder(modelName = "nomic-embed-text-v1.5") {
   let pipeline;
   let dims = modelName.includes("MiniLM") ? 384 : 768;
+  const profile = process.env.STELLAVAULT_PROFILE_MEMORY === "1";
+  let callCount = 0;
   return {
     async initialize() {
-      const { pipeline: createPipeline } = await import("@xenova/transformers");
-      pipeline = await createPipeline("feature-extraction", `Xenova/${modelName}`, {
-        quantized: true
-      });
+      pipeline = await getPipeline(modelName);
     },
     async embed(text) {
-      const output = await pipeline(text, { pooling: "mean", normalize: true });
-      return Array.from(output.data).slice(0, dims);
+      let output = await pipeline(text, { pooling: "mean", normalize: true });
+      const result = Array.from(output.data).slice(0, dims);
+      try {
+        output.dispose?.();
+      } catch {
+      }
+      output = null;
+      return result;
     },
-    async embedBatch(texts, batchSize = 32) {
+    async embedBatch(texts, batchSize = 16) {
       const results = [];
+      let processed = 0;
       for (let i = 0; i < texts.length; i += batchSize) {
         const batch = texts.slice(i, i + batchSize);
-        const output = await pipeline(batch, { pooling: "mean", normalize: true });
+        let output = await pipeline(batch, { pooling: "mean", normalize: true });
         const flat = output.data;
         for (let j = 0; j < batch.length; j++) {
-          results.push(Array.from(flat.slice(j * dims, (j + 1) * dims)));
+          results.push(Array.from(flat.subarray(j * dims, (j + 1) * dims)));
+        }
+        try {
+          output.dispose?.();
+        } catch {
+        }
+        output = null;
+        processed += batch.length;
+        callCount += batch.length;
+        if (processed % 256 === 0 && typeof globalThis.gc === "function") {
+          globalThis.gc();
+        }
+        if (profile && callCount % 100 < batchSize) {
+          const rss = Math.round(process.memoryUsage().rss / 1024 / 1024);
+          const heap = Math.round(process.memoryUsage().heapUsed / 1024 / 1024);
+          console.error(`[profile-memory] embedded=${callCount} rss=${rss}MB heap=${heap}MB`);
         }
       }
       return results;
@@ -453,9 +497,11 @@ function createLocalEmbedder(modelName = "nomic-embed-text-v1.5") {
     }
   };
 }
+var pipelineCache;
 var init_local_embedder = __esm({
   "packages/core/dist/indexer/local-embedder.js"() {
     "use strict";
+    pipelineCache = /* @__PURE__ */ new Map();
   }
 });
 
@@ -525,13 +571,15 @@ __export(indexer_exports, {
 async function indexVault(vaultPath, options) {
   const start = Date.now();
   const { store, embedder, chunkOptions, onProgress } = options;
-  const { documents } = scanVault(vaultPath);
+  const scan = scanVault(vaultPath);
+  const { documents } = scan;
   const existingDocs = await store.getAllDocuments();
   const existingMap = new Map(existingDocs.map((d) => [d.id, d.contentHash]));
   let indexed = 0;
   let skipped = 0;
   let failed = 0;
   let totalChunks = 0;
+  const failedFiles = [];
   const scannedIds = /* @__PURE__ */ new Set();
   for (let i = 0; i < documents.length; i++) {
     const doc = documents[i];
@@ -555,6 +603,7 @@ async function indexVault(vaultPath, options) {
       totalChunks += chunks.length;
     } catch (err) {
       failed++;
+      failedFiles.push({ path: doc.filePath, error: err?.message ?? String(err) });
       console.error(errors.indexingFailed(doc.filePath, err).format());
     }
   }
@@ -571,7 +620,10 @@ async function indexVault(vaultPath, options) {
     deleted,
     failed,
     totalChunks,
-    elapsedMs: Date.now() - start
+    elapsedMs: Date.now() - start,
+    totalFiles: scan.scannedFiles,
+    skippedFiles: scan.skipped,
+    failedFiles
   };
 }
 var init_indexer = __esm({
@@ -645,12 +697,10 @@ async function buildGraphData(store, options = {}) {
   ]);
   const edges = [];
   const edgeCounts = /* @__PURE__ */ new Map();
+  const docsWithVecs = docs.filter((d) => embeddings.has(d.id));
   const normalizedVecs = /* @__PURE__ */ new Map();
-  for (const doc of docs) {
-    const vec = embeddings.get(doc.id);
-    if (!vec)
-      continue;
-    normalizedVecs.set(doc.id, normalizeVector([...vec]));
+  for (const doc of docsWithVecs) {
+    normalizedVecs.set(doc.id, normalizeVector([...embeddings.get(doc.id)]));
   }
   const docIds = [...normalizedVecs.keys()];
   const vecArray = docIds.map((id) => normalizedVecs.get(id));
@@ -1255,36 +1305,34 @@ var init_wiki_compiler = __esm({
 });
 
 // packages/core/dist/federation/identity.js
-import { randomBytes, createHash as createHash3, createHmac } from "node:crypto";
-import { readFileSync as readFileSync7, writeFileSync as writeFileSync8, existsSync as existsSync7, mkdirSync as mkdirSync9, chmodSync } from "node:fs";
-import { join as join8 } from "node:path";
+import { createHash as createHash3, createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, sign, verify } from "node:crypto";
+import { chmodSync, existsSync as existsSync7, mkdirSync as mkdirSync9, readFileSync as readFileSync7, writeFileSync as writeFileSync8 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
-function getOrCreateIdentity(displayName) {
-  if (existsSync7(IDENTITY_FILE)) {
-    const raw = JSON.parse(readFileSync7(IDENTITY_FILE, "utf-8"));
-    return {
-      peerId: raw.peerId,
-      publicKey: Buffer.from(raw.publicKey, "hex"),
-      secretKey: Buffer.from(raw.secretKey, "hex"),
-      displayName: raw.displayName,
-      createdAt: raw.createdAt
-    };
-  }
-  const secretKey = randomBytes(32);
-  const publicKey = createHash3("sha256").update(secretKey).digest();
-  const peerId = createHash3("sha256").update(publicKey).digest("hex").slice(0, 16);
-  const identity = {
+import { join as join8 } from "node:path";
+function derivePeerId(publicKey) {
+  return createHash3("sha256").update(publicKey).digest("hex").slice(0, 16);
+}
+function generateIdentity(displayName) {
+  const { publicKey: pkObj, privateKey: skObj } = generateKeyPairSync("ed25519");
+  const publicKey = pkObj.export({ type: "spki", format: "der" });
+  const secretKey = skObj.export({ type: "pkcs8", format: "der" });
+  const peerId = derivePeerId(publicKey);
+  return {
     peerId,
     publicKey,
     secretKey,
     displayName: displayName ?? `node-${peerId.slice(0, 6)}`,
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
+}
+function persistIdentity(identity) {
   mkdirSync9(IDENTITY_DIR, { recursive: true });
   const content = JSON.stringify({
+    version: IDENTITY_VERSION,
+    algorithm: IDENTITY_ALGORITHM,
     peerId: identity.peerId,
-    publicKey: publicKey.toString("hex"),
-    secretKey: secretKey.toString("hex"),
+    publicKey: identity.publicKey.toString("hex"),
+    secretKey: identity.secretKey.toString("hex"),
     displayName: identity.displayName,
     createdAt: identity.createdAt
   }, null, 2);
@@ -1293,36 +1341,103 @@ function getOrCreateIdentity(displayName) {
     chmodSync(IDENTITY_FILE, 384);
   } catch {
   }
+}
+function getOrCreateIdentity(displayName) {
+  if (existsSync7(IDENTITY_FILE)) {
+    const raw = JSON.parse(readFileSync7(IDENTITY_FILE, "utf-8"));
+    const isV2 = raw.version === IDENTITY_VERSION && raw.algorithm === IDENTITY_ALGORITHM;
+    if (isV2) {
+      return {
+        peerId: String(raw.peerId),
+        publicKey: Buffer.from(String(raw.publicKey), "hex"),
+        secretKey: Buffer.from(String(raw.secretKey), "hex"),
+        displayName: String(raw.displayName),
+        createdAt: String(raw.createdAt)
+      };
+    }
+    const bakPath = IDENTITY_FILE.replace(/\.json$/, ".v1.bak.json");
+    writeFileSync8(bakPath, JSON.stringify(raw, null, 2), { encoding: "utf-8", mode: 384 });
+    console.warn(`[federation] Identity migrated to v2 (Ed25519). v1 backup: ${bakPath}`);
+  }
+  const identity = generateIdentity(displayName);
+  persistIdentity(identity);
   return identity;
 }
-var IDENTITY_DIR, IDENTITY_FILE;
+function signMessage(secretKeyDer, message) {
+  const keyObj = createPrivateKey({ key: secretKeyDer, format: "der", type: "pkcs8" });
+  return sign(null, message, keyObj);
+}
+function verifySignature(publicKeyDer, message, signature) {
+  try {
+    const keyObj = createPublicKey({ key: publicKeyDer, format: "der", type: "spki" });
+    return verify(null, message, keyObj, signature);
+  } catch {
+    return false;
+  }
+}
+function peerIdFromPublicKey(publicKey) {
+  return derivePeerId(publicKey);
+}
+var IDENTITY_DIR, IDENTITY_FILE, IDENTITY_VERSION, IDENTITY_ALGORITHM;
 var init_identity = __esm({
   "packages/core/dist/federation/identity.js"() {
     "use strict";
     IDENTITY_DIR = join8(homedir4(), ".stellavault", "federation");
     IDENTITY_FILE = join8(IDENTITY_DIR, "identity.json");
+    IDENTITY_VERSION = 2;
+    IDENTITY_ALGORITHM = "ed25519";
   }
 });
 
 // packages/core/dist/federation/node.js
-import { createHash as createHash4 } from "node:crypto";
+import { createHash as createHash4, randomBytes as randomBytes2 } from "node:crypto";
 import { EventEmitter } from "node:events";
-var FEDERATION_TOPIC, FederationNode;
+var FEDERATION_TOPIC, REPLAY_CACHE_LIMIT, DEFAULT_HANDSHAKE_TIMEOUT_MS, DEFAULT_RATE_LIMIT_PER_SEC, DEFAULT_RATE_LIMIT_BURST, FederationNode;
 var init_node = __esm({
   "packages/core/dist/federation/node.js"() {
     "use strict";
     init_identity();
     FEDERATION_TOPIC = createHash4("sha256").update("stellavault-federation-v1").digest();
+    REPLAY_CACHE_LIMIT = 1e4;
+    DEFAULT_HANDSHAKE_TIMEOUT_MS = 3e4;
+    DEFAULT_RATE_LIMIT_PER_SEC = 50;
+    DEFAULT_RATE_LIMIT_BURST = 100;
     FederationNode = class extends EventEmitter {
       swarm = null;
       identity;
       peers = /* @__PURE__ */ new Map();
+      connStates = /* @__PURE__ */ new WeakMap();
+      replayCache = /* @__PURE__ */ new Set();
+      replayQueue = [];
       running = false;
       documentCount = 0;
       topTopics = [];
-      constructor(displayName) {
+      // Configurable per-instance — see constructor options.
+      handshakeTimeoutMs;
+      rateLimitPerSec;
+      rateLimitBurst;
+      /**
+       * @param init Either a displayName string (legacy positional form) or an
+       *             options object. Pass `{ identity }` to skip the on-disk identity
+       *             load — useful for tests that need many ephemeral peers.
+       *             `handshakeTimeoutMs` drops connections stuck in handshake
+       *             (set to 0 to disable; default 30s).
+       *             `rateLimitPerSec` / `rateLimitBurst` cap per-peer envelope
+       *             processing rate (set rateLimitPerSec=0 to disable).
+       */
+      constructor(init) {
         super();
-        this.identity = getOrCreateIdentity(displayName);
+        if (init && typeof init === "object") {
+          this.identity = init.identity ?? getOrCreateIdentity(init.displayName);
+          this.handshakeTimeoutMs = init.handshakeTimeoutMs ?? DEFAULT_HANDSHAKE_TIMEOUT_MS;
+          this.rateLimitPerSec = init.rateLimitPerSec ?? DEFAULT_RATE_LIMIT_PER_SEC;
+          this.rateLimitBurst = init.rateLimitBurst ?? DEFAULT_RATE_LIMIT_BURST;
+        } else {
+          this.identity = getOrCreateIdentity(init);
+          this.handshakeTimeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS;
+          this.rateLimitPerSec = DEFAULT_RATE_LIMIT_PER_SEC;
+          this.rateLimitBurst = DEFAULT_RATE_LIMIT_BURST;
+        }
       }
       get peerId() {
         return this.identity.peerId;
@@ -1340,7 +1455,6 @@ var init_node = __esm({
         this.documentCount = documentCount;
         this.topTopics = topTopics.slice(0, 5);
       }
-      // Design Ref: §4 — join()
       async join() {
         if (this.running)
           return;
@@ -1354,7 +1468,6 @@ var init_node = __esm({
         this.running = true;
         this.emit("joined", { peerId: this.peerId, topic: FEDERATION_TOPIC.toString("hex").slice(0, 16) });
       }
-      // Design Ref: §4 — joinDirect() 수동 IP 폴백
       async joinDirect(host, port) {
         const net = await import("node:net");
         const conn = net.connect(port, host);
@@ -1374,7 +1487,7 @@ var init_node = __esm({
           return;
         for (const [, peer] of this.peers) {
           try {
-            this.sendMessage(peer.conn, { type: "leave", peerId: this.peerId });
+            this.sendSigned(peer.conn, { type: "leave", peerId: this.peerId });
             peer.conn.end();
           } catch {
           }
@@ -1388,30 +1501,109 @@ var init_node = __esm({
       getPeers() {
         return [...this.peers.values()].map((p) => p.info);
       }
-      // 피어에게 검색 쿼리 전송 (FederatedSearch에서 사용)
       sendSearchQuery(peerId, queryId, embedding, limit) {
         const peer = this.peers.get(peerId);
         if (!peer)
           return;
-        this.sendMessage(peer.conn, { type: "search_query", queryId, embedding, limit });
+        this.sendSigned(peer.conn, { type: "search_query", queryId, embedding, limit });
       }
-      // 피어에게 검색 결과 응답 (FederatedSearch에서 사용)
       sendSearchResult(peerId, queryId, results) {
         const peer = this.peers.get(peerId);
         if (!peer)
           return;
-        this.sendMessage(peer.conn, { type: "search_result", queryId, results });
+        this.sendSigned(peer.conn, { type: "search_result", queryId, results });
       }
       // --- Private ---
+      /**
+       * Stable JSON for signing. Sorts keys recursively so nested objects
+       * produced by different JS runtimes (or by future code paths that build
+       * objects in a different insertion order) still hash identically on
+       * both sides. RFC 8785-style canonicalization, scoped to what
+       * FederationMessage / SignedEnvelope actually carry. Keys whose value
+       * is `undefined` are omitted (matches JSON.stringify semantics), so
+       * sender and receiver agree on optional fields like `publicKeyHex`.
+       */
+      canonicalize(value) {
+        if (value === null || typeof value !== "object")
+          return JSON.stringify(value);
+        if (Array.isArray(value)) {
+          return "[" + value.map((v) => this.canonicalize(v)).join(",") + "]";
+        }
+        const obj = value;
+        const keys = Object.keys(obj).filter((k) => obj[k] !== void 0).sort();
+        return "{" + keys.map((k) => JSON.stringify(k) + ":" + this.canonicalize(obj[k])).join(",") + "}";
+      }
+      sendSigned(conn, payload, includePublicKey = false) {
+        try {
+          const envBase = {
+            payload,
+            peerId: this.peerId,
+            nonce: randomBytes2(16).toString("hex"),
+            ...includePublicKey ? { publicKeyHex: this.identity.publicKey.toString("hex") } : {}
+          };
+          const canonical = Buffer.from(this.canonicalize(envBase), "utf-8");
+          const sig = signMessage(this.identity.secretKey, canonical);
+          const envelope = { ...envBase, signature: sig.toString("hex") };
+          conn.write(JSON.stringify(envelope) + "\n");
+        } catch {
+        }
+      }
+      rememberNonce(nonceHex) {
+        if (this.replayCache.has(nonceHex))
+          return false;
+        this.replayCache.add(nonceHex);
+        this.replayQueue.push(nonceHex);
+        if (this.replayQueue.length > REPLAY_CACHE_LIMIT) {
+          const oldest = this.replayQueue.shift();
+          if (oldest)
+            this.replayCache.delete(oldest);
+        }
+        return true;
+      }
       handleConnection(conn) {
-        this.sendMessage(conn, {
-          type: "handshake",
-          peerId: this.peerId,
-          displayName: this.identity.displayName,
-          version: "0.1.0",
-          documentCount: this.documentCount,
-          topTopics: this.topTopics
-        });
+        const state = {
+          conn,
+          ourNonce: randomBytes2(32),
+          helloSent: false,
+          weResponded: false,
+          peerVerified: false,
+          peerPublicKey: null,
+          peerId: null,
+          pendingPeerInfo: null,
+          ready: false,
+          handshakeTimer: null,
+          rlTokens: this.rateLimitBurst,
+          rlLastRefill: Date.now()
+        };
+        this.connStates.set(conn, state);
+        if (this.handshakeTimeoutMs > 0) {
+          state.handshakeTimer = setTimeout(() => {
+            if (state.ready)
+              return;
+            try {
+              conn.end();
+            } catch {
+            }
+            this.emit("handshake_timeout", { peerId: state.peerId });
+          }, this.handshakeTimeoutMs);
+          const timer = state.handshakeTimer;
+          timer.unref?.();
+        }
+        this.sendSigned(
+          conn,
+          {
+            type: "hello",
+            peerId: this.peerId,
+            displayName: this.identity.displayName,
+            version: "0.2.0",
+            documentCount: this.documentCount,
+            topTopics: this.topTopics,
+            nonce: state.ourNonce.toString("hex")
+          },
+          /* includePublicKey */
+          true
+        );
+        state.helloSent = true;
         let buffer = "";
         const MAX_BUFFER = 1024 * 1024;
         const MAX_MESSAGE = 64 * 1024;
@@ -1430,107 +1622,214 @@ var init_node = __esm({
               continue;
             if (line.length > MAX_MESSAGE)
               continue;
-            try {
-              const msg = JSON.parse(line);
-              this.handleMessage(conn, msg);
-            } catch {
-            }
+            this.dispatchLine(conn, line);
           }
         });
         conn.on("close", () => {
-          for (const [peerId, peer] of this.peers) {
-            if (peer.conn === conn) {
-              this.peers.delete(peerId);
-              this.emit("peer_left", { peerId });
-              break;
-            }
+          const st = this.connStates.get(conn);
+          if (st?.handshakeTimer)
+            clearTimeout(st.handshakeTimer);
+          this.connStates.delete(conn);
+          if (st?.peerId && this.peers.get(st.peerId)?.conn === conn) {
+            this.peers.delete(st.peerId);
+            this.emit("peer_left", { peerId: st.peerId });
           }
         });
         conn.on("error", () => {
         });
       }
-      // MED: 메시지 스키마 기본 검증
-      validateMessage(msg) {
-        if (!msg || typeof msg !== "object")
-          return false;
-        const m = msg;
-        if (typeof m.type !== "string")
-          return false;
-        if (m.type === "handshake" && (typeof m.peerId !== "string" || typeof m.displayName !== "string"))
-          return false;
-        if (m.type === "search_query" && (!Array.isArray(m.embedding) || m.embedding.length !== 384))
-          return false;
-        if (m.type === "search_result" && !Array.isArray(m.results))
+      /**
+       * Token-bucket admission control. Returns false when the inbound rate
+       * exceeds the configured limit; the caller should drop the envelope
+       * silently (we don't disconnect — the peer might be momentarily bursty,
+       * not malicious, and a real attacker would just reconnect).
+       */
+      admitEnvelope(state) {
+        if (this.rateLimitPerSec <= 0)
+          return true;
+        const now = Date.now();
+        const elapsed = (now - state.rlLastRefill) / 1e3;
+        if (elapsed > 0) {
+          state.rlTokens = Math.min(this.rateLimitBurst, state.rlTokens + elapsed * this.rateLimitPerSec);
+          state.rlLastRefill = now;
+        }
+        if (state.rlTokens < 1) {
+          this.emit("rate_limited", { peerId: state.peerId });
           return false;
+        }
+        state.rlTokens -= 1;
         return true;
       }
-      handleMessage(conn, msg) {
-        if (!this.validateMessage(msg))
+      dispatchLine(conn, line) {
+        const state = this.connStates.get(conn);
+        if (!state)
+          return;
+        if (!this.admitEnvelope(state))
+          return;
+        let envelope;
+        try {
+          envelope = JSON.parse(line);
+        } catch {
+          return;
+        }
+        if (!envelope || typeof envelope !== "object")
+          return;
+        if (typeof envelope.peerId !== "string")
+          return;
+        if (typeof envelope.signature !== "string")
+          return;
+        if (typeof envelope.nonce !== "string")
+          return;
+        if (envelope.nonce.length < 16 || envelope.nonce.length > 128)
+          return;
+        if (!envelope.payload || typeof envelope.payload !== "object")
+          return;
+        if (!this.rememberNonce(envelope.nonce))
+          return;
+        let publicKey = null;
+        if (!state.peerPublicKey) {
+          if (envelope.payload && envelope.payload.type !== "hello")
+            return;
+          if (!envelope.publicKeyHex || typeof envelope.publicKeyHex !== "string")
+            return;
+          try {
+            publicKey = Buffer.from(envelope.publicKeyHex, "hex");
+          } catch {
+            return;
+          }
+          const derived = peerIdFromPublicKey(publicKey);
+          if (derived !== envelope.peerId)
+            return;
+        } else {
+          if (envelope.peerId !== state.peerId)
+            return;
+          publicKey = state.peerPublicKey;
+        }
+        const { signature, ...envBase } = envelope;
+        const canonical = Buffer.from(this.canonicalize(envBase), "utf-8");
+        let sigBuf;
+        try {
+          sigBuf = Buffer.from(signature, "hex");
+        } catch {
+          return;
+        }
+        if (sigBuf.length !== 64)
           return;
+        if (!verifySignature(publicKey, canonical, sigBuf))
+          return;
+        this.handleMessage(conn, state, envelope.payload, publicKey);
+      }
+      handleMessage(conn, state, msg, publicKey) {
         switch (msg.type) {
-          case "handshake": {
-            const safeName = (msg.displayName ?? "").slice(0, 50);
-            const peerInfo = {
+          case "hello": {
+            if (state.peerPublicKey)
+              return;
+            if (typeof msg.peerId !== "string" || typeof msg.nonce !== "string")
+              return;
+            let nonceBuf;
+            try {
+              nonceBuf = Buffer.from(msg.nonce, "hex");
+            } catch {
+              return;
+            }
+            if (nonceBuf.length !== 32)
+              return;
+            if (!this.rememberNonce(msg.nonce))
+              return;
+            state.peerPublicKey = publicKey;
+            state.peerId = msg.peerId;
+            state.pendingPeerInfo = {
               peerId: msg.peerId,
-              displayName: safeName,
+              displayName: (msg.displayName ?? "").slice(0, 50),
               documentCount: Math.min(msg.documentCount ?? 0, 1e6),
-              // 합리적 상한
               topTopics: (msg.topTopics ?? []).slice(0, 10),
               joinedAt: (/* @__PURE__ */ new Date()).toISOString(),
               lastSeen: (/* @__PURE__ */ new Date()).toISOString()
             };
-            this.peers.set(msg.peerId, { info: peerInfo, conn });
-            this.emit("peer_joined", peerInfo);
+            const response = signMessage(this.identity.secretKey, nonceBuf);
+            this.sendSigned(conn, {
+              type: "challenge_response",
+              signedNonce: response.toString("hex")
+            });
+            state.weResponded = true;
+            this.maybeMarkReady(conn, state);
+            break;
+          }
+          case "challenge_response": {
+            if (state.peerVerified)
+              return;
+            if (typeof msg.signedNonce !== "string")
+              return;
+            let sigBuf;
+            try {
+              sigBuf = Buffer.from(msg.signedNonce, "hex");
+            } catch {
+              return;
+            }
+            if (sigBuf.length !== 64)
+              return;
+            if (!verifySignature(publicKey, state.ourNonce, sigBuf))
+              return;
+            state.peerVerified = true;
+            this.maybeMarkReady(conn, state);
             break;
           }
           case "search_query": {
+            if (!state.ready)
+              return;
             this.emit("search_request", {
-              peerId: msg.queryId,
-              // queryId를 추적용으로 사용
+              peerId: state.peerId,
               queryId: msg.queryId,
               embedding: msg.embedding,
               limit: msg.limit,
-              // respond 함수: 호출 측에서 사용
-              respondTo: (() => {
-                for (const [pid, peer] of this.peers) {
-                  if (peer.conn === conn)
-                    return pid;
-                }
-                return null;
-              })()
+              respondTo: state.peerId
             });
             break;
           }
           case "search_result": {
+            if (!state.ready)
+              return;
             this.emit("search_response", {
               queryId: msg.queryId,
               results: msg.results,
-              peerId: (() => {
-                for (const [pid, peer] of this.peers) {
-                  if (peer.conn === conn)
-                    return pid;
-                }
-                return "unknown";
-              })()
+              peerId: state.peerId ?? "unknown"
             });
             break;
           }
           case "leave": {
-            const legit = this.peers.get(msg.peerId);
-            if (legit && legit.conn === conn) {
+            if (!state.ready)
+              return;
+            if (msg.peerId !== state.peerId)
+              return;
+            const registered = this.peers.get(msg.peerId);
+            if (registered && registered.conn === conn) {
               this.peers.delete(msg.peerId);
               this.emit("peer_left", { peerId: msg.peerId });
             }
             break;
           }
+          case "challenge":
+          case "ready":
+            break;
+          case "handshake":
+            console.warn(`[federation] Rejected v1 handshake from peerId=${state.peerId ?? "unknown"}. Peer must upgrade to v2 (Ed25519).`);
+            break;
         }
       }
-      // Design Ref: §7 — JSON + newline delimiter
-      sendMessage(conn, msg) {
-        try {
-          conn.write(JSON.stringify(msg) + "\n");
-        } catch {
+      maybeMarkReady(conn, state) {
+        if (state.ready)
+          return;
+        if (!state.weResponded || !state.peerVerified)
+          return;
+        if (!state.peerId || !state.pendingPeerInfo)
+          return;
+        state.ready = true;
+        if (state.handshakeTimer) {
+          clearTimeout(state.handshakeTimer);
+          state.handshakeTimer = null;
         }
+        this.peers.set(state.peerId, { info: state.pendingPeerInfo, conn });
+        this.emit("peer_joined", state.pendingPeerInfo);
       }
     };
   }
@@ -1710,10 +2009,10 @@ var init_sharing = __esm({
       /\b\d{6}[-]\d{7}\b/
     ];
     DEFAULT_CONFIG2 = {
-      defaultLevel: 2,
-      // 기본: 스니펫까지
-      myNodeLevel: 2,
-      // 내 노드 기본: 스니펫까지
+      defaultLevel: 1,
+      // 기본: 제목+유사도까지만 (스니펫 안 보냄)
+      myNodeLevel: 0,
+      // 내 노드 기본: 수신 전용 (명시적 set-level 필요)
       rules: [
         // 기본 규칙
         { pattern: "public", type: "tag", level: 4 },
@@ -1800,6 +2099,11 @@ var init_search = __esm({
         this.node.on("search_request", async (req) => {
           if (!req.respondTo)
             return;
+          const cfg = loadSharingConfig();
+          if (cfg.myNodeLevel === 0) {
+            this.node.sendSearchResult(req.respondTo, req.queryId, []);
+            return;
+          }
           try {
             const allStores = [this.store, ...this.additionalStores];
             const allScored = await Promise.all(allStores.map((s) => s.searchSemantic(req.embedding, req.limit).catch(() => [])));
@@ -1835,8 +2139,13 @@ var federation_exports = {};
 __export(federation_exports, {
   FederatedSearch: () => FederatedSearch,
   FederationNode: () => FederationNode,
-  getOrCreateIdentity: () => getOrCreateIdentity
+  getOrCreateIdentity: () => getOrCreateIdentity,
+  isFederationExperimentalEnabled: () => isFederationExperimentalEnabled
 });
+function isFederationExperimentalEnabled() {
+  const v = (process.env.STELLAVAULT_FEDERATION_EXPERIMENTAL ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes" || v === "on";
+}
 var init_federation = __esm({
   "packages/core/dist/federation/index.js"() {
     "use strict";
@@ -3099,7 +3408,8 @@ import { Command } from "commander";
 // packages/cli/dist/commands/index-cmd.js
 import ora from "ora";
 import chalk from "chalk";
-import { createHash as createHash6 } from "node:crypto";
+import { createHash as createHash7 } from "node:crypto";
+import { writeFileSync as writeFileSync15 } from "node:fs";
 import { join as join20 } from "node:path";
 import { homedir as homedir12 } from "node:os";
 import { mkdirSync as mkdirSync15 } from "node:fs";
@@ -3170,9 +3480,8 @@ function createSqliteVecStore(dbPath, dimensions = 384) {
       const rows = db.prepare(`
         SELECT chunk_id, distance
         FROM chunk_embeddings
-        WHERE embedding MATCH ?
+        WHERE embedding MATCH ? AND k = ?
         ORDER BY distance
-        LIMIT ?
       `).all(float32Buffer(embedding), limit);
       return rows.map((r) => ({
         chunkId: r.chunk_id,
@@ -3258,6 +3567,22 @@ function createSqliteVecStore(dbPath, dimensions = 384) {
       }
       return result;
     },
+    async findDocumentNeighbors(embedding, limit) {
+      const knnK = Math.max(limit * 3, 30);
+      const rows = db.prepare(`
+        SELECT c.document_id, MIN(ce.distance) as distance
+        FROM chunk_embeddings ce
+        JOIN chunks c ON c.id = ce.chunk_id
+        WHERE ce.embedding MATCH ? AND k = ?
+        GROUP BY c.document_id
+        ORDER BY distance
+        LIMIT ?
+      `).all(float32Buffer(embedding), knnK, limit * 2);
+      return rows.slice(0, limit).map((r) => ({
+        documentId: r.document_id,
+        similarity: 1 / (1 + r.distance)
+      }));
+    },
     async close() {
       db.close();
     },
@@ -4599,7 +4924,7 @@ Please write the ${format} draft based on the context above. Save the result to
 
 // packages/core/dist/mcp/tools/agentic-graph.js
 import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync7 } from "node:fs";
-import { join as join7 } from "node:path";
+import { join as join7, resolve as resolvePath } from "node:path";
 function createAgenticGraphTools(store, embedder, vaultPath) {
   let nodeCreationCount = 0;
   let nodeCreationWindowStart = Date.now();
@@ -4672,8 +4997,8 @@ ${content}${relatedSection}`;
         const safeTitle = title.replace(/[<>:"/\\|?*]/g, "").replace(/\s+/g, " ").trim().slice(0, 80);
         const dir = join7(vaultPath, folder);
         const filePath = join7(dir, `${safeTitle}.md`);
-        const resolvedPath = __require("node:path").resolve(filePath);
-        const resolvedVault = __require("node:path").resolve(vaultPath);
+        const resolvedPath = resolvePath(filePath);
+        const resolvedVault = resolvePath(vaultPath);
         if (!resolvedPath.startsWith(resolvedVault)) {
           return { content: [{ type: "text", text: "Error: invalid folder path." }] };
         }
@@ -4739,6 +5064,7 @@ The note will appear in the graph after next index.`
 // packages/core/dist/mcp/server.js
 function createMcpServer(options) {
   const { store, searchEngine, embedder, vaultPath = "", decayEngine } = options;
+  const ready = options.ready ?? Promise.resolve();
   const learningPathTool = createLearningPathTool(store);
   const detectGapsTool = createDetectGapsTool(store);
   const getEvolutionTool = createGetEvolutionTool(store);
@@ -4746,7 +5072,7 @@ function createMcpServer(options) {
   const askTool = createAskTool(searchEngine, vaultPath);
   const generateDraftTool = createGenerateDraftTool(searchEngine, vaultPath);
   const agenticTools = embedder ? createAgenticGraphTools(store, embedder, vaultPath) : [];
-  const server = new Server({ name: "stellavault", version: "0.7.2" }, { capabilities: { tools: {} } });
+  const server = new Server({ name: "stellavault", version: "0.7.3" }, { capabilities: { tools: {} } });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: [
       searchToolDef,
@@ -4770,6 +5096,7 @@ function createMcpServer(options) {
     ]
   }));
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    await ready;
     const { name, arguments: args } = request.params;
     try {
       let result;
@@ -4873,8 +5200,18 @@ function createMcpServer(options) {
       const { createServer } = await import("node:http");
       const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => `sv-${Date.now()}` });
       await server.connect(transport);
+      const allowedOrigins = options.corsOrigins ?? ["http://localhost", "http://127.0.0.1"];
+      const allowWildcard = allowedOrigins.includes("*");
       const httpServer = createServer(async (req, res) => {
-        res.setHeader("Access-Control-Allow-Origin", "*");
+        const origin = req.headers.origin;
+        if (origin) {
+          if (allowWildcard) {
+            res.setHeader("Access-Control-Allow-Origin", "*");
+          } else if (allowedOrigins.some((allowed) => origin === allowed || origin.startsWith(allowed + ":"))) {
+            res.setHeader("Access-Control-Allow-Origin", origin);
+            res.setHeader("Vary", "Origin");
+          }
+        }
         res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
         res.setHeader("Access-Control-Allow-Headers", "Content-Type");
         if (req.method === "OPTIONS") {
@@ -5087,11 +5424,11 @@ Author: ${pack2.author}`,
 init_graph_data();
 import express from "express";
 import cors from "cors";
-import { randomBytes as randomBytes2 } from "node:crypto";
+import { randomBytes as randomBytes3 } from "node:crypto";
 
 // packages/core/dist/api/routes/federation.js
 import { Router } from "express";
-function createFederationRouter(store) {
+function createFederationRouter(store, requireAuth) {
   const router = Router();
   let federationNode = null;
   let federationAvailable = null;
@@ -5134,7 +5471,15 @@ function createFederationRouter(store) {
       res.json({ available: true, active: false, peerCount: 0, peers: [], displayName: null, peerId: null });
     }
   });
-  router.post("/join", async (req, res) => {
+  router.post("/join", requireAuth, async (req, res) => {
+    const { isFederationExperimentalEnabled: isFederationExperimentalEnabled2 } = await Promise.resolve().then(() => (init_federation(), federation_exports));
+    if (!isFederationExperimentalEnabled2()) {
+      return res.status(503).json({
+        success: false,
+        error: "federation-experimental-disabled",
+        message: "Federation is experimental and disabled by default. Set STELLAVAULT_FEDERATION_EXPERIMENTAL=1 in the environment to enable."
+      });
+    }
     const available = await probeFederationAvailable();
     if (!available) {
       return res.status(501).json({
@@ -5176,7 +5521,7 @@ function createFederationRouter(store) {
       res.status(500).json({ success: false, error: err instanceof Error ? err.message : "Federation join failed" });
     }
   });
-  router.post("/leave", async (_req, res) => {
+  router.post("/leave", requireAuth, async (_req, res) => {
     if (!federationNode || !federationNode.isRunning) {
       return res.json({ success: true, active: false, message: "Not active" });
     }
@@ -5231,7 +5576,7 @@ function createKnowledgeRouter(opts) {
         res.status(404).json({ error: "Document not found" });
         return;
       }
-      const { readFileSync: readFileSync18, writeFileSync: writeFileSync21, unlinkSync } = await import("node:fs");
+      const { readFileSync: readFileSync18, writeFileSync: writeFileSync22, unlinkSync } = await import("node:fs");
       const { join: join30, resolve: resolve22 } = await import("node:path");
       const [keeper, removed] = docA.content.length >= docB.content.length ? [docA, docB] : [docB, docA];
       const keeperPath = resolve22(join30(vaultPath, keeper.filePath));
@@ -5249,7 +5594,7 @@ function createKnowledgeRouter(opts) {
 > Merged from: ${removed.title} (${removed.filePath})
 
 ${removed.content}`;
-      writeFileSync21(keeperPath, keeperContent + appendix, "utf-8");
+      writeFileSync22(keeperPath, keeperContent + appendix, "utf-8");
       try {
         unlinkSync(removedPath);
       } catch {
@@ -5272,7 +5617,7 @@ ${removed.content}`;
         res.status(400).json({ error: "clusterA, clusterB required" });
         return;
       }
-      const { writeFileSync: writeFileSync21, mkdirSync: mkdirSync22 } = await import("node:fs");
+      const { writeFileSync: writeFileSync22, mkdirSync: mkdirSync22 } = await import("node:fs");
       const { join: join30, resolve: resolve22 } = await import("node:path");
       const nameA = clusterA.replace(/\s*\(\d+\)$/, "");
       const nameB = clusterB.replace(/\s*\(\d+\)$/, "");
@@ -5320,7 +5665,7 @@ ${removed.content}`;
       }
       mkdirSync22(dir, { recursive: true });
       const filePath = join30(dir, `${safeTitle}.md`);
-      writeFileSync21(filePath, content, "utf-8");
+      writeFileSync22(filePath, content, "utf-8");
       res.json({ success: true, title: safeTitle, path: filePath });
     } catch (err) {
       console.error(err);
@@ -5332,6 +5677,7 @@ ${removed.content}`;
 
 // packages/core/dist/api/routes/ingest.js
 import { Router as Router3 } from "express";
+import { createHash as createHash5 } from "node:crypto";
 function createIngestRouter(opts) {
   const { store, vaultPath, requireAuth, assertNotPrivateUrl } = opts;
   const router = Router3();
@@ -5402,7 +5748,7 @@ function createIngestRouter(opts) {
       });
       try {
         const doc = {
-          id: __require("node:crypto").createHash("sha256").update(result.savedTo).digest("hex").slice(0, 16),
+          id: createHash5("sha256").update(result.savedTo).digest("hex").slice(0, 16),
           filePath: result.savedTo,
           title: result.title,
           content,
@@ -5469,12 +5815,12 @@ function createIngestRouter(opts) {
           return;
         }
         try {
-          const { writeFileSync: writeFileSync21, unlinkSync } = await import("node:fs");
+          const { writeFileSync: writeFileSync22, unlinkSync } = await import("node:fs");
           const { join: join30 } = await import("node:path");
           const { tmpdir } = await import("node:os");
           const safeName = (file.originalname ?? "upload").replace(/[^a-zA-Z0-9._-]/g, "_").slice(0, 100);
           const tmpPath = join30(tmpdir(), `sv-upload-${Date.now()}-${safeName}`);
-          writeFileSync21(tmpPath, file.buffer);
+          writeFileSync22(tmpPath, file.buffer);
           const { extractFileContent: extractFileContent2 } = await Promise.resolve().then(() => (init_file_extractors(), file_extractors_exports));
           const ext = file.originalname.split(".").pop()?.toLowerCase() ?? "";
           const binaryExts = /* @__PURE__ */ new Set(["pdf", "docx", "pptx", "xlsx", "xls"]);
@@ -5510,7 +5856,7 @@ function createIngestRouter(opts) {
           });
           try {
             const doc = {
-              id: __require("node:crypto").createHash("sha256").update(result.savedTo).digest("hex").slice(0, 16),
+              id: createHash5("sha256").update(result.savedTo).digest("hex").slice(0, 16),
               filePath: result.savedTo,
               title: result.title,
               content,
@@ -5580,7 +5926,7 @@ ${desc}
         if (content.length > 1e4)
           content = content.slice(0, 1e4) + "\n\n...(truncated)";
       }
-      const { writeFileSync: writeFileSync21, mkdirSync: mkdirSync22 } = await import("node:fs");
+      const { writeFileSync: writeFileSync22, mkdirSync: mkdirSync22 } = await import("node:fs");
       const { join: join30 } = await import("node:path");
       const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
       const clipDir = join30(vaultPath || ".", "06_Research", "clips");
@@ -5598,7 +5944,7 @@ tags: [clip${isYT ? ", youtube" : ""}]
 > Source: ${url}
 
 ${content}`;
-      writeFileSync21(join30(clipDir, fileName), md, "utf-8");
+      writeFileSync22(join30(clipDir, fileName), md, "utf-8");
       res.json({ success: true, fileName, path: join30(clipDir, fileName) });
     } catch (err) {
       console.error(err);
@@ -5856,7 +6202,7 @@ function createAnalyticsRouter(opts) {
 function createApiServer(options) {
   const { store, searchEngine, port = 3333, vaultName = "", vaultPath = "", decayEngine, graphUiPath } = options;
   const app = express();
-  const authToken = randomBytes2(32).toString("hex");
+  const authToken = randomBytes3(32).toString("hex");
   app.use((_req, res, next) => {
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.setHeader("X-Frame-Options", "DENY");
@@ -5897,11 +6243,14 @@ function createApiServer(options) {
     const token = req.headers["x-stellavault-token"];
     if (token === authToken)
       return next();
-    if (req.query.token === authToken)
-      return next();
-    res.status(403).json({ error: "Invalid or missing auth token. GET /api/token first." });
+    res.status(403).json({ error: "Invalid or missing auth token. Send X-Stellavault-Token header." });
   }
-  app.get("/api/token", (_req, res) => {
+  app.get("/api/token", (req, res) => {
+    const origin = req.headers.origin;
+    if (!origin || !allowedOrigins.includes(origin)) {
+      res.status(403).json({ error: "Token endpoint requires a same-origin browser request." });
+      return;
+    }
     res.json({ token: authToken });
   });
   function assertNotPrivateUrl(url) {
@@ -6085,7 +6434,7 @@ function createApiServer(options) {
         return;
       }
       const { resolve: resolve22, join: join30 } = await import("node:path");
-      const { writeFileSync: writeFileSync21, readFileSync: readFileSync18 } = await import("node:fs");
+      const { writeFileSync: writeFileSync22, readFileSync: readFileSync18 } = await import("node:fs");
       const fullPath = resolve22(vaultPath, doc.filePath);
       if (!fullPath.startsWith(resolve22(vaultPath))) {
         res.status(403).json({ error: "Access denied" });
@@ -6112,7 +6461,7 @@ function createApiServer(options) {
           updated = content;
         }
       }
-      writeFileSync21(fullPath, updated, "utf-8");
+      writeFileSync22(fullPath, updated, "utf-8");
       await store.upsertDocument({
         ...doc,
         title: title ?? doc.title,
@@ -6301,7 +6650,7 @@ function createApiServer(options) {
   app.get("/api/sync/status", (_req, res) => {
     res.json(syncState);
   });
-  app.use("/api/federate", createFederationRouter(store));
+  app.use("/api/federate", createFederationRouter(store, requireAuth));
   if (graphUiPath) {
     app.get(/^(?!\/api\/)(?!.*\.[a-z0-9]+$).*$/i, (_req, res) => {
       res.sendFile(`${graphUiPath}/index.html`);
@@ -6749,7 +7098,7 @@ async function captureVoice(audioPath, options) {
 }
 
 // packages/core/dist/cloud/sync.js
-import { createCipheriv, createDecipheriv, randomBytes as randomBytes3, createHash as createHash5 } from "node:crypto";
+import { createCipheriv, createDecipheriv, randomBytes as randomBytes4, createHash as createHash6 } from "node:crypto";
 import { readFileSync as readFileSync14, writeFileSync as writeFileSync14, existsSync as existsSync14, mkdirSync as mkdirSync14, chmodSync as chmodSync2 } from "node:fs";
 import { join as join15 } from "node:path";
 import { homedir as homedir7 } from "node:os";
@@ -6757,7 +7106,7 @@ var CLOUD_DIR = join15(homedir7(), ".stellavault", "cloud");
 var KEY_FILE = join15(CLOUD_DIR, "encryption.key");
 var SYNC_STATE_FILE = join15(CLOUD_DIR, "sync-state.json");
 function encrypt(data, key) {
-  const iv = randomBytes3(16);
+  const iv = randomBytes4(16);
   const cipher = createCipheriv("aes-256-gcm", key, iv);
   const encrypted = Buffer.concat([cipher.update(data), cipher.final()]);
   const tag = cipher.getAuthTag();
@@ -6771,14 +7120,14 @@ function decrypt(encrypted, key, iv, tag) {
 function getOrCreateEncryptionKey(userKey) {
   mkdirSync14(CLOUD_DIR, { recursive: true });
   if (userKey) {
-    const key2 = createHash5("sha256").update(userKey).digest();
+    const key2 = createHash6("sha256").update(userKey).digest();
     writeFileSync14(KEY_FILE, key2.toString("hex"), "utf-8");
     return key2;
   }
   if (existsSync14(KEY_FILE)) {
     return Buffer.from(readFileSync14(KEY_FILE, "utf-8").trim(), "hex");
   }
-  const key = randomBytes3(32);
+  const key = randomBytes4(32);
   writeFileSync14(KEY_FILE, key.toString("hex"), { encoding: "utf-8", mode: 384 });
   try {
     chmodSync2(KEY_FILE, 384);
@@ -6805,7 +7154,7 @@ async function s3Put(config, objectKey, data, contentType = "application/octet-s
       "Content-Type": contentType,
       "Content-Length": String(data.length),
       "x-amz-date": date,
-      "x-amz-content-sha256": createHash5("sha256").update(data).digest("hex"),
+      "x-amz-content-sha256": createHash6("sha256").update(data).digest("hex"),
       // R2는 Bearer token 지원
       "Authorization": `Bearer ${secretAccessKey}`
     },
@@ -6902,24 +7251,27 @@ var CREDITS_FILE = join19(homedir11(), ".stellavault", "federation", "credits.js
 
 // packages/core/dist/index.js
 init_retry();
+init_math();
 init_indexer();
-function createKnowledgeHub(config) {
+function createKnowledgeHub(config, options = {}) {
   const embedder = createLocalEmbedder(config.embedding.localModel);
   const dims = embedder.dimensions;
   const store = createSqliteVecStore(config.dbPath, dims);
   const searchEngine = createSearchEngine({ store, embedder, rrfK: config.search.rrfK });
-  const mcpServer = createMcpServer({ store, searchEngine, vaultPath: config.vaultPath });
+  const mcpServer = createMcpServer({ store, searchEngine, vaultPath: config.vaultPath, ready: options.ready });
   return { store, embedder, searchEngine, mcpServer, config };
 }
 
 // packages/cli/dist/commands/index-cmd.js
 function getVaultDbPath(vaultPath) {
-  const hash = createHash6("sha256").update(vaultPath).digest("hex").slice(0, 8);
+  const hash = createHash7("sha256").update(vaultPath).digest("hex").slice(0, 8);
   const dir = join20(homedir12(), ".stellavault", "vaults");
   mkdirSync15(dir, { recursive: true });
   return join20(dir, `${hash}.db`);
 }
-async function indexCommand(vaultPath) {
+async function indexCommand(vaultPath, opts = {}) {
+  if (opts.profileMemory)
+    process.env.STELLAVAULT_PROFILE_MEMORY = "1";
   const config = loadConfig();
   const vault2 = vaultPath ?? config.vaultPath;
   if (!vault2) {
@@ -6936,28 +7288,85 @@ async function indexCommand(vaultPath) {
     } catch {
     }
   }
-  const spinner = ora("Initializing...").start();
+  const spinnerEnabled = !opts.noSpinner && !opts.verbose && process.stderr.isTTY;
+  const spinner = ora({ text: "Initializing...", isEnabled: spinnerEnabled }).start();
   const store = createSqliteVecStore(dbPath);
-  await store.initialize();
-  spinner.text = "Loading embedding model...";
-  const embedder = createLocalEmbedder(config.embedding.localModel);
-  await embedder.initialize();
-  spinner.text = "Starting indexing...";
-  const result = await indexVault(vault2, {
-    store,
-    embedder,
-    chunkOptions: config.chunking,
-    onProgress(current, total, doc) {
-      spinner.text = `[${current}/${total}] ${doc.title}`;
+  const cleanupSpinner = () => {
+    try {
+      spinner.stop();
+    } catch {
     }
+  };
+  process.once("uncaughtException", cleanupSpinner);
+  process.once("SIGINT", () => {
+    cleanupSpinner();
+    process.exit(130);
   });
-  await store.close();
-  spinner.stop();
-  console.log("");
-  console.log(chalk.green("\u2705 Indexing complete"));
-  console.log(`  \u{1F4C4} Indexed: ${result.indexed} | \u23ED\uFE0F Skipped: ${result.skipped} | \u{1F5D1}\uFE0F Deleted: ${result.deleted}${result.failed ? ` | \u274C Failed: ${result.failed}` : ""}`);
-  console.log(`  \u{1F9E9} Chunks: ${result.totalChunks} | \u23F1 ${(result.elapsedMs / 1e3).toFixed(1)}s`);
-  console.log(`  \u{1F4BE} DB: ${dbPath}`);
+  process.once("SIGTERM", () => {
+    cleanupSpinner();
+    process.exit(143);
+  });
+  try {
+    await store.initialize();
+    spinner.text = "Loading embedding model...";
+    const embedder = createLocalEmbedder(config.embedding.localModel);
+    await embedder.initialize();
+    spinner.text = "Starting indexing...";
+    const result = await indexVault(vault2, {
+      store,
+      embedder,
+      chunkOptions: config.chunking,
+      onProgress(current, total, doc) {
+        const mb = Math.round(process.memoryUsage().rss / 1024 / 1024);
+        if (spinnerEnabled) {
+          spinner.text = `[${current}/${total}] ${doc.title} (${mb}MB)`;
+        } else if (opts.verbose || current % 50 === 0 || current === total) {
+          console.error(`[${current}/${total}] ${doc.title} (${mb}MB)`);
+        }
+      }
+    });
+    await store.close();
+    spinner.stop();
+    const reasonCount = {
+      "empty": 0,
+      "parse-error": 0,
+      "binary": 0,
+      "too-large": 0,
+      "unreadable": 0
+    };
+    for (const s of result.skippedFiles)
+      reasonCount[s.reason]++;
+    console.log("");
+    console.log(chalk.green("\u2705 Indexing complete"));
+    console.log(`  \u{1F4C1} Files:   ${result.totalFiles} total`);
+    console.log(`  \u{1F4C4} Indexed: ${result.indexed} | \u23ED\uFE0F Unchanged: ${result.skipped} | \u{1F5D1}\uFE0F Deleted: ${result.deleted}${result.failed ? ` | \u274C Failed: ${result.failed}` : ""}`);
+    if (result.skippedFiles.length > 0) {
+      const parts = Object.entries(reasonCount).filter(([, c]) => c > 0).map(([r, c]) => `${r}=${c}`).join(", ");
+      console.log(`  \u26A0\uFE0F  Skipped: ${result.skippedFiles.length} (${parts})`);
+    }
+    console.log(`  \u{1F9E9} Chunks:  ${result.totalChunks} | \u23F1 ${(result.elapsedMs / 1e3).toFixed(1)}s`);
+    console.log(`  \u{1F4BE} DB: ${dbPath}`);
+    if (opts.logSkipped) {
+      writeFileSync15(opts.logSkipped, JSON.stringify({ skipped: result.skippedFiles, failed: result.failedFiles }, null, 2));
+      console.log(chalk.dim(`  \u{1F4CB} Skip log: ${opts.logSkipped}`));
+    }
+  } catch (err) {
+    spinner.fail(chalk.red("Indexing failed"));
+    const e = err;
+    console.error(chalk.red(`
+  ${e.message ?? err}`));
+    if (e.stack)
+      console.error(chalk.dim(e.stack.split("\n").slice(1, 5).join("\n")));
+    if ((e.message ?? "").match(/heap|out of memory|allocation failed/i)) {
+      console.error(chalk.yellow("\n  \u{1F4A1} Hint: large vault detected. Retry with a larger Node heap:"));
+      console.error(chalk.yellow('     NODE_OPTIONS="--max-old-space-size=8192 --expose-gc" stellavault index <path>'));
+    }
+    try {
+      await store.close();
+    } catch {
+    }
+    process.exit(1);
+  }
 }
 
 // packages/cli/dist/commands/search-cmd.js
@@ -7005,14 +7414,29 @@ async function searchCommand(query, options, cmd) {
 import chalk3 from "chalk";
 async function serveCommand() {
   const config = loadConfig();
-  const hub = createKnowledgeHub(config);
-  await hub.store.initialize();
-  await hub.embedder.initialize();
-  const stats = await hub.store.getStats();
-  console.error(chalk3.green("\u{1F680} MCP Server running (stdio mode)"));
-  console.error(`\u{1F4DA} ${stats.documentCount} documents | ${stats.chunkCount} chunks`);
+  let resolveReady;
+  const ready = new Promise((r) => {
+    resolveReady = r;
+  });
+  const hub = createKnowledgeHub(config, { ready });
+  console.error(chalk3.green("\u{1F680} MCP Server running (stdio mode) \u2014 index loading in background"));
   console.error(chalk3.dim("\u{1F4A1} Claude Code: claude mcp add stellavault -- stellavault serve"));
-  await hub.mcpServer.startStdio();
+  const serverPromise = hub.mcpServer.startStdio();
+  (async () => {
+    try {
+      const t0 = Date.now();
+      await hub.store.initialize();
+      await hub.embedder.initialize();
+      const stats = await hub.store.getStats();
+      const elapsed = Date.now() - t0;
+      console.error(`\u{1F4DA} ${stats.documentCount} documents | ${stats.chunkCount} chunks (ready in ${elapsed}ms)`);
+      resolveReady();
+    } catch (err) {
+      console.error(chalk3.red("\u274C Index load failed: " + err.message));
+      resolveReady();
+    }
+  })();
+  await serverPromise;
 }
 
 // packages/cli/dist/commands/status-cmd.js
@@ -7026,14 +7450,34 @@ async function statusCommand(_opts, cmd) {
   const stats = await store.getStats();
   const topics = await store.getTopics();
   await store.close();
+  let totalFiles = null;
+  let skippedFiles = null;
+  if (config.vaultPath) {
+    try {
+      const scan = scanVault(config.vaultPath);
+      totalFiles = scan.scannedFiles;
+      skippedFiles = scan.skippedFiles;
+    } catch {
+    }
+  }
   if (jsonMode) {
-    console.log(JSON.stringify({ ...stats, vaultPath: config.vaultPath, dbPath: config.dbPath, topics: topics.slice(0, 20) }, null, 2));
+    console.log(JSON.stringify({
+      ...stats,
+      totalFiles,
+      skippedFiles,
+      vaultPath: config.vaultPath,
+      dbPath: config.dbPath,
+      topics: topics.slice(0, 20)
+    }, null, 2));
     return;
   }
   console.log("");
   console.log(chalk4.bold("\u{1F4CA} Stellavault Status"));
   console.log("\u2500".repeat(40));
-  console.log(`  \u{1F4C4} Documents: ${stats.documentCount}`);
+  console.log(`  \u{1F4C4} Documents: ${stats.documentCount}${totalFiles != null ? ` / ${totalFiles} files (${Math.round(stats.documentCount / totalFiles * 100)}%)` : ""}`);
+  if (skippedFiles != null && skippedFiles > 0) {
+    console.log(`  \u26A0\uFE0F  Skipped:  ${skippedFiles} (run: stellavault index --log-skipped skipped.json)`);
+  }
   console.log(`  \u{1F9E9} Chunks:    ${stats.chunkCount}`);
   console.log(`  \u{1F550} Last indexed: ${stats.lastIndexed ?? "never"}`);
   console.log(`  \u{1F4BE} DB: ${config.dbPath}`);
@@ -7153,7 +7597,7 @@ async function openBrowser(url) {
 
 // packages/cli/dist/commands/card-cmd.js
 import chalk6 from "chalk";
-import { writeFileSync as writeFileSync15 } from "node:fs";
+import { writeFileSync as writeFileSync16 } from "node:fs";
 import { resolve as resolve12 } from "node:path";
 async function cardCommand(options) {
   const output = options.output ?? "knowledge-card.svg";
@@ -7164,7 +7608,7 @@ async function cardCommand(options) {
     if (!res.ok)
       throw new Error(`API error: ${res.status}. Is 'stellavault graph' running?`);
     const svg = await res.text();
-    writeFileSync15(outPath, svg, "utf-8");
+    writeFileSync16(outPath, svg, "utf-8");
     console.error(chalk6.green(`\u2705 Profile card saved: ${outPath}`));
     console.error(chalk6.dim("   Embed in GitHub README:"));
     console.error(chalk6.dim(`   ![Knowledge Card](${output})`));
@@ -7215,8 +7659,8 @@ async function packExportCommand(name, options) {
   }
   const outPath = resolve13(process.cwd(), options.output ?? `${name}.sv-pack`);
   const content = readFileSync15(srcPath, "utf-8");
-  const { writeFileSync: writeFileSync21 } = await import("node:fs");
-  writeFileSync21(outPath, content);
+  const { writeFileSync: writeFileSync22 } = await import("node:fs");
+  writeFileSync22(outPath, content);
   console.error(chalk7.green(`\u2705 Exported: ${outPath}`));
 }
 async function packImportCommand(filePath) {
@@ -7373,11 +7817,29 @@ function runScript(scriptPath, cwd) {
 // packages/cli/dist/commands/review-cmd.js
 import chalk10 from "chalk";
 import { createInterface } from "node:readline";
+function globToRegex(glob) {
+  const esc = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, ".+").replace(/\*/g, "[^/]*").replace(/\?/g, ".");
+  return new RegExp("^" + esc + "$");
+}
+function seededRotate(arr, seed) {
+  if (!seed)
+    return arr;
+  let h = 2166136261;
+  for (let i = 0; i < seed.length; i++) {
+    h ^= seed.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  const offset = Math.abs(h) % Math.max(1, arr.length);
+  return arr.slice(offset).concat(arr.slice(0, offset));
+}
 async function reviewCommand(options) {
   const config = loadConfig();
   const hub = createKnowledgeHub(config);
   const count = parseInt(options.count ?? "5", 10);
-  console.error(chalk10.dim("\u23F3 Initializing..."));
+  const minAgeDays = parseInt(options.minAge ?? "0", 10);
+  const excludeRe = options.exclude ? globToRegex(options.exclude) : null;
+  if (!options.json)
+    console.error(chalk10.dim("\u23F3 Initializing..."));
   await hub.store.initialize();
   const db = hub.store.getDb();
   if (!db) {
@@ -7385,7 +7847,41 @@ async function reviewCommand(options) {
     process.exit(1);
   }
   const decayEngine = new DecayEngine(db);
-  const decaying = await decayEngine.getDecaying(0.6, count);
+  let pool = await decayEngine.getDecaying(0.6, Math.max(count * 5, 50));
+  if (excludeRe || minAgeDays > 0) {
+    pool = pool.filter((d) => {
+      const doc = db.prepare("SELECT file_path FROM documents WHERE id = ?").get(d.documentId);
+      const fp = doc?.file_path ?? "";
+      if (excludeRe && excludeRe.test(fp))
+        return false;
+      if (minAgeDays > 0) {
+        const ageDays = (Date.now() - new Date(d.lastAccess).getTime()) / 864e5;
+        if (ageDays < minAgeDays)
+          return false;
+      }
+      return true;
+    });
+  }
+  if (options.seed)
+    pool = seededRotate(pool, options.seed);
+  const decaying = pool.slice(0, count);
+  if (options.json) {
+    const out = decaying.map((d) => {
+      const doc = db.prepare("SELECT file_path FROM documents WHERE id = ?").get(d.documentId);
+      const ageDays = Math.round((Date.now() - new Date(d.lastAccess).getTime()) / 864e5);
+      return {
+        documentId: d.documentId,
+        title: d.title,
+        filePath: doc?.file_path ?? null,
+        retrievability: d.retrievability,
+        lastAccess: d.lastAccess,
+        ageDays,
+        reviewScore: d.retrievability * 0.7 + Math.min(1, ageDays / 30) * 0.3
+      };
+    });
+    console.log(JSON.stringify(out, null, 2));
+    return;
+  }
   if (decaying.length === 0) {
     console.log(chalk10.green("\n\u2728 All knowledge is healthy! No notes to review."));
     return;
@@ -7534,7 +8030,7 @@ async function gapsCommand() {
 
 // packages/cli/dist/commands/clip-cmd.js
 import chalk13 from "chalk";
-import { writeFileSync as writeFileSync16, mkdirSync as mkdirSync17 } from "node:fs";
+import { writeFileSync as writeFileSync17, mkdirSync as mkdirSync17 } from "node:fs";
 import { join as join22 } from "node:path";
 async function clipCommand(url, options) {
   if (!url) {
@@ -7583,7 +8079,7 @@ async function clipCommand(url, options) {
       "",
       content
     ].join("\n");
-    writeFileSync16(filePath, md, "utf-8");
+    writeFileSync17(filePath, md, "utf-8");
     console.log(chalk13.green(`\u2705 Saved: ${fileName}`));
     console.log(chalk13.dim(`   \u2192 ${filePath}`));
     console.log(chalk13.dim("   \u{1F4A1} Run stellavault index to make it searchable"));
@@ -7784,7 +8280,7 @@ async function digestCommand(options) {
 \u{1F9E0} Health: R=${report.averageR} | Decaying ${report.decayingCount} | Critical ${report.criticalCount}`);
   console.log(chalk15.dim("\n\u2550".repeat(50)));
   if (options.visual) {
-    const { writeFileSync: writeFileSync21, mkdirSync: mkdirSync22, existsSync: existsSync25 } = await import("node:fs");
+    const { writeFileSync: writeFileSync22, mkdirSync: mkdirSync22, existsSync: existsSync25 } = await import("node:fs");
     const { join: join30, resolve: resolve22 } = await import("node:path");
     const outputDir = resolve22(config.vaultPath, "_stellavault/digests");
     if (!existsSync25(outputDir))
@@ -7829,7 +8325,7 @@ async function digestCommand(options) {
       "---",
       `*Generated by \`stellavault digest --visual\` on ${(/* @__PURE__ */ new Date()).toISOString()}*`
     ].filter(Boolean).join("\n");
-    writeFileSync21(outputPath, md, "utf-8");
+    writeFileSync22(outputPath, md, "utf-8");
     console.log(chalk15.green(`
 Visual digest saved: ${filename}`));
     console.log(chalk15.dim(`Open in Obsidian to see Mermaid charts.`));
@@ -7838,7 +8334,7 @@ Visual digest saved: ${filename}`));
 
 // packages/cli/dist/commands/init-cmd.js
 import { createInterface as createInterface2 } from "node:readline";
-import { existsSync as existsSync18, mkdirSync as mkdirSync18, writeFileSync as writeFileSync17 } from "node:fs";
+import { existsSync as existsSync18, mkdirSync as mkdirSync18, writeFileSync as writeFileSync18 } from "node:fs";
 import { join as join23 } from "node:path";
 import { homedir as homedir14 } from "node:os";
 import ora2 from "ora";
@@ -7886,7 +8382,7 @@ async function initCommand() {
       search: { defaultLimit: 10, rrfK: 60 },
       mcp: { mode: "stdio", port: 3333 }
     };
-    writeFileSync17(join23(homedir14(), ".stellavault.json"), JSON.stringify(configData, null, 2), "utf-8");
+    writeFileSync18(join23(homedir14(), ".stellavault.json"), JSON.stringify(configData, null, 2), "utf-8");
     console.log(chalk16.dim(`  Config saved: ~/.stellavault.json`));
     console.log("");
     console.log(chalk16.cyan("  Step 2/3") + " \u2014 Indexing your vault");
@@ -7984,7 +8480,7 @@ Andrej Karpathy's approach: every session auto-compiles into structured knowledg
         }
       ];
       for (const s of samples) {
-        writeFileSync17(join23(rawDir, s.file), s.content, "utf-8");
+        writeFileSync18(join23(rawDir, s.file), s.content, "utf-8");
       }
       const reSpinner = ora2({ text: "  Indexing sample notes...", indent: 2 }).start();
       const reResult = await indexVault(vaultPath, {
@@ -8158,10 +8654,22 @@ async function contradictionsCommand(_opts, cmd) {
 import { createInterface as createInterface3 } from "node:readline";
 import chalk19 from "chalk";
 async function federateJoinCommand(options) {
+  if (!isFederationExperimentalEnabled()) {
+    console.log("");
+    console.log(chalk19.red("  \u2726 Federation is experimental and disabled by default."));
+    console.log("");
+    console.log(chalk19.dim("  Enable it by setting an environment variable:"));
+    console.log(chalk19.dim('    PowerShell:  $env:STELLAVAULT_FEDERATION_EXPERIMENTAL = "1"'));
+    console.log(chalk19.dim("    bash/zsh:    export STELLAVAULT_FEDERATION_EXPERIMENTAL=1"));
+    console.log("");
+    console.log(chalk19.dim("  Then re-run `stellavault federate join`."));
+    console.log("");
+    process.exit(2);
+  }
   const config = loadConfig();
   const identity = getOrCreateIdentity(options.name);
   console.log("");
-  console.log(chalk19.bold("  \u2726 Stellavault Federation"));
+  console.log(chalk19.bold("  \u2726 Stellavault Federation") + chalk19.yellow(" (experimental)"));
   console.log(chalk19.dim(`  Node: ${identity.displayName} (${identity.peerId})`));
   console.log("");
   const store = createSqliteVecStore(config.dbPath);
@@ -8174,6 +8682,13 @@ async function federateJoinCommand(options) {
   node.setLocalStats(stats.documentCount, topics.slice(0, 5).map((t2) => t2.topic));
   const search = new FederatedSearch(node, store, embedder);
   search.startResponder();
+  const sharingCfg = loadSharingConfig();
+  if (sharingCfg.myNodeLevel === 0) {
+    console.log(chalk19.yellow("  \u26A0 Receive-only mode (my node level = 0)."));
+    console.log(chalk19.dim("    Run `set-level 1` or higher in the federation prompt to share."));
+  } else {
+    console.log(chalk19.dim(`  Sharing level: ${sharingCfg.myNodeLevel} (set-level <0-4> to change)`));
+  }
   node.on("joined", (info) => {
     console.log(chalk19.green(`  \u2726 Joined federation network`));
     console.log(chalk19.dim(`    Topic: ${info.topic}`));
@@ -8621,7 +9136,7 @@ import chalk25 from "chalk";
 // packages/core/dist/intelligence/draft-generator.js
 init_wiki_compiler();
 init_config();
-import { writeFileSync as writeFileSync18, mkdirSync as mkdirSync19, existsSync as existsSync19 } from "node:fs";
+import { writeFileSync as writeFileSync19, mkdirSync as mkdirSync19, existsSync as existsSync19 } from "node:fs";
 import { join as join24, resolve as resolve16, basename as basename5, extname as extname7 } from "node:path";
 function generateDraft(vaultPath, options = {}, folders = DEFAULT_FOLDERS) {
   const { topic, format = "blog", maxSections = 8, blueprint } = options;
@@ -8705,7 +9220,7 @@ function generateDraft(vaultPath, options = {}, folders = DEFAULT_FOLDERS) {
   const filename = `${timestamp}-${slug}.md`;
   const filePath = join24("_drafts", filename);
   const fullPath = resolve16(vaultPath, filePath);
-  writeFileSync18(fullPath, body, "utf-8");
+  writeFileSync19(fullPath, body, "utf-8");
   return {
     title: draftTitle,
     filePath,
@@ -8901,7 +9416,7 @@ async function draftCommand(topic, options) {
   }
 }
 async function enhanceWithAI(vaultPath, draftPath, topic, format) {
-  const { readFileSync: readFileSync18, writeFileSync: writeFileSync21 } = await import("node:fs");
+  const { readFileSync: readFileSync18, writeFileSync: writeFileSync22 } = await import("node:fs");
   const { resolve: resolve22 } = await import("node:path");
   const fullPath = resolve22(vaultPath, draftPath);
   const scaffold = readFileSync18(fullPath, "utf-8");
@@ -8946,7 +9461,7 @@ ${aiContent.text}
 ---
 *Generated by \`stellavault draft --ai\` using Claude API at ${(/* @__PURE__ */ new Date()).toISOString()}*
 `;
-      writeFileSync21(fullPath, enhanced, "utf-8");
+      writeFileSync22(fullPath, enhanced, "utf-8");
     }
   } catch (err) {
     console.error(chalk25.yellow(`  AI enhancement failed: ${err instanceof Error ? err.message : "unknown"}. Keeping rule-based draft.`));
@@ -8955,7 +9470,7 @@ ${aiContent.text}
 
 // packages/cli/dist/commands/session-cmd.js
 import chalk26 from "chalk";
-import { writeFileSync as writeFileSync19, mkdirSync as mkdirSync20, existsSync as existsSync20, appendFileSync } from "node:fs";
+import { writeFileSync as writeFileSync20, mkdirSync as mkdirSync20, existsSync as existsSync20, appendFileSync } from "node:fs";
 import { resolve as resolve17, join as join25 } from "node:path";
 async function sessionSaveCommand(options) {
   const config = loadConfig();
@@ -9021,7 +9536,7 @@ async function sessionSaveCommand(options) {
       `# Daily Log \u2014 ${dateStr}`,
       ""
     ].join("\n");
-    writeFileSync19(logFile, header + entry.join("\n"), "utf-8");
+    writeFileSync20(logFile, header + entry.join("\n"), "utf-8");
   } else {
     appendFileSync(logFile, entry.join("\n"), "utf-8");
   }
@@ -9192,7 +9707,7 @@ async function lintCommand() {
 
 // packages/cli/dist/commands/fleeting-cmd.js
 import chalk30 from "chalk";
-import { writeFileSync as writeFileSync20, mkdirSync as mkdirSync21, existsSync as existsSync22 } from "node:fs";
+import { writeFileSync as writeFileSync21, mkdirSync as mkdirSync21, existsSync as existsSync22 } from "node:fs";
 import { join as join27, resolve as resolve19 } from "node:path";
 async function fleetingCommand(text, options) {
   if (!text || text.trim().length < 2) {
@@ -9226,7 +9741,7 @@ async function fleetingCommand(text, options) {
     "---",
     `*Captured via \`stellavault fleeting\` at ${now.toLocaleString("ko-KR")}*`
   ].join("\n");
-  writeFileSync20(filePath, content, "utf-8");
+  writeFileSync21(filePath, content, "utf-8");
   console.log(chalk30.green(`Captured: ${filename}`));
   console.log(chalk30.dim(`Location: raw/${filename}`));
   console.log(chalk30.dim("Run `stellavault compile` to process into wiki."));
@@ -9647,25 +10162,25 @@ if (nodeVersion < 20) {
   process.exit(1);
 }
 var program = new Command();
-var SV_VERSION = true ? "0.7.2" : "0.0.0-dev";
+var SV_VERSION = true ? "0.7.4" : "0.0.0-dev";
 program.name("stellavault").description("Stellavault \u2014 Self-compiling knowledge base for your Obsidian vault").version(SV_VERSION).option("--json", "Output in JSON format (for scripting)").option("--quiet", "Suppress non-essential output");
 program.command("init").description("Interactive setup wizard \u2014 get started in 3 minutes").action(initCommand);
 program.command("doctor").description("Diagnose setup issues (config, vault, DB, model, Node version)").action(doctorCommand);
-program.command("index [vault-path]").description("Index your vault (vectorize all documents for search)").action(indexCommand);
+program.command("index [vault-path]").description("Index your vault (vectorize all documents for search)").option("--no-spinner", "Disable spinner (for CI / log redirection)").option("-v, --verbose", "Verbose progress logs instead of spinner").option("--log-skipped <file>", "Write skipped/failed file list as JSON").option("--profile-memory", "Log RSS/heap every ~100 embeddings (diagnoses memory leaks)").action((vaultPath, opts) => indexCommand(vaultPath, opts));
 program.command("status").description("Show index status (document count, last indexed, DB size)").action(statusCommand);
 program.command("search <query>").description("Search your knowledge base (hybrid BM25 + vector)").option("-l, --limit <n>", "Max results", "5").action(searchCommand);
 program.command("ask <question>").description("Ask a question \u2014 search, compose answer, optionally save").option("-s, --save", "Save answer as a new note in your vault").option("-q, --quotes", "Show direct quotes from sources").action((question, opts) => askCommand(question, opts));
 program.command("ingest <input>").description("Ingest any input (URL, file, text, PDF, YouTube) into your vault").option("-t, --tags <tags>", "Comma-separated tags").option("-s, --stage <stage>", "Note stage: fleeting, literature, permanent", "fleeting").option("--title <title>", "Override title").action((input, opts) => ingestCommand(input, opts));
 program.command("clip <url>").description("Clip a web page or YouTube video into your vault").option("-f, --folder <path>", "Vault subfolder for clips", "06_Research/clips").action(clipCommand);
 program.command("graph").description("Launch the 3D knowledge graph in your browser").action(graphCommand);
-program.command("serve").description("Start MCP server (for Claude Code / Claude Desktop)").action(serveCommand);
+program.command("serve").alias("mcp").description("Start MCP server (for Claude Code / Claude Desktop). Alias: mcp").action(serveCommand);
 program.command("decay").description("Memory decay report \u2014 find notes you are forgetting").action(decayCommand);
 program.command("brief").description("Daily knowledge briefing (decay + gaps + activity)").action(briefCommand);
 program.command("digest").description("Weekly knowledge activity report").option("-d, --days <n>", "Period in days", "7").option("-v, --visual", "Save as .md with Mermaid charts for Obsidian").action(digestCommand);
 program.command("gaps").description("Detect knowledge gaps (weak connections between clusters)").action(gapsCommand);
 program.command("duplicates").description("Find duplicate or near-identical notes").option("-t, --threshold <n>", "Similarity threshold (0\u20131)", "0.88").action(duplicatesCommand);
 program.command("contradictions").description("Detect contradicting statements across your notes").action(contradictionsCommand);
-program.command("review").description("Daily review \u2014 resurface fading notes for spaced repetition").option("-n, --count <n>", "Number of notes to review", "5").action(reviewCommand);
+program.command("review").description("Daily review \u2014 resurface fading notes for spaced repetition").option("-n, --count <n>", "Number of notes to review", "5").option("--json", "Output as JSON (non-interactive, for automation)").option("--seed <value>", "Deterministic seed for rotation (e.g. day-of-year)").option("--exclude <glob>", 'Exclude paths matching glob (e.g. "Templates/**")').option("--min-age <days>", "Only notes older than N days", "0").action(reviewCommand);
 program.command("learn").description("AI learning path \u2014 personalized recommendations based on decay + gaps").action(learnCommand);
 program.command("lint").description("Knowledge health check \u2014 gaps, duplicates, contradictions, stale notes").action(() => lintCommand());
 program.command("draft [topic]").description("Generate a draft from your knowledge (blog/report/outline/instagram/thread/script)").option("--format <type>", "Output format: blog, report, outline, instagram, thread, script").option("--ai", "Use Claude API for AI-enhanced draft (requires ANTHROPIC_API_KEY)").option("--blueprint <spec>", 'Chapter structure: "Ch1:tag1,tag2; Ch2:tag3"').action((topic, opts) => draftCommand(topic, opts));